refactor(examples): extract the app spine into dsh-agent-core + app packages

Implements docs/rfc/.../2026-06-20-extract-example-app-packages.md. Each
example was thick — a hand-rolled start.ts, an infra preamble, nested
base.yml/base-core.yml/acp-tail.yml includes, and a coupled front-door
cluster enforced only by prose. This moves the composition into packages so
each example is a thin leaf cordis.yml: pick the swappable backends, load one
app package.

New packages:
  - @deepseek-ai/dsh-agent-core (packages/core/agent-core): one bundle plugin
    that loads the providerless/executor-less/UI-less spine (timer + llm +
    sessions + system-prompt + tools + agents + invariants + tool-bash +
    agent-loop) via ctx.plugin(...) inside apply(), and forwards agent-loop's
    `agents` list as its own Config (export const Config = AgentLoop.Config,
    default []).
  - @deepseek-ai/dsh-stdio-agent (packages/ui/stdio-agent): terminal chat APP —
    agent-core + console logger + readline UI + a pre-created `main` agent, with
    a bin. The demo:echo/coding front door.
  - @deepseek-ai/dsh-acp-agent (packages/ui/acp-agent): ACP server APP —
    agent-core + JSONL persistence + the acp bridge, NO stdout logger, with a
    bin. The stdout-purity footgun is structurally unreachable from the leaf.

Amendment to the RFC: hmr stays a LEAF cordis.yml entry, not baked into
dsh-stdio-agent. hmr is a Loader-only dev plugin (throws without
--expose-internals; the in-process test tier can't even import its decorator
form), so a package statically importing it could never carry the per-file
coverage gate. Unlike the console logger, a stray hmr is not a stdout-purity
footgun, so leaving it at the leaf costs no safety. With hmr out, all three new
packages carry in-process unit specs at 100%.

Boot glue (Loader tail, .env load, snapshot-mode selection, stdin-dispose
lifecycle) moves into each app's bin; start.ts and base.yml/base-core.yml/
acp-tail.yml are deleted. Each app package gets a keyless real-load-path test
that boots through its bin + the cordis Loader (guarding the unwrapExports
export-shape bug class, postmortem 0001). ACP snapshot replay stays green
against the existing committed goldens (pure boot restructuring). RFC moved
proposed->implemented with the amendment recorded; package/example/architecture
docs and the module graph updated.

packages/core/README.md

@@ -9,5 +9,8 @@ The packages every harness build is assembled from: the session log, the system-
 | `tools/` | Tool registry + `tools/execute` waterfall | `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 providerless/executor-less/UI-less spine as code | (loads the spine) |
 
 `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 whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `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 only the swappable backends. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own.

packages/core/agent-core/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-agent-core
+
+The **providerless, executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs 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.
+
+This is the package to read to see **the whole plugin tree at once** — the teaching role the inlined `echo-agent` `cordis.yml` used to play before the spine moved behind this bundle.
+
+## The tree it loads
+
+`apply(ctx, config)` mounts each of these as a child of the bundle fiber:
+
+```
+@cordisjs/plugin-timer            timer service (writes nothing to stdout)
+@deepseek-ai/dsh-llm              abstract LLM service + content-block vocabulary
+@deepseek-ai/dsh-session          event-sourced session log + store
+@deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
+@deepseek-ai/dsh-tools            tool registry + tools/execute waterfall
+@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
+@deepseek-ai/dsh-invariants       dev-mode event-contract assertions
+@deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
+@deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
+```
+
+## What it deliberately leaves OUTSIDE the bundle
+
+The spine is everything COMMON to every front door. The swappable and front-door-coupled pieces stay out, picked by whatever loads the bundle:
+
+- **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).
+- **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).
+
+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'
+// Config === AgentLoop.Config — the `agents` list, default [].
+```
+
+The bundle FORWARDS `agent-loop`'s `agents` list as its own (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`). Forwarding the list is exactly why the loop can live in the shared spine even though the apps disagree on which agents to pre-create.
+
+## Why a code bundle, not a shared YAML include
+
+A YAML include can dedupe the config, but it cannot OWN a `bin`, and it can only *describe* the front-door coupling in a comment and trust each leaf to obey. Moving the spine into a package, and the front-door cluster into the app packages, turns "the ACP app never logs to stdout" from a prose warning into a property of the artifact. Services register in the root store keyed by their isolate symbol, so a child loaded here is visible to the bundle's siblings (the leaf's adapter and executor) exactly as a nested `plugin-include` subtree's services were — cordis gates every read on `inject`, never on load order.

packages/core/agent-core/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-agent-core",
+  "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + agent-loop)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-timer": "^1.1.2",
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tool-bash": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/core/agent-core/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * 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
+ * agent registry, the dev-mode invariants, the model-facing `bash` tool
+ * schemas, 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
+ */
+
+import type { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import * as invariants from '@deepseek-ai/dsh-invariants'
+import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
+
+export const name = 'agent-core'
+
+/**
+ * Bundle config: the agent-loop `agents` list, forwarded verbatim. Default `[]`
+ * — an app that pre-creates no agents (the ACP bridge creates them on demand at
+ * `session/new`) simply omits it; an app that needs a pre-created `main` (the
+ * stdio chat) supplies one. This IS {@link AgentLoopConfig}, so the schema and
+ * the forwarded shape can never drift.
+ */
+export type Config = AgentLoopConfig
+
+/** Forward the loop's own schema so validation + defaulting stay identical. */
+export const Config = AgentLoop.Config
+
+/**
+ * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
+ * `agent-loop` receives the forwarded `agents` list. Load order is irrelevant
+ * (cordis pends each fiber on its `inject` until the services it needs exist),
+ * but the listing mirrors the dependency layering for readability: the LLM
+ * vocabulary and core registries first, then the dev tripwire and the bash tool
+ * consumer, then the loop that drives them.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(Timer)
+  ctx.plugin(LlmService)
+  ctx.plugin(SessionStore)
+  ctx.plugin(SystemPrompt)
+  ctx.plugin(ToolRegistry)
+  ctx.plugin(AgentRegistry)
+  ctx.plugin(invariants)
+  ctx.plugin(toolBash)
+  ctx.plugin(AgentLoop, { agents: config.agents })
+}

packages/core/agent-core/tests/agent-core.spec.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import * as agentCore from '../src/index.ts'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+
+/**
+ * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
+ * up the whole providerless spine in one `ctx.plugin`, and the forwarded
+ * `agents` config reaches the loop (default `[]`, or a pre-created agent).
+ *
+ * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE
+ * import, the same shape the Loader builds from `unwrapExports`. The real
+ * Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
+ * bin smokes; here we assert the composition + config forwarding.
+ */
+async function mount(config?: agentCore.Config): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(agentCore, config)
+  // The bundle mounts its children inside apply() (not awaited there); let their
+  // fibers settle so the spine services and any pre-created agent are ready.
+  await new Promise(resolve => setTimeout(resolve, 50))
+  return ctx
+}
+
+describe('dsh-agent-core bundle', () => {
+  it('brings up the full providerless spine', async () => {
+    const ctx = await mount()
+    // One service from each layer of the spine proves the children loaded.
+    expect(ctx.get('timer')).toBeDefined()
+    expect(ctx.get('llm')).toBeDefined()
+    expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('systemPrompt')).toBeDefined()
+    expect(ctx.get('tools')).toBeDefined()
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults the agents list to empty (no pre-created agents)', async () => {
+    const ctx = await mount()
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('forwards a pre-created agent to the loop', async () => {
+    const ctx = await mount({
+      agents: [{ id: AgentId('main'), model: 'mock', systemPrompt: 'hi' }],
+    })
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('re-exports the loop config schema as its own', () => {
+    expect(agentCore.Config).toBeDefined()
+    expect(agentCore.name).toBe('agent-core')
+  })
+})

packages/core/agent-core/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/timer"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/agent-loop"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../bash/tool-bash"
+    }
+  ]
+}