Merge remote-tracking branch 'origin/master' into feat/adr0016-type-build-check

examples/coding-agent/README.md

@@ -32,15 +32,16 @@ RESUME_SESSION_ID=<prior-session-id> pnpm run demo:coding
 
 The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent.
 
-## What each plugin demonstrates
+## What each leaf entry demonstrates
+
+This example is a thin leaf `cordis.yml`: it picks the swappable backends and loads one app package. 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) all 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 — so the leaf has only four entries:
 
 | 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:coding` 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`) + `tool-bash` | the executor seam + tool schemas as separate plugins |
-| `agent-loop` | agent created from config with a coding system prompt |
-| `session-persistence` (`dsh-session-persistence-jsonl`) | durable JSONL persistence (`root: ./.sessions`): append-only event log per session, crash-safe atomic writes — the shared backend, no per-example file |
-| `src/stdio-chat.ts` | UI as a plugin; copied from echo-agent with reasoning-dimming and an exit-on-idle close handler for piped stdin. Example-local on purpose — extract a shared UI package when a third example needs it |
+| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) 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 |
 
 ## End-to-end tests (`pnpm run test:e2e`, key-gated)
 

examples/coding-agent/cordis.yml

@@ -1,59 +1,59 @@
-# The coding-agent plugin tree, loaded via @cordisjs/plugin-include.
-# Infra (logger/timer/hmr) first, then the shared provider/tool core (nested
-# include of ../base.yml), then this example's agent-loop config + UI.
+# The coding-agent plugin tree: the real coding agent. 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, invariants, tool-bash, agent-loop), the console
+# logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
 #
-# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
-# environment — start.ts loads the gitignored repo-root .env first.
-
-- id: logger
-  name: '@cordisjs/plugin-logger-console'
-
-- id: timer
-  name: '@cordisjs/plugin-timer'
+# `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
+# dev plugin that needs `--expose-internals` — the `demo:coding` 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.
 
+# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
 - id: hmr
   name: '@cordisjs/plugin-hmr'
   config:
     root: ['.']
 
-# Shared provider/tool core (llm, sessions, system-prompt, tools, agents,
-# invariants, llm-deepseek, bash-local, tool-bash). Nested include: the path is
-# resolved relative to THIS file's directory.
-- id: base
-  name: '@cordisjs/plugin-include'
+# The DeepSeek adapter. Swap to '@deepseek-ai/dsh-llm-pi-ai' for the pi-ai-backed
+# twin (same config shape; `reasoning: high` replaces thinking/reasoningEffort).
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
   config:
-    path: '../base.yml'
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-flash
+      - deepseek-v4-pro
 
-# agent-loop is per-example (NOT in base.yml): coding-agent pre-creates a `main`
-# agent its stdio-chat drives via ctx.agents.get('main').
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
+# Local bash executor (the model's only tool, via agent-core's tool-bash schema).
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
   config:
-    agents:
-      - id: main
-        model: deepseek-v4-flash
-        # Set RESUME_SESSION_ID to continue a prior persisted session (the ids
-        # live under ./.sessions); unset starts a fresh session each run.
-        resumeSessionId: !!js process.env.RESUME_SESSION_ID
-        systemPrompt: |
-          You are coding-agent, a CLI coding assistant.
+    timeoutMs: 60000
 
-          Your only tools are bash (plus bash_output/bash_kill for background
-          tasks). Do ALL file operations through bash: read with cat/sed/head,
-          search with grep, write with heredocs (cat <<'EOF' > file), edit
-          with sed or a rewrite. Each bash call runs in a fresh shell — pass
-          workdir instead of cd, and never rely on shell state between calls.
-
-          Check the [exit code: N] marker on every command; investigate
-          failures before moving on. Verify your work by running the code or
-          tests. Keep answers brief and factual.
-
-- id: session-persistence
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: './.sessions'
-
-- id: stdio-chat
-  name: '@deepseek-ai/dsh-ui-stdio'
+# The stdio chat app: the whole spine + front-door cluster, configured for a
+# real coding agent driving a pre-created `main` agent.
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
   config:
+    model: deepseek-v4-flash
+    # Set RESUME_SESSION_ID to continue a prior persisted session (the ids live
+    # under ./.sessions); unset starts a fresh session each run.
+    resumeSessionId: !!js process.env.RESUME_SESSION_ID
+    persistenceRoot: './.sessions'
     welcome: 'coding-agent ready. Give it a coding task (bash is its only tool).'
+    systemPrompt: |
+      You are coding-agent, a CLI coding assistant.
+
+      Your only tools are bash (plus bash_output/bash_kill for background
+      tasks). Do ALL file operations through bash: read with cat/sed/head,
+      search with grep, write with heredocs (cat <<'EOF' > file), edit
+      with sed or a rewrite. Each bash call runs in a fresh shell — pass
+      workdir instead of cd, and never rely on shell state between calls.
+
+      Check the [exit code: N] marker on every command; investigate
+      failures before moving on. Verify your work by running the code or
+      tests. Keep answers brief and factual.

examples/coding-agent/start.ts

@@ -1,30 +0,0 @@
-import { pathToFileURL } from 'node:url'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-
-// Load DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL from a gitignored repo-root .env
-// (Node >= 21.7 native). Absent file is fine — the environment may already
-// carry the variables; cordis.yml reads them via the `!!js` tag. A
-// present-but-unreadable/malformed .env is a real misconfiguration: surface it
-// rather than silently running with the wrong environment.
-try {
-  process.loadEnvFile(new URL('../../.env', import.meta.url).pathname)
-} catch (error) {
-  if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
-    process.stderr.write(`coding-agent: failed to load .env: ${String(error)}\n`)
-  }
-  // ENOENT (no .env) is fine — rely on the ambient environment.
-}
-
-// Boot a Cordis app from this example's cordis.yml — the same shape as the
-// upstream `cordis` bin, pinned to this directory.
-const ctx = new Context()
-ctx.baseUrl = pathToFileURL(import.meta.dirname).href + '/'
-
-await ctx.plugin(Loader)
-await ctx.loader.create({
-  name: '@cordisjs/plugin-include',
-  config: {
-    path: './cordis.yml',
-  },
-})

