Merge remote-tracking branch 'origin/master' into codex/rfc-subagent-background-tasks

# Conflicts: # docs/config-catalog.md # docs/module-graph.md # examples/coding-agent/README.md # examples/coding-agent/cordis.yml # packages/README.md # packages/examples/acp-demo/README.md # packages/examples/agent-spine-demo/README.md # packages/examples/agent-spine-demo/package.json # packages/examples/agent-spine-demo/src/index.ts # packages/examples/stdio-demo/README.md # pnpm-lock.yaml # scripts/doc-budgets.manifest.json # scripts/verify-package-readme-model-experience.ts
2026-07-15 16:57:03 +08:00
parent 4f92ede4a0 5ee9217146
commit 306b79fa2c
153 changed files with 3991 additions and 602 deletions
@@ -54,7 +54,7 @@ pnpm run test:snapshot
 Run built-bin smoke tests after `pnpm run build` when app packages, app boot, package runtime imports, bin entries, loader behavior, or published artifact paths change.

 ```sh
-pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts
+pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts
 ```

 Run real e2e when behavior depends on a real model/API, tool-use loop, ACP integration, prompt injection, or end-to-end agent UX. If `.env` is available, use it; do not print secrets.
@@ -0,0 +1,8 @@
+# Editor-side declaration of the repo's text conventions. Pairs with
+# .gitattributes: that file pins what GIT produces (LF checkouts), this one
+# pins what EDITORS write to disk — the one path git's filters cannot reach.
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
@@ -0,0 +1,7 @@
+# The repo's canonical text form is LF, enforced at checkout too: no smudge
+# boundary between working tree and repo, so byte-level gates (verify-*
+# comparisons, blob hashing, coverage offsets) see one form on every host.
+# If a file class ever genuinely needs CRLF in the working tree (.bat/.cmd
+# for cmd.exe), add a `*.bat text eol=crlf` override AFTER this line — the
+# in-repo form stays LF; CRLF becomes checkout-time presentation only.
+* text=auto eol=lf
@@ -160,6 +160,29 @@ jobs:
      - name: Run complete keyless Python suite
        run: uv run --python 3.10 --group test --project python/sdk pytest

+  # Windows build lane: install + `pnpm run build` (tsc -b + tsdown) on native
+  # Windows. Windows path/shell support is still partial, so this lane covers
+  # the build surface only — tests and gates are not run here yet. Wired into
+  # all-checks-passed so a native-Windows build regression cannot land silently.
+  windows-build:
+    runs-on: windows-2025
+    name: windows / build
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+      - name: Enable corepack (pnpm)
+        run: corepack enable
+
+      - name: Install (immutable)
+        run: pnpm install --frozen-lockfile
+
+      - name: Build (tsc -b + tsdown)
+        run: pnpm run build
+
  # Single stable required check for branch protection: require "all checks
  # passed" instead of enumerating matrix legs whose names change as lanes and
  # node versions evolve. Every other job in THIS workflow must be listed in
@@ -171,7 +194,7 @@ jobs:
  all-checks-passed:
    name: all checks passed
    runs-on: ubuntu-latest
-    needs: [node-24, node-compat, python-sdk]
+    needs: [node-24, node-compat, python-sdk, windows-build]
    if: always()
    steps:
      - name: Fail if any needed job did not succeed
@@ -11,7 +11,7 @@ DeepSeek Harness SDK is a plugin-based agent harness on vendored Cordis: **every
 ```
 vendor/      Vendored Cordis source — manifest + sync procedure in vendor/README.md
 packages/    Harness packages at packages/<group>/<pkg>/, all named @deepseek-ai/dsh-<pkg>
-  core/        product API spine: session, system-prompt, tools, agent, agent-loop, agent-core (the bundle)
+  core/        product API spine: session, system-prompt, tools, agent, agent-loop
  llm/         LLM seam + the DeepSeek adapters (hand-rolled + pi-ai design twin)
  bash/        bash executor seam + local impl + model-facing bash tools
  fs/          filesystem seam + local impl + policy gate + read/write/edit tools
@@ -26,11 +26,12 @@ packages/    Harness packages at packages/<group>/<pkg>/, all named @deepseek-ai
  cordis/      self-referential toolset: the agent inspects/mounts plugins in its own runtime
  hooks/       Claude Code / Codex hook bridges + shared wire-protocol library
  session-persistence/  persistence seam + JSONL/SQLite backends
-  ui/          ACP/stdio/JSON-RPC front doors; boot, approval, and interaction plugins
+  ui/          ACP/stdio/JSON-RPC bridges; boot, approval, interaction plugins
+  examples/    demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) leaves load
  support/     dev/test infrastructure packages
  util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
-examples/    Runnable demos: thin cordis.yml leaves over the app packages (see examples/AGENTS.md)
+examples/    Runnable cordis.yml leaves over packages/examples bundles (see examples/AGENTS.md)
 docs/        architecture, generated catalogs, RFCs, postmortems, cookbook (see docs/AGENTS.md)
 scripts/     repo gates and generators
 ```
@@ -78,7 +79,7 @@ printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})'
 printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE'
 test -n "$(find .sessions -path '.sessions/cwd-*/main-session-*.jsonl' -type f -print -quit)"
 rm -rf .sessions
-pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
+pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
 ```

 `test:coverage`, not `test`, is the gate ([why](docs/testing.md)); report only commands actually run.
@@ -139,7 +139,7 @@ Some seams bend the template deliberately. LLM keeps interface and consumer voca

 ### Bundles And Apps

-`dsh-agent-core` is the default composition bundle: one plugin loading the shared spine ([README](../packages/core/agent-core/README.md)). App packages compose it with a front door and boot `bin`: `dsh-stdio-agent` for terminal REPL, and `dsh-acp-agent` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` instead boots an external `cordis.yml`; the Python SDK injects the package default only when no explicit config channel is set and drives `dsh-jsonrpc` over line-delimited stdio JSON-RPC ([Python SDK](../python/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` is the default composition bundle: one plugin loading the shared spine ([README](../packages/examples/agent-spine-demo/README.md)). App packages compose it with a front door and boot `bin`: `dsh-stdio-demo` for terminal REPL, and `dsh-acp-demo` for ACP over JSON-RPC stdio with no stdout logger ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` instead boots an external `cordis.yml`; the Python SDK injects the package default only when no explicit config channel is set and drives `dsh-jsonrpc` over line-delimited stdio JSON-RPC ([Python SDK](../python/README.md)). A deployment is a thin `cordis.yml` leaf: swappable backends, one app entry, and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).

 ### Where New Behavior Goes

@@ -40,13 +40,13 @@ flowchart LR
  pkg_tool_todo["tool-todo"]
  pkg_user_interaction["user-interaction"]
  svc_userInteraction["ctx.userInteraction<br/>Human question/answer seam"]
-  pkg_stdio_agent["stdio-agent"]
+  pkg_stdio_demo["stdio-demo"]
  pkg_skill["skill"]
  svc_skills["ctx.skills<br/>Skill provider registry"]
  pkg_skill_local["skill-local"]
  svc_agents["ctx.agents<br/>Agent registry"]
  svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
-  pkg_agent_core["agent-core"]
+  pkg_agent_spine_demo["agent-spine-demo"]
  pkg_bash["bash"]
  svc_bash["ctx.bash<br/>Bash executor seam"]
  pkg_bash_local["bash-local"]
@@ -116,7 +116,7 @@ flowchart LR
  pkg_session_query --> svc_sessionQuery
  pkg_skill --> svc_skills
  pkg_skill_local --> svc_skills
-  pkg_stdio_agent --> svc_userInteraction
+  pkg_stdio_demo --> svc_userInteraction
  pkg_subagent --> svc_subagents
  pkg_subagent_acp --> svc_subagents
  pkg_subagent_fork --> svc_subagents
@@ -133,11 +133,11 @@ flowchart LR
  pkg_web_search_perplexity --> svc_web
  pkg_workflow --> svc_workflows
  pkg_workflow_workerthread --> svc_workflows
-  svc_agentLoop --> pkg_agent_core
+  svc_agentLoop --> pkg_agent_spine_demo
  svc_agents --> pkg_acp
  svc_agents --> pkg_agent_loop
  svc_agents --> pkg_invariants
-  svc_agents --> pkg_stdio_agent
+  svc_agents --> pkg_stdio_demo
  svc_agents --> pkg_subagent_inprocess
  svc_approval --> pkg_tool_bash
  svc_approval --> pkg_tools
@@ -180,7 +180,7 @@ flowchart LR
  svc_tools --> pkg_tool_todo
  svc_tools --> pkg_tool_web
  svc_userInteraction --> pkg_acp
-  svc_userInteraction --> pkg_stdio_agent
+  svc_userInteraction --> pkg_stdio_demo
  svc_userInteraction --> pkg_tool_ask_user
  svc_web --> pkg_tool_web
  svc_workflows --> pkg_tool_workflow
@@ -195,10 +195,10 @@ flowchart LR
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | - | - | Resolves live and optional persisted logs into one logical corpus for exact reads. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
-| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-agent`](../packages/ui/stdio-agent), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
+| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
-| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-demo`](../packages/examples/stdio-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. |
+| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
 | `ctx.sandbox` | `seam` | [`sandbox`](../packages/sandbox/sandbox) | [`sandbox-local`](../packages/sandbox/sandbox-local) | [`bash-sandbox`](../packages/bash/bash-sandbox) | - | Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement. |
 | `ctx.approval` | `seam` | `approval` | [`acp`](../packages/ui/acp) | [`tools`](../packages/core/tools), [`tool-bash`](../packages/bash/tool-bash) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
@@ -27,7 +27,7 @@ Depends on: `Stream` (`@agentclientprotocol/sdk`)

 Source: [`packages/ui/acp/src/index.ts:203`](../packages/ui/acp/src/index.ts)

-## `@deepseek-ai/dsh-acp-agent`
+## `@deepseek-ai/dsh-acp-demo`

 ```ts config-catalog
 /**
@@ -37,7 +37,7 @@ Source: [`packages/ui/acp/src/index.ts:203`](../packages/ui/acp/src/index.ts)
 * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
 * the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * `tools` is the tool registry's config (its presentation `mode`, forwarded
- * through agent-core); `persistenceRoot` is the JSONL backend's directory.
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
 */
 export interface Config {
  /** Model name for ACP-created agents (must have a registered adapter). */
@@ -46,11 +46,11 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /** Model-facing bash tool config forwarded through agent-core. */
  toolBash?: NonNullable<agentCore.Config['toolBash']>
@@ -59,11 +59,34 @@ export interface Config {
 }
 ```

-Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)

-Source: [`packages/ui/acp-agent/src/index.ts:31`](../packages/ui/acp-agent/src/index.ts)
+Source: [`packages/examples/acp-demo/src/index.ts:31`](../packages/examples/acp-demo/src/index.ts)

-## `@deepseek-ai/dsh-agent-core`
+## `@deepseek-ai/dsh-agent-loop`
+
+Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
+
+```ts config-catalog
+/** Plugin configuration for declarative startup agents. */
+export interface Config {
+  /** Agents created or resumed at plugin startup. */
+  agents: (AgentOptions & {
+    /** Registry identity for the live agent. */
+    id: AgentId
+    /** Optional workspace for a fresh session. */
+    cwd?: string
+    /** Persisted session to resume instead of creating a fresh session. */
+    resumeSessionId?: SessionId
+  })[]
+}
+```
+
+Depends on: [`AgentId`](../packages/core/agent/src/index.ts) · [`AgentOptions`](../packages/core/agent/src/index.ts) · [`SessionId`](../packages/core/session/src/index.ts)
+
+Source: [`packages/core/agent-loop/src/index.ts:322`](../packages/core/agent-loop/src/index.ts)
+
+## `@deepseek-ai/dsh-agent-spine-demo`

 ```ts config-catalog
 /**
@@ -111,30 +134,7 @@ export interface SkillConfig {

 Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts)

-Source: [`packages/core/agent-core/src/index.ts:90`](../packages/core/agent-core/src/index.ts)
-
-## `@deepseek-ai/dsh-agent-loop`
-
-Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
-
-```ts config-catalog
-/** Plugin configuration for declarative startup agents. */
-export interface Config {
-  /** Agents created or resumed at plugin startup. */
-  agents: (AgentOptions & {
-    /** Registry identity for the live agent. */
-    id: AgentId
-    /** Optional workspace for a fresh session. */
-    cwd?: string
-    /** Persisted session to resume instead of creating a fresh session. */
-    resumeSessionId?: SessionId
-  })[]
-}
-```
-
-Depends on: [`AgentId`](../packages/core/agent/src/index.ts) · [`AgentOptions`](../packages/core/agent/src/index.ts) · [`SessionId`](../packages/core/session/src/index.ts)
-
-Source: [`packages/core/agent-loop/src/index.ts:322`](../packages/core/agent-loop/src/index.ts)
+Source: [`packages/examples/agent-spine-demo/src/index.ts:55`](../packages/examples/agent-spine-demo/src/index.ts)

 ## `@deepseek-ai/dsh-bash-local`

@@ -433,6 +433,57 @@ export interface Config {

 Source: [`packages/support/llm-replay/src/index.ts:306`](../packages/support/llm-replay/src/index.ts)

+## `@deepseek-ai/dsh-mcp-client`
+
+Requires: `tools`
+
+```ts config-catalog
+/** Discriminated union of all supported MCP transport configurations. */
+export type Config = StdioConfig | StreamableHttpConfig
+
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+  /** Transport type: spawn a child process and communicate over stdio. */
+  transport: 'stdio'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** Executable to spawn. */
+  command: string
+  /** Arguments passed to the command. */
+  args: string[]
+  /** Extra env vars merged on top of scrubbed ambient env. */
+  env: Record<string, string>
+  /** Working directory for the child process. */
+  cwd: string
+  /** Timeout per callTool invocation (ms). */
+  toolCallTimeoutMs: number
+}
+
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+  /** Transport type: connect to an MCP server over Streamable HTTP (SSE). */
+  transport: 'streamable-http'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** MCP server URL. */
+  url: string
+  /** Extra headers (e.g. auth tokens). */
+  headers: Record<string, string>
+  /** Timeout per callTool invocation (ms). */
+  toolCallTimeoutMs: number
+}
+```
+
+Source: [`packages/mcp/mcp-client/src/index.ts:91`](../packages/mcp/mcp-client/src/index.ts)
+
 ## `@deepseek-ai/dsh-permission`

 Requires: `bash` · `approval`
@@ -638,13 +689,13 @@ export interface Config {

 Source: [`packages/ui/stdio/src/index.ts:30`](../packages/ui/stdio/src/index.ts)

-## `@deepseek-ai/dsh-stdio-agent`
+## `@deepseek-ai/dsh-stdio-demo`

 ```ts config-catalog
 /**
 * App config: the swappable per-demo values, each routed to where the app wires
 * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
- * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
+ * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
@@ -658,13 +709,13 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /** Model-facing bash tool config forwarded through agent-core. */
  toolBash?: NonNullable<agentCore.Config['toolBash']>
