Merge remote-tracking branch 'origin/master' into feat/tui-package

# Conflicts:
#	docs/architecture.md
#	docs/config-catalog.md
#	docs/cordis-catalog/events.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	examples/coding-agent/cordis.yml
#	examples/echo-agent/cordis.yml
#	knip.json
#	packages/core/agent-loop/README.md
#	packages/core/agent-loop/tests/config-session-id.spec.ts
#	packages/examples/README.md
#	packages/examples/stdio-demo/README.md
#	packages/examples/stdio-demo/tests/stdio-agent.spec.ts

examples/coding-agent/code-mode.cordis.yml

@@ -11,9 +11,12 @@
       - id: stdio-agent
         name: '@deepseek-ai/dsh-stdio-demo'
         config:
+          provider: deepseek
           model: deepseek-v4-flash
           resumeSessionId: !!js process.env.RESUME_SESSION_ID
           persistenceRoot: './.sessions'
+          workspaceContext:
+            maxBytes: 65536
           tools:
             mode: code
           welcome: 'code-mode agent ready. Give it a multi-tool task.'

examples/coding-agent/composition.md

@@ -23,6 +23,8 @@ flowchart LR
   bundle_agent_core --> spine_sessions["ctx.sessions"]
   bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
   bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_coding_token_meter["token-meter<br/>@deepseek-ai/dsh-token-meter"]
+  cfg --> plugin_coding_token_meter
   plugin_coding_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
   cfg --> plugin_coding_compact_basic
   plugin_coding_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
@@ -47,6 +49,14 @@ flowchart LR
   cfg --> plugin_coding_fs_policy
   plugin_coding_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
   cfg --> plugin_coding_tool_fs
+  plugin_coding_tool_fs_search["tool-fs-search<br/>@deepseek-ai/dsh-tool-fs-search"]
+  cfg --> plugin_coding_tool_fs_search
+  plugin_coding_timeout_policy["timeout-policy<br/>@deepseek-ai/dsh-timeout-policy"]
+  cfg --> plugin_coding_timeout_policy
+  plugin_coding_spill_local["spill-local<br/>@deepseek-ai/dsh-spill-local"]
+  cfg --> plugin_coding_spill_local
+  plugin_coding_spill_policy["spill-policy<br/>@deepseek-ai/dsh-spill-policy"]
+  cfg --> plugin_coding_spill_policy
 ```
 
 | Plugin id | Package / module |
@@ -55,6 +65,7 @@ flowchart LR
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
 | `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` |
+| `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
@@ -67,6 +78,10 @@ flowchart LR
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
 | `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` |
+| `timeout-policy` | `@deepseek-ai/dsh-timeout-policy` |
+| `spill-local` | `@deepseek-ai/dsh-spill-local` |
+| `spill-policy` | `@deepseek-ai/dsh-spill-policy` |
 
 Source config: [`examples/coding-agent/cordis.yml`](cordis.yml).
 

examples/coding-agent/cordis.yml

@@ -1,6 +1,7 @@
 # Coding agent with swappable DeepSeek and local-bash backends. `dsh-stdio-demo`
-# supplies the agent spine, generic task controls, JSONL persistence, TTY-selected
-# `dsh-tui`/`dsh-stdio` terminal front doors, and `main` agent.
+# supplies the agent spine, workspace instructions, generic task controls,
+# JSONL persistence, TTY-selected `dsh-tui`/`dsh-stdio` terminal front doors,
+# readline logging, and `main` agent.
 # HMR remains a leaf because it requires Loader internals; `demo:repl` passes
 # `--expose-internals`. The app bin loads the gitignored root `.env`; this file
 # reads `DEEPSEEK_API_KEY` and optional `DEEPSEEK_BASE_URL` through `!!js`.
@@ -11,16 +12,12 @@
   config:
     root: ['.']
 
-# The DeepSeek adapter. Swap to '@deepseek-ai/dsh-llm-pi-ai' for the pi-ai-backed
-# twin (same config shape; `reasoning: high` replaces thinking/reasoningEffort).
+# The native DeepSeek adapter.
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
   config:
     apiKey: !!js process.env.DEEPSEEK_API_KEY
     baseURL: !!js process.env.DEEPSEEK_BASE_URL
-    models:
-      - deepseek-v4-pro
-      - deepseek-v4-flash
 
 # Local executor for the app bundle's bash tool.
 - id: bash
