feat(examples): add one-shot CLI demo

examples/README.md

@@ -1,6 +1,6 @@
 # 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-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`.
+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-cli-demo`](../packages/examples/cli-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
 
@@ -17,7 +17,7 @@ Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigge
 
 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.
+Run interactively with `pnpm run demo:repl`, or run one headless task with `pnpm run demo:cli -- "task"` (both need `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
 
 Run the Code Mode overlay with `pnpm run demo:code-mode`, or pass `acp` for the ACP example. See the [Code Mode example](coding-agent/README.md#code-mode) for its composition and a sample task.
 

examples/coding-agent/README.md

@@ -1,6 +1,6 @@
 # coding-agent
 
-The REPL agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + stdio chat + JSONL persistence, loaded from `cordis.yml`. The UI is a terminal readline REPL.
+Coding-agent demo wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + workflows + `todo_write` + JSONL persistence. `cordis.yml` runs the terminal readline REPL; `cli.cordis.yml` keeps the same coding capabilities behind a headless one-shot CLI.
 
 ## Run it
 
@@ -17,10 +17,24 @@ Type a coding task. The agent works through the `read`/`write`/`edit` filesystem
 > fix the failing test in /path/to/project
 [main turn 1] (reasoning…)
   [tool call] bash({"command": "node --test", "workdir": "/path/to/project"})
-  [tool result] … [exit code: 1]
+[tool result] … [exit code: 1]
   …
 ```
 
+### One-shot CLI
+
+Run one task through all model and tool steps, flush its fresh session, print the final result, and exit:
+
+```sh
+pnpm run demo:cli -- "fix the failing test in this workspace"
+pnpm run demo:cli --output-format json -- "summarize the current implementation"
+pnpm run demo:cli --output-format stream-json -- "run the focused tests"
+```
+
+The root command supplies `cli.cordis.yml`, which disables HMR and the REPL app and inserts [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo). Exactly one quoted positional task is required; there is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the parent `main` session's canonical task-turn events before that record. Non-completed turns retain partial output but exit nonzero; argument and boot failures leave stdout empty.
+
+This is non-interactive automation with the same local bash, filesystem, skill, subagent, workflow, and todo capabilities as the REPL. It can mutate the launch workspace and spend provider tokens. No prompt, approval, resume, further turn, or stdin context is available in v1; see the [CLI package contract](../../packages/examples/cli-demo/README.md).
+
 ### Resuming a prior session
 
 Each run starts a fresh session by default (its event log lands under `./.sessions/`). To **continue** a previous conversation, set `RESUME_SESSION_ID` to that session's id — the `main` agent then rehydrates the persisted log instead of starting fresh, so the model sees the earlier turns as history:
@@ -55,7 +69,7 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 | `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`/`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-demo`) | 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 |
+| `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the REPL 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 |
 | `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 |
@@ -69,4 +83,4 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 - `tests/compaction.e2e.ts` — the compaction smoke: a real multi-step bash task runs with a deliberately tiny context window so the auto-compaction listener fires MID-SESSION. Verifies the WORLD — a `compact/start…end` pair landed in the real log, the surface shrank (a replace node shadowed older nodes), and the agent still produced a correct final answer after compaction.
 - `tests/todo-write.e2e.ts` — a real model drives the real `todo_write` tool and the test verifies the resulting `todo/write` session event.
 
-These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless boot smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` (the full real tree, dummy key, no prompt → no model call) and `tests/code-mode-keyless-smoke.e2e.ts` (the same guard for the Code Mode overlay).
+These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. `tests/cli.e2e.ts` runs the one-shot bin with a real model and verifies its temporary file externally. The keyless Loader smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts`, `tests/code-mode-keyless-smoke.e2e.ts`, and `tests/cli-keyless-smoke.e2e.ts`; the CLI smoke mocks only the LLM boundary and asserts a real bash round trip plus persisted stream output.

examples/coding-agent/cli.cordis.yml

@@ -0,0 +1,24 @@
+# One-shot headless overlay: keep the coding capabilities from `cordis.yml`,
+# replace its REPL app with the stdout-pure CLI app, and disable dev-only HMR.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: hmr
+        name: '@cordisjs/plugin-hmr'
+        disabled: true
+      - id: stdio-agent
+        name: '@deepseek-ai/dsh-stdio-demo'
+        disabled: true
+      - insert:
+          - id: cli-agent
+            name: '@deepseek-ai/dsh-cli-demo'
+            config:
+              model: deepseek-v4-flash
+              persistenceRoot: './.sessions'
+              persona: |
+                You are coding-agent, a coding assistant powered by the {{model}} model.
+
+                Verify your work by running the code or tests. Keep answers brief and
+                factual.

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

@@ -0,0 +1,43 @@
+import { readdir } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+describe('coding-agent one-shot CLI keyless smoke', () => {
+  it('boots the real Loader tree, runs a real bash tool round trip, and persists the turn', async () => {
+    let persisted = false
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'coding-agent CLI',
+      tempDirPrefix: 'coding-cli-smoke-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'prove the tool path'],
+      tsconfigPath,
+      inspect: async (cwd) => {
+        const files = await readdir(cwd, { recursive: true })
+        persisted = files.some(file => file.endsWith('.jsonl'))
+      },
+    })
+    const lines = stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent)
+    const result = lines.at(-1)
+    expect(stderr).toBe('')
+    expect(events.some(event => event.type === 'tool/call' && event.data.name === 'bash')).toBe(true)
+    const toolResult = events.find(event => event.type === 'tool/result')
+    expect(JSON.stringify(toolResult)).toContain('CLI_TOOL_ROUND_TRIP')
+    expect(result).toMatchObject({
+      type: 'result',
+      success: true,
+      turn: 1,
+      reason: { kind: 'completed' },
+      usage: { inputTokens: 18, outputTokens: 8, cacheReadTokens: 2, reasoningTokens: 1 },
+    })
+    expect(String(result?.['result'])).toContain('CLI_TOOL_ROUND_TRIP')
+    expect(persisted).toBe(true)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})

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

@@ -0,0 +1,33 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cli.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const hasKey = Boolean(process.env.DEEPSEEK_API_KEY)
+
+describe.skipIf(!hasKey)('coding-agent one-shot CLI with real model', () => {
+  it('modifies a temporary workspace and verifies the file outside the agent', async () => {
+    let verified = ''
+    const { stdout } = await runLoaderSmoke({
+      label: 'coding-agent CLI real model',
+      tempDirPrefix: 'coding-cli-real-',
+      binScript,
+      configPath,
+      binArgs: [
+        '--config',
+        configPath,
+        'Read task.txt, replace its complete contents with exactly "value=after" followed by a newline, read it again, and report briefly.',
+      ],
+      tsconfigPath,
+      processTimeoutMs: 120_000,
+      prepare: cwd => writeFile(join(cwd, 'task.txt'), 'value=before\n'),
+      inspect: async (cwd) => { verified = await readFile(join(cwd, 'task.txt'), 'utf8') },
+    })
+    expect(verified).toBe('value=after\n')
+    expect(stdout.trim().length).toBeGreaterThan(0)
+  }, 135_000)
+})

examples/coding-agent/tests/fixtures/cli-mock-llm.ts

@@ -0,0 +1,37 @@
+import type { Context } from 'cordis'
+import { CallId, LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+/** Keyless coding smoke adapter: one real bash call followed by a final answer. */
+class CliMockAdapter extends LlmAdapter {
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const toolResult = options.messages.at(-1)?.content.find(block => block.type === 'tool-result')
+    if (toolResult === undefined) {
+      const args = JSON.stringify({ command: 'printf CLI_TOOL_ROUND_TRIP', description: 'Prove the CLI tool round trip.' })
+      yield { type: 'block-start', index: 0, blockType: 'tool-call' }
+      yield { type: 'tool-call-delta', index: 0, id: CallId('cli-smoke-call'), name: 'bash', argumentsDelta: args }
+      yield { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('cli-smoke-call'), name: 'bash', arguments: args } }
+      yield { type: 'usage', usage: { inputTokens: 11, outputTokens: 3, cacheReadTokens: 2 } }
+      yield { type: 'finish', reason: { kind: 'tool-calls' } }
+      return
+    }
+
+    const toolText = toolResult.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    const reply = `CLI tool round trip complete: ${toolText.trim()}`
+    yield { type: 'block-start', index: 0, blockType: 'text' }
+    yield { type: 'text-delta', index: 0, text: reply }
+    yield { type: 'block-end', index: 0, block: { type: 'text', text: reply } }
+    yield { type: 'usage', usage: { inputTokens: 7, outputTokens: 5, reasoningTokens: 1 } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+export const name = 'cli-mock-llm'
+export const inject = ['llm']
+
+/** Register the keyless `cli-mock` adapter. */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['cli-mock'], new CliMockAdapter())
+}

examples/coding-agent/tests/fixtures/cli.cordis.yml

@@ -0,0 +1,24 @@
+- id: cli-mock-llm
+  name: './cli-mock-llm.ts'
+
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ../../cordis.yml
+    patches:
+      - id: hmr
+        name: '@cordisjs/plugin-hmr'
+        disabled: true
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: stdio-agent
+        name: '@deepseek-ai/dsh-stdio-demo'
+        disabled: true
+      - insert:
+          - id: cli-agent
+            name: '@deepseek-ai/dsh-cli-demo'
+            config:
+              model: cli-mock
+              persistenceRoot: './.sessions'
+              persona: 'Keyless CLI smoke.'