@@ -679,9 +730,9 @@ export interface Config {
 }
 ```

-Depends on: [`agentCore`](../packages/core/agent-core/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)

-Source: [`packages/ui/stdio-agent/src/index.ts:36`](../packages/ui/stdio-agent/src/index.ts)
+Source: [`packages/examples/stdio-demo/src/index.ts:36`](../packages/examples/stdio-demo/src/index.ts)

 ## `@deepseek-ai/dsh-subagent-acp`

@@ -1252,7 +1303,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))
- `@deepseek-ai/dsh-jsonrpc-agent` ([`packages/ui/jsonrpc-agent/src/index.ts`](../packages/ui/jsonrpc-agent/src/index.ts))
+- `@deepseek-ai/dsh-jsonrpc-demo` ([`packages/examples/jsonrpc-demo/src/index.ts`](../packages/examples/jsonrpc-demo/src/index.ts))
 - `@deepseek-ai/dsh-loader-smoke` ([`packages/support/loader-smoke/src/index.ts`](../packages/support/loader-smoke/src/index.ts))
 - `@deepseek-ai/dsh-scope` ([`packages/core/scope/src/index.ts`](../packages/core/scope/src/index.ts))
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-extension-cookbook.md: 40ee22b352c884d7f295c87726c54ab8e166c844
-extension-cookbook.zh.md: 4e5bc68c973649574bcb2404bea00096eb9ca41f
+extension-cookbook.md: 3474bc116b43f9be57b52e947f9cf99730f7e796
+extension-cookbook.zh.md: 1a605b20fe4e171a948ac2a046193a2f4d884e44
@@ -87,7 +87,7 @@ export function apply(ctx: Context) {

 ## Runnable wirings

-Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite behind a terminal REPL UI, `pnpm run demo:repl`), and [`examples/acp-agent`](../../examples/acp-agent) (an agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent), the ACP demo loads [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle.
+Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite behind a terminal REPL UI, `pnpm run demo:repl`), and [`examples/acp-agent`](../../examples/acp-agent) (an agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the ACP demo loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle.

 ## The feature → mechanism map

@@ -87,7 +87,7 @@ export function apply(ctx: Context) {

 ## 可运行的组装示例

-三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app 包入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent)，ACP 演示加载 [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent)，两个 app 包通过 [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle 共享主干。
+三个完整示例从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具——全 mock 骨架检查，`pnpm run demo:echo`）、[`examples/coding-agent`](../../examples/coding-agent)（DeepSeek V4 + bash 工具套件，配合终端 REPL UI，`pnpm run demo:repl`）、[`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露为 ACP 服务器的 agent——客户端驱动形态，`pnpm run demo:acp`）。每个叶子只是其可替换后端加一个 app 包入口：stdio 演示加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，ACP 演示加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，两个 app 包通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) bundle 共享主干。

 ## 功能→机制映射

@@ -1,6 +1,6 @@
 # User Interaction

-The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-agent` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations.
+The user-interaction seam of [dsh-user-interaction](../../packages/ui/user-interaction). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. UI surfaces provide the active `UserInteractionProvider`: `dsh-stdio-demo` renders questions in readline, and `dsh-acp` maps them to ACP form elicitations.

 Source: [`packages/ui/user-interaction/src/index.ts`](../../packages/ui/user-interaction/src/index.ts)

@@ -10,9 +10,9 @@

 本文介绍 DeepSeek Harness 整体架构，它是 **DeepSeek Code** 的底层基座。微内核设计讨论中确立了核心设计准则：**一切皆插件**。内核刻意做得极精简，仅包含少量抽象服务，外加一个实体循环插件 `dsh-agent-loop`。所有产品功能均基于本文定义的扩展接口开发为独立插件，无需改动主循环逻辑。

-> Dependency rule: extension plugins depend on interfaces, never on `dsh-agent-loop` (the loop is swappable); the sanctioned exception is the composition bundle `dsh-agent-core`, whose job is assembling the concrete spine.
+> Dependency rule: extension plugins depend on interfaces, never on `dsh-agent-loop` (the loop is swappable); the sanctioned exception is the composition bundle `dsh-agent-spine-demo`, whose job is assembling the concrete spine.

-依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-core`，它的职责是组装整套实体主干。
+依赖约束规范：各类扩展插件仅依赖抽象接口，严禁直接依赖 `dsh-agent-loop`（该主循环支持替换实现）；唯一允许的特例是组合包 `dsh-agent-spine-demo`，它的职责是组装整套实体主干。

 > This document covers **behavior**; type shapes live in [core-data-structures/](../core-data-structures/core.md), the per-event/service reference in the [generated catalog](../cordis-catalog/events.md), per-package contracts in the package READMEs ([map](../../packages/README.md)).

@@ -18,7 +18,6 @@ flowchart TD
  end
  subgraph group_core["packages/core"]
    pkg_agent["agent"]
-    pkg_agent_core["agent-core"]
    pkg_agent_loop["agent-loop"]
    pkg_scope["scope"]
    pkg_session["session"]
@@ -94,13 +93,10 @@ flowchart TD
  end
  subgraph group_ui["packages/ui"]
    pkg_acp["acp"]
-    pkg_acp_agent["acp-agent"]
    pkg_app_boot["app-boot"]
    pkg_jsonrpc["jsonrpc"]
-    pkg_jsonrpc_agent["jsonrpc-agent"]
    pkg_permission["permission"]
    pkg_stdio["stdio"]
-    pkg_stdio_agent["stdio-agent"]
    pkg_tool_ask_user["tool-ask-user"]
    pkg_user_approval["user-approval"]
    pkg_user_interaction["user-interaction"]
@@ -112,9 +108,18 @@ flowchart TD
  subgraph group_context["packages/context"]
    pkg_time_context["time-context"]
  end
+  subgraph group_examples["packages/examples"]
+    pkg_acp_demo["acp-demo"]
+    pkg_agent_spine_demo["agent-spine-demo"]
+    pkg_jsonrpc_demo["jsonrpc-demo"]
+    pkg_stdio_demo["stdio-demo"]
+  end
  subgraph group_guard["packages/guard"]
    pkg_repeat_tool_guard["repeat-tool-guard"]
  end
+  subgraph group_mcp["packages/mcp"]
+    pkg_mcp_client["mcp-client"]
+  end
  subgraph group_sandbox["packages/sandbox"]
    pkg_sandbox["sandbox"]
    pkg_sandbox_local["sandbox-local"]
@@ -278,6 +283,8 @@ flowchart TD
  pkg_tool_ask_user --> pkg_user_interaction
  pkg_repeat_tool_guard --> pkg_agent
  pkg_repeat_tool_guard --> pkg_tools
+  pkg_mcp_client --> pkg_llm
+  pkg_mcp_client --> pkg_tools
  pkg_tool_tasks --> pkg_agent
  pkg_tool_tasks --> pkg_system_prompt
  pkg_tool_tasks --> pkg_tasks
@@ -287,19 +294,6 @@ flowchart TD
  pkg_tool_workflow --> pkg_system_prompt
  pkg_tool_workflow --> pkg_tools
  pkg_tool_workflow --> pkg_workflow
-  pkg_agent_core --> pkg_agent
-  pkg_agent_core --> pkg_agent_loop
-  pkg_agent_core --> pkg_invariants
-  pkg_agent_core --> pkg_llm
-  pkg_agent_core --> pkg_session
-  pkg_agent_core --> pkg_skill
-  pkg_agent_core --> pkg_skill_local
-  pkg_agent_core --> pkg_system_prompt
-  pkg_agent_core --> pkg_tasks
-  pkg_agent_core --> pkg_tool_bash
-  pkg_agent_core --> pkg_tool_skill
-  pkg_agent_core --> pkg_tool_tasks
-  pkg_agent_core --> pkg_tools
  pkg_subagent_acp --> pkg_agent
  pkg_subagent_acp --> pkg_llm
  pkg_subagent_acp --> pkg_subagent
@@ -329,6 +323,19 @@ flowchart TD
  pkg_jsonrpc --> pkg_llm_deepseek
  pkg_jsonrpc --> pkg_session
  pkg_jsonrpc --> pkg_subagent
+  pkg_agent_spine_demo --> pkg_agent
+  pkg_agent_spine_demo --> pkg_agent_loop
+  pkg_agent_spine_demo --> pkg_invariants
+  pkg_agent_spine_demo --> pkg_llm
+  pkg_agent_spine_demo --> pkg_session
+  pkg_agent_spine_demo --> pkg_skill
+  pkg_agent_spine_demo --> pkg_skill_local
+  pkg_agent_spine_demo --> pkg_system_prompt
+  pkg_agent_spine_demo --> pkg_tasks
+  pkg_agent_spine_demo --> pkg_tool_bash
+  pkg_agent_spine_demo --> pkg_tool_skill
+  pkg_agent_spine_demo --> pkg_tool_tasks
+  pkg_agent_spine_demo --> pkg_tools
  pkg_workflow_workerthread --> pkg_agent
  pkg_workflow_workerthread --> pkg_brand
  pkg_workflow_workerthread --> pkg_llm
@@ -342,22 +349,22 @@ flowchart TD
  pkg_subagent_fork --> pkg_subagent_inprocess
  pkg_subagent_spawn --> pkg_subagent
  pkg_subagent_spawn --> pkg_subagent_inprocess