@@ -32,11 +29,14 @@
 - id: stdio-agent
   name: '@deepseek-ai/dsh-stdio-demo'
   config:
+    provider: deepseek
     model: deepseek-v4-flash
     # Set RESUME_SESSION_ID to continue a prior persisted session (the ids live
     # under ./.sessions); unset starts a fresh session each run.
     resumeSessionId: !!js process.env.RESUME_SESSION_ID
     persistenceRoot: './.sessions'
+    workspaceContext:
+      maxBytes: 65536
     welcome: 'agent REPL ready. Give it a coding task.'
     ui:
       mode: auto
@@ -51,17 +51,14 @@
       Verify your work by running the code or tests. Keep answers brief and
       factual.
 
-# Summarize an older range when derived history approaches the context window.
-# This leaf consumes `ctx.llm` and the app's `agent/pre-step` seam.
+# Replay-aware request pressure with one service-wide context window.
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+# Summarize an older range when measured history approaches the context window.
+# Service-wide policy provides the ordinary threshold and retained-tail defaults.
 - id: compact-basic
   name: '@deepseek-ai/dsh-compact-basic'
-  config:
-    contextWindow: 128000
-    thresholdRatio: 0.8
-    retainTokens: 20480
-    summarizationModel: ''
-    maxTokens: 8192
-    compactionRetries: 1
 
 # Expose fresh-child `spawn` and completed-prefix `fork` through independent
 # in-process backends. Each tool instance needs a distinct `toolName`; the registry
@@ -117,3 +114,29 @@
 
 - id: tool-fs
   name: '@deepseek-ai/dsh-tool-fs'
+
+# Bash-backed discovery tools (glob/grep): fixed ripgrep commands through the
+# local bash executor above — not ctx.fs. Capped results save the complete
+# formatted list through the spill backend below (ctx.spillStore, optional).
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+
+# The tool-call timeout enforcer: arms each declared ToolDefinition.timeoutMs
+# (the search tools above declare 30s) as a deadline on exec.signal. Without
+# it a declared budget is advisory and only the bash executor's own timeout
+# backstop applies.
+- id: timeout-policy
+  name: '@deepseek-ai/dsh-timeout-policy'
+
+# Tool-output spill stack: a local backend that saves oversized tool text under
+# a private session-scoped dir, and the tools/post-execute policy that replaces
+# an over-budget plain-text result with a preview + the spill locator/retrieval
+# hint. A leaf pair after the app (needs ctx.tools). The policy is a no-op until
+# a tool returns more than maxInlineBytes of plain text.
+- id: spill-local
+  name: '@deepseek-ai/dsh-spill-local'
+
+- id: spill-policy
+  name: '@deepseek-ai/dsh-spill-policy'
+  config:
+    maxInlineBytes: 50000

examples/coding-agent/tests/code-mode.e2e.ts

@@ -1,10 +1,10 @@
-import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
@@ -14,6 +14,9 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
+import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import * as WorkspaceContext from '@deepseek-ai/dsh-workspace-context'
 
 /**
  * With-key Code Mode proof: a real model receives only `run_code`, composes two
@@ -23,6 +26,7 @@ import { WorkerCodeRuntime } from '@deepseek-ai/dsh-code-runtime-worker'
 
 const PERSONA = 'You are coding-agent. You work by writing TypeScript programs for run_code: '
   + 'batch related tool work into one program and print or return ONLY the findings that matter.'
+const WORKSPACE_PROBE = 'dragonfruit-8675309'
 
 let ctx: Context | undefined
 let workdir: string | undefined
@@ -45,13 +49,29 @@ async function codeModeHarness(cwd: string): Promise<Context> {
   await harness.plugin(ToolRegistry, { mode: 'code' })
   await harness.plugin(AgentRegistry)
   await harness.plugin(AgentLoop, { agents: [] })
-  await harness.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await harness.plugin(LlmDeepSeek)
   await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
   await harness.plugin(ToolBash)
   await harness.plugin(WorkerCodeRuntime, {})
   return harness
 }
 
+async function workspaceCodeModeHarness(): Promise<Context> {
+  const harness = new Context()
+  await harness.plugin(LlmService)
+  await harness.plugin(SessionStore)
+  await harness.plugin(SystemPrompt, { persona: PERSONA })
+  await harness.plugin(ToolRegistry, { mode: 'code' })
+  await harness.plugin(AgentRegistry)
+  await harness.plugin(LocalFileSystem, { cwd: '/' })
+  await harness.plugin(ToolFs)
+  await harness.plugin(WorkspaceContext, { maxBytes: 65536 })
+  await harness.plugin(AgentLoop, { agents: [] })
+  await harness.plugin(LlmDeepSeek, { models: [{ id: 'deepseek-v4-flash' }] })
+  await harness.plugin(WorkerCodeRuntime, {})
+  return harness
+}
+
 function waitForIdle(harness: Context, agent: ReactLoopAgent): Promise<void> {
   return new Promise((resolve) => {
     const dispose = harness.on('agent/status', (subject, status) => {
@@ -67,7 +87,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a p
   it('collapses the wire tool list to [run_code], bridges sub-calls, and returns curated output', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-e2e-'))
     ctx = await codeModeHarness(workdir)
-    const agent = ctx.agentLoop.create(AgentId('e2e-code-mode'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('e2e-code-mode'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{
       type: 'text',
@@ -107,4 +127,43 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a p
     expect(finalText).toContain('alpha-7')
     expect(finalText).toContain('beta-9')
   }, 180_000)
+
+  it('delivers nested workspace instructions discovered by an fs sub-call after the outer result', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-code-mode-workspace-e2e-'))
+    await mkdir(join(workdir, '.git'), { recursive: true })
+    await mkdir(join(workdir, 'pkg/deep'), { recursive: true })
+    await writeFile(join(workdir, 'pkg/AGENTS.md'), `If asked for the Code Mode workspace handshake, reply with exactly ${WORKSPACE_PROBE} and nothing else.\n`)
+    await writeFile(join(workdir, 'pkg/deep/task.txt'), 'Touch this file to discover the nested instructions.\n')
+    ctx = await workspaceCodeModeHarness()
+    const handle = await ctx.agents.create({
+      agentId: AgentId('e2e-code-mode-workspace'),
+      sessionId: SessionId('e2e-code-mode-workspace-session'),
+      meta: { cwd: workdir },
+      agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    })
+
+    handle.agent.send([{
+      type: 'text',
+      text: 'Use one run_code program to call tools.read on pkg/deep/task.txt. After it finishes, answer: Code Mode workspace handshake?',
+    }])
+    await waitForIdle(ctx, handle.agent as ReactLoopAgent)
+
+    const events: SessionEvent[] = [...handle.agent.session.events]
+    const dispatch = events.find(event => event.type === 'tool/code-dispatch' && event.data.name === 'read')
+    const outerResult = events.find(event => event.type === 'tool/result')
+    const workspaceContext = events.find(event => event.type === 'context/message'
+      && typeof event.data.meta === 'object'
+      && event.data.meta !== null
+      && !Array.isArray(event.data.meta)
+      && event.data.meta.kind === 'workspace-instructions')
+    expect(dispatch).toBeDefined()
+    expect(outerResult).toBeDefined()
+    expect(workspaceContext).toBeDefined()
+    expect(workspaceContext!.seq).toBeGreaterThan(outerResult!.seq)
+    const finalMessage = events.findLast(event => event.type === 'assistant/message')
+    const answer = finalMessage?.type === 'assistant/message'
+      ? finalMessage.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
+      : ''
+    expect(answer).toContain(WORKSPACE_PROBE)
+  }, 180_000)
 })

examples/coding-agent/tests/coding-task.e2e.ts

@@ -54,7 +54,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('coding task: fix a failing test
     expect(before.status).not.toBe(0)
 
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(AgentId('e2e-task'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('e2e-task'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{
       type: 'text',

examples/coding-agent/tests/compaction.e2e.ts

@@ -33,17 +33,20 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     // Reasoning tokens require a larger generation cap than the retained checkpoint.
     ctx = await codingHarness(workdir, {
       persona: SYSTEM_PROMPT,
-      compact: {
+      tokenMeter: {
         contextWindow: 2000,
+      },
+      compact: {
         thresholdRatio: 0.5,
         retainTokens: 400,
+        summarizationProvider: '',
         summarizationModel: '',
         maxTokens: 1024,
         compactionRetries: 1,
       },
       persistenceRoot: join(workdir, '.sessions'),
     })
-    const agent = ctx.agentLoop.create(AgentId('e2e-compaction'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('e2e-compaction'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{
       type: 'text',

examples/coding-agent/tests/full-loop.e2e.ts

@@ -28,7 +28,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('full loop: real model + real bas
   it('runs a bash command on request and reports its output', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-full-loop-e2e-'))
     ctx = await codingHarness(workdir, { persona: SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(AgentId('e2e-loop'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('e2e-loop'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text: 'Run `echo e2e-ok` with the bash tool and tell me its exact output.' }])
     await waitForIdle(ctx, agent)

examples/coding-agent/tests/harness.ts

@@ -1,15 +1,13 @@
 import { Context } from 'cordis'
-import LlmService from '@deepseek-ai/dsh-llm'
-import SessionStore from '@deepseek-ai/dsh-session'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import type { TokenMeterConfig } from '@deepseek-ai/dsh-token-meter'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
 import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
@@ -46,23 +44,26 @@ export interface CodingHarnessOptions {
    * compaction plugin (the default suites run without it).
    */
   compact?: BasicCompactConfig
+  /** Optional token-meter capacity loaded before compact-basic. */
+  tokenMeter?: TokenMeterConfig
 }
 
 export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise<Context> {
   const ctx = new Context()
-  await ctx.plugin(LlmService)
-  await ctx.plugin(SessionStore)
-  await ctx.plugin(SystemPrompt, { persona: options.persona ?? '' })
-  await ctx.plugin(ToolRegistry)
-  await ctx.plugin(AgentRegistry)
+  await mountAgentLoopTestDependencies(ctx, {
+    systemPrompt: { persona: options.persona ?? '' },
+  })
   await ctx.plugin(AgentLoop, { agents: [] })
-  await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await ctx.plugin(LlmDeepSeek)
   await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
   await ctx.plugin(ToolBash)
   await ctx.plugin(ToolTodo)
-  // Compaction is opt-in: only the compaction e2e loads it, with a lowered
-  // contextWindow/retainTokens so a short real session crosses the threshold.
-  if (options.compact !== undefined) await ctx.plugin(BasicCompactService, options.compact)
+  // Compaction is opt-in: only the compaction e2e loads the reusable meter and
+  // backend, with a lower context window so a short real session crosses the threshold.
+  if (options.compact !== undefined) {
+    await ctx.plugin(TokenMeterService, options.tokenMeter)
+    await ctx.plugin(BasicCompactService, options.compact)
+  }
   // Durable JSONL persistence is opt-in: only the resume e2e needs it, and the
   // other suites stay file-free. Loaded last so a resume's deferred
   // `ctx.inject(['sessionPersistence'])` resolves once this is present.

examples/coding-agent/tests/resume.e2e.ts

@@ -42,7 +42,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     const first = (await ctx.agents.create({
       agentId: AgentId('resume-1'),
       sessionId: SESSION_ID,
-      agentOptions: { model: 'deepseek-v4-flash' },
+      agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
     })).agent as ReactLoopAgent
     first.send([{ type: 'text', text: `Remember this code for later: ${SECRET}. Just acknowledge it.` }])
     await waitForIdle(ctx, first)
@@ -56,7 +56,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     const resumed = (await ctx.agents.resume({
       agentId: AgentId('resume-2'),
       resumeSessionId: SESSION_ID,
-      agentOptions: { model: 'deepseek-v4-flash' },
+      agentOptions: { provider: 'deepseek', model: 'deepseek-v4-flash' },
     })).agent as ReactLoopAgent
     expect(resumed.session.id).toBe(SESSION_ID)
     // The prior user turn is in the rehydrated log before the model is asked.

examples/coding-agent/tests/todo-write.e2e.ts

@@ -26,7 +26,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('todo_write: real model records a
   it('appends a todo/write event with the model-produced task list', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'dsh-todo-write-e2e-'))
     ctx = await codingHarness(workdir, { persona: TODO_SYSTEM_PROMPT })
-    const agent = ctx.agentLoop.create(AgentId('e2e-todo'), { model: 'deepseek-v4-flash' })
+    const agent = ctx.agentLoop.create(AgentId('e2e-todo'), { provider: 'deepseek', model: 'deepseek-v4-flash' })
 
     agent.send([{ type: 'text', text:
       'Use the todo_write tool to record a plan of exactly two steps: first '