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

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 */

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 })
+}