-  pkg_acp_agent --> pkg_acp
-  pkg_acp_agent --> pkg_agent_core
-  pkg_acp_agent --> pkg_app_boot
-  pkg_acp_agent --> pkg_session_persistence_jsonl
-  pkg_acp_agent --> pkg_tools
-  pkg_acp_agent --> pkg_user_interaction
-  pkg_stdio_agent --> pkg_agent
-  pkg_stdio_agent --> pkg_agent_core
-  pkg_stdio_agent --> pkg_app_boot
-  pkg_stdio_agent --> pkg_llm
-  pkg_stdio_agent --> pkg_session
-  pkg_stdio_agent --> pkg_session_persistence_jsonl
-  pkg_stdio_agent --> pkg_stdio
-  pkg_stdio_agent --> pkg_tool_ask_user
-  pkg_stdio_agent --> pkg_tools
-  pkg_stdio_agent --> pkg_user_interaction
+  pkg_acp_demo --> pkg_acp
+  pkg_acp_demo --> pkg_agent_spine_demo
+  pkg_acp_demo --> pkg_app_boot
+  pkg_acp_demo --> pkg_session_persistence_jsonl
+  pkg_acp_demo --> pkg_tools
+  pkg_acp_demo --> pkg_user_interaction
+  pkg_stdio_demo --> pkg_agent
+  pkg_stdio_demo --> pkg_agent_spine_demo
+  pkg_stdio_demo --> pkg_app_boot
+  pkg_stdio_demo --> pkg_llm
+  pkg_stdio_demo --> pkg_session
+  pkg_stdio_demo --> pkg_session_persistence_jsonl
+  pkg_stdio_demo --> pkg_stdio
+  pkg_stdio_demo --> pkg_tool_ask_user
+  pkg_stdio_demo --> pkg_tools
+  pkg_stdio_demo --> pkg_user_interaction
 ```

 | Package | Group | Depends on |
@@ -370,8 +377,8 @@ flowchart TD
 | [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | — |
 | [`app-boot`](../packages/ui/app-boot) | `ui` | — |
-| [`jsonrpc-agent`](../packages/ui/jsonrpc-agent) | `ui` | — |
 | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — |
+| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | — |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
 | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm) |
@@ -423,17 +430,18 @@ flowchart TD
 | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
 | [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
 | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
+| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
 | [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`agent-core`](../packages/core/agent-core) | `core` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools) |
 | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
 | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
 | [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
 | [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
 | [`subagent-mock`](../packages/support/subagent-mock) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent) |
 | [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools) |
 | [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`acp-agent`](../packages/ui/acp-agent) | `ui` | [`acp`](../packages/ui/acp), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`stdio-agent`](../packages/ui/stdio-agent) | `ui` | [`agent`](../packages/core/agent), [`agent-core`](../packages/core/agent-core), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`stdio-demo`](../packages/examples/stdio-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
@@ -70,6 +70,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [The approval seam — one-shot permission decisions over a waterfall of answerers](implemented/feature/2026-07-06-approval-seam.md) | 2026-07-06 |
 | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 |
 | [The subprocess sandbox — confinement seam, native runners, escalation, and per-session modes](implemented/feature/2026-07-06-sandbox.md) | 2026-07-06 |
+| [MCP client plugin — connect to external MCP servers and bridge their tools](implemented/feature/2026-07-07-mcp-client-plugin.md) | 2026-07-07 |
 | [The session prefix — request-only messages in front of the derived history](implemented/feature/2026-07-07-session-prefix.md) | 2026-07-07 |
 | [Background subagent tasks](implemented/feature/2026-07-08-background-subagent-tasks.md) | 2026-07-08 |
 | [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 |
@@ -12,18 +12,18 @@ The leaf configs also owned a coupled front door. ACP requires stdout purity and

 Each example is now **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root).

- **`@deepseek-ai/dsh-agent-core`** ([packages/core/agent-core](../../../../packages/core/agent-core)) composes the providerless, executor-less, UI-less spine and forwards the loop's agent-list config. Its dependency on the concrete loop is intentional because this package composes the spine rather than extending it; swapping the loop means supplying another bundle.
- **`@deepseek-ai/dsh-stdio-agent`** ([packages/ui/stdio-agent](../../../../packages/ui/stdio-agent)) and **`@deepseek-ai/dsh-acp-agent`** ([packages/ui/acp-agent](../../../../packages/ui/acp-agent)) bake in their front doors. Stdio includes `ui-stdio`, a console logger, and `main`; ACP includes the bridge and JSONL persistence but no stdout logger or pre-created agent. Leaves may add plugins, but the safe composition is now the default artifact.
- **`start.ts` is gone.** Each app package exposes a `bin` (`dsh-stdio-agent` / `dsh-acp-agent`); the `demo:*` scripts invoke it (e.g. `dsh-stdio-agent ./cordis.yml`). The Loader-boot tail, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); each bin is a thin self-executing composition over those helpers plus its app-specific lifecycle (the ACP bin: snapshot-mode selection and stdin-dispose). The `bin.ts` files themselves stay coverage-excluded (self-executing CLI entries, like the old `start.ts`) and are driven by the keyless Loader-path tests.
+- **`@deepseek-ai/dsh-agent-spine-demo`** ([packages/examples/agent-spine-demo](../../../../packages/examples/agent-spine-demo)) composes the providerless, executor-less, UI-less spine and forwards the loop's agent-list config. Its dependency on the concrete loop is intentional because this package composes the spine rather than extending it; swapping the loop means supplying another bundle.
+- **`@deepseek-ai/dsh-stdio-demo`** ([packages/examples/stdio-demo](../../../../packages/examples/stdio-demo)) and **`@deepseek-ai/dsh-acp-demo`** ([packages/examples/acp-demo](../../../../packages/examples/acp-demo)) bake in their front doors. Stdio includes `ui-stdio`, a console logger, and `main`; ACP includes the bridge and JSONL persistence but no stdout logger or pre-created agent. Leaves may add plugins, but the safe composition is now the default artifact.
+- **`start.ts` is gone.** Each app package exposes a `bin` (`dsh-stdio-demo` / `dsh-acp-demo`); the `demo:*` scripts invoke it (e.g. `dsh-stdio-demo ./cordis.yml`). The Loader-boot tail, `.env` loading, and fail-loud guards live in the shared [`@deepseek-ai/dsh-app-boot`](../../../../packages/ui/app-boot) package (unit-tested under the per-file coverage gate — see [share the app bins' boot glue](../simplification/2026-07-04-share-app-bin-boot-glue.md)); each bin is a thin self-executing composition over those helpers plus its app-specific lifecycle (the ACP bin: snapshot-mode selection and stdin-dispose). The `bin.ts` files themselves stay coverage-excluded (self-executing CLI entries, like the old `start.ts`) and are driven by the keyless Loader-path tests.
 - **Each leaf `cordis.yml` collapses** to backends + config: the LLM adapter (`llm-deepseek` with apiKey/models, or `llm-replay`), the bash executor (`bash-local`), `hmr` for the stdio demos (see the amendment below), and one app entry carrying the app's config (model, system prompt, persistence root — surfaced as the app package's own `Config`, which routes each value to wherever the app wires it: stdio onto its pre-created agent, acp onto the bridge plugin).
- **echo-agent folds onto `dsh-stdio-agent`**, swapping the LLM backend to the local `mock-llm` and adding the local `echo-tool` (plus `bash-local`, which the spine's `tool-bash` injects) at the leaf — the clean demonstration of "swap the backend, keep the app". `mock-llm.ts` / `echo-tool.ts` stay as example-local teaching plugins.
- **`base.yml`, `base-core.yml`, and `acp-agent/acp-tail.yml` are retired** — the spine they shared now lives in `dsh-agent-core`.
+- **echo-agent folds onto `dsh-stdio-demo`**, swapping the LLM backend to the local `mock-llm` and adding the local `echo-tool` (plus `bash-local`, which the spine's `tool-bash` injects) at the leaf — the clean demonstration of "swap the backend, keep the app". `mock-llm.ts` / `echo-tool.ts` stay as example-local teaching plugins.
+- **`base.yml`, `base-core.yml`, and `acp-agent/acp-tail.yml` are retired** — the spine they shared now lives in `dsh-agent-spine-demo`.

 `bash-local` and the LLM adapter stay **leaf choices**: the bundle ships `tool-bash` (the consumer schema), the leaf picks the executor implementation, so a sandboxed executor or replay adapter swaps in without touching the app.

 ### Amendment on implementation: `hmr` stays a leaf entry

-The proposal listed `hmr` among the stdio app's baked-in front-door cluster. Validating against the code, baking `hmr` into the `dsh-stdio-agent` package fights cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead:
+The proposal listed `hmr` among the stdio app's baked-in front-door cluster. Validating against the code, baking `hmr` into the `dsh-stdio-demo` package fights cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead:

 1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader` service, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier.
 2. The in-process test tier (vitest) cannot even *import* the vendored `hmr` module (its class-decorator `@Inject` form fails under Vite's transform), so a package whose `apply` statically imported it could never satisfy the per-file 100% coverage gate on its headline function.
@@ -45,11 +45,11 @@ The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a

 ## Consequences

- **The bare-plugin-tree pedagogy.** echo-agent's inlined `cordis.yml` showed every plugin at once; the spine now lives behind a bundle, so seeing the whole tree means opening `dsh-agent-core`. The app package's README carries that teaching weight.
+- **The bare-plugin-tree pedagogy.** echo-agent's inlined `cordis.yml` showed every plugin at once; the spine now lives behind a bundle, so seeing the whole tree means opening `dsh-agent-spine-demo`. The app package's README carries that teaching weight.
 - **A layer of indirection.** "What does this demo load?" becomes a package read, not a single YAML scan.

 ## Related

- Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-core` and the `base*.yml` files are deleted.
+- Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-spine-demo` and the `base*.yml` files are deleted.
 - Builds on the [capability-seams](2026-06-13-capability-seams.md) interface/implementation/consumer split — backends and presentation stay leaf choices; the spine is the shared bundle.
 - Complements [Reorganize packages into a modular hierarchy](2026-06-20-package-hierarchy.md): the new app/core packages slot into existing groups under that hierarchy (`core` for the reusable spine bundle, `ui` for the app-specific front doors).
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: 372058dc04c4a36e82f5a5a6f5ef1af48068e4e3
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: cd12a65d185e8cdeafc4d04faad4a3349c6150d4
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: b177af24e988c6a314db522b8de0d1c09e30464f
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 0b964e8a748e4adcc32c017957e5294a3f258365
@@ -23,12 +23,12 @@ The exe is packaged with the **`--sea` (enhanced SEA) mode** of [@yao-pkg/pkg](h

 Terminology reminder: pkg's `/snapshot` VFS has nothing to do with this repo's testing-system "snapshot" (ACP replay goldens, `$DSH_SNAPSHOT`); this document says "VFS" for the former.

-### The serving surface is a plugin: the two packages ui/jsonrpc + ui/jsonrpc-agent
+### The serving surface is a plugin: the two packages ui/jsonrpc + examples/jsonrpc-demo

-The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `ui/acp` + `ui/acp-agent` pattern — the serving surface is itself a plugin:
+The deterministic protocol implementation (`server.ts` / `transport.ts`) lands as two packages on the existing `ui/acp` + `examples/acp-demo` pattern — the serving surface is itself a plugin:

 - [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md) (`@deepseek-ai/dsh-jsonrpc`): the pure protocol plugin; on apply it mounts `HarnessSdkServer` plus a line-delimited JSON-RPC transport on the process stdio, with disposal through `ctx.effect()`. Whether to serve is decided by `cordis.yml`; a yml that does not mount it is a legitimate process that does not serve. Protocol-level exit belongs to the plugin (after answering the `shutdown` request it disposes its own fiber, then `exit(0)`; an HMR-style unload only stops the service without exiting the process).
- [`packages/ui/jsonrpc-agent`](../../../../packages/ui/jsonrpc-agent/README.md) (`@deepseek-ai/dsh-jsonrpc-agent`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md) (`@deepseek-ai/dsh-jsonrpc-demo`): a thin app bin — `installFailLoud` + `loadEnv` + config discovery + `boot()` from [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts), done once boot completes; the server is brought up by the `dsh-jsonrpc` entry in the yml. Its only dependency is app-boot. Process-level exit belongs to the bin (stdin EOF/SIGTERM → dispose then 0, SIGINT → 130).

 Config discovery has two channels and fails loudly when both are missing: the `DSH_CORDIS_CONFIG` environment variable first (the SDK client convention), then an argv positional argument; no default path and no built-in fallback whatsoever — "the plugins actually booted are decided by an external cordis.yml" is a hard semantic.

@@ -40,13 +40,13 @@ The deploy root is [`python/sdk-runtime/package.json`](../../../../python/sdk-ru

 ### Build pipeline and artifacts

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → inject the pkg configuration (`bin` points at `node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js` inside the closure, `assets` is a full glob — dynamic import is invisible to pkg's static analysis, so everything must be packed in explicitly) → one `pkg --sea` per target → the executables `dsh-jsonrpc-agent-pkg-<platform>-<arch>` land in `dist-exe/` and are copied back into the runtime directory. CI treats them as intermediate test inputs and retains their platform wheels. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted yields a zero-symlink file tree (most stable for the pkg VFS, physically guaranteeing a single cordis instance); disabling automatic peer installation keeps unpublished package names from triggering registry resolution; link-workspace-packages points the closure at workspace/vendor sources.
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → inject the pkg configuration (`bin` points at `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js` inside the closure, `assets` is a full glob — dynamic import is invisible to pkg's static analysis, so everything must be packed in explicitly) → one `pkg --sea` per target → the executables `dsh-jsonrpc-agent-pkg-<platform>-<arch>` land in `dist-exe/` and are copied back into the runtime directory. CI treats them as intermediate test inputs and retains their platform wheels. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted yields a zero-symlink file tree (most stable for the pkg VFS, physically guaranteeing a single cordis instance); disabling automatic peer installation keeps unpublished package names from triggering registry resolution; link-workspace-packages points the closure at workspace/vendor sources.

 CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml), triggered explicitly only — `workflow_dispatch`, or the `build-exe` label on a pull request; native builds on the three platforms linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64, with `~/.pkg-cache` cached; macOS ad-hoc signing is handled by pkg. Each leg drives a mock SSE model through the SDK with the default config and a custom `cordis.yml`, drives the exe directly over NDJSON JSON-RPC, verifies the JSONL and final response, and installs release-shaped wheels into a clean venv without `runtime_bin`; Linux additionally inspects GLIBC requirements and runs in a manylinux 2.28 container. A full three-target run retains four artifacts, each containing one release file: the platform-independent SDK wheel and three native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts only `python-vX.Y.Z` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and three native runtime wheels, then a single serialized job checks and publishes all four to the project PyPI registry. Windows is a non-goal.

 ### Python SDK distribution: two carriers, exe for production, node for development

-The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds three kinds of content: the checked-in default `runtime/cordis.yml`, the build-injected platform exe, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions.
+The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds three kinds of content: the checked-in default `runtime/cordis.yml`, the build-injected platform exe, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions.

 [`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) reads the authoritative stable `X.Y.Z` from the repository root `package.json` and stages both packages at that version, with the SDK depending exactly on `deepseek-harness-runtime-bin==X.Y.Z`. An optional `python-vX.Y.Z` release tag is a consistency assertion and is rejected when it differs from the repository version; the source `pyproject.toml` development sentinel never determines a release version. The SDK is a `py3-none-any` wheel; the wheel-only runtime package contains exactly one exe and uses one of `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, or `py3-none-macosx_11_0_arm64`. Its Hatch hook rejects sdists, universal tags, mixed executable payloads, and unsupported platforms.

@@ -54,7 +54,7 @@ The exe's "must be explicitly configured" hard semantic is unchanged; the zero-c

 ### Naming lineage

-`@deepseek-ai/dsh-jsonrpc-agent` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python dist names are `deepseek-harness` / `deepseek-harness-runtime-bin`.
+`@deepseek-ai/dsh-jsonrpc-demo` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python dist names are `deepseek-harness` / `deepseek-harness-runtime-bin`.

 ## Disposition of worker-style plugins

@@ -23,12 +23,12 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后

 术语提醒：pkg 的 `/snapshot` VFS 与本仓库测试体系的“快照”（ACP 回放 golden、`$DSH_SNAPSHOT`）无关，本文用“VFS”指前者。

-### 对外服务接口也是插件：ui/jsonrpc + ui/jsonrpc-agent 两包
+### 对外服务接口也是插件：ui/jsonrpc + examples/jsonrpc-demo 两包

-确定性协议实现（`server.ts` / `transport.ts`）按 `ui/acp` + `ui/acp-agent` 的既有模式落为两包——对外服务接口本身也是插件：
+确定性协议实现（`server.ts` / `transport.ts`）按 `ui/acp` + `examples/acp-demo` 的既有模式落为两包——对外服务接口本身也是插件：

 - [`packages/ui/jsonrpc`](../../../../packages/ui/jsonrpc/README.md)（`@deepseek-ai/dsh-jsonrpc`）：纯协议插件；执行 `apply` 时，在进程 stdio 上挂载 `HarnessSdkServer` 与按行传输的 JSON-RPC 层，资源释放走 `ctx.effect()`。是否提供服务由 `cordis.yml` 决定；未挂载该插件的配置会启动一个不提供此服务的合法进程。协议级退出归插件所有（应答 `shutdown` 请求后 dispose 自身 fiber，再调用 `exit(0)`；HMR 式卸载只停止服务，不退出进程）。
- [`packages/ui/jsonrpc-agent`](../../../../packages/ui/jsonrpc-agent/README.md)（`@deepseek-ai/dsh-jsonrpc-agent`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。
+- [`packages/examples/jsonrpc-demo`](../../../../packages/examples/jsonrpc-demo/README.md)（`@deepseek-ai/dsh-jsonrpc-demo`）：轻量应用入口——`installFailLoud` + `loadEnv` + 配置发现 + [`dsh-app-boot`](../../../../packages/ui/app-boot/src/index.ts) 的 `boot()`；`boot()` 完成后入口即完成，服务器由 `cordis.yml` 中的 `dsh-jsonrpc` 条目启动。它只依赖 `app-boot`。进程级退出归 `bin` 所有（stdin EOF/SIGTERM → dispose 后返回 0，SIGINT → 130）。

 配置发现有两个通道，均缺失时立即报错：优先使用 `DSH_CORDIS_CONFIG` 环境变量（SDK 客户端约定），其次使用 argv 位置参数；没有默认路径或内置回退——“实际启动的插件由外部 `cordis.yml` 决定”是硬语义。

@@ -40,13 +40,13 @@ exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真

 ### 构建管线与产物

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 注入 pkg 配置（`bin` 指向闭包内的 `node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`；`assets` 使用全量 glob，因为动态 `import()` 对 pkg 静态分析不可见，必须显式打入全部内容）→ 每个构建目标调用一次 `pkg --sea` → 可执行文件 `dsh-jsonrpc-agent-pkg-<platform>-<arch>` 写入 `dist-exe/`，并拷回运行时目录。CI 将这些文件作为测试中间输入，只保留对应平台的 wheel 包。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 产出无符号链接的文件树（对 pkg VFS 最稳定，并从物理上保证只有一个 Cordis 实例）；关闭对等依赖自动安装可避免未发布包名触发注册表解析；`link-workspace-packages` 让闭包指向工作区/vendor 源码。
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 注入 pkg 配置（`bin` 指向闭包内的 `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`；`assets` 使用全量 glob，因为动态 `import()` 对 pkg 静态分析不可见，必须显式打入全部内容）→ 每个构建目标调用一次 `pkg --sea` → 可执行文件 `dsh-jsonrpc-agent-pkg-<platform>-<arch>` 写入 `dist-exe/`，并拷回运行时目录。CI 将这些文件作为测试中间输入，只保留对应平台的 wheel 包。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 产出无符号链接的文件树（对 pkg VFS 最稳定，并从物理上保证只有一个 Cordis 实例）；关闭对等依赖自动安装可避免未发布包名触发注册表解析；`link-workspace-packages` 让闭包指向工作区/vendor 源码。

 CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)，且只允许显式触发：手动派发 `workflow_dispatch`，或给 PR 添加 `build-exe` 标签。linux-x64、linux-arm64（`ubuntu-24.04-arm`）和 macos-arm64 三个平台分别进行原生构建，并缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都使用模拟 SSE 模型，分别通过默认配置和自定义 `cordis.yml` 驱动 SDK，再通过 NDJSON JSON-RPC 直接驱动 exe，校验 JSONL 与最终响应；最后把发布形态的 wheel 包安装到干净的 venv 中，并在不传 `runtime_bin` 的情况下运行。Linux 还会检查 GLIBC 依赖，并在 manylinux 2.28 容器中运行。完整构建三个目标时保留 4 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 3 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-vX.Y.Z` 标签流水线，构建一个 SDK wheel 包和 3 个原生运行时 wheel 包，再由单个串行任务校验并将这 4 个文件发布到项目的 PyPI 注册表。Windows 不在目标范围内。

 ### Python SDK 分发：双载体，exe 用于生产，`node` 用于开发

-Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含三类内容：检入的默认 `runtime/cordis.yml`、构建注入的平台 exe，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-agent/lib/bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。
+Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含三类内容：检入的默认 `runtime/cordis.yml`、构建注入的平台 exe，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。

 [`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) 从仓库根目录的 `package.json` 读取权威的稳定版本 `X.Y.Z`，以该版本暂存两个包，并让 SDK 精确依赖 `deepseek-harness-runtime-bin==X.Y.Z`。可选的 `python-vX.Y.Z` 发布标签只是一项一致性断言，与仓库版本不同时会被拒绝；源码 `pyproject.toml` 中的开发占位版本从不决定发布版本。SDK 是 `py3-none-any` wheel 包；只提供 wheel 包的运行时包恰好包含一个 exe，标签为 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 或 `py3-none-macosx_11_0_arm64`。其 Hatch 钩子拒绝 sdist、通用标签、混合可执行载荷以及不支持的平台。

@@ -54,7 +54,7 @@ exe“必须显式配置”的硬语义不变；零配置体验由包装层恢

 ### 命名血统

-`@deepseek-ai/dsh-jsonrpc-agent`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包清单；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发名为 `deepseek-harness` / `deepseek-harness-runtime-bin`。
+`@deepseek-ai/dsh-jsonrpc-demo`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包清单；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发名为 `deepseek-harness` / `deepseek-harness-runtime-bin`。

 ## 工作线程插件

@@ -20,7 +20,7 @@ Providers return `{ answers: [{ id, selected, custom? }] }`. `selected` is alway

 ## UI mappings

-`dsh-stdio-agent`'s in-package readline module renders each question, shows each option's `description` on the next line, supports comma/space-separated numeric choices for `multi_select`, accepts free-form custom answers, and rejects pending questions on abort, provider disposal, or stdin EOF. A batched request is asked in order and resolved as one answer object. The stdio provider serializes simultaneous requests with an internal queue so only one prompt owns stdin at a time.
+`dsh-stdio-demo`'s in-package readline module renders each question, shows each option's `description` on the next line, supports comma/space-separated numeric choices for `multi_select`, accepts free-form custom answers, and rejects pending questions on abort, provider disposal, or stdin EOF. A batched request is asked in order and resolved as one answer object. The stdio provider serializes simultaneous requests with an internal queue so only one prompt owns stdin at a time.

 `dsh-acp` provides the same seam for ACP sessions. It routes an ask request from the calling `Agent` through the bridge's `agent→sessionId` reverse map and calls ACP `unstable_createElicitation` with a session-scoped form for each question. Single-select options become a `choice` string enum; `multi_select` options become a `choice` array enum; optionless questions use a required `custom` text field. If the client returns both `choice` and non-empty `custom`, the custom answer wins. ACP `decline`/`cancel`, a missing answer, a missing session, and a client without elicitation support all become structured `UserInteractionError`s.

@@ -46,4 +46,4 @@ The feature gives the model a powerful pause primitive, so prompt guidance matte

 ## Testing

-Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. `dsh-stdio-agent` tests cover option descriptions, queued requests, EOF/abort cleanup, optionless free-form input, invalid option reprompts, duplicate multi-select numbers, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop.
+Unit coverage pins provider registration/disposal, duplicate-provider rejection, abort-before-provider, empty-question rejection, structured tool errors through `ctx.tools.execute()`, batched answers, multi-select answers, custom answers, and the model schema including the removal of `value`, `recommended`, `allow_custom`, and `desc`. `dsh-stdio-demo` tests cover option descriptions, queued requests, EOF/abort cleanup, optionless free-form input, invalid option reprompts, duplicate multi-select numbers, and batched question flows. ACP bridge tests drive a real in-memory ACP connection with the real `ask_user_question` tool and verify selected-option, custom-overrides-choice, multi-select, and optionless free-form elicitation paths continue the agent loop.
@@ -10,7 +10,7 @@ DeepSeek Harness uses the same primitive so project-specific review, plugin-auth

 ## Decision

-`@deepseek-ai/dsh-skill` is the pure provider registry (`ctx.skills`), `@deepseek-ai/dsh-skill-local` is the shipped local filesystem provider, and `@deepseek-ai/dsh-tool-skill` owns the session-prefix catalog and model-facing loader tool. `dsh-agent-core` loads the registry, local provider, and consumer by default so stdio and ACP apps get the same behavior while embedded or remote providers contribute skills without changing the registry or consumer. Its `skills` config forwards `registry`, `local`, and `tool` branches to those owners.
+`@deepseek-ai/dsh-skill` is the pure provider registry (`ctx.skills`), `@deepseek-ai/dsh-skill-local` is the shipped local filesystem provider, and `@deepseek-ai/dsh-tool-skill` owns the session-prefix catalog and model-facing loader tool. `dsh-agent-spine-demo` loads the registry, local provider, and consumer by default so stdio and ACP apps get the same behavior while embedded or remote providers contribute skills without changing the registry or consumer. Its `skills` config forwards `registry`, `local`, and `tool` branches to those owners.

 Provider plugins register synchronously during `apply()`. Provider membership is direct effect-owned state: registration and disposal invalidate completed catalogs synchronously, and discovery reads the current provider map on demand rather than observing registry-change events. Provider catalogs return ranked candidates from awaited `list()` calls, where remote providers perform initialization, authentication, and discovery while honoring the lookup abort signal. The registry validates each candidate, resolves same-name skills first-wins by rank, provider registration order, and provider-local order, then sorts summaries by skill name for deterministic consumers. It caches only completed catalog snapshots and retries when a provider/runtime revision changes during discovery, so an unload cannot freeze a stale, unresolvable skill into a session prefix. Runtime `ctx.skills.register(...)` remains a convenience for embedded in-process skills and uses project-over-user priority; `runtime` is reserved as the registry-owned provider name.

@@ -23,7 +23,7 @@ One `cordis.yml` entry mounts the seam. Not loading it is the fail-closed opt-ou
  #   policy: never   # deployment default for sessions without an override; 'ask' when omitted
 ```

-The entry alone provides mechanism, not a channel: with no answerer composed, every ask resolves `unavailable` and the asking tool call denies — fail-closed needs no configuration. Composing the ACP app (`@deepseek-ai/dsh-acp-agent`, as in [the acp-agent example's default tree](../../../../examples/acp-agent/README.md)) completes the loop: its bridge registers an answerer that prompts the owning editor session via `session/request_permission`, so a hook's `ask` or an escalation request surfaces as a one-shot Allow/Reject prompt attached to the already-streamed tool call. `policy: never` is the unattended stance — every ask auto-rejects deterministically, stated in the system prompt, no human in the loop. `policy` is validated against the closed list at plugin load; anything else throws.
+The entry alone provides mechanism, not a channel: with no answerer composed, every ask resolves `unavailable` and the asking tool call denies — fail-closed needs no configuration. Composing the ACP app (`@deepseek-ai/dsh-acp-demo`, as in [the acp-agent example's default tree](../../../../examples/acp-agent/README.md)) completes the loop: its bridge registers an answerer that prompts the owning editor session via `session/request_permission`, so a hook's `ask` or an escalation request surfaces as a one-shot Allow/Reject prompt attached to the already-streamed tool call. `policy: never` is the unattended stance — every ask auto-rejects deterministically, stated in the system prompt, no human in the loop. `policy` is validated against the closed list at plugin load; anything else throws.

 What a composed deployment observes: `allowed-once` lets exactly that call proceed; rejection, dismissal, and channel absence deny with three distinct reasons the model can tell apart; every ask lands a durable `approval/asked`/`approval/decided` pair on the asking agent's session log; nothing about a grant persists past the call that asked.

@@ -21,7 +21,7 @@ The system-prompt assembly owns the canonical model-facing tool order, exactly w

 Scope is deliberately narrow: this fixes the REGISTRATION-ORDER race, not plugin behavior. A `system-prompt/assemble` listener may still add, remove, or rearrange tools — same as it may edit sections after their sort — and owns the determinism of what it emits; the waterfall contract already demands deterministic listeners (the reconstructability invariant would catch a listener that diverges between build and replay).

-Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: the app configs (`dsh-stdio-agent`, `dsh-acp-agent`) accept the key and forward it through `dsh-agent-core` (whose schema is the intersection of the owners' schemas) to the `SystemPrompt` child. One schemastery footnote is load-bearing: a schemastery array defaults to `[]`, but an omitted `toolOrder` must stay ABSENT (= lexicographic) rather than become an explicitly-configured empty list (invalid — it lacks the rest entry), so every schema on the chain forces the default to `undefined`.
+Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: the app configs (`dsh-stdio-demo`, `dsh-acp-demo`) accept the key and forward it through `dsh-agent-spine-demo` (whose schema is the intersection of the owners' schemas) to the `SystemPrompt` child. One schemastery footnote is load-bearing: a schemastery array defaults to `[]`, but an omitted `toolOrder` must stay ABSENT (= lexicographic) rather than become an explicitly-configured empty list (invalid — it lacks the rest entry), so every schema on the chain forces the default to `undefined`.

 ## Alternatives considered

@@ -0,0 +1,212 @@
+# RFC: MCP client plugin — connect to external MCP servers and bridge their tools
+
+Status: implemented
+
+## Problem
+
+The harness had no way to consume tools from the MCP (Model Context Protocol) ecosystem. MCP is the emerging standard for tool servers — GitHub, filesystem, databases, code search, and hundreds of community servers expose tools via MCP. Users want to point the harness at one or more MCP servers and have their tools appear as native model-facing tools, without writing per-server glue code.
+
+The `ToolRegistry` already accepts raw JSON Schema tool definitions (documented in `dsh-tools` README: "Raw JSON-Schema tool definitions (from MCP servers) are still accepted by `ToolRegistry.register()` directly"), and the extension cookbook sketches the intended pattern ("MCP | one plugin per server: discover tools → `ctx.tools.register()`"). The infrastructure was ready; the bridge plugin was missing.
+
+## Decision
+
+### Package
+
+A single package `@deepseek-ai/dsh-mcp-client` at `packages/mcp/mcp-client/`. No capability-seam three-package split — there is no foreseeable second MCP client implementation, and the convention is "don't split preemptively" ([capability seams RFC](../../implemented/architecture/2026-06-13-capability-seams.md)).
+
+### SDK
+
+Use the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) (`Client`, `StdioClientTransport`, `StreamableHTTPClientTransport`). The harness does not implement its own JSON-RPC — consistent with how ACP delegates to `@agentclientprotocol/sdk`.
+
+### Scope
+
+MCP Client only (no server side — ACP already covers the "expose harness as an agent" role). Bridge **Tools** only — Resources and Prompts are deferred (they require harness-side consumption mechanisms that don't exist yet, and design space is large).
+
+### Plugin shape
+
+Namespace plugin (named exports `name`/`inject`/`Config`/`apply`, no `export default`). `inject: ['tools']`. Each MCP server is one plugin instance in `cordis.yml` — the same package loaded N times with different configs, like `dsh-tool-subagent`.
+
+### Configuration
+
+Flat discriminated union on the `transport` field:
+
+```typescript
+interface StdioConfig {
+  transport: 'stdio'
+  serverName: string          // required namespace, ^[A-Za-z0-9_-]{1,32}$
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  toolCallTimeoutMs?: number  // default 60_000
+}
+
+interface StreamableHttpConfig {
+  transport: 'streamable-http'
+  serverName: string          // required namespace, ^[A-Za-z0-9_-]{1,32}$
+  url: string
+  headers?: Record<string, string>
+  toolCallTimeoutMs?: number  // default 60_000
+}
+
+type Config = StdioConfig | StreamableHttpConfig
+```
+
+`serverName` is the stable local identity that namespaces this server's tools in the model-facing name (below). It is deliberately user configuration, NOT the remote `serverInfo.name`: the remote name is untrusted input, is not unique across deployments (prod and staging instances of one server report the same name), and may change on server upgrade — none of which may silently rename model-facing tools. A duplicate `serverName` across live instances is a configuration error: the later instance fails at load with an actionable message, never silent shadowing or skipping. A short `serverName` (`gh`) is also the knob for shortening public names.
+
+Example `cordis.yml` usage:
+
+```yaml
+- id: mcp-github
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js `Bearer ${process.env.MCP_TOKEN}`
+```
+
+The model sees `mcp__github__create_issue`, `mcp__github__search_code`, `mcp__web__search`.
+
+### Lifecycle
+
+Boot-time from `cordis.yml`. HMR (`@cordisjs/plugin-hmr`) provides hot-swap: editing the yml entry triggers dispose of the old instance (disconnects, unregisters tools) and creation of a new one (connects, discovers, registers). No runtime-dynamic API for now. Public names are pure functions of `(serverName, rawName)`, so an HMR swap that keeps `serverName` recreates identical model-facing names — session history and permission rules stay valid — and adding or removing an unrelated server never renames an existing tool.
+
+### Tool discovery and registration
+
+Every MCP tool has two names:
+
+- `rawName` — the exact MCP `Tool.name`, used only on the wire (`tools/call`).
+- `publicName` — the globally unique model-facing name registered in the `ToolRegistry`:
+
+      mcp__<serverName>__<rawName>
+
+This server-qualified shape is the de-facto standard among multi-server agent clients — every surveyed end-user product qualifies MCP tools by server ([Claude Code](https://code.claude.com/docs/en/agent-sdk/mcp#tool-naming-convention) `mcp__github__list_issues`, [Codex](https://openai.com/index/unrolling-the-codex-agent-loop/) `mcp__weather__get-forecast`, [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#3-tool-naming-and-namespaces), [VS Code](https://github.com/microsoft/vscode/blob/ab9ec62c6a61e429a9abd612ff220c3f4834c9ea/src/vs/workbench/contrib/mcp/common/mcpServer.ts#L217-L260), [Cline](https://github.com/cline/cline/blob/52fdbb1d72f7324a28142a7ba7678d4b53c902f4/sdk/packages/core/src/extensions/mcp/name-transform.ts#L20-L35), [Roo Code](https://github.com/RooCodeInc/Roo-Code/blob/b867ec9145750d0ae1ff7f02d35406e9bf2a0b16/src/utils/mcp-name.ts#L117-L140), [Goose](https://github.com/block/goose/blob/b3a012cbdde854b0fe14f95b1c48543bf6517c0a/crates/goose/src/agents/extension_manager.rs#L1391-L1441), [OpenCode](https://github.com/anomalyco/opencode/blob/d199b1bff90282a4f9cd6251b5fc7b16875a52f6/packages/opencode/src/mcp/catalog.ts#L117-L120)); the exact `mcp__<server>__<tool>` spelling follows Claude Code and Codex. The `mcp__` marker keeps MCP registrations out of the native tools' namespace and gives permission/telemetry rules a stable shape (`mcp__*`, `mcp__github__*`).
+
+1. On connect: drain `client.listTools()` pagination, derive every tool's `publicName`, then register each as a raw `ToolDefinition` via `ctx.tools.register()`. The MCP JSON Schema and description pass through unchanged (no `defineTool` DSL conversion); only the model-facing `name` is replaced.
+2. Listen for `notifications/tools/list_changed` → re-run the same sync (dispose previous generation, register new). Deterministic names mean unchanged tools keep their names across re-syncs.
+3. The executor closes over `rawName`; the public name is never sent to the server and never parsed to recover the raw name.
+4. No `presentCall`/`presentResult` — the ACP bridge's generic-card fallback handles rendering.
+5. Tools are transparent in the system prompt — no "[via MCP]" annotation beyond the name itself.
+
+### Public name normalization
+
+MCP allows tool names up to 128 characters including `.`; the DeepSeek function-name contract allows `[A-Za-z0-9_-]` and at most 64. Public names are normalized deterministically: invalid characters become `_`, and when replacement or truncation changed the name, a 12-hex-char SHA-256 hash of the `(serverName, rawName)` identity is appended so distinct MCP identities can never collapse into the same public name:
+
+```typescript
+function publicToolName(serverName: string, rawName: string): string {
+  const joined = `mcp__${serverName}__${rawName}`
+  const normalized = joined.replace(/[^A-Za-z0-9_-]/g, '_')
+  if (normalized === joined && normalized.length <= 64) return normalized
+  const hash = sha256(`${serverName}\0${rawName}`).slice(0, 12)
+  return `${normalized.slice(0, 64 - 13)}_${hash}`
+}
+```
+
+### Name conflict handling
+
+MCP guarantees tool-name uniqueness only [within one server](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-names); cross-server collisions are the norm, not the exception (a [Microsoft Research survey](https://www.microsoft.com/en-us/research/blog/tool-space-interference-in-the-mcp-era-designing-for-agent-compatibility-at-scale/#namespacing-issues-and-naming-ambiguity) of 1,470 servers found 775 colliding tool names; `search` alone appears in 32 servers, and the official GitHub server publishes bare `create_issue`). The always-on namespace makes collisions structurally impossible instead of handling them at collision time:
+
+- Two servers publishing `search` coexist as `mcp__github__search` and `mcp__web__search`.
+- A native harness tool named `search` is unaffected.
+- Duplicate `serverName` config fails the later instance at load (see Configuration).
+- A server listing the same tool name twice is an invalid tool list: the sync throws and the previous generation stays registered.
+- A registry conflict during the swap can only mean a foreign tool squats on this server's `mcp__<serverName>__` namespace: the partial generation is rolled back (zero tools from this server) and the error is logged loudly.
+
+Tools are never silently skipped; which tools are available never depends on plugin load order.
+
+### Naming invariants
+
+1. Every MCP tool has the stable identity `(serverName, rawName)`; every active identity has exactly one public name.
+2. Public names are deterministic, globally unique, and satisfy the DeepSeek 64-char `[A-Za-z0-9_-]` contract.
+3. MCP `tools/call` always receives the original raw name.
+4. Connecting, disconnecting, or re-syncing an unrelated server never renames an existing tool.
+5. Registration order never determines which tool is available.
+
+### Tool execution
+
+A unified `execute` handler for all tools from one MCP server:
+
+1. Resolve `rawName` (the executor closes over it) and call `client.callTool({ name: rawName, arguments }, { signal: exec.signal })` with the configured timeout — the public name is never sent to the server.
+2. Map the result:
+   - Multiple `text` content blocks → join with `'\n'` into a single `TextBlock` (required: `flattenText` uses `join('')` without separator, so multiple blocks would lose inter-block boundaries).
+   - `image` content blocks → discard with a `ctx.logger.warn` (the harness has no image content block type; [drop-image RFC](../../implemented/simplification/2026-07-04-drop-image-content-block.md)).
+   - `isError: true` → map to the harness `isError` result path (`{ content: [...], isError: true }`).
+3. Cancellation: `exec.signal` (from the agent loop's cancel) is passed through to the MCP SDK's `callTool`, which sends `$/cancelRequest` to the server.
+
+### Subprocess environment (stdio transport)
+
+Replicate the `buildChildEnv` + `SENSITIVE_ENV_PATTERN` scrub from `dsh-subagent-acp`: filter ambient env (strip credential-shaped vars matching `/KEY|SECRET|TOKEN/i`), then merge `config.env` on top. Explicit env overrides survive the scrub.
+
+### Disconnection / crash
+
+No auto-reconnect. If the MCP server process exits or the transport closes:
+
+1. The effect disposes → all registered tools are unregistered (fiber-scoped disposers).
+2. Subsequent model calls to those tools → `ToolNotFoundError` → `isError: true`.
+3. Recovery: user edits `cordis.yml` (triggers HMR reload) or restarts the harness.
+
+This matches the ACP subagent pattern: "crash = terminal, report error, clean up, don't retry."
+
+## Alternatives considered
+
+### MCP Server side (expose harness tools to external MCP clients)
+
+Deferred. The ACP bridge already exposes the harness as an agent server. Adding an MCP server layer would duplicate that with a different protocol, and the primary user need is consuming external tools, not exposing them.
+
+### Capability-seam three-package split (interface / impl / consumer)
+
+Rejected. There is no foreseeable alternative MCP client implementation — MCP has one protocol, one SDK. The convention is "don't split preemptively" until a second implementation appears.
+
+### Auto-reconnect with exponential backoff
+
+Rejected for v1. Adds complexity (partial-availability state where tools are registered but temporarily non-functional), and stdio process crashes usually indicate a configuration problem that retrying won't fix. HMR already provides the manual recovery path. Can be added as a future `reconnect: boolean` config if needed.
+
+### Bridge Resources and Prompts
+
+Deferred. Resources need a harness-side mechanism to decide WHEN to inject content (system prompt? on demand? model-triggered?). Prompts need a "prompt template" concept the harness lacks. Both require their own design; Tools are the high-value, low-risk starting point.
+
+### Raw model-facing tool names with an optional `toolPrefix`
+
+Rejected — this was the original proposal, built on the premise that "most MCP servers already use semantic prefixes in their tool names (e.g. `github_create_issue`)". The premise is false: the official GitHub server publishes `create_issue`, the reference filesystem server `read_file`, Sentry `search_issues` — and the Microsoft survey above shows collisions are common at ecosystem scale. Collision-time prefixing (or warn-and-skip) also makes the available tool set depend on plugin load order, and a tool could be silently renamed when an unrelated server is added — invalidating session history and permission rules mid-conversation. No surveyed multi-server agent product ships raw names.
+
+### Server-only namespace (`github__create_issue`, no `mcp__` marker)
+
+Rejected for v1. It prevents cross-server collisions but does not separate MCP registrations from native harness tools, and it forfeits MCP-wide policy shapes (`mcp__*`). The marker costs 5 characters; the `mcp__<server>__<tool>` spelling matches Claude Code and Codex, maximizing model familiarity. If the ToolRegistry later grows source-aware namespaces, dropping the literal marker can be revisited as a naming-policy change.
+
+### Deriving the namespace from the server-announced `serverInfo.name`
+
+Rejected. The remote name is untrusted, non-unique across deployments, and changeable on upgrade; tool identity and permission rules must not silently follow it. The namespace is local configuration.
+
+### Preserve multiple TextBlocks in tool result
+
+Rejected. `flattenText()` in the DeepSeek serializer uses `join('')` (no separator) when flattening `ContentBlock[]` to wire format. Multiple text blocks would silently lose inter-block boundaries — a correctness bug. All existing tools return a single TextBlock; the MCP bridge follows suit.
+
+## Testing
+
+Coverage is named per tier; each behavior lives at the cheapest tier that can express it.
+
+- **Unit** (`tests/mcp-client.spec.ts`, `tests/apply.spec.ts`, mocked MCP SDK): the `publicToolName` algorithm (clean, normalize, truncate-and-hash, determinism, distinct-identity separation), raw-vs-public wire discipline, cross-server and native-tool coexistence, duplicate-`serverName` load failure and reservation release, invalid-tool-list rejection, generation swap/rollback, failed-re-sync retention, result mapping, cancellation, config schema validation. 100% per-file coverage gates the package.
+- **E2E** (`tests/mcp-client.e2e.ts`, keyless): the real MCP protocol against the in-repo fixture server, `@modelcontextprotocol/server-everything`, and `@modelcontextprotocol/server-filesystem` over stdio, and against an in-process `StreamableHTTPServerTransport` server over Streamable HTTP — discovery under the namespace, dotted-name normalization end to end, execution round-trips, duplicate-`serverName` rejection, disposal.
+- **Snapshot**: deliberately none. MCP tools introduce no new transcript surface — they register as raw `ToolDefinition`s and render through the ACP bridge's generic-card fallback, which the bridge's unit suite already pins (`packages/ui/acp/tests/stream-update.spec.ts`). Adding an MCP server to the snapshot example's `cordis.yml` would mutate the pinned `text-turn` system-prompt fixture (forcing a with-key re-record of every recorded golden) and make every replay depend on spawning an external MCP server process — for zero new rendering behavior. If a later change gives MCP tools their own render intent, that change names its snapshot coverage then.
+
+## Consequences
+
+- A `cordis.yml` entry per MCP server is the entire integration cost: `serverName: filesystem` + a stdio command (or a Streamable HTTP URL) puts `mcp__filesystem__read_file` in the model's tool list, callable, with the raw `read_file` on the wire.
+- Public names are part of session history and permission/config surfaces; the naming algorithm is a v1 contract pinned by tests, and changing it after release is a breaking change.
+- The `mcp__<serverName>__` qualifier costs tokens on every name. Accepted: descriptions and JSON schemas dominate tool-definition tokens, and the qualifier buys stable identity, collision isolation, and MCP-wide policy shapes (`mcp__*`, `mcp__github__*`).
+- **MCP SDK stability**: the `@modelcontextprotocol/sdk` is still evolving; breaking changes require updating the bridge. The version is pinned, and the SDK is widely adopted (Claude Desktop, Cursor, VS Code) so breaking changes are unlikely to be silent.
+- **Tool schema quality**: MCP servers may expose poorly-described tools (vague descriptions, incomplete JSON schemas). The harness passes them through as-is — garbage-in-garbage-out; that is the server author's responsibility, not the bridge's.
+- **Stdio process management**: a misbehaving MCP server that ignores signals could wedge dispose. The Cordis fiber disposal has bounded quiescence; a stuck transport eventually times out at the framework level.
+- Crash recovery is manual (HMR edit or restart) — accepted for v1; a `reconnect` config remains open as future work.
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-14-time-context-plugin.md: 13e0eff4b9d286ee562d7a0a2c0a3a659126ba3b
-2026-07-14-time-context-plugin.zh.md: 5ee50a4d49eb9a7e00a09f70b436e15d72612b1f
+2026-07-14-time-context-plugin.md: 105bf53550f087fdefb1e6fe0ec493f8628d3e18
+2026-07-14-time-context-plugin.zh.md: 60e9004b1453e75e1bcd84870ad7f18d200a95d8
@@ -12,7 +12,7 @@ Prompt assembly can derive both facts per step from durable session timestamps,

 ## Decision

-`@deepseek-ai/dsh-time-context` is an opt-in function plugin at `packages/context/time-context/`. The `context/` product group holds bounded request-context enrichments that define neither a tool nor a service. `dsh-agent-core` and shipped examples do not load the package; deployments mount it explicitly when its token and disclosure costs are acceptable.
+`@deepseek-ai/dsh-time-context` is an opt-in function plugin at `packages/context/time-context/`. The `context/` product group holds bounded request-context enrichments that define neither a tool nor a service. `dsh-agent-spine-demo` and shipped examples do not load the package; deployments mount it explicitly when its token and disclosure costs are acceptable.

 The plugin registers the global `context:time` system-prompt section at order 10, after the deployment persona and before tool guidance. For an active turn it emits an ISO-shaped timestamp with numeric UTC offset and IANA zone, plus a compact whole-second duration since the last model-visible message before the turn opened. Bare and idle assemblies receive an empty section.

@@ -45,7 +45,7 @@ Unit tests pin formatting, baselines, refresh policy, validation, per-agent stat
 - **Refresh from a background timer** — rejected because a new value has no consumer outside request assembly. Timer-driven `agent.inject()` would create turns and wake idle sessions merely to report time passing.
 - **Keep UTC as the omitted default** — rejected because an explicitly enabled clock should follow its deployment environment unless the operator chooses UTC. `timeZone: UTC` remains available when a deployment requires it.
 - **Add a time-zone detection library** — rejected because Node's `Intl` runtime already exposes the process's IANA zone. Another dependency cannot infer a remote user's zone either.
- **Mount the plugin in `dsh-agent-core`** — rejected because time zone, disclosure, token budget, and freshness are deployment policy. Opt-in keeps default context stable.
+- **Mount the plugin in `dsh-agent-spine-demo`** — rejected because time zone, disclosure, token budget, and freshness are deployment policy. Opt-in keeps default context stable.
 - **Place the package in `core/`** — rejected because `core/` owns the product API spine, while this plugin is an optional leaf with no service key.

 ## Consequences
@@ -12,7 +12,7 @@ Status: implemented

 ## 决策

-`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 产品分组用于容纳既不定义工具、也不定义服务的有界请求上下文增强。`dsh-agent-core` 和仓库提供的示例都不会加载该 package；只有当 token 与信息披露成本可接受时，部署方才显式挂载它。
+`@deepseek-ai/dsh-time-context` 是位于 `packages/context/time-context/`、需要显式启用的函数插件。`context/` 产品分组用于容纳既不定义工具、也不定义服务的有界请求上下文增强。`dsh-agent-spine-demo` 和仓库提供的示例都不会加载该 package；只有当 token 与信息披露成本可接受时，部署方才显式挂载它。

 该插件注册顺序值为 10 的全局系统提示词区段 `context:time`，位置在部署方角色设定之后、工具指导之前。对于活跃轮次，它会输出带数字 UTC 偏移和 IANA 时区、形似 ISO 的时间戳，以及从轮次开始前最后一条模型可见消息起算的紧凑整秒时长。未绑定 agent 或 agent 处于空闲状态时，该区段为空。

@@ -45,7 +45,7 @@ agent loop（智能体循环）会在发送前通过 `request/header` 和 `reque
 - **通过后台计时器刷新**——不予采纳，因为请求组装之外没有消费新值的对象。由计时器驱动 `agent.inject()` 会创建轮次，并且只为报告时间流逝就唤醒空闲会话。
 - **省略配置时仍默认使用 UTC**——不予采纳，因为显式启用的时钟应跟随部署环境，除非运维方选择 UTC。需要 UTC 的部署仍可配置 `timeZone: UTC`。
 - **引入时区探测库**——不予采纳，因为 Node 的 `Intl` 运行时已经能够提供进程的 IANA 时区，而且额外依赖同样无法推断远程用户的时区。
- **在 `dsh-agent-core` 中挂载插件**——不予采纳，因为时区、信息披露、token 预算和新鲜度都属于部署策略。选择加入能保持默认上下文稳定。
+- **在 `dsh-agent-spine-demo` 中挂载插件**——不予采纳，因为时区、信息披露、token 预算和新鲜度都属于部署策略。选择加入能保持默认上下文稳定。
 - **将 package 放入 `core/`**——不予采纳，因为 `core/` 负责产品 API 主干，而该插件是没有服务键的可选叶节点。

 ## 后果
@@ -13,7 +13,7 @@ Set `engines.node` to `^22.19.0 || >=24.0.0` and test the keyless CI compatibili
 Two Node features gate the source runtime:

 - **`node:sqlite`** — `packages/session-persistence/session-persistence-sqlite` does a top-level `import { DatabaseSync } from 'node:sqlite'`. The module dropped its `--experimental-sqlite` flag requirement at **22.13** (LTS) and **23.4** (Current); before those, importing it throws at load.
- **Native TypeScript type-stripping** — the `packages/ui/stdio-agent/tests/built-bin.e2e.ts` smoke boots the published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` plugins (`mock-llm.ts`, `echo-tool.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.
+- **Native TypeScript type-stripping** — the `packages/examples/stdio-demo/tests/built-bin.e2e.ts` smoke boots the published `lib/bin.js` under plain `node` (no tsx) and loads the example's `.ts` plugins (`mock-llm.ts`, `echo-tool.ts`). Type-stripping is the default from **22.18** (LTS) and **23.6** (Current); before those it needs `--experimental-strip-types`.

 Those source features clear on the 22.x line at **22.18**, but the installed Pi adapter dependency raises the advertised LTS floor. `@deepseek-ai/dsh-llm-pi-ai` depends on `@earendil-works/pi-ai@0.79.3`, whose package declares `engines.node >=22.19.0`, so the LTS floor is **22.19**. The 24.x branch remains `>=24.0.0`. The disjoint range excludes Node 23 entirely: Node 23.0–23.5 still has at least one flagged source feature, and the 23 line is non-LTS/EOL, so advertising `>=23.6` would add a dead release line and a CI leg no deployment should use.

@@ -4,7 +4,7 @@ Status: implemented

 ## Problem

-The readline UI was a whole package (`@deepseek-ai/dsh-ui-stdio` under `packages/support/`) whose only runtime importer was the app package `@deepseek-ai/dsh-stdio-agent`. The examples reach the readline UI by loading the app, never by composing the helper themselves; every other repo reference was mechanical or descriptive surface that existed BECAUSE the package boundary existed — manifest and tsconfig entries, generated module-graph rows, dependency-graph and README rows, and doc comments naming the package. The ui group README recorded the support placement rationale ("exists chiefly for the examples and the coverage gate — `ui/` is reserved for surfaces shipped as product"), which left a standing tension: a shipped product app depending on a support package documented as NOT product surface.
+The readline UI was a whole package (`@deepseek-ai/dsh-ui-stdio` under `packages/support/`) whose only runtime importer was the app package `@deepseek-ai/dsh-stdio-demo`. The examples reach the readline UI by loading the app, never by composing the helper themselves; every other repo reference was mechanical or descriptive surface that existed BECAUSE the package boundary existed — manifest and tsconfig entries, generated module-graph rows, dependency-graph and README rows, and doc comments naming the package. The ui group README recorded the support placement rationale ("exists chiefly for the examples and the coverage gate — `ui/` is reserved for surfaces shipped as product"), which left a standing tension: a shipped product app depending on a support package documented as NOT product surface.

 The boundary bought package metadata, workspace and tsconfig references, module-graph rows, README entries, and publint surface for a helper that is not independently swappable: the stdio app's front-door cluster always includes the readline UI, and nothing else can meaningfully consume it.

@@ -6,7 +6,7 @@ Status: implemented

 Two pieces of `dsh-acp` surface were unreachable from any shipped configuration:

-1. **`AcpConfig.agentName` / `agentVersion`** (`packages/ui/acp/src/index.ts`). The shipped app package hands the bridge only `{ model }` (`packages/ui/acp-agent/src/index.ts`), so no leaf `cordis.yml` — the only production config surface — could set the knobs at all; they were settable solely by direct-mounting the bridge, which only a unit test did. Every snapshot golden — the hook-matrix scenarios included — pins the schema defaults (`deepseek-harness-acp` / `0.0.1`). The pair also carried a live `TODO(double-default)`: the literals existed twice (schema `.default(...)` plus `??` fallbacks), with the TODO asking to pick one home.
+1. **`AcpConfig.agentName` / `agentVersion`** (`packages/ui/acp/src/index.ts`). The shipped app package hands the bridge only `{ model }` (`packages/examples/acp-demo/src/index.ts`), so no leaf `cordis.yml` — the only production config surface — could set the knobs at all; they were settable solely by direct-mounting the bridge, which only a unit test did. Every snapshot golden — the hook-matrix scenarios included — pins the schema defaults (`deepseek-harness-acp` / `0.0.1`). The pair also carried a live `TODO(double-default)`: the literals existed twice (schema `.default(...)` plus `??` fallbacks), with the TODO asking to pick one home.
 2. **The `toolKindFor` name heuristic** (same file) special-cased `bash*`/`read*`/`write`/`edit*` tool names in the generic-fallback path. Since the [render-intent union](../architecture/2026-07-02-tool-render-intent-union.md), every first-party tool those arms matched ships its own `presentCall` carrying its kind, and the presenter-less production tools (`subagent`, `subagent_fork`) fell through to `other` anyway. The arms were production-reachable only when a tool declined to present its own call — a `presentCall` that THROWS (the containment fallback), or model arguments that fail the tool's schema so `defineTool`'s `presentCall` wrapper returns `undefined` (e.g. a `bash` call missing the required `description`) — and the bridge's own module doc states the design rule the heuristic violated: "the bridge never special-cases tool names".

 ## Decision
@@ -22,7 +22,7 @@ The machinery lives in [`packages/support/acp-snapshot`](../../../../packages/su

 - **Copy the modules into each example** — the fork this RFC exists to prevent: the record/guard logic is exactly the code that must stay byte-identical across suites, and examples are outside the coverage gate, so each copy is also unmeasured.
 - **A shared module directory under `examples/`** — keeps the code outside the coverage gate and forces relative imports across example boundaries, against the package-name import convention; `examples/` leaves stay thin by design.
- **A `/testing` subpath export of `dsh-acp-agent`** — couples test infrastructure into a product package's surface and dependency set; `packages/support/` exists precisely for real-but-lower-compatibility dev/test packages, with `dsh-llm-replay` as the precedent this package completes.
+- **A `/testing` subpath export of `dsh-acp-demo`** — couples test infrastructure into a product package's surface and dependency set; `packages/support/` exists precisely for real-but-lower-compatibility dev/test packages, with `dsh-llm-replay` as the precedent this package completes.
 - **Export raw test-body functions instead of a suite factory** — each example would re-own the `describe`/`it` skeleton (~80 lines of registration boilerplate per suite) for no flexibility gain; the factory keeps consumers to a scenario table plus one call, and the exported pure helpers preserve unit-testability inside the factory design.
 - **An injectable ACP `Client` factory instead of declarative `permissionAnswers`** — maximally flexible, but it leaks SDK client construction to every consumer and reopens per-example drift in exactly the layer being unified; a declarative queue keeps `input.json` the single scripting surface and stays golden-normalizable.
 - **Generalize beyond ACP (a transport-agnostic snapshot harness)** — no second transport exists; the harness is ACP-shaped end to end (SDK client, JSON-RPC frames, `session/update` waiters), and a speculative abstraction would be a seam split ahead of any consumer.
@@ -1,6 +1,6 @@
 # RFC: Make the shared example base providerless

-Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-core` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
+Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-spine-demo` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.

 ## Problem

@@ -1,12 +1,12 @@
 # Examples

-Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor), loads one app package, and may add optional product tools or demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-agent`](../packages/ui/stdio-agent), [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent)) and the [`@deepseek-ai/dsh-agent-core`](../packages/core/agent-core) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`.
+Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor), loads one app package, and may add optional product tools or demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-demo`](../packages/examples/stdio-demo), [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo)) and the [`@deepseek-ai/dsh-agent-spine-demo`](../packages/examples/agent-spine-demo) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`.

 ## echo-agent

-A mock model + echo tool on the stdio chat app — the all-mock skeleton. The leaf swaps `dsh-stdio-agent`'s LLM backend to a local `mock-echo` adapter and adds a local `echo` tool. Demonstrates:
+A mock model + echo tool on the stdio chat app — the all-mock skeleton. The leaf swaps `dsh-stdio-demo`'s LLM backend to a local `mock-echo` adapter and adds a local `echo` tool. Demonstrates:

- A thin leaf `cordis.yml` loading the `@deepseek-ai/dsh-stdio-agent` app
+- A thin leaf `cordis.yml` loading the `@deepseek-ai/dsh-stdio-demo` app
 - Registering a mock `LlmAdapter` (streaming scripted responses)
 - Registering a tool via `ctx.tools.register()`
 - "Swap the backend, keep the app" — the only difference from `coding-agent` is the adapter
@@ -15,7 +15,7 @@ Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigge

 ## coding-agent

-A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-agent` app. The UI is a terminal readline REPL.
+A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite, `subagent` delegation, and the `todo_write` task tracker on the same `@deepseek-ai/dsh-stdio-demo` app. The UI is a terminal readline REPL.

 Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.

@@ -29,7 +29,7 @@ Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/R

 ## acp-agent

-An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.
+An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.

 Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:code-mode acp` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design.

@@ -11,7 +11,7 @@ The leaf config loads the ACP app, DeepSeek adapter, sandboxed bash, approval an

 ## stdout is the protocol

-This example loads **no stdout logger** — `stdout` carries the JSON-RPC frames, and any other write corrupts them. `@deepseek-ai/dsh-acp-agent` includes no logger entry, so this leaf has none to get wrong by default; do not add one (use a stderr exporter if you need logs).
+This example loads **no stdout logger** — `stdout` carries the JSON-RPC frames, and any other write corrupts them. `@deepseek-ai/dsh-acp-demo` includes no logger entry, so this leaf has none to get wrong by default; do not add one (use a stderr exporter if you need logs).

 ## Zed configuration

@@ -8,7 +8,7 @@
        name: '@deepseek-ai/dsh-llm-deepseek'
        disabled: true
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -6,7 +6,7 @@
    path: ./cordis.yml
    patches:
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -10,7 +10,7 @@
        name: '@deepseek-ai/dsh-llm-deepseek'
        disabled: true
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -8,7 +8,7 @@
    path: ./cordis.yml
    patches:
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -10,7 +10,7 @@
        name: '@deepseek-ai/dsh-llm-deepseek'
        disabled: true
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -9,7 +9,7 @@
    path: ./cordis.yml
    patches:
      - id: acp-agent
-        name: '@deepseek-ai/dsh-acp-agent'
+        name: '@deepseek-ai/dsh-acp-demo'
        config:
          model: deepseek-v4-flash
          persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -18,9 +18,9 @@ flowchart LR
  cfg --> plugin_acp_approval
  plugin_acp_permission["permission<br/>@deepseek-ai/dsh-permission"]
  cfg --> plugin_acp_permission
-  plugin_acp_acp_agent["acp-agent<br/>@deepseek-ai/dsh-acp-agent"]
+  plugin_acp_acp_agent["acp-agent<br/>@deepseek-ai/dsh-acp-demo"]
  cfg --> plugin_acp_acp_agent
-  plugin_acp_acp_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_acp_acp_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
  plugin_acp_acp_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
  plugin_acp_acp_agent --> frontdoor_acp["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]
  bundle_agent_core --> spine_llm["ctx.llm"]
@@ -58,7 +58,7 @@ flowchart LR
 | `bash` | `@deepseek-ai/dsh-bash-sandbox` |
 | `approval` | `@deepseek-ai/dsh-user-approval` |
 | `permission` | `@deepseek-ai/dsh-permission` |
-| `acp-agent` | `@deepseek-ai/dsh-acp-agent` |
+| `acp-agent` | `@deepseek-ai/dsh-acp-demo` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
 | `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
@@ -37,7 +37,7 @@
 # Persistence root: $DSH_SNAPSHOT_SESSIONS_ROOT when the snapshot harness sets it
 # (so it can harvest / isolate the log), else ./.sessions for the demo.
 - id: acp-agent
-  name: '@deepseek-ai/dsh-acp-agent'
+  name: '@deepseek-ai/dsh-acp-demo'
  config:
    model: deepseek-v4-flash
    persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
@@ -23,7 +23,7 @@ import {
 */

 // The child runs from a temp cwd, so its bin and config path are absolute.
-const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 // Resolve tsx absolutely because the subprocess runs outside the repo.
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
@@ -13,11 +13,11 @@ import { defineAcpSnapshotSuite, type Scenario, type SnapshotSuiteOptions } from
 * docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md.
 */

-// The dsh-acp-agent bin (the demo:acp entry), this example's cordis.yml, and
+// The dsh-acp-demo bin (the demo:acp entry), this example's cordis.yml, and
 // the repo-root tsconfig (four levels up from examples/acp-agent/tests) — all
 // ABSOLUTE: the subprocess cwd is a temp dir outside the repo.
 const AGENT = {
-  binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
+  binScript: fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)),
  configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
  tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
 }
@@ -26,7 +26,7 @@ import {
 * or runner support self-skip; real denial markers remain on sandbox e2e tiers.
 */

-const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // The subprocess runs from a temp cwd outside the repo; point tsx at the repo
@@ -23,7 +23,7 @@ import {
 * The test owns and disposes the ACP subprocess.
 */

-const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
@@ -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` schema (`tool-bash`) and the `task_*` control tools (`tool-tasks`) 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 |
@@ -9,7 +9,7 @@
    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
@@ -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"]
@@ -54,7 +54,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` |
@@ -1,16 +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, tasks + the task_* control tools, 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, 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
@@ -37,7 +30,7 @@

 # 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
@@ -8,7 +8,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 * 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 tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

@@ -9,7 +9,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 * immediate EOF guarantees there is no model call.
 */

-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 tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

@@ -20,9 +20,9 @@ flowchart LR
  cfg --> plugin_cordis_web
  plugin_cordis_web_fetch_local["web-fetch-local<br/>@deepseek-ai/dsh-web-fetch-local"]
  cfg --> plugin_cordis_web_fetch_local
-  plugin_cordis_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  plugin_cordis_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-demo"]
  cfg --> plugin_cordis_stdio_agent
-  plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
  plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
  plugin_cordis_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
  bundle_agent_core --> spine_llm["ctx.llm"]
@@ -41,7 +41,7 @@ flowchart LR
 | `fs-local` | `@deepseek-ai/dsh-fs-local` |
 | `web` | `@deepseek-ai/dsh-web` |
 | `web-fetch-local` | `@deepseek-ai/dsh-web-fetch-local` |
-| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` |
 | `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` |

 Source config: [`examples/cordis-agent/cordis.yml`](cordis.yml).
@@ -49,7 +49,7 @@

 # The app bundle pre-creates the self-referential demo's `main` agent.
 - 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
@@ -8,7 +8,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 * prompt and assert the banner. The dummy key never reaches a model call.
 */

-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 tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

@@ -4,7 +4,7 @@ Runnable demo: stdin chat with a scripted mock model and an echo tool. The all-m

 ## What it shows

-This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent) app (which bundles the whole [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, the console logger, JSONL persistence, the readline UI, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`:
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo) app (which bundles the whole [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) spine, the console logger, JSONL persistence, the readline UI, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`:

 - `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the `echo` tool when the user types "echo <something>". Registered with `ctx.llm.registerAdapter(['mock-echo'], …)`.
 - `echo-tool.ts` — a tool registered via `ctx.tools.register(defineTool(…))` with typed `execute` args; echoes text back uppercased.
@@ -17,16 +17,16 @@ Swapping `mock-llm` for the real `llm-deepseek` adapter is all that separates th
 |---|---|---|
 | `src/mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter(['mock-echo'], …)`, streaming chunks with the proper `block-start`/`block-end` protocol |
 | `src/echo-tool.ts` | Tool registration | `ctx.tools.register(defineTool(…))` with typed `execute` args, returning `ContentBlock[]` |
-| `cordis.yml` | Leaf wiring | the two backends + `hmr` + one `@deepseek-ai/dsh-stdio-agent` entry carrying the app config |
+| `cordis.yml` | Leaf wiring | the two backends + `hmr` + one `@deepseek-ai/dsh-stdio-demo` entry carrying the app config |

-The spine, UI, persistence, and boot glue all live in `@deepseek-ai/dsh-stdio-agent` and the bundle it loads — this folder holds only the demo-specific mocks and the leaf wiring.
+The spine, UI, persistence, and boot glue all live in `@deepseek-ai/dsh-stdio-demo` and the bundle it loads — this folder holds only the demo-specific mocks and the leaf wiring.

 ## Run

 ```sh
 pnpm run demo:echo
 # or:
-node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml
+node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml
 ```

 Type a message and press Enter. "echo <text>" triggers a tool call round-trip (the mock model requests the `echo` tool, which echoes the text uppercased, and the next model step acknowledges it).
@@ -16,9 +16,9 @@ flowchart LR
  cfg --> plugin_echo_echo_tool
  plugin_echo_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
  cfg --> plugin_echo_bash
-  plugin_echo_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-agent"]
+  plugin_echo_stdio_agent["stdio-agent<br/>@deepseek-ai/dsh-stdio-demo"]
  cfg --> plugin_echo_stdio_agent
-  plugin_echo_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"]
+  plugin_echo_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
  plugin_echo_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
  plugin_echo_stdio_agent --> frontdoor_stdio["readline UI<br/>console logger<br/>pre-created main agent"]
  bundle_agent_core --> spine_llm["ctx.llm"]
@@ -33,7 +33,7 @@ flowchart LR
 | `mock-llm` | `./src/mock-llm.ts` |
 | `echo-tool` | `./src/echo-tool.ts` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
-| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` |

 Source config: [`examples/echo-agent/cordis.yml`](cordis.yml).

@@ -3,7 +3,7 @@
 # No API key: the `mock-echo` adapter never touches the network.

 # Hot-module reload for the dev/demo loop (a leaf entry, not baked into
-# dsh-stdio-agent — it needs `node --expose-internals`, which `demo:echo` passes).
+# dsh-stdio-demo — it needs `node --expose-internals`, which `demo:echo` passes).
 - id: hmr
  name: '@cordisjs/plugin-hmr'
  config:
@@ -24,7 +24,7 @@

 # The app pre-creates `main` on the mock model and supplies logging, persistence, and readline UI.
 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    model: mock-echo
    persona: 'You are echo-agent, a demo agent.'
@@ -8,7 +8,7 @@ import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-l
 * and the complete behavior proof for the example.
 */

-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 tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

@@ -82,11 +82,11 @@
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
    },
-    "packages/ui/acp-agent": {
+    "packages/examples/acp-demo": {
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
    },
-    "packages/ui/stdio-agent": {
+    "packages/examples/stdio-demo": {
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
    },
@@ -94,7 +94,7 @@
      "entry": ["tests/**/*.spec.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
    },
-    "packages/ui/jsonrpc-agent": {
+    "packages/examples/jsonrpc-demo": {
      "project": ["src/**/*.ts"]
    },
    "packages/subagent/subagent-spawn": {
@@ -113,6 +113,11 @@
    "packages/fs/tool-fs": {
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
+    "packages/mcp/mcp-client": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts", "tests/fixture-server.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"],
+      "ignoreDependencies": ["@modelcontextprotocol/server-everything", "@modelcontextprotocol/server-filesystem"]
    }
  }
 }
@@ -71,11 +71,11 @@
    "constraints": "tsx scripts/check-workspace-constraints.ts",
    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
    "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
-    "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
-    "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
+    "demo:echo": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml",
+    "demo:repl": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/coding-agent/cordis.yml",
    "demo:code-mode": "node scripts/demo-code-mode.mjs",
-    "demo:cordis": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/cordis-agent/cordis.yml",
-    "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts --config examples/acp-agent/cordis.yml",
+    "demo:cordis": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/cordis-agent/cordis.yml",
+    "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",
    "postinstall": "node scripts/install-lefthook.mjs"
  },
  "devDependencies": {
@@ -28,7 +28,8 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface |
-| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface |
+| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
+| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (the `Branded<B>` primitive) | Support — small, stable, harness-dep-free |

@@ -38,6 +39,6 @@ Groups distinguish product API from support infrastructure. New packages join an

 The inter-package dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).

-**Extension plugins depend on interfaces, never the concrete loop.** Composition bundles such as `dsh-agent-core` intentionally assemble that loop. Swappable capabilities split into interface, implementation, and consumer packages; see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md).
+The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-spine-demo`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).

 Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
@@ -1,6 +1,6 @@
 # context/ — optional request context

-Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-core` bundle excludes them.
+Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-spine-demo` bundle excludes them.

 | Package | Role | ctx key |
 |---|---|---|
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-time-context

-Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-core` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).
+Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).

 ## Config

@@ -9,7 +9,7 @@
  name: '@deepseek-ai/dsh-time-context'

 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    model: mock-echo
    persona: 'Test the time-context plugin.'
@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 import { foldRequestHeader, type SessionEvent } from '@deepseek-ai/dsh-session'

-const binScript = fileURLToPath(new URL('../../../ui/stdio-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
@@ -10,10 +10,9 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
 | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
-| `agent-core/` | Bundle plugin: the default executor-less/UI-less spine as code | (loads the spine) |

 `scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.

 `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.

-`agent-core` is the composition counterpart: one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes the shared control spine while leaving executors, LLM adapters, alternate skill providers, and UI front doors outside the bundle.
+The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
@@ -0,0 +1,20 @@
+# examples/ — ready-to-run demo bundles
+
+Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling the spine and a front door by hand. These are **demo / reference** packages — the `-demo` npm suffix marks each one as non-product surface, readable straight off the package name. The runnable leaves under the repo-root [`examples/`](../../examples/AGENTS.md) and the [Python SDK runtime](../../python/sdk-runtime/README.md) are the consumers; each is just its swappable backends plus one bundle entry.
+
+| Package | npm name | Role |
+|---|---|---|
+| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + `tool-skill` + `agent-loop`) |
+| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal stdio chat app: the spine + console logger + readline UI + a pre-created `main` agent, with a boot `bin` |
+| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
+| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |
+
+`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with opposite front-door clusters (console logger + readline UI vs the stdout-owning ACP bridge) and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+
+These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
+
+Do not confuse this group with the repo-root [`examples/`](../../examples/AGENTS.md): that directory holds the runnable `cordis.yml` **leaves**; this group holds the **bundles** those leaves load.
+
+## The jsonrpc bin/exe names are legacy
+
+`jsonrpc-demo` renamed like its siblings, but its bin is still `dsh-jsonrpc-agent` and the single-file executable is still `dsh-jsonrpc-agent-pkg` (referenced across the [Python distribution](../../python/sdk-runtime/README.md)). Those names are the SDK's runtime-startup surface; they are reconciled when the SDK unifies that startup flow, not by this move.
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-acp-agent
+# @deepseek-ai/dsh-acp-demo

-The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
+The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster an [Agent Client Protocol](../../ui/acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.

-It is the structured counterpart to [`@deepseek-ai/dsh-stdio-agent`](../stdio-agent/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.
+It is the structured counterpart to [`@deepseek-ai/dsh-stdio-demo`](../stdio-demo/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.

 ## What it bakes in — and what it deliberately omits

@@ -10,13 +10,13 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it

 | Plugin | Why |
 |---|---|
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
+| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
 | ~~`@deepseek-ai/dsh-user-approval`~~ | **omitted by default** — permission policy is deployment-specific; sandbox/approval leaves opt in and the ACP bridge then supplies the answerer |
-| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../acp/README.md)) |
+| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../../ui/acp/README.md)) |
 | ~~`hmr`~~ | **omitted** — the editor owns the subprocess |

 Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends, so the common mistake — copying a console-logger entry from the stdio config — has no place here. (A leaf author technically *can* still add `@cordisjs/plugin-logger-console` as a sibling entry; the package can't forbid that. So the rule stands: never add a stdout logger to an ACP leaf — stdout is the JSON-RPC channel. Use a stderr exporter if you need logs.)
@@ -28,17 +28,17 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | `model` | (required) | the per-session agent template the bridge creates agents from |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `agent-core` |
-| `skills` | owner defaults | skill registry, local provider, and model-facing skill-tool config through `agent-core` |
-| `toolBash` | owner defaults | model-facing bash config through `agent-core`, including bash's producer-local `enableRunInBackground` |
-| `toolTasks` | owner defaults | generic `task_output` wait bounds through `agent-core` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
+| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
+| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |

 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor.

 ## The bin

-`dsh-acp-agent [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`):
+`dsh-acp-demo [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`):

 - loads a gitignored `.env` from the cwd — **skipped** in snapshot REPLAY so a stray key can never trigger a live call;
 - honors `DSH_SNAPSHOT=replay` by booting the sibling `cordis.snapshot.yml` (the keyless replay tree, `llm-replay` in place of `llm-deepseek`);
@@ -50,7 +50,7 @@ All diagnostics go to **stderr** — stdout is the protocol.

 ## Model Experience

-Indirectly, through `dsh-agent-core` and `dsh-acp`, which compose each ACP agent's prompt, tools, and message history; this app bundle adds no model-bound content itself.
+Indirectly, through `dsh-agent-spine-demo` and `dsh-acp`, which compose each ACP agent's prompt, tools, and message history; this app bundle adds no model-bound content itself.

 ## Known Limitations and Deferred Work

@@ -1,13 +1,13 @@
 {
-  "name": "@deepseek-ai/dsh-acp-agent",
-  "description": "ACP server app: the agent-core spine + JSONL persistence + the ACP bridge (no stdout logger, no hmr, no pre-created agents), with a bin to boot a leaf cordis.yml over JSON-RPC stdio",
+  "name": "@deepseek-ai/dsh-acp-demo",
+  "description": "ACP server app: the agent-spine-demo bundle + JSONL persistence + the ACP bridge (no stdout logger, no hmr, no pre-created agents), with a bin to boot a leaf cordis.yml over JSON-RPC stdio",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "bin": {
-    "dsh-acp-agent": "lib/bin.js"
+    "dsh-acp-demo": "lib/bin.js"
  },
  "exports": {
    ".": {
@@ -34,7 +34,7 @@
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
    "@deepseek-ai/dsh-app-boot": "^0.0.1",
    "@deepseek-ai/dsh-acp": "^0.0.1",
-    "@deepseek-ai/dsh-agent-core": "^0.0.1",
+    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -47,7 +47,7 @@
    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@deepseek-ai/dsh-acp": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 /**
 * Boot an ACP stdio server from `cordis.yml`; usage is
- * `dsh-acp-agent [--config path]`, defaulting to `./cordis.yml`. Shared env
+ * `dsh-acp-demo [--config path]`, defaulting to `./cordis.yml`. Shared env
 * loading, Loader guards, snapshot config selection, and settled-tree boot live
 * in dsh-app-boot. Replay skips `.env` and selects sibling
 * `cordis.snapshot.yml` so a stray key cannot trigger a model call. EOF disposes
 * and flushes snapshot runs; editors normally own process lifetime. Stdout is
 * reserved for JSON-RPC, so diagnostics go only to stderr.
- * @module @deepseek-ai/dsh-acp-agent/bin
+ * @module @deepseek-ai/dsh-acp-demo/bin
 */

 import { parseArgs } from 'node:util'
 import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'

-const NAME = 'dsh-acp-agent'
+const NAME = 'dsh-acp-demo'

 /* v8 ignore start -- thin self-executing composition over the unit-tested
   dsh-app-boot helpers; exercised end-to-end by the snapshot suite and the
@@ -1,23 +1,23 @@
 /**
- * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}),
+ * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}),
 * JSONL session persistence, and the {@link @deepseek-ai/dsh-acp} bridge. It
 * writes nothing to stdout.
 * It pre-creates no agents and leaves adapters, executors, and optional tools to
 * the leaf, which must likewise avoid stdout loggers. Named exports are
 * required so Loader retains this plugin's `Config` schema (see
 * docs/postmortem/0001).
- * @module @deepseek-ai/dsh-acp-agent
+ * @module @deepseek-ai/dsh-acp-demo
 */

 import type { Context } from 'cordis'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'

-export const name = 'acp-agent'
+export const name = 'acp-demo'

 /**
 * App config: the swappable per-deployment values. `model` configures the
@@ -26,7 +26,7 @@ export const name = 'acp-agent'
 * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
 * the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * `tools` is the tool registry's config (its presentation `mode`, forwarded
- * through agent-core); `persistenceRoot` is the JSONL backend's directory.
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
 */
 export interface Config {
  /** Model name for ACP-created agents (must have a registered adapter). */
@@ -35,11 +35,11 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /** Model-facing bash tool config forwarded through agent-core. */
  toolBash?: NonNullable<agentCore.Config['toolBash']>
@@ -68,7 +68,7 @@ export const Config: z<Config> = z.object({
 /* jscpd:ignore-end */

 /**
- * Compose the spine with the ACP front door. The agent-core bundle pre-creates
+ * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
 * NO agents (its `agents` list defaults to `[]`) and carries the deployment
 * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
 * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
@@ -10,7 +10,7 @@ import type { Message } from '@deepseek-ai/dsh-llm'
 import * as acpAgent from '../src/index.ts'

 /**
- * In-process unit coverage for the @deepseek-ai/dsh-acp-agent composition:
+ * In-process unit coverage for the @deepseek-ai/dsh-acp-demo composition:
 * mounting it brings up the agent-core spine + JSONL persistence + the ACP
 * bridge in one `ctx.plugin`. Unlike the stdio app, this one loads NO
 * Loader-only plugin (no hmr), so it mounts in a plain Context.
@@ -30,7 +30,7 @@ async function mount(config: acpAgent.Config, withBash = false): Promise<Context
 }

 async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<acpAgent.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-demo-skills-'))
  return {
    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
@@ -49,7 +49,7 @@ async function composePrefix(ctx: Context): Promise<Message[]> {
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-default-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-demo-default-skills-'))
  process.env.DSH_HOME = join(home, '.dsh')
  process.env.DSH_AGENTS_HOME = join(home, '.agents')
  try {
@@ -68,9 +68,9 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  }
 }

-describe('dsh-acp-agent composition', () => {
+describe('dsh-acp-demo composition', () => {
  it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test', skills: await isolatedSkillsConfig() })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig() })
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('sessions')).toBeDefined()
    expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -127,7 +127,7 @@ describe('dsh-acp-agent composition', () => {
  })

  it('exposes its plugin shape', () => {
-    expect(acpAgent.name).toBe('acp-agent')
+    expect(acpAgent.name).toBe('acp-demo')
    expect(acpAgent.Config).toBeDefined()
  })

@@ -135,7 +135,7 @@ describe('dsh-acp-agent composition', () => {
    const ctx = await mount({
      model: 'mock',
      toolOrder: ['zulu', TOOL_ORDER_REST],
-      persistenceRoot: '/tmp/dsh-acp-agent-test-tool-order',
+      persistenceRoot: '/tmp/dsh-acp-demo-test-tool-order',
    })
    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
    // this providerless mount, so register two plain tools to order.
@@ -161,7 +161,7 @@ describe('dsh-acp-agent composition', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(acpAgent) as Record<string, unknown>
    expect(unwrapped).toBe(acpAgent)
-    expect(unwrapped.name).toBe('acp-agent')
+    expect(unwrapped.name).toBe('acp-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
@@ -25,14 +25,14 @@ import { afterEach, describe, expect, it } from 'vitest'
 */

 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const acpBin = join(repoRoot, 'packages/ui/acp-agent/lib/bin.js')
+const acpBin = join(repoRoot, 'packages/examples/acp-demo/lib/bin.js')

 const dshPackages = [
-  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
  'core/tools', 'core/agent-loop', 'llm/llm', 'llm/llm-deepseek', 'bash/bash',
  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'ui/acp', 'ui/acp-agent',
+  'session-persistence/session-persistence-jsonl', 'ui/acp', 'examples/acp-demo',
 ]
 const vendorPackages = [
  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -82,7 +82,7 @@ async function makeConsumer(): Promise<string> {
    '- id: bash',
    '  name: \'@deepseek-ai/dsh-bash-local\'',
    '- id: acp-agent',
-    '  name: \'@deepseek-ai/dsh-acp-agent\'',
+    '  name: \'@deepseek-ai/dsh-acp-demo\'',
    '  config:',
    '    model: deepseek-v4-flash',
    '    persona: \'test agent\'',
@@ -100,7 +100,7 @@ afterEach(async () => {
  consumer = undefined
 })

-describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, no tsx)', () => {
  it('boots the published bin and answers an initialize JSON-RPC frame on stdout', async () => {
    consumer = await makeConsumer()
    child = spawn(process.execPath, ['--expose-internals', acpBin, '--config', './cordis.yml'], {
@@ -26,7 +26,7 @@ import {

 const binScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Repo root is four levels up from packages/ui/acp-agent/tests.
+// Repo root is four levels up from packages/examples/acp-demo/tests.
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))

 // A minimal leaf that loads this app + the two backends — the same shape as
@@ -40,7 +40,7 @@ const CORDIS_YML = `
 - id: bash
  name: '@deepseek-ai/dsh-bash-local'
 - id: acp-agent
-  name: '@deepseek-ai/dsh-acp-agent'
+  name: '@deepseek-ai/dsh-acp-demo'
  config:
    model: deepseek-v4-flash
    persona: 'You are a test agent.'
@@ -105,7 +105,7 @@ async function boot(): Promise<Spawned & { cwd: string }> {
  return { ...spawned, cwd }
 }

-describe('dsh-acp-agent real-load-path smoke (bin + Loader, keyless)', () => {
+describe('dsh-acp-demo real-load-path smoke (bin + Loader, keyless)', () => {
  it('boots via its bin and answers initialize → session/new → session/load', async () => {
    const { client, cwd, stderr } = await boot()
    // initialize: a broken export shape (collapsed bridge plugin, dropped inject)
@@ -18,22 +18,22 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    },
    {
-      "path": "../acp"
+      "path": "../../ui/acp"
    },
    {
      "path": "../../core/agent"
    },
    {
-      "path": "../../core/agent-core"
+      "path": "../agent-spine-demo"
    },
    {
-      "path": "../user-interaction"
+      "path": "../../ui/user-interaction"
    },
    {
-      "path": "../tool-ask-user"
+      "path": "../../ui/tool-ask-user"
    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
@@ -1,4 +1,4 @@
-# @deepseek-ai/dsh-agent-core
+# @deepseek-ai/dsh-agent-spine-demo

 The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.

@@ -33,14 +33,14 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
+- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).

 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.

 ## Config

 ```ts
-import type { Config } from '@deepseek-ai/dsh-agent-core'
+import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
 // { agents?, persona?, toolOrder?, tools?, skills?, toolBash?, toolTasks? }
 // The schema intersects the owner schemas,
 // so validation and defaulting can never drift from the owners.
@@ -1,5 +1,5 @@
 {
-  "name": "@deepseek-ai/dsh-agent-core",
+  "name": "@deepseek-ai/dsh-agent-spine-demo",
  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + tasks + invariants + tool-bash + tool-skill + tool-tasks + agent-loop)",
  "version": "0.0.1",
  "private": true,
@@ -1,46 +1,11 @@
 /**
- * The providerless, executor-less, UI-less agent spine as ONE bundle plugin.
- *
- * Loads the fixed set of services every harness agent needs — `timer`, the LLM
- * service, the session store, system-prompt assembly, the tool registry, the
- * skill registry plus local provider, the agent registry, the background task
- * registry + its `task_*` controls, the dev-mode invariants, the model-facing
- * `bash` and `skill` tools, and the concrete `agent-loop` — and forwards the loop's `agents`
- * list as its OWN config (default `[]`), so each app supplies its own
- * pre-created agents.
- *
- * It is deliberately NOT the whole app: the swappable choices stay OUTSIDE the
- * bundle, picked by whatever loads it.
- *  - the LLM ADAPTER (`llm-deepseek`/`llm-pi-ai`/`llm-replay`) — the bundle
- *    ships the abstract `llm` service + `tool-bash` consumer schema; the leaf
- *    registers a concrete adapter on `ctx.llm`.
- *  - the bash EXECUTOR (`bash-local` or a sandboxed impl) — the bundle ships
- *    the `bash` tool consumer; the leaf provides `ctx.bash`.
- *  - the PRESENTATION (stdio UI / ACP bridge / a logger) and the per-app infra
- *    (a console logger, `hmr`) — these are the coupled "front-door cluster" the
- *    app packages ({@link @deepseek-ai/dsh-stdio-agent},
- *    {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine.
- *
- * This is the interface/implementation/consumer seam at the composition level:
- * the bundle owns the shared spine, the leaf owns the backends, the app package
- * owns the front door. `timer` is in the spine (common to every front door — it
- * writes nothing to stdout); the console logger is NOT (it writes to stdout,
- * which the ACP bridge reserves for its JSON-RPC channel).
- *
- * Services register in the root store keyed by their isolate symbol, so a child
- * loaded here via `ctx.plugin(...)` is visible to the bundle's SIBLINGS (the
- * leaf's adapter and executor) exactly as a nested `plugin-include` subtree's
- * services were before this bundle existed — cordis gates every read on
- * `inject`, never on load order, so the fixed child set resolves regardless of
- * which entry loads first.
- *
- * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
- * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
- * default would collapse the module to the bare `apply` function and drop the
- * `Config` schema (see docs/postmortem/0001). The keyless Loader-path smokes in
- * the app packages guard this end-to-end.
- *
- * @module @deepseek-ai/dsh-agent-core
+ * Default executor-less, UI-less agent spine. It bundles the common services,
+ * background-task registry and controls, concrete loop, local skill provider,
+ * and model-facing bash/skill consumers; deployments still choose the LLM
+ * adapter, bash executor, and presentation.
+ * The plugin intentionally exposes named exports only because Loader default
+ * unwrapping would discard its `Config` schema (see docs/postmortem/0001).
+ * @module @deepseek-ai/dsh-agent-spine-demo
 */

 import type { Context } from 'cordis'
@@ -60,7 +25,7 @@ import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'

-export const name = 'agent-core'
+export const name = 'agent-spine-demo'

 /** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
 export interface SkillConfig {
@@ -19,7 +19,7 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
 }

 /**
- * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
+ * Unit coverage for the @deepseek-ai/dsh-agent-spine-demo bundle: mounting it brings
 * up the whole default spine in one `ctx.plugin`, and the forwarded
 * `agents` config reaches the loop (default `[]`, or a pre-created agent).
 *
@@ -31,8 +31,8 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
 async function mount(config?: agentCore.Config, withBash = false): Promise<Context> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
-  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
  const ctx = new Context()
  if (withBash) ctx.provide('bash', { sandboxMode: undefined })
  try {
@@ -58,8 +58,8 @@ async function mount(config?: agentCore.Config, withBash = false): Promise<Conte
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
-  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
  try {
    return await run()
  } finally {
@@ -76,7 +76,7 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  }
 }

-describe('dsh-agent-core bundle', () => {
+describe('dsh-agent-spine-demo bundle', () => {
  it('brings up the full default spine', async () => {
    const ctx = await mount()
    // One service from each layer of the spine proves the children loaded.
@@ -133,9 +133,9 @@ describe('dsh-agent-core bundle', () => {
  })

  it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
-    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-home-'))
-    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-agents-'))
-    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-custom-'))
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-agents-'))
+    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-custom-'))
    await mkdir(custom, { recursive: true })
    await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
    const ctx = await mount({
@@ -212,7 +212,7 @@ describe('dsh-agent-core bundle', () => {

  it('re-exports the loop config schema as its own', () => {
    expect(agentCore.Config).toBeDefined()
-    expect(agentCore.name).toBe('agent-core')
+    expect(agentCore.name).toBe('agent-spine-demo')
  })

  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
@@ -224,7 +224,7 @@ describe('dsh-agent-core bundle', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(agentCore) as Record<string, unknown>
    expect(unwrapped).toBe(agentCore)
-    expect(unwrapped.name).toBe('agent-core')
+    expect(unwrapped.name).toBe('agent-spine-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
@@ -1,10 +1,10 @@
-# @deepseek-ai/dsh-jsonrpc-agent
+# @deepseek-ai/dsh-jsonrpc-demo

-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. `lib/bin.js` is also the [single-executable runtime](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) entry.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../ui/jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. `lib/bin.js` is also the [single-executable runtime](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) entry.

 ## Config discovery

-The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
+The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../ui/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.

 A config without `dsh-jsonrpc` is valid and serves nothing; the bin does not designate a server plugin.

@@ -1,5 +1,5 @@
 {
-  "name": "@deepseek-ai/dsh-jsonrpc-agent",
+  "name": "@deepseek-ai/dsh-jsonrpc-demo",
  "description": "Bin that boots an external Cordis config for the stdio JSON-RPC SDK runtime",
  "version": "0.0.1",
  "private": true,
@@ -7,7 +7,7 @@
 * stdin EOF and SIGTERM dispose the root context and exit 0; SIGINT exits 130.
 * Protocol `shutdown` belongs to the server plugin. Stdout is reserved for frames.
 *
- * @module @deepseek-ai/dsh-jsonrpc-agent/bin
+ * @module @deepseek-ai/dsh-jsonrpc-demo/bin
 */

 import { existsSync } from 'node:fs'
@@ -3,7 +3,7 @@
 * process exit. This module exports no composition plugin; the config chooses
 * whether to load the {@link @deepseek-ai/dsh-jsonrpc} serving plugin.
 *
- * @module @deepseek-ai/dsh-jsonrpc-agent
+ * @module @deepseek-ai/dsh-jsonrpc-demo
 */

 export {}
@@ -15,7 +15,7 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    }
  ]
 }
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-stdio-agent
+# @deepseek-ai/dsh-stdio-demo

-The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.

-It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
+It is the readline counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.

 ## What it bakes in

@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
@@ -28,19 +28,19 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `model` | (required) | the pre-created `main` agent's model |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `agent-core` |
-| `skills` | owner defaults | skill registry, local provider, and model-facing skill-tool config through `agent-core` |
-| `toolBash` | owner defaults | model-facing bash config through `agent-core`, including bash's producer-local `enableRunInBackground` |
-| `toolTasks` | owner defaults | generic `task_output` wait bounds through `agent-core` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
+| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
+| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
+| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |

-Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header.
+Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-demo` was started. Resumed sessions keep the cwd stored in the persisted session header.

 ## The bin

-`dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`, or install the Loader's optional `node-addon-require-builtin` fallback, so the Loader can resolve the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages). The `demo:echo` / `demo:repl` scripts use `--expose-internals`.
+`dsh-stdio-demo [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`, or install the Loader's optional `node-addon-require-builtin` fallback, so the Loader can resolve the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages). The `demo:echo` / `demo:repl` scripts use `--expose-internals`.

 ## Example leaf `cordis.yml`

@@ -60,7 +60,7 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
  config:
    timeoutMs: 60000
 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    model: deepseek-v4-flash
    persona: 'You are a coding assistant powered by the {{model}} model.'
@@ -72,7 +72,7 @@ Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo —

 ### Composed terminal agent request

-**What the model sees**: Through `dsh-agent-core`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.
+**What the model sees**: Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.

 **Token effect**: Child prompt and schema costs repeat per request; user input and tool history grow until compaction. The welcome banner, logger output, and rendered transcript are terminal-only and add zero model tokens.

@@ -1,13 +1,13 @@
 {
-  "name": "@deepseek-ai/dsh-stdio-agent",
-  "description": "Terminal stdio chat app: the agent-core spine + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
+  "name": "@deepseek-ai/dsh-stdio-demo",
+  "description": "Terminal stdio chat app: the agent-spine-demo bundle + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "bin": {
-    "dsh-stdio-agent": "lib/bin.js"
+    "dsh-stdio-demo": "lib/bin.js"
  },
  "exports": {
    ".": {
@@ -36,7 +36,7 @@
    "@cordisjs/plugin-logger-console": "^1.0.0",
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-agent-core": "^0.0.1",
+    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-stdio": "^0.0.1",
@@ -53,7 +53,7 @@
    "@cordisjs/plugin-logger-console": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 /**
- * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-agent [config]`, defaulting to the
+ * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-demo [config]`, defaulting to the
 * cwd file. Shared `.env` loading, fail-loud Loader guards, and settled-tree boot live in
 * dsh-app-boot. The echo and REPL demos invoke this bin with their own leaf configs.
- * @module @deepseek-ai/dsh-stdio-agent/bin
+ * @module @deepseek-ai/dsh-stdio-demo/bin
 */

 import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'

-const NAME = 'dsh-stdio-agent'
+const NAME = 'dsh-stdio-demo'

 /* v8 ignore start -- thin self-executing composition over the unit-tested
   dsh-app-boot helpers; exercised end-to-end by the keyless Loader-path and
@@ -1,12 +1,12 @@
 /**
- * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}) plus the
+ * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}) plus the
 * coupled front-door cluster a terminal chat needs — a console logger, the independently
 * packaged readline UI, JSONL session persistence, the user-interaction seam with its
 * `ask_user_question` tool, and a pre-created `main` agent the UI drives.
 * Swappable adapters, executors, optional tools, and HMR stay in the leaf. This
 * Loader plugin intentionally exposes named exports only; a default export
 * would hide its `Config` schema (see docs/postmortem/0001).
- * @module @deepseek-ai/dsh-stdio-agent
+ * @module @deepseek-ai/dsh-stdio-demo
 */

 import type { Context } from 'cordis'
@@ -15,18 +15,18 @@ import z from 'schemastery'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiStdio from '@deepseek-ai/dsh-stdio'

-export const name = 'stdio-agent'
+export const name = 'stdio-demo'

 /**
 * App config: the swappable per-demo values, each routed to where the app wires
 * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
- * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
+ * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
@@ -40,13 +40,13 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /** Model-facing bash tool config forwarded through agent-core. */
  toolBash?: NonNullable<agentCore.Config['toolBash']>
@@ -80,7 +80,7 @@ export const Config: z<Config> = z.object({

 /**
 * Compose the spine with the stdio front door. The console logger comes first
- * (infra), then the agent-core bundle pre-creating the `main` agent from this
+ * (infra), then the agent-spine-demo bundle pre-creating the `main` agent from this
 * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
 * backend, then the readline UI bound to `main`. The `hmr` dev-reload plugin is
 * a leaf concern (see the module doc), so it is not mounted here.
@@ -14,16 +14,16 @@ import { afterEach, describe, expect, it } from 'vitest'
 */

 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
+const stdioBin = join(repoRoot, 'packages/examples/stdio-demo/lib/bin.js')

 // Symlink each required workspace package by package name so plain Node resolves its built `main`,
 // matching an installed dependency rather than tsconfig paths.
 const dshPackages = [
-  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
  'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
  'bash/tool-bash', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'ui/stdio-agent',
+  'session-persistence/session-persistence-jsonl', 'examples/stdio-demo',
  'ui/stdio', 'ui/tool-ask-user', 'ui/user-interaction',
 ]
 const vendorPackages = [
@@ -71,7 +71,7 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi
    '- id: bash',
    '  name: \'@deepseek-ai/dsh-bash-local\'',
    '- id: stdio-agent',
-    '  name: \'@deepseek-ai/dsh-stdio-agent\'',
+    '  name: \'@deepseek-ai/dsh-stdio-demo\'',
    '  config:',
    '    model: mock-echo',
    '    persona: \'demo\'',
@@ -120,7 +120,7 @@ afterEach(async () => {
  consumer = undefined
 })

-describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+describe.skipIf(!existsSync(stdioBin))('dsh-stdio-demo BUILT bin (node lib/bin.js, no tsx)', () => {
  it('boots the published bin, prints its banner, and runs the echo tool round-trip', async () => {
    consumer = await makeConsumer('BUILT-BIN-OK ready.')
    const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi')
@@ -26,7 +26,7 @@ async function mount(config: stdioAgent.Config, withBash = false): Promise<Conte
 }

 async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<stdioAgent.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-skills-'))
  return {
    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
@@ -45,7 +45,7 @@ async function composePrefix(ctx: Context): Promise<Message[]> {
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-default-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-default-skills-'))
  process.env.DSH_HOME = join(home, '.dsh')
  process.env.DSH_AGENTS_HOME = join(home, '.agents')
  try {
@@ -64,9 +64,9 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  }
 }

-describe('dsh-stdio-agent app', () => {
+describe('dsh-stdio-demo app', () => {
  it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec', skills: await isolatedSkillsConfig() })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig() })
    // The spine services (brought up by the agent-core bundle) are all present.
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('agentLoop')).toBeDefined()
@@ -112,7 +112,7 @@ describe('dsh-stdio-agent app', () => {
    const ctx = await mount({
      model: 'mock',
      persona: 'hi',
-      persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-resume',
      resumeSessionId: 'no-such-session',
      skills: await isolatedSkillsConfig(),
    })
@@ -141,7 +141,7 @@ describe('dsh-stdio-agent app', () => {
  })

  it('exposes its name and Config schema', () => {
-    expect(stdioAgent.name).toBe('stdio-agent')
+    expect(stdioAgent.name).toBe('stdio-demo')
    expect(stdioAgent.Config).toBeDefined()
  })

@@ -149,7 +149,7 @@ describe('dsh-stdio-agent app', () => {
    const ctx = await mount({
      model: 'mock',
      toolOrder: ['zulu', TOOL_ORDER_REST],
-      persistenceRoot: '/tmp/dsh-stdio-agent-spec-tool-order',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-tool-order',
    })
    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
    // this providerless mount, so register two plain tools to order.
@@ -175,7 +175,7 @@ describe('dsh-stdio-agent app', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(stdioAgent) as Record<string, unknown>
    expect(unwrapped).toBe(stdioAgent)
-    expect(unwrapped.name).toBe('stdio-agent')
+    expect(unwrapped.name).toBe('stdio-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
@@ -18,7 +18,7 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    },
    {
      "path": "../../../vendor/logger-console"
@@ -30,16 +30,16 @@
      "path": "../../core/session"
    },
    {
-      "path": "../../core/agent-core"
+      "path": "../agent-spine-demo"
    },
    {
-      "path": "../user-interaction"
+      "path": "../../ui/user-interaction"
    },
    {
-      "path": "../stdio"
+      "path": "../../ui/stdio"
    },
    {
-      "path": "../tool-ask-user"
+      "path": "../../ui/tool-ask-user"
    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
@@ -0,0 +1,7 @@
+# MCP — Model Context Protocol
+
+Packages bridging the harness to the MCP ecosystem.
+
+| Package | Role |
+|---|---|
+| `mcp-client/` | MCP client bridge: connects to external MCP servers and registers their tools on `ctx.tools` |
@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-mcp-client
+
+MCP client bridge plugin: connects to external [Model Context Protocol](https://modelcontextprotocol.io/) servers and registers their tools on `ctx.tools`, making them available to the model as native tools under server-qualified names (`mcp__<serverName>__<rawName>`).
+
+## Usage
+
+One plugin instance per MCP server in `cordis.yml`:
+
+```yaml
+- id: mcp-github
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
+```
+
+The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged `serverName` reproduces identical tool names.
+
+## Config
+
+| Field | Transport | Required | Description |
+|---|---|---|---|
+| `transport` | both | yes | `"stdio"` or `"streamable-http"` |
+| `serverName` | both | yes | Namespace for this server's model-facing tool names; `[A-Za-z0-9_-]{1,32}`, unique across live instances |
+| `command` | stdio | yes | Executable to spawn |
+| `args` | stdio | no | Arguments passed to the command |
+| `env` | stdio | no | Extra env vars merged on top of scrubbed ambient env |
+| `cwd` | stdio | no | Working directory for the child process |
+| `url` | http | yes | MCP server URL |
+| `headers` | http | no | Extra headers (e.g. auth tokens) |
+| `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+
+## Tool naming
+
+Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`) and the public name `mcp__<serverName>__<rawName>` registered on `ctx.tools`. Public names are normalized to the DeepSeek function-name contract (64 chars, `[A-Za-z0-9_-]`); when replacement or truncation changes the name, a deterministic 12-hex-char hash of `(serverName, rawName)` is appended so distinct tools never collapse into one name. Names are pure functions of `(serverName, rawName)` — connection order, re-syncs, and other servers never rename a tool.
+
+- Two servers publishing the same raw name (e.g. `search`) coexist under their namespaces.
+- A duplicate `serverName` across live instances fails the later plugin instance at load.
+- A server listing the same tool name twice is rejected as an invalid tool list.
+- A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.
+
+## Behavior
+
+- On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
+- Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
+- Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support — the public name is never sent to the server.
+- Image content in results is discarded with a placeholder (the harness has no image block type).
+- On disconnect/crash: all tools are unregistered; no auto-reconnect.
+
+## Services consumed
+
+| Service | Usage |
+|---|---|
+| `ctx.tools` | Register/unregister MCP tools |
+
+## Model Experience
+
+### Discovered MCP tools
+
+**What the model sees**: After initial discovery succeeds, each advertised MCP tool appears as a native tool named `mcp__<serverName>__<rawName>` (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync replaces the generation; plugin disposal removes it.
+
+**Token effect**: Data-dependent schema cost is paid on every request while the tools are registered. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.
+
+### Tool-call history and results
+
+**What the model sees**: The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained text result; image, audio, resource, and unsupported blocks become short placeholders, and MCP `isError` results follow the registry's model-visible error path.
+
+**Token effect**: Arguments and mapped text are retained until compaction. Binary and resource payloads are discarded rather than added to context.
+
+## Known Limitations and Deferred Work
+
+- **Initial discovery is asynchronous** — plugin load does not wait for connection and `listTools()`, so a turn started immediately after boot or HMR can assemble before the MCP tools are registered.
+- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Crash recovery is manual** — transport closure unregisters the server's tools, but reconnect requires an HMR reload or harness restart.
+- **Non-text results are lossy** — image, audio, and resource payloads are replaced with placeholders, and a structured-only result has no model-visible structured representation.
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-mcp-client",
+  "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@modelcontextprotocol/server-everything": "^2026.7.4",
+    "@modelcontextprotocol/server-filesystem": "^2026.7.4",
+    "cordis": "^4.0.0-rc.7",
+    "zod": "^4.4.3"
+  }
+}
--- a/Show More
+++ b/Show More