examples/coding-agent/tests/coding-task.e2e.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
+import { AgentId } from '@deepseek-ai/dsh-agent'
 import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness'
 
 /**
@@ -53,7 +54,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('coding task: fix a failing test
     expect(before.status).not.toBe(0)
 
     ctx = await codingHarness(workdir)
-    const agent = ctx.agentLoop.create('e2e-task', {
+    const agent = ctx.agentLoop.create(AgentId('e2e-task'), {
       model: 'deepseek-v4-flash',
       systemPrompt: SYSTEM_PROMPT,
     })

examples/coding-agent/tests/full-loop.e2e.ts

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
+import { AgentId } from '@deepseek-ai/dsh-agent'
 import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness'
 
 /**
@@ -20,7 +21,7 @@ afterEach(async () => {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('full loop: real model + real bash tool', () => {
   it('runs a bash command on request and reports its output', async () => {
     ctx = await codingHarness(process.cwd())
-    const agent = ctx.agentLoop.create('e2e-loop', {
+    const agent = ctx.agentLoop.create(AgentId('e2e-loop'), {
       model: 'deepseek-v4-flash',
       systemPrompt: SYSTEM_PROMPT,
     })

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

@@ -7,21 +7,28 @@ import { afterEach, describe, expect, it } from 'vitest'
 
 /**
  * Keyless Loader-path smoke for examples/coding-agent: boot the REAL example
- * through its `cordis.yml` (the cordis Loader, `unwrapExports`, the full plugin
- * tree incl. the extracted `@deepseek-ai/dsh-ui-stdio`), then close stdin with
- * no prompt and assert the ready banner + a clean exit.
+ * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` (the
+ * cordis Loader, `unwrapExports`, the full plugin tree incl. the
+ * `@deepseek-ai/dsh-agent-core` bundle and the extracted
+ * `@deepseek-ai/dsh-ui-stdio`), then close stdin with no prompt and assert the
+ * ready banner + a clean exit.
  *
  * No prompt is ever sent, so the model is NEVER called — this is why it runs
  * without a real key. coding-agent's `cordis.yml` loads `llm-deepseek`, whose
  * `apply()` only requires a key to be PRESENT (it does not validate it and only
  * uses it when a stream actually starts), so a dummy key lets the tree boot
  * while the absence of any prompt guarantees no network call. The value is the
- * real-Loader-path guard for the shared UI plugin's export shape (a broken
- * `export default` that drops `inject` would crash here — see postmortem 0001),
- * complementing coding-agent's with-key e2e suites which prove the real product.
+ * real-Loader-path guard for the app + bundle + UI plugin export shapes (a broken
+ * `export default` that drops `inject`/`Config` would crash here — see postmortem
+ * 0001), complementing coding-agent's with-key e2e suites which prove the real
+ * product.
  */
 
-const startScript = fileURLToPath(new URL('../start.ts', import.meta.url))
+// The dsh-stdio-agent bin (the demo:coding entry) and this example's cordis.yml.
+// The bin resolves its config-path arg from CWD; the test spawns from a temp
+// cwd, so we pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
 // `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
@@ -45,7 +52,7 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> {
     const proc = spawn(
       process.execPath,
       // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:coding).
-      ['--expose-internals', '--import', tsxLoader, startScript],
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
       {
         cwd,
         env: {

examples/coding-agent/tests/resume.e2e.ts

@@ -4,6 +4,8 @@ import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
 import type { Context } from 'cordis'
 import type { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness'
 
 /**
@@ -15,7 +17,7 @@ import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness'
  */
 
 const SECRET = 'plum-galaxy-1791'
-const SESSION_ID = 'resume-e2e-session'
+const SESSION_ID = SessionId('resume-e2e-session')
 
 let ctx: Context | undefined
 let root: string | undefined
@@ -38,10 +40,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     // log on disk survives.
     ctx = await codingHarness(process.cwd(), root)
     const first = ctx.agents.create({
-      agentId: 'resume-1',
+      agentId: AgentId('resume-1'),
       sessionId: SESSION_ID,
       agentOptions: { model: 'deepseek-v4-flash', systemPrompt: SYSTEM_PROMPT },
-    }) as ReactLoopAgent
+    }).agent as ReactLoopAgent
     first.send([{ type: 'text', text: `Remember this code for later: ${SECRET}. Just acknowledge it.` }])
     await waitForIdle(ctx, first)
     await ctx.fiber.dispose()
@@ -51,11 +53,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     // session. The loaded event log seeds the live session, so the model sees
     // run 1's exchange as conversation history.
     ctx = await codingHarness(process.cwd(), root)
-    const resumed = await ctx.agents.resume({
-      agentId: 'resume-2',
+    const resumed = (await ctx.agents.resume({
+      agentId: AgentId('resume-2'),
       resumeSessionId: SESSION_ID,
       agentOptions: { model: 'deepseek-v4-flash', systemPrompt: SYSTEM_PROMPT },
-    }) as ReactLoopAgent
+    })).agent as ReactLoopAgent
     expect(resumed.session.id).toBe(SESSION_ID)
     // The prior user turn is in the rehydrated log before the model is asked.
     expect(JSON.stringify(resumed.session.deriveMessages())).toContain(SECRET)