Merge remote-tracking branch 'origin/master' into codex/skill-system

# Conflicts:
#	docs/architecture.md
#	docs/config-catalog.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	examples/acp-agent/tests/snapshots/text-turn/session.jsonl
#	packages/core/agent-core/src/index.ts
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	packages/support/acp-snapshot/src/suite.ts
#	packages/ui/acp-agent/src/index.ts

examples/coding-agent/README.md

@@ -31,6 +31,21 @@ RESUME_SESSION_ID=<prior-session-id> pnpm run demo:repl
 
 The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent.
 
+## 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 model is then offered exactly ONE wire tool — `run_code` — plus a generated TypeScript SDK section declaring every other registered tool; it composes them by writing a program, each program tool call bridges back through the ordinary `tools/pre-execute`/`post-execute` pipeline one at a time and is logged as a `tool/code-dispatch` session event, and ONLY what the program prints or returns re-enters its context. (Flip the mode to `both` to offer native calls AND `run_code` side by side.)
+
+```sh
+pnpm run demo:code-mode        # this overlay under the REPL (default UI)
+pnpm run demo:code-mode acp    # the acp-agent example's same-shaped overlay
+```
+
+Try a task that spans several tool calls, e.g.:
+
+> Count the lines of every `*.md` file under docs/ and write the three largest to summary.txt.
+
+and watch the transcript: one `run_code` call, a program looping over tools, and a result the model curated instead of five round-trips of raw tool output.
+
 ## 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:
@@ -54,4 +69,4 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 - `tests/compaction.e2e.ts` — the compaction smoke: a real multi-step bash task runs with a deliberately tiny context window so the auto-compaction listener fires MID-SESSION. Verifies the WORLD — a `compact/start…end` pair landed in the real log, the surface shrank (a replace node shadowed older nodes), and the agent still produced a correct final answer after compaction.
 - `tests/todo-write.e2e.ts` — a real model drives the real `todo_write` tool and the test verifies the resulting `todo/write` session event.
 
-These self-skip without `DEEPSEEK_API_KEY`. The keyless boot smoke is `tests/keyless-smoke.e2e.ts` (boots the full real tree with a dummy key and no prompt, so no model call), which runs in the default e2e gate.
+These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless boot smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` (the full real tree, dummy key, no prompt → no model call) and `tests/code-mode-keyless-smoke.e2e.ts` (the same guard for the Code Mode overlay).

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

@@ -0,0 +1,33 @@
+# 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.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: stdio-agent
+        name: '@deepseek-ai/dsh-stdio-agent'
+        config:
+          model: deepseek-v4-flash
+          resumeSessionId: !!js process.env.RESUME_SESSION_ID
+          persistenceRoot: './.sessions'
+          tools:
+            mode: code
+          welcome: 'code-mode agent ready. Give it a multi-tool task.'
+          persona: |
+            You are coding-agent, a coding assistant powered by the {{model}} model.
+
+            You work by writing TypeScript programs for run_code: batch related
+            tool work into one program, loop and branch where it helps, and print
+            or return ONLY the findings that matter.
+      - insert:
+          - id: code-runtime
+            name: '@deepseek-ai/dsh-code-runtime-worker'

examples/coding-agent/composition.md

@@ -35,6 +35,10 @@ flowchart LR
   cfg --> plugin_coding_tool_subagent
   plugin_coding_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
   cfg --> plugin_coding_tool_subagent_fork
+  plugin_coding_workflow_workerthread["workflow-workerthread<br/>@deepseek-ai/dsh-workflow-workerthread"]
+  cfg --> plugin_coding_workflow_workerthread
+  plugin_coding_tool_workflow["tool-workflow<br/>@deepseek-ai/dsh-tool-workflow"]
+  cfg --> plugin_coding_tool_workflow
   plugin_coding_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
   cfg --> plugin_coding_tool_todo
   plugin_coding_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
@@ -57,6 +61,8 @@ flowchart LR
 | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
 | `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
 | `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` |
+| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` |
 | `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `fs-policy` | `@deepseek-ai/dsh-fs-policy` |

examples/coding-agent/cordis.yml

@@ -102,6 +102,18 @@
     provider: fork
     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.
+- id: workflow-workerthread
+  name: '@deepseek-ai/dsh-workflow-workerthread'
+  config:
+    provider: spawn
+
+- 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.
 - id: tool-todo

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

@@ -0,0 +1,91 @@
+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'
+
+/**
+ * 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`.
+ */
+
+const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/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))
+
+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 10s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 10_000)
+
+    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()
+  })
+}
+
+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)
+    expect(stdout).toContain('code-mode agent ready.')
+  }, 15_000)
+})

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

@@ -0,0 +1,115 @@
+import { mkdtemp, readFile, rm } 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 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'
+import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+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'
+
+/**
+ * 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`.
+ */
+
+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.'
+
+let ctx: Context | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  // Always dispose, even on failure/retry/timeout: agent-loop teardown stops
+  // the loop, the executor kills stray processes, and the code runtime's
+  // dispose awaits worker exits.
+  await ctx?.fiber.dispose()
+  ctx = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function codeModeHarness(cwd: string): 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(AgentLoop, { agents: [] })
+  await harness.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
+  await harness.plugin(LocalBashExecutor, { cwd, timeoutMs: 30_000 })
+  await harness.plugin(ToolBash)
+  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) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('Code Mode: real model writes a program over real tools', () => {
+  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' })
+
+    agent.send([{
+      type: 'text',
+      text: 'Using one run_code program: run `echo alpha-7` with the bash tool, run `echo beta-9` with the bash tool, '
+        + 'then write both outputs joined by a plus sign into combined.txt (bash heredoc or redirect), '
+        + 'and return only the joined string.',
+    }])
+    await waitForIdle(ctx, agent)
+    const events: SessionEvent[] = [...agent.session.events]
+
+    // The wire contract: every request this session made offered EXACTLY ONE
+    // tool — run_code (the logged header snapshots the assembled list).
+    const headers = events.filter(event => event.type === 'request/header')
+    expect(headers.length).toBeGreaterThan(0)
+    for (const header of headers) {
+      expect(header.data.header.tools?.map(tool => tool.name)).toEqual([RUN_CODE_NAME])
+    }
+    // The model actually went through run_code…
+    const calls = events.filter(event => event.type === 'tool/call')
+    expect(calls.length).toBeGreaterThan(0)
+    expect(calls.every(event => event.data.name === RUN_CODE_NAME)).toBe(true)
+    // …and the program's tool calls landed as dispatch events under it.
+    const dispatches = events.filter(event => event.type === 'tool/code-dispatch')
+    expect(dispatches.length).toBeGreaterThanOrEqual(2)
+    expect(dispatches.every(event => event.data.name === 'bash')).toBe(true)
+    const parents = new Set(calls.map(event => event.data.callId))
+    expect(dispatches.every(event => parents.has(event.data.parentCallId))).toBe(true)
+
+    // World verification: the file the program wrote, and the curated answer.
+    const combined = await readFile(join(workdir, 'combined.txt'), 'utf8')
+    expect(combined).toContain('alpha-7')
+    expect(combined).toContain('beta-9')
+    const finalMessage = events.findLast(event => event.type === 'assistant/message')
+    const finalText = finalMessage !== undefined
+      ? finalMessage.data.content.filter(block => block.type === 'text').map(block => block.text).join('')
+      : ''
+    expect(finalText).toContain('alpha-7')
+    expect(finalText).toContain('beta-9')
+  }, 180_000)
+})