Merge master into codex/grep-glob-require-rg

2026-08-15 21:04:50 +00:00 · 2026-07-17 21:25:37 +08:00
parent faae2d389b cf872d002f
commit b3b353b017
1149 changed files with 61193 additions and 21544 deletions
--- a/examples/coding-agent/README.md
+++ b/examples/coding-agent/README.md
@@ -11,7 +11,7 @@ The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem t
 pnpm run demo:repl
 ```

-Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ `bash_output` / `bash_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.
+Type a coding task. The agent works through the `read`/`write`/`edit` filesystem tools for ordinary file operations and `bash` (+ the generic `task_output` / `task_list` / `task_kill` for background tasks) for shell commands, searches, and test runs, each in a fresh `bash -c` (the system prompt tells the model to pass `workdir` instead of `cd`). Both the fs tools and bash resolve relative paths against the session workspace. It can also delegate with `subagent`/`subagent_fork` and track multi-step work with `todo_write` (a whole-list task tracker rendered as a checklist). Reasoning streams dimmed; tool calls/results render inline.

 ```
 > fix the failing test in /path/to/project
@@ -33,7 +33,7 @@ The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_

 ## Code Mode

-[`code-mode.cordis.yml`](code-mode.cordis.yml) is this same tree flipped to [Code Mode](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md): an include overlay over `./cordis.yml` whose two patches insert the worker-thread code runtime (`@deepseek-ai/dsh-code-runtime-worker`, registering `ctx.codeRuntime`) and set `tools: { mode: code }` on the app. The registry contributes exactly one reserved wire transport — `run_code` — plus a generated TypeScript SDK section declaring the visible end-capability tools. The model composes those capabilities by writing a program; each program call carries an immutable link to its enclosing transport, bridges back through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation one at a time, and is logged as a `tool/code-dispatch` session event. Only what the program prints or returns re-enters model context. (Flip the mode to `both` to offer native calls and `run_code` side by side.)
+[`code-mode.cordis.yml`](code-mode.cordis.yml) overlays the same tree with the worker-thread runtime and `tools: { mode: code }`. The model receives one `run_code` transport plus a generated TypeScript SDK for the visible tools; only program output returns to model context. Use `mode: both` to expose native calls alongside `run_code`. See the [Code Mode RFC](../../docs/rfc/implemented/feature/2026-06-15-code-mode.md) for the execution contract.

 ```sh
 pnpm run demo:code-mode        # this overlay under the REPL (default UI)
@@ -48,14 +48,14 @@ and watch the transcript: one `run_code` call, a program looping over tools, and

 ## What each leaf entry demonstrates

-This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (console logger, JSONL persistence, readline UI, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent) app and the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle it loads; the leaf wires the backends and model-facing optional tools:
+This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads one app package, and adds product tools that are intentionally outside the shared spine. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (console logger, JSONL persistence, readline UI, the pre-created `main` agent) live inside the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app and the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle it loads; the leaf wires the backends and model-facing optional tools:

 | Entry | Demonstrates |
 |---|---|
 | `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:repl` passes |
 | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
-| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice |
-| `stdio-agent` (`@deepseek-ai/dsh-stdio-agent`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
+| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash` schema (`tool-bash`) and generic `task_*` controls (`tool-tasks`) come from `dsh-agent-spine-demo`, so only the executor is a leaf choice |
+| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
 | `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
 | `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
 | `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a checklist in stdio |
--- a/examples/coding-agent/code-mode.cordis.yml
+++ b/examples/coding-agent/code-mode.cordis.yml
@@ -1,24 +1,21 @@
-# Code Mode overlay: the live coding-agent tree (./cordis.yml) with two
-# load-time patches — the app entry's config gains `tools: { mode: code }`
-# (the registry offers exactly one wire tool, run_code, plus the generated
-# TypeScript SDK prompt section declaring bash/read/write/edit/subagent/
-# todo_write) and the worker-thread code runtime joins the tree as
-# `ctx.codeRuntime`. The dsh-stdio-agent bin boots this file for
-# `pnpm run demo:code-mode` (the acp-agent example carries the same-shaped
-# overlay for the `acp` UI). A config patch REPLACES the entry's whole
-# config, so the base entry's fields are restated verbatim; only `tools`,
-# the welcome, and the persona's second paragraph are Code Mode deltas.
+# Code Mode adds `ctx.codeRuntime` and changes the registry to one wire tool,
+# `run_code`, plus a generated SDK for bash/read/write/edit/subagent/todo_write.
+# `demo:code-mode` selects this overlay; the ACP example has the same UI-specific
+# shape. A config patch replaces the whole app config, so unchanged base fields
+# are restated; only `tools`, `welcome`, and the persona's second paragraph differ.
 - id: base
  name: '@cordisjs/plugin-include'
  config:
    path: ./cordis.yml
    patches:
      - id: stdio-agent
-        name: '@deepseek-ai/dsh-stdio-agent'
+        name: '@deepseek-ai/dsh-stdio-demo'
        config:
          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.'
--- a/examples/coding-agent/composition.md
+++ b/examples/coding-agent/composition.md
@@ -14,9 +14,9 @@ flowchart LR
  cfg --> plugin_coding_llm_deepseek
  plugin_coding_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
  cfg --> plugin_coding_bash
-  plugin_coding_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  plugin_coding_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-demo"]
  cfg --> plugin_coding_stdio_agent
-  plugin_coding_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_coding_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
  plugin_coding_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
  plugin_coding_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
  bundle_agent_core --> spine_llm["ctx.llm"]
@@ -62,7 +62,7 @@ flowchart LR
 | `hmr` | `@cordisjs/plugin-hmr` |
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
-| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
--- a/examples/coding-agent/cordis.yml
+++ b/examples/coding-agent/cordis.yml
@@ -1,15 +1,9 @@
-# The coding-agent plugin tree: the REPL agent demo. The two swappable
-# backends — the DeepSeek adapter and the local bash executor — plus `hmr` for
-# the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio-
-# agent), which bundles the whole agent-core spine (timer, llm, sessions,
-# system-prompt, tools, agents, invariants, tool-bash, agent-loop), the console
-# logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
-#
-# `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
-# dev plugin that needs `--expose-internals` — the `demo:repl` script passes
-# it. Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
-# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env
-# first. cordis.yml reads them via the `!!js` tag.
+# REPL agent with swappable DeepSeek and local-bash backends. `dsh-stdio-demo`
+# supplies the agent spine, workspace instructions, generic task controls,
+# logging, JSONL persistence, readline UI, 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`.

 # Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
 - id: hmr
@@ -28,38 +22,34 @@
      - deepseek-v4-pro
      - deepseek-v4-flash

-# Local bash executor for agent-core's tool-bash schema (one of several tool
-# stacks in this tree: filesystem, subagent, and todo_write load below).
+# Local executor for the app bundle's bash tool.
 - id: bash
  name: '@deepseek-ai/dsh-bash-local'
  config:
    timeoutMs: 60000

-# The stdio chat app: the whole spine + front-door cluster, configured for a
-# REPL agent demo driving a pre-created `main` agent.
+# The app bundle pre-creates the REPL's `main` agent.
 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    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.'
-    # The persona: identity + behavior only, nothing about transports or
-    # tooling — tool guidance lives with each tool plugin (descriptions +
-    # prompt sections). {{model}} is the prompt variable the agent loop
-    # resolves from this agent's configured model.
+    # Keep the persona to identity and behavior; tool plugins own tool guidance.
+    # The loop resolves {{model}} from this agent's configuration.
    persona: |
      You are coding-agent, a coding assistant powered by the {{model}} model.

      Verify your work by running the code or tests. Keep answers brief and
      factual.

-# Automatic context compaction: when the derived history approaches the model's
-# context window, summarize an older range into a checkpoint so a long-running
-# or tool-heavy session keeps fitting. A leaf entry (needs ctx.llm + the
-# agent-loop's `agent/pre-step` seam from the app above).
+# Summarize an older range when derived history approaches the context window.
+# This leaf consumes `ctx.llm` and the app's `agent/pre-step` seam.
 - id: compact-basic
  name: '@deepseek-ai/dsh-compact-basic'
  config:
@@ -70,13 +60,9 @@
    maxTokens: 8192
    compactionRetries: 1

-# The subagent seam + BOTH in-process backends + two model-facing tools, as leaf
-# entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh
-# child) and fork (a child seeded with the parent's completed-turn prefix) are
-# independent backends over the shared dsh-subagent-inprocess driver. Exposing
-# both transports is pure config: load each backend, then load dsh-tool-subagent
-# once per backend with a distinct toolName (the tool registry rejects a
-# duplicate name) — no code change.
+# Expose fresh-child `spawn` and completed-prefix `fork` through independent
+# in-process backends. Each tool instance needs a distinct `toolName`; the registry
+# rejects duplicates. These leaves follow the app because it provides `ctx.agents` and `ctx.tools`.
 - id: subagent
  name: '@deepseek-ai/dsh-subagent'

@@ -103,10 +89,8 @@
    toolName: subagent_fork


-# Dynamic workflows: the worker-thread engine (ctx.workflows) over the spawn
-# subagent backend above, plus the model-facing `workflow` tool. The model
-# writes a JavaScript orchestration script (meta + body); the engine runs it
-# in its own worker thread and fans agent() calls out as spawn children.
+# The worker-thread workflow engine fans a model-written JavaScript script's
+# `agent()` calls out through the spawn backend; the adjacent tool exposes it to the model.
 - id: workflow-workerthread
  name: '@deepseek-ai/dsh-workflow-workerthread'
  config:
@@ -114,14 +98,12 @@

 - id: tool-workflow
  name: '@deepseek-ai/dsh-tool-workflow'
-# The model-facing todo_write tool: whole-list task tracking written to the
-# session log (todo/write), rendered as a stdio checklist / ACP plan.
+# `todo_write` replaces the logged whole list and renders as a stdio checklist or ACP plan.
 - id: tool-todo
  name: '@deepseek-ai/dsh-tool-todo'

-# Filesystem capability stack: local provider, read-before-write/edit policy
-# gate, then the model-facing read/write/edit tools. stdio-agent is a single
-# session, so relative paths resolve from the process cwd (the workspace).
+# Policy loads before the model-facing filesystem tools so writes and edits require
+# an observed file. This single-session app resolves relative paths from the process cwd.
 - id: fs-local
  name: '@deepseek-ai/dsh-fs-local'
  config:
--- a/examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts
+++ b/examples/coding-agent/tests/code-mode-keyless-smoke.e2e.ts
@@ -1,99 +1,27 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'

 /**
- * Keyless Loader-path smoke for the Code Mode overlay: boot the REAL
- * example through the `@deepseek-ai/dsh-stdio-agent` bin against
- * `code-mode.cordis.yml` (the cordis Loader, `unwrapExports`, the include
- * patches over ./cordis.yml, the worker-thread code runtime, and the
- * registry in `mode: code`), then close stdin with no prompt and assert
- * the Code Mode banner + a clean exit.
- *
- * No prompt is ever sent, so the model is NEVER called and no `run_code`
- * turn happens — a dummy key lets `llm-deepseek`'s key-PRESENT check boot
- * the tree. This is the export-shape guard (postmortem 0001) for the Code
- * Mode composition; the with-key proof lives in `code-mode.e2e.ts`.
+ * Keyless Loader-path smoke for the Code Mode overlay: boot the real include
+ * tree through stdio-agent and `code-mode.cordis.yml`, then close stdin without
+ * a prompt and assert the banner. No model or `run_code` turn runs.
 */

-const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../code-mode.cordis.yml', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
-// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
-// the repo, so point it at the repo tsconfig.
-const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-// The real-API workflow runs up to 14 e2e files at once. Cold tsx/Loader
-// startup can therefore outlive a tight smoke-test deadline before the child
-// emits any output; 30s still detects a wedged process without confusing
-// bounded CI contention with a lifecycle failure.
-const PROCESS_TIMEOUT_MS = 30_000
-// Leave enough room for the process-owned timeout to report captured output
-// before Vitest aborts the test itself.
-const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
-
-let child: ChildProcessWithoutNullStreams | undefined
-let workdir: string | undefined
-
-afterEach(async () => {
-  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
-  child = undefined
-  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
-  workdir = undefined
-})
-
-async function bootAndEof(): Promise<{ stdout: string; code: number }> {
-  workdir = await mkdtemp(join(tmpdir(), 'code-mode-smoke-'))
-  const cwd = workdir
-  return new Promise((resolve, reject) => {
-    const proc = spawn(
-      process.execPath,
-      // --expose-internals: the included cordis.yml loads the HMR plugin (mirrors demo:code-mode).
-      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
-      {
-        cwd,
-        env: {
-          ...process.env,
-          TSX_TSCONFIG_PATH: repoTsconfig,
-          // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots.
-          // No prompt is sent, so the adapter never streams — no network call.
-          DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      },
-    )
-    child = proc
-    let stdout = ''
-    let stderr = ''
-    proc.stdout.setEncoding('utf8')
-    proc.stdout.on('data', (chunk: string) => { stdout += chunk })
-    proc.stderr.setEncoding('utf8')
-    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
-
-    const timer = setTimeout(() => {
-      proc.kill('SIGKILL')
-      reject(new Error(`code-mode overlay did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`))
-    }, PROCESS_TIMEOUT_MS)
-
-    proc.on('exit', (code) => {
-      clearTimeout(timer)
-      if (code === 0) resolve({ stdout, code })
-      else reject(new Error(`code-mode overlay exited ${code}. stderr:\n${stderr}`))
-    })
-    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
-
-    // No prompt — just EOF, so the stdio UI exits without ever running a turn.
-    proc.stdin.end()
-  })
-}
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

 describe('code-mode overlay keyless smoke (real code-mode.cordis.yml via the Loader)', () => {
  it('boots the Code Mode plugin tree, prints its banner, and exits cleanly on EOF', async () => {
-    const { stdout, code } = await bootAndEof()
-    expect(code).toBe(0)
+    const { stdout } = await runLoaderSmoke({
+      label: 'code-mode overlay',
+      tempDirPrefix: 'code-mode-smoke-',
+      binScript,
+      configPath,
+      tsconfigPath,
+      env: { DEEPSEEK_API_KEY: 'keyless-smoke-no-call' },
+    })
    expect(stdout).toContain('code-mode agent ready.')
-  }, TEST_TIMEOUT_MS)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })
--- a/examples/coding-agent/tests/code-mode.e2e.ts
+++ b/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,20 +14,19 @@ 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'

 /**
- * The Code Mode with-key proof (the RFC's e2e tier): a REAL model under
- * `mode: 'code'`, a task that requires composing two tool calls, verified
- * against the WORLD — the persisted request header carried exactly
- * `[run_code]` as the wire tool list, each sub-call landed as a
- * `tool/code-dispatch` event, the file the program wrote exists on disk, and
- * the final answer is the program's curated output. Key-gated (see
- * vitest.e2e.config.ts); the keyless Loader-path smoke of the overlay lives
- * in `code-mode-keyless-smoke.e2e.ts`.
+ * With-key Code Mode proof: a real model receives only `run_code`, composes two
+ * sub-calls, writes a file, and returns curated output while the log records
+ * each `tool/code-dispatch`. The keyless Loader smoke is in the sibling test.
 */

 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
@@ -57,6 +56,22 @@ async function codeModeHarness(cwd: string): Promise<Context> {
  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: ['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) => {
@@ -112,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: { 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)
 })
--- a/examples/coding-agent/tests/compaction.e2e.ts
+++ b/examples/coding-agent/tests/compaction.e2e.ts
@@ -7,25 +7,11 @@ import { AgentId } from '@deepseek-ai/dsh-agent'
 import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness.ts'

 /**
- * The compaction smoke test: a real model runs a multi-step bash task with a
- * deliberately tiny context window, so the auto-compaction listener fires
- * MID-SESSION and summarizes the older history into a checkpoint. This is the
- * first end-to-end exercise of the compaction seam (it is wired nowhere else),
- * and the runaway-survival regression net — it proves a session that grows past
- * the window keeps running rather than overflowing. Key-gated.
- *
- * Verifies the WORLD, not the agent's self-report: a compact/start…end pair
- * landed in the real session log, the surface actually shrank (a replace node
- * exists and shadowed older nodes), and the agent still produced a final answer
- * after compaction (so the summarized history did not break the conversation).
- *
- * FIXME(compaction-snapshot): this key-gated e2e is the ONLY coverage of runaway
- * compaction — there is no keyless full-transcript snapshot of it. dsh-llm-replay
- * reconstructs one model call per (turn, step) from `assistant/chunk` events, but
- * `summarize()` assembles its stream into a local BlockAssembler and appends no
- * `assistant/chunk`, so the interleaved summarization call is unreplayable. A
- * snapshot needs replay-harness work to serve that call; deferred as a follow-up.
+ * Key-gated smoke for mid-session compaction. It verifies the compact event
+ * pair, replacement of older surface nodes, and a final answer after compaction.
 */
+// FIXME(compaction-snapshot): this is the only full compaction coverage because
+// replay cannot serve the summarizer's unlogged model call.

 let workdir: string | undefined
 let ctx: Context | undefined
@@ -40,18 +26,11 @@ afterEach(async () => {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compacts mid-flight and keeps running', () => {
  it('summarizes older history into a checkpoint without breaking the task', async () => {
    workdir = await mkdtemp(join(tmpdir(), 'dsh-compaction-'))
-    // A handful of files for the model to read, so multiple bash steps
-    // accumulate surface nodes (tool calls + results) and grow the history past
-    // the (deliberately tiny) window.
    for (let i = 1; i <= 4; i++) {
      await writeFile(join(workdir, `file${i}.txt`), `This is file number ${i}. `.repeat(50))
    }

-    // Tiny window so a couple of steps crosses the threshold. The generation
-    // cap is deliberately larger than the final checkpoint because
-    // reasoning-capable APIs count reasoning tokens against the provider output
-    // budget even though those blocks are stripped before the checkpoint is
-    // stored.
+    // Reasoning tokens require a larger generation cap than the retained checkpoint.
    ctx = await codingHarness(workdir, {
      persona: SYSTEM_PROMPT,
      compact: {
--- a/examples/coding-agent/tests/harness.ts
+++ b/examples/coding-agent/tests/harness.ts
@@ -1,11 +1,7 @@
 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'
@@ -50,11 +46,9 @@ export interface CodingHarnessOptions {

 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(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
--- a/examples/coding-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/coding-agent/tests/keyless-smoke.e2e.ts
@@ -1,110 +1,28 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
-import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'

 /**
- * Keyless Loader-path smoke for examples/coding-agent: boot the REAL example
- * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` (the
- * cordis Loader, `unwrapExports`, the full plugin tree incl. the
- * `@deepseek-ai/dsh-agent-core` bundle and the app's in-package readline UI
- * module), then close stdin with no prompt and assert the
- * ready banner + a clean exit.
- *
- * No prompt is ever sent, so the model is NEVER called — this is why it runs
- * without a real key. coding-agent's `cordis.yml` loads `llm-deepseek`, whose
- * `apply()` only requires a key to be PRESENT (it does not validate it and only
- * uses it when a stream actually starts), so a dummy key lets the tree boot
- * while the absence of any prompt guarantees no network call. The value is the
- * real-Loader-path guard that the composed tree boots (see postmortem 0001;
- * the app carries no `inject`, so its export SHAPE is pinned by the stdio-agent
- * unit suite's unwrap assertion, not by a crash here),
- * complementing coding-agent's with-key e2e suites which prove the real
- * product.
+ * Keyless Loader-path smoke for examples/coding-agent: boot the real example
+ * through the stdio-agent bin and its `cordis.yml`, then close stdin without a
+ * prompt and assert the banner. The dummy key satisfies adapter construction;
+ * immediate EOF guarantees there is no model call.
 */

-// The dsh-stdio-agent bin (the demo:repl entry) and this example's cordis.yml.
-// The bin resolves its config-path arg from CWD; the test spawns from a temp
-// cwd, so we pass the example config's ABSOLUTE path.
-const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/stdio-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
-// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
-// the repo, so point it at the repo tsconfig (root is four levels up).
-const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
-// The real-API workflow runs up to 14 e2e files at once. Cold tsx/Loader
-// startup can therefore outlive a tight smoke-test deadline before the child
-// emits any output; 30s still detects a wedged process without confusing
-// bounded CI contention with a lifecycle failure.
-const PROCESS_TIMEOUT_MS = 30_000
-// Leave enough room for the process-owned timeout to report captured output
-// before Vitest aborts the test itself.
-const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000
-
-let child: ChildProcessWithoutNullStreams | undefined
-let workdir: string | undefined
-
-afterEach(async () => {
-  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
-  child = undefined
-  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
-  workdir = undefined
-})
-
-async function bootAndEof(): Promise<{ stdout: string; code: number }> {
-  workdir = await mkdtemp(join(tmpdir(), 'coding-smoke-'))
-  const cwd = workdir
-  return new Promise((resolve, reject) => {
-    const proc = spawn(
-      process.execPath,
-      // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:repl).
-      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
-      {
-        cwd,
-        env: {
-          ...process.env,
-          TSX_TSCONFIG_PATH: repoTsconfig,
-          // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots.
-          // No prompt is sent, so the adapter never streams — no network call.
-          DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
-          DSH_HOME: join(cwd, '.dsh'),
-          DSH_AGENTS_HOME: join(cwd, '.agents'),
-        },
-        stdio: ['pipe', 'pipe', 'pipe'],
-      },
-    )
-    child = proc
-    let stdout = ''
-    let stderr = ''
-    proc.stdout.setEncoding('utf8')
-    proc.stdout.on('data', (chunk: string) => { stdout += chunk })
-    proc.stderr.setEncoding('utf8')
-    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
-
-    const timer = setTimeout(() => {
-      proc.kill('SIGKILL')
-      reject(new Error(`coding-agent did not exit within ${PROCESS_TIMEOUT_MS / 1_000}s. stdout:\n${stdout}\nstderr:\n${stderr}`))
-    }, PROCESS_TIMEOUT_MS)
-
-    proc.on('exit', (code) => {
-      clearTimeout(timer)
-      if (code === 0) resolve({ stdout, code })
-      else reject(new Error(`coding-agent exited ${code}. stderr:\n${stderr}`))
-    })
-    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
-
-    // No prompt — just EOF, so the stdio UI exits without ever running a turn.
-    proc.stdin.end()
-  })
-}
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

 describe('coding-agent keyless smoke (real cordis.yml via the Loader)', () => {
  it('boots the full plugin tree, prints its banner, and exits cleanly on EOF', async () => {
-    const { stdout, code } = await bootAndEof()
-    expect(code).toBe(0)
+    const { stdout } = await runLoaderSmoke({
+      label: 'coding-agent',
+      tempDirPrefix: 'coding-smoke-',
+      binScript,
+      configPath,
+      tsconfigPath,
+      env: { DEEPSEEK_API_KEY: 'keyless-smoke-no-call' },
+    })
    expect(stdout).toContain('agent REPL ready.')
-  }, TEST_TIMEOUT_MS)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })