Merge remote-tracking branch 'origin/master' into worktree/provider-routed-llm-adapters

# Conflicts: # docs/config-catalog.md # packages/examples/acp-demo/tests/acp-agent.spec.ts # packages/examples/stdio-demo/README.md # packages/examples/stdio-demo/src/index.ts # packages/examples/stdio-demo/tests/stdio-agent.spec.ts
2026-07-15 20:14:09 +08:00
parent d24e212f96 5ee9217146
commit f47a87fcf5
138 changed files with 613 additions and 530 deletions
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -0,0 +1,58 @@
+# @deepseek-ai/dsh-acp-demo
+
+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-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
+
+stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it LEAVES OUT as what it includes:
+
+| Plugin | Why |
+|---|---|
+| `@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](../../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.)
+
+## Config
+
+| Key | Default | Routed to |
+|---|---|---|
+| `provider` | (required) | the initial provider route for each per-session agent the bridge creates; ACP model selection may replace it per session |
+| `model` | (required) | the initial model for each per-session agent; ACP clients may switch among adapter-advertised models |
+| `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{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 (`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` |
+| `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-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`);
+- in a snapshot run, disposes the context on stdin EOF so the session log is fully flushed before exit.
+
+Run it under `node --expose-internals`, or Loader's optional `node-addon-require-builtin` fallback is required, so the cordis Loader can resolve the config's bare plugin specifiers through its internal module loader. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
+
+All diagnostics go to **stderr** — stdout is the protocol.
+
+## Model Experience
+
+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
+
+- **JSONL persistence is baked in** — config chooses its root but cannot select a different backend; that requires a sibling entry or differently composed app package.
+- **User-question and approval mechanisms are omitted by default** — the bridge can answer both when their services/tools are composed, but this front door does not enable those deployment policies itself.
+- **A leaf can still corrupt stdout** — the app mounts no console logger, but it cannot prevent a sibling leaf entry from writing non-protocol bytes to the ACP channel.
--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -0,0 +1,58 @@
+{
+  "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-demo": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./bin": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-include": "^1.0.4",
+    "@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-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",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.17.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-acp": "workspace:^",
+    "@deepseek-ai/dsh-agent": "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:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "cordis": "^4.0.0-rc.7",
+    "schemastery": "^3.17.0"
+  }
+}
--- a/packages/examples/acp-demo/src/bin.ts
+++ b/packages/examples/acp-demo/src/bin.ts
@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Boot an ACP stdio server from `cordis.yml`; usage is
+ * `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-demo/bin
+ */
+
+import { parseArgs } from 'node:util'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+
+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
+   built-bin smoke */
+installFailLoud(NAME)
+const snapshotMode = process.env['DSH_SNAPSHOT']
+if (snapshotMode !== 'replay') loadEnv(NAME)
+const { values } = parseArgs({
+  args: process.argv.slice(2),
+  options: { config: { type: 'string', short: 'c' } },
+  strict: true,
+})
+const ctx = await boot(NAME, resolveConfigPath(values.config ?? './cordis.yml', snapshotMode))
+if (snapshotMode !== undefined) {
+  process.stdin.on('end', () => {
+    void ctx.fiber.dispose().then(() => { process.exit(0) })
+  })
+}
+/* v8 ignore stop */
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -0,0 +1,84 @@
+/**
+ * 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-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-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-demo'
+
+/**
+ * App config: the swappable per-deployment values. `provider` and `model` configure the
+ * agent template the ACP bridge creates each session's agent from (NOT a
+ * pre-created agent — ACP creates agents at `session/new`); `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);
+ * `tools` is the tool registry's config (its presentation `mode`, forwarded
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
+ */
+export interface Config {
+  /** Provider route for ACP-created agents. */
+  provider: string
+  /** Model name for ACP-created agents (must have a registered adapter). */
+  model: string
+  /** Deployment persona (the system-prompt plugin's `persona` 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-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-spine-demo. */
+  skills?: agentCore.SkillConfig
+}
+
+// Each front door owns a complete, directly readable config schema; extracting
+// the common fields would make two small app contracts depend on a new facade.
+/* jscpd:ignore-start */
+export const Config: z<Config> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  persona: z.string(),
+  // The array default is forced to undefined: ABSENT means "lexicographic
+  // order" (the owning dsh-system-prompt schema does the same), while
+  // schemastery's native [] default would read as an invalid configured list.
+  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
+  tools: ToolRegistry.Config,
+  // TODO(single-default-literal): share this schema default and the defensive
+  // apply() fallback through one named constant while retaining both boundaries.
+  persistenceRoot: z.string().default('./.sessions'),
+  skills: agentCore.SkillConfigSchema,
+})
+/* jscpd:ignore-end */
+
+/**
+ * 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`
+ * from the provider/model pair. No logger, no `hmr` — stdout stays pure.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(agentCore, {
+    ...config.persona !== undefined ? { persona: config.persona } : {},
+    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
+    ...config.tools !== undefined ? { tools: config.tools } : {},
+    ...config.skills !== undefined ? { skills: config.skills } : {},
+  })
+  ctx.plugin(UserInteractionService)
+  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
+  ctx.plugin(acp, { provider: config.provider, model: config.model })
+}
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -0,0 +1,155 @@
+import { describe, expect, it } from 'vitest'
+import { mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+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-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.
+ *
+ * The REAL Loader-path guard (export shape via `unwrapExports`, the headline
+ * ACP operations end-to-end) is the keyless bin smoke in `load-path.e2e.ts`;
+ * this spec asserts the composition and the persistenceRoot default branch.
+ */
+async function mount(config: acpAgent.Config): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(acpAgent, config)
+  // The bundle mounts its children inside apply() (not awaited there); let their
+  // fibers settle so the spine services are ready.
+  await new Promise(resolve => setTimeout(resolve, 50))
+  return ctx
+}
+
+async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<acpAgent.Config['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 } } : {},
+  }
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const agent = { session: { header: { cwd: '/tmp' } } } as unknown as Agent
+  const empty: Message[] = []
+  return await agentEvents(ctx, agent).waterfall(
+    'agent/session-prefix', empty, new AbortController().signal,
+    () => Promise.resolve(empty),
+  )
+}
+
+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-demo-default-skills-'))
+  process.env.DSH_HOME = join(home, '.dsh')
+  process.env.DSH_AGENTS_HOME = join(home, '.agents')
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
+describe('dsh-acp-demo composition', () => {
+  it('brings up the spine + persistence + the ACP bridge', async () => {
+    const ctx = await mount({ provider: 'mock', 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()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('userInteraction')).toBeDefined()
+    expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
+    // No pre-created agents — ACP session/new creates them on demand.
+    expect(ctx.get('agents')!.list()).toHaveLength(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults the persistence root when omitted', async () => {
+    // Exercises the `?? './.sessions'` fallback for a direct-apply caller that
+    // bypasses the schema's `.default(...)`: call `apply` directly (not via
+    // `ctx.plugin`, which validates+defaults the config first) with no
+    // persistenceRoot, so the runtime fallback is the one that fires.
+    const ctx = new Context()
+    // No persona: covers the omitted-persona forwarding branch too.
+    acpAgent.apply(ctx, { provider: 'mock', model: 'mock', skills: await isolatedSkillsConfig() })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('uses default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      acpAgent.apply(ctx, { provider: 'mock', model: 'mock' })
+      await new Promise(resolve => setTimeout(resolve, 50))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
+  it('forwards skill config into agent-core', async () => {
+    const ctx = await mount({ provider: 'mock', model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+    ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' })
+    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...')
+    await ctx.fiber.dispose()
+  })
+
+  it('exposes its plugin shape', () => {
+    expect(acpAgent.name).toBe('acp-demo')
+    expect(acpAgent.Config).toBeDefined()
+  })
+
+  it('forwards toolOrder through agent-core to the system-prompt assembly', async () => {
+    const ctx = await mount({
+      provider: 'mock',
+      model: 'mock',
+      toolOrder: ['zulu', TOOL_ORDER_REST],
+      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.
+    for (const name of ['alpha', 'zulu']) {
+      ctx.get('tools')!.register({
+        name,
+        description: name,
+        parameters: {},
+        execute: async () => [],
+      })
+    }
+    const assembly = await ctx.get('systemPrompt')!.assemble()
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'skill'])
+    await ctx.fiber.dispose()
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
+    // A default export would make `unwrapExports` collapse this inject-less namespace and silently
+    // drop `name`/`Config` while the app still boots. Guard the postmortem-0001 shape directly.
+    expect('default' in acpAgent).toBe(false)
+    expect(typeof acpAgent.apply).toBe('function')
+
+    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-demo')
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -0,0 +1,188 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, mkdir, rm, symlink, writeFile, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+import { Readable, Writable } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and
+ * require a valid initialize response. This catches built-only settle races and stdout protocol
+ * leaks that the tsx source-path smoke cannot. It skips before build; initialize is keyless, with a
+ * dummy key used only to boot the adapter. `--expose-internals` enables Cordis bare-plugin loading.
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const acpBin = join(repoRoot, 'packages/examples/acp-demo/lib/bin.js')
+
+const dshPackages = [
+  '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', 'examples/acp-demo',
+]
+const vendorPackages = [
+  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
+  'schemastery', 'cosmokit',
+]
+// Resolve ACP's declared third-party dependencies from that package, not this test: pnpm's strict
+// layout need not hoist them. Symlink those exact paths into the plain-Node consumer.
+const npmDeps = ['@agentclientprotocol/sdk', 'zod']
+const acpPkgDir = join(repoRoot, 'packages/ui/acp')
+
+async function pkgName(absDir: string): Promise<string> {
+  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
+  return json.name
+}
+
+async function link(target: string, name: string, nm: string): Promise<void> {
+  const dest = join(nm, name)
+  await mkdir(dirname(dest), { recursive: true })
+  await symlink(target, dest)
+}
+
+/** Build a temp consumer dir + a minimal acp `cordis.yml`. Returns the dir. */
+async function makeConsumer(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'acp-built-bin-'))
+  const nm = join(dir, 'node_modules')
+  for (const rel of dshPackages) {
+    const abs = join(repoRoot, 'packages', rel)
+    await link(abs, await pkgName(abs), nm)
+  }
+  for (const v of vendorPackages) {
+    const abs = join(repoRoot, 'vendor', v)
+    await link(abs, await pkgName(abs), nm)
+  }
+  for (const dep of npmDeps) {
+    // Resolve from `ui/acp`'s package.json URL (the package that declares the
+    // dep), not this test file's location — `acp-agent` does not depend on these.
+    const fromAcp = pathToFileURL(join(acpPkgDir, 'package.json')).href
+    const resolved = fileURLToPath(import.meta.resolve(`${dep}/package.json`, fromAcp))
+    await link(dirname(resolved), dep, nm)
+  }
+  await writeFile(join(dir, 'cordis.yml'), [
+    '- id: llm-deepseek',
+    '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
+    '  config:',
+    '    apiKey: !!js process.env.DEEPSEEK_API_KEY',
+    '- id: bash',
+    '  name: \'@deepseek-ai/dsh-bash-local\'',
+    '- id: acp-agent',
+    '  name: \'@deepseek-ai/dsh-acp-demo\'',
+    '  config:',
+    '    provider: deepseek',
+    '    model: deepseek-v4-flash',
+    '    persona: \'test agent\'',
+    '',
+  ].join('\n'))
+  return dir
+}
+
+let consumer: string | undefined
+let child: ReturnType<typeof spawn> | undefined
+
+afterEach(async () => {
+  if (child !== undefined) { child.kill('SIGKILL'); child = undefined }
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+  consumer = undefined
+})
+
+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'], {
+      cwd: consumer,
+      // Dummy key: initialize never reaches the model, so it is never used.
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+        DSH_HOME: join(consumer, '.dsh'),
+        DSH_AGENTS_HOME: join(consumer, '.agents'),
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    const stderr: string[] = []
+    child.stderr!.setEncoding('utf8')
+    child.stderr!.on('data', (c: string) => stderr.push(c))
+    // Tee raw stdout for a protocol-purity check, and feed it to the SDK client.
+    const rawOut: string[] = []
+    const passthrough = new Readable({ read() {} })
+    child.stdout!.on('data', (buf: Buffer) => { rawOut.push(buf.toString('utf8')); passthrough.push(buf) })
+    child.stdout!.on('end', () => passthrough.push(null))
+    const stream = ndJsonStream(
+      Writable.toWeb(child.stdin!) as WritableStream<Uint8Array>,
+      Readable.toWeb(passthrough) as ReadableStream<Uint8Array>,
+    )
+    const makeClient = (_a: AcpAgent): Client => ({
+      sessionUpdate(_p: SessionNotification): Promise<void> { return Promise.resolve() },
+      requestPermission(_p: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+      },
+    })
+    const client = new ClientSideConnection(makeClient, stream)
+
+    const init = await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    // A response at all proves the built bin booted the bridge (the settle-race
+    // regression would exit before answering); loadSession proves the real app
+    // mounted, not a collapsed export shape.
+    expect(init.agentCapabilities?.loadSession).toBe(true)
+    expect(stderr.join('')).not.toContain('without inject')
+    // stdout purity: every emitted line is a JSON-RPC frame, no logger leak.
+    for (const line of rawOut.join('').split('\n').filter(l => l.trim().length > 0)) {
+      expect(() => JSON.parse(line) as unknown).not.toThrow()
+    }
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
+    // boot() pre-resolves the bootstrap include to an absolute URL, so a nonexistent config
+    // directory cannot break its import; the include plugin's own read must fail loud instead.
+    const { code, stderr } = await runBinExpectingExit('/nonexistent/dir/cordis.yml')
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('config file not found')
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => {
+    // Existing directory plus missing config exercises the include plugin's fail-loud path.
+    consumer = await makeConsumer()
+    const { code, stderr } = await runBinExpectingExit('./does-not-exist.yml', consumer)
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('config file not found')
+  }, 30_000)
+})
+
+/** Spawn the built acp bin against `configArg` and resolve with its exit code + stderr. */
+function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise<{ code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, ['--expose-internals', acpBin, '--config', configArg], {
+      cwd,
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    child = proc
+    let stderr = ''
+    proc.stderr.setEncoding('utf8')
+    proc.stderr.on('data', (c: string) => { stderr += c })
+    const timer = setTimeout(() => { proc.kill('SIGKILL'); reject(new Error(`bin did not exit within 25s. stderr:\n${stderr}`)) }, 25_000)
+    proc.on('exit', (code) => { clearTimeout(timer); resolve({ code: code ?? -1, stderr }) })
+    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
+    proc.stdin.end()
+  })
+}
--- a/packages/examples/acp-demo/tests/load-path.e2e.ts
+++ b/packages/examples/acp-demo/tests/load-path.e2e.ts
@@ -0,0 +1,135 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { Readable, Writable } from 'node:stream'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+
+/**
+ * Source-path Loader smoke through the package's own bin, covering initialize, session/new, and
+ * session/load across the `unwrapExports` path implicated by postmortem 0001. Session creation and
+ * unknown-id loading reach factories but not the model, so a dummy key is sufficient. The temp cwd
+ * is also the session workspace, and an explicit root tsconfig keeps unbuilt path aliases resolvable
+ * when the child starts outside the repository.
+ */
+
+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/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
+// examples/acp-agent/cordis.yml, inlined so the package test owns its fixture.
+const CORDIS_YML = `
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+- id: acp-agent
+  name: '@deepseek-ai/dsh-acp-demo'
+  config:
+    provider: deepseek
+    model: deepseek-v4-flash
+    persona: 'You are a test agent.'
+`
+
+interface Spawned {
+  child: ChildProcessWithoutNullStreams
+  client: ClientSideConnection
+  stderr: string[]
+}
+
+let spawned: Spawned | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (spawned !== undefined) {
+    spawned.child.kill('SIGKILL')
+    spawned = undefined
+  }
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function boot(): Promise<Spawned & { cwd: string }> {
+  workdir = await mkdtemp(join(tmpdir(), 'acp-agent-pkg-'))
+  const cwd = workdir
+  const configPath = join(cwd, 'cordis.yml')
+  await writeFile(configPath, CORDIS_YML)
+  const child = spawn(
+    process.execPath,
+    ['--import', tsxLoader, binScript, '--config', configPath],
+    {
+      cwd,
+      env: {
+        ...process.env,
+        TSX_TSCONFIG_PATH: repoTsconfig,
+        // Key-present check only; no prompt is sent, so the model is never called.
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'keyless-acp-agent-smoke',
+        DSH_HOME: join(cwd, '.dsh'),
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    },
+  )
+  const stderr: string[] = []
+  child.stderr.setEncoding('utf8')
+  child.stderr.on('data', (chunk: string) => stderr.push(chunk))
+  const stream = ndJsonStream(
+    Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+  )
+  const makeClient = (_agent: AcpAgent): Client => ({
+    sessionUpdate(_params: SessionNotification): Promise<void> {
+      return Promise.resolve()
+    },
+    requestPermission(_params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+      return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+    },
+  })
+  const client = new ClientSideConnection(makeClient, stream)
+  spawned = { child, client, stderr }
+  return { ...spawned, cwd }
+}
+
+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)
+    // crashes the tree on the first service read here — see postmortem 0001.
+    const init = await client.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: {},
+    })
+    expect(init.agentCapabilities?.loadSession).toBe(true)
+
+    // session/new reaches the agent FACTORY (create) without the model.
+    const { sessionId } = await client.newSession({ cwd, mcpServers: [] })
+    expect(sessionId).toBeTruthy()
+
+    // session/load reaches the resume FACTORY + persistence without the model: load an UNKNOWN
+    // id (loading the live `sessionId` would correctly reject as "already loaded"). Persistence
+    // and resume run from the JSON-RPC loop outside bridge injection; a healthy tree reaches
+    // not-found, while a collapsed export would fail earlier with missing injection.
+    const unknownId = '00000000-0000-4000-8000-000000000000'
+    await client.loadSession({ sessionId: unknownId, cwd, mcpServers: [] }).then(
+      () => { throw new Error('expected session/load of an unknown id to reject') },
+      (error: unknown) => { expect(String(error)).not.toContain('without inject') },
+    )
+
+    expect(stderr.join('')).not.toContain('without inject')
+  }, 30_000)
+})
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../ui/app-boot"
+    },
+    {
+      "path": "../../ui/acp"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../agent-spine-demo"
+    },
+    {
+      "path": "../../ui/user-interaction"
+    },
+    {
+      "path": "../../ui/tool-ask-user"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    }
+  ]
+}
--- a/packages/examples/acp-demo/tsdown.config.ts
+++ b/packages/examples/acp-demo/tsdown.config.ts
@@ -0,0 +1,19 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * acp-agent ships TWO entries: the plugin (`index`) and the CLI `bin` (`bin`),
+ * the latter referenced by package.json `bin`/`exports["./bin"]`. The root
+ * tsdown builds only `lib/types/index.js`, so this override adds
+ * `lib/types/bin.js`. Declarations come from `tsc -b` (dts: false),
+ * matching every package.
+ */
+export default defineConfig({
+  entry: ['lib/types/index.js', 'lib/types/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})