dsh-live-trace 0.1.0

package/scripts/demo.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * Offline demo: run the real dashboard against a scripted trace, with no
+ * Harness and no model provider involved.
+ *
+ * This exists so the board can be seen (and its layout checked) in a second,
+ * without installing the plugin anywhere. It drives the same `TraceHub` and
+ * `createTraceServer` the Host plugin uses, so what appears on screen is the
+ * production rendering path.
+ *
+ *   node scripts/demo.mjs [--duration <ms>] [--no-color]
+ *
+ * Without `--duration` the board stays live until you press q in it.
+ */
+
+import { spawn } from 'node:child_process'
+import { mkdirSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { serversDir } from '../lib/paths.js'
+import { writeServerRecord } from '../lib/registry.js'
+import { TraceHub } from '../lib/tracker.js'
+import { createTraceServer } from '../lib/transport.js'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+function parseArgs(argv) {
+  const options = { duration: undefined, color: true }
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === '--duration') options.duration = Number.parseInt(argv[index + 1], 10)
+    else if (argv[index] === '--no-color') options.color = false
+  }
+  return options
+}
+
+const options = parseArgs(process.argv.slice(2))
+const runtimeDir = join(tmpdir(), `dsh-live-trace-demo-${process.pid}`)
+const socketPath = join(runtimeDir, 'sockets', `${process.pid}.sock`)
+const sessionId = 'session-6e3caa1a-3c38-4222-8d66-0bb3b8c30c45'
+const startedAt = Date.now()
+const session = { id: sessionId, header: { createdAt: startedAt, cwd: process.cwd(), agentPreset: 'standard' }, seq: 0 }
+
+const hub = new TraceHub({ now: () => Date.now(), streamIntervalMs: 500, backlogSize: 500 })
+const server = createTraceServer({
+  socketPath,
+  runtimeDir,
+  hub,
+  serverInfo: () => ({ pid: process.pid, version: 'demo', profile: 'demo', cwd: process.cwd() }),
+  heartbeatMs: 2000
+})
+await server.ready
+
+mkdirSync(serversDir(runtimeDir), { recursive: true })
+const publishRegistry = () => {
+  writeServerRecord(serversDir(runtimeDir), {
+    pid: process.pid,
+    socket: socketPath,
+    version: 'demo',
+    profile: 'demo',
+    cwd: process.cwd(),
+    startedAt,
+    heartbeat: Date.now(),
+    activeSessionId: sessionId,
+    sessions: [
+      { id: sessionId, createdAt: startedAt, cwd: process.cwd(), title: 'live trace demo', turn: 3, step: 2 }
+    ]
+  })
+}
+publishRegistry()
+
+const child = spawn(
+  process.execPath,
+  [
+    join(HERE, '..', 'bin', 'dsh-live-trace.js'),
+    '--runtime-dir',
+    runtimeDir,
+    '--session',
+    sessionId,
+    // Force the full-screen board even when the demo's own stdout is a pipe,
+    // which is what a capture or a CI check needs.
+    '--alt-screen',
+    ...(options.color ? [] : ['--no-color'])
+  ],
+  { stdio: 'inherit' }
+)
+
+let finished = false
+/** Tear down the viewer, the socket, and the temporary runtime directory. */
+function finish() {
+  if (finished) return
+  finished = true
+  child.kill('SIGTERM')
+  server.close().finally(() => {
+    rmSync(runtimeDir, { recursive: true, force: true })
+    process.exit(0)
+  })
+}
+// Registered before the script runs: the viewer may quit at any moment.
+child.on('exit', finish)
+process.on('SIGINT', finish)
+process.on('SIGTERM', finish)
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+let seq = 0
+const appendEvent = (type, data) => hub.onSessionEvent(session, { type, seq: seq++, time: Date.now(), data })
+
+async function script() {
+  hub.onSessionCreated(session, 'startup')
+  appendEvent('permission/preset', { preset: 'workspace-write' })
+  appendEvent('sandbox/mode', { mode: 'workspace-write' })
+  appendEvent('approval/policy', { policy: 'ask' })
+  hub.onAgentCreated({ options: { provider: 'deepseek-official', model: 'deepseek-flash' }, session }, 'startup')
+  appendEvent('turn/start', { turn: 3 })
+  await sleep(400)
+  appendEvent('step/start', { turn: 3, step: 1 })
+  appendEvent('session/title', { title: 'live trace demo', messageSeqs: [] })
+  appendEvent('user/message', {
+    id: 'u1',
+    role: 'user',
+    content: [{ type: 'text', text: '把登录逻辑抽到 src/auth.ts，并补上测试' }],
+    source: { kind: 'user' }
+  })
+  await sleep(300)
+
+  hub.onAssistantStream({ session }, { type: 'start', attemptId: 'attempt-1', revision: 1, turn: 3, step: 1 })
+  for (const text of ['先读一下现有的登录代码，', '确认调用点，', '再决定抽象边界…']) {
+    hub.onAssistantStream(
+      { session },
+      { type: 'chunk', attemptId: 'attempt-1', revision: 1, index: 0, time: Date.now(), chunk: { type: 'text-delta', index: 0, text } }
+    )
+    hub.flushStreams()
+    await sleep(320)
+  }
+  appendEvent('assistant/message', {
+    turn: 3,
+    step: 1,
+    message: {
+      id: 'a1',
+      role: 'assistant',
+      content: [
+        {
+          type: 'reasoning',
+          text: [
+            '先确认 `login()` 的所有调用点，再决定抽象边界。',
+            '',
+            '1. 只有两处直接调用，都在 `src/routes/` 里。',
+            '2. 会话创建逻辑已经在 `src/session.ts`，可以直接复用。',
+            '3. 把校验逻辑留在原文件，导出 `login()` 即可。',
+            '4. 测试需要覆盖：正常登录、错误密码、会话过期。',
+            '5. lint 规则要求显式返回类型，所以要标注 `Promise<Session>`。'
+          ].join('\n')
+        },
+        {
+          type: 'text',
+          text: [
+            '## 计划',
+            '',
+            '把 `login()` 抽到 **src/auth.ts**，然后跑测试：',
+            '',
+            '- 读取 `src/login.ts`',
+            '- 写入新模块',
+            '- 运行 `npm test`',
+            '',
+            '```ts',
+            'export async function login(user: string): Promise<Session> {',
+            '  // 校验并创建会话',
+            '  return createSession(user)',
+            '}',
+            '```'
+          ].join('\n')
+        }
+      ],
+      source: { kind: 'model' }
+    },
+    stream: [],
+    usage: { inputTokens: 3200, outputTokens: 180, totalTokens: 3380 }
+  })
+  await sleep(200)
+
+  const calls = [
+    { id: 'c1', name: 'read_file', args: { path: 'src/login.ts' }, result: '返回 234 行', ms: 300 },
+    { id: 'c2', name: 'write_file', args: { path: 'src/auth.ts' }, result: '写入 96 行', ms: 300 },
+    { id: 'c3', name: 'bash', args: { command: 'npm test', description: 'Run the test suite' }, result: '测试通过 (12 passed)', ms: 900 },
+    { id: 'c4', name: 'bash', args: { command: 'npm run lint', description: 'Lint the workspace' }, result: '2 problems (0 errors, 2 warnings)', ok: false, ms: 700 }
+  ]
+  for (const call of calls) {
+    appendEvent('tool/call', { turn: 3, step: 1, callId: call.id, name: call.name, arguments: JSON.stringify(call.args) })
+    await sleep(240)
+    appendEvent('tool/result', {
+      turn: 3,
+      step: 1,
+      message: {
+        id: `r-${call.id}`,
+        role: 'tool',
+        toolCallId: call.id,
+        isError: call.ok === false,
+        content: [{ type: 'text', text: call.result }],
+        source: { kind: 'tool', callId: call.id }
+      },
+      ...(call.ok === false ? { error: { name: 'LintError', code: 'LINT_WARNINGS', reason: '2 warnings' } } : {})
+    })
+    await sleep(call.ms)
+  }
+
+  // A file write whose content exists only in the call arguments, exactly like
+  // a real `write` tool creating a new file.
+  const writeArgs = JSON.stringify({
+    file_path: 'src/auth.ts',
+    content: [
+      "import { createSession, type Session } from './session'",
+      '',
+      'export async function login(user: string): Promise<Session> {',
+      '  return createSession(user)',
+      '}',
+      ''
+    ].join('\n')
+  })
+  appendEvent('tool/call', { turn: 3, step: 1, callId: 'c5', name: 'write', arguments: writeArgs })
+  await sleep(260)
+  appendEvent('tool/result', {
+    turn: 3,
+    step: 1,
+    message: {
+      id: 'r-c5',
+      role: 'tool',
+      toolCallId: 'c5',
+      content: [{ type: 'text', text: 'wrote 96 bytes to src/auth.ts' }],
+      source: { kind: 'tool', callId: 'c5' }
+    },
+    meta: { operation: 'create', diffs: [] }
+  })
+  await sleep(400)
+
+  appendEvent('approval/asked', { id: 'ap-1', toolName: 'bash', reason: 'runs outside the sandbox' })
+  await sleep(1000)
+  appendEvent('approval/decided', { id: 'ap-1', outcome: 'allowed-once' })
+  await sleep(300)
+
+  appendEvent('step/start', { turn: 3, step: 2 })
+  appendEvent('assistant/message', {
+    turn: 3,
+    step: 2,
+    message: {
+      id: 'a2',
+      role: 'assistant',
+      content: [
+        {
+          type: 'text',
+          text: [
+            '### 完成',
+            '',
+            '登录逻辑已抽到 `src/auth.ts`：',
+            '',
+            '| 检查 | 结果 |',
+            '| --- | --- |',
+            '| 测试 | 12 passed |',
+            '| lint | 2 warnings |',
+            '',
+            '```bash',
+            '$ npm test',
+            '✓ 12 passed',
+            '```'
+          ].join('\n')
+        }
+      ],
+      source: { kind: 'model' }
+    },
+    stream: [],
+    usage: { inputTokens: 4400, outputTokens: 260, totalTokens: 4660 }
+  })
+  appendEvent('request/context', { provider: 'deepseek-official', model: 'deepseek-flash', capacity: 1_000_000 })
+  appendEvent('turn/end', { turn: 3, reason: { kind: 'completed' } })
+  publishRegistry()
+}
+
+await script()
+
+if (Number.isFinite(options.duration)) {
+  setTimeout(finish, options.duration)
+} else {
+  process.stdout.write('\nDemo trace complete. The board stays live — press q in the dashboard to exit.\n')
+}

package/scripts/install-profile.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Wire `dsh-live-trace` into a DSH profile's composition.
+ *
+ * This is a file-level installer: it edits the profile's `package.json`
+ * (dependency + bundle selection) and links the package into the profile's
+ * `node_modules`. It deliberately does not run a package manager, so it works
+ * offline and never touches the packages pnpm already manages. Use
+ * `dsh plugin --profile <name> add <dir>` instead when you would rather have
+ * pnpm own the dependency.
+ *
+ *   node scripts/install-profile.mjs [--profile web] [--home <dsh-home>]
+ *                                    [--package <dir>] [--uninstall] [--dry-run]
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = 'dsh-live-trace'
+const HERE = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_DIR = resolve(HERE, '..')
+
+function parseArgs(argv) {
+  const options = { profile: 'web', home: undefined, packageDir: PACKAGE_DIR, uninstall: false, dryRun: false, link: true }
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = () => {
+      const next = argv[index + 1]
+      if (next === undefined || next.startsWith('--')) throw new Error(`missing value for ${argv[index]}`)
+      index += 1
+      return next
+    }
+    switch (argv[index]) {
+      case '--profile':
+        options.profile = value()
+        break
+      case '--home':
+        options.home = resolve(value())
+        break
+      case '--package':
+        options.packageDir = resolve(value())
+        break
+      case '--uninstall':
+        options.uninstall = true
+        break
+      case '--dry-run':
+        options.dryRun = true
+        break
+      case '--no-link':
+        options.link = false
+        break
+      case '--help':
+        options.help = true
+        break
+      default:
+        throw new Error(`unknown option: ${argv[index]}`)
+    }
+  }
+  return options
+}
+
+function resolveHome(explicit) {
+  if (explicit !== undefined) return explicit
+  const fromEnv = process.env.DSH_HOME
+  if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) return resolve(fromEnv.trim())
+  return join(homedir(), '.dsh')
+}
+
+const HELP = `dsh-live-trace profile installer
+
+  --profile <name>   DSH profile to wire up (default: web)
+  --home <dir>       DSH home (default: $DSH_HOME or ~/.dsh)
+  --package <dir>    package directory to link (default: this package)
+  --no-link          edit package.json only; do not create a node_modules link
+  --uninstall        remove the dependency, bundle entry, and link
+  --dry-run          print what would change and exit
+  --help             show this message
+`
+
+function main() {
+  const options = parseArgs(process.argv.slice(2))
+  if (options.help === true) {
+    process.stdout.write(HELP)
+    return 0
+  }
+
+  const home = resolveHome(options.home)
+  const profileDir = join(home, 'profiles', options.profile)
+  const manifestPath = join(profileDir, 'package.json')
+  const linkPath = join(profileDir, 'node_modules', PACKAGE_NAME)
+
+  if (!existsSync(manifestPath)) {
+    process.stderr.write(
+      `dsh-live-trace: no profile manifest at ${manifestPath}\n` +
+        `Create the profile first (booting it once with "dsh --profile ${options.profile}" does this),\n` +
+        'or pass --home to point at the right DSH home.\n'
+    )
+    return 1
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  const dependencySpec = `link:${options.packageDir}`
+
+  if (options.uninstall === true) {
+    if (manifest.dependencies?.[PACKAGE_NAME] !== undefined) delete manifest.dependencies[PACKAGE_NAME]
+    removeFromBundles(manifest, PACKAGE_NAME)
+    if (options.dryRun !== true) {
+      writeManifest(manifestPath, manifest)
+      rmSync(linkPath, { force: true })
+    }
+    process.stdout.write(`dsh-live-trace: ${options.dryRun ? 'would remove from' : 'removed from'} ${manifestPath}\n`)
+    return 0
+  }
+
+  manifest.dependencies = { ...(manifest.dependencies ?? {}), [PACKAGE_NAME]: dependencySpec }
+  const bundles = manifest.dsh?.profile?.bundles
+  if (!Array.isArray(bundles)) {
+    process.stderr.write(
+      `dsh-live-trace: ${manifestPath} has no dsh.profile.bundles list, so the plugin cannot be selected.\n` +
+        'Add one (see any shipped profile template) and re-run.\n'
+    )
+    return 1
+  }
+  const added = !bundles.includes(PACKAGE_NAME)
+  if (added) bundles.push(PACKAGE_NAME)
+
+  if (options.dryRun === true) {
+    process.stdout.write(`would write ${manifestPath}:\n${JSON.stringify(manifest, null, 2)}\n`)
+    if (options.link) process.stdout.write(`would link ${linkPath} -> ${options.packageDir}\n`)
+    return 0
+  }
+
+  writeManifest(manifestPath, manifest)
+
+  if (options.link === true) {
+    mkdirSync(join(profileDir, 'node_modules'), { recursive: true })
+    rmSync(linkPath, { recursive: true, force: true })
+    symlinkSync(options.packageDir, linkPath, 'dir')
+  }
+
+  process.stdout.write(
+    [
+      `dsh-live-trace: installed into profile "${options.profile}"`,
+      `  manifest: ${manifestPath}`,
+      `  dependency: ${PACKAGE_NAME} -> ${dependencySpec}`,
+      options.link ? `  link: ${linkPath} -> ${options.packageDir}` : '  link: skipped (--no-link)',
+      '',
+      'Next:',
+      `  1. restart the Harness (or let it hot-reload): dsh --profile ${options.profile}`,
+      '  2. in another terminal, run: dsh-live-trace',
+      ''
+    ].join('\n')
+  )
+  return 0
+}
+
+function removeFromBundles(manifest, name) {
+  const bundles = manifest.dsh?.profile?.bundles
+  if (!Array.isArray(bundles)) return
+  const index = bundles.indexOf(name)
+  if (index !== -1) bundles.splice(index, 1)
+}
+
+function writeManifest(path, manifest) {
+  writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`)
+}
+
+try {
+  process.exitCode = main()
+} catch (error) {
+  process.stderr.write(`dsh-live-trace: ${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 2
+}

package/scripts/mock-provider.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+/**
+ * A minimal Anthropic-Messages-compatible SSE provider.
+ *
+ * DEVELOPMENT TOOL — not part of the plugin's runtime. It exists so the whole
+ * pipeline (real agent loop -> real session events -> observer plugin ->
+ * `dsh-live-trace`) can be exercised offline, without a provider account:
+ *
+ *   node scripts/mock-provider.mjs &                      # listens on 127.0.0.1:8799
+ *   DEEPSEEK_BASE_URL=http://127.0.0.1:8799 \
+ *   DEEPSEEK_API_KEY=sk-mock \
+ *   dsh --profile <profile> "<task>"
+ *
+ * Turn 1 streams thinking + text and asks for one `bash` call; turn 2 streams a
+ * final answer. Env: MOCK_LLM_PORT, MOCK_LLM_CHUNK_DELAY_MS.
+ */
+
+
+import { createServer } from 'node:http'
+
+const PORT = Number(process.env.MOCK_LLM_PORT ?? 8799)
+const CHUNK_DELAY_MS = Number(process.env.MOCK_LLM_CHUNK_DELAY_MS ?? 90)
+
+function send(res, event) {
+  res.write(`event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`)
+}
+
+function sse(res, events) {
+  let chain = Promise.resolve()
+  for (const event of events) {
+    chain = chain.then(
+      () =>
+        new Promise((resolve) => {
+          setTimeout(() => {
+            send(res, event)
+            resolve()
+          }, CHUNK_DELAY_MS)
+        })
+    )
+  }
+  return chain
+}
+
+function firstToolTurn() {
+  return [
+    { type: 'message_start', message: { usage: { input_tokens: 4200, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '用户想看这个插件的实现，' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '所以我先列一下目录，再看入口文件。' } },
+    { type: 'content_block_stop', index: 0 },
+    { type: 'content_block_start', index: 1, content_block: { type: 'text', text: '' } },
+    { type: 'content_block_delta', index: 1, delta: { type: 'text_delta', text: '我先看看项目结构，' } },
+    { type: 'content_block_delta', index: 1, delta: { type: 'text_delta', text: '然后读一下插件的入口。' } },
+    { type: 'content_block_stop', index: 1 },
+    {
+      type: 'content_block_start',
+      index: 2,
+      content_block: {
+        type: 'tool_use',
+        id: 'toolu_01',
+        name: 'bash',
+        input: {
+          command: 'ls -1 dsh-live-trace && echo "--- entry ---" && head -4 dsh-live-trace/index.js',
+          description: 'Inspect the plugin package layout'
+        }
+      }
+    },
+    { type: 'content_block_stop', index: 2 },
+    { type: 'message_delta', delta: { stop_reason: 'tool_use' }, usage: { output_tokens: 186 } },
+    { type: 'message_stop' }
+  ]
+}
+
+/** Second turn: run something that produces rich, multi-line output. */
+function commandTurn() {
+  return [
+    { type: 'message_start', message: { usage: { input_tokens: 4600, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '接着跑一遍测试，确认当前状态。' } },
+    { type: 'content_block_stop', index: 0 },
+    {
+      type: 'content_block_start',
+      index: 1,
+      content_block: {
+        type: 'tool_use',
+        id: 'toolu_02',
+        name: 'bash',
+        input: {
+          command: 'cd dsh-live-trace && node --test test/width.test.js test/tools.test.js 2>&1 | tail -12',
+          description: 'Run the measurement and tool-helper tests'
+        }
+      }
+    },
+    { type: 'content_block_stop', index: 1 },
+    { type: 'message_delta', delta: { stop_reason: 'tool_use' }, usage: { output_tokens: 96 } },
+    { type: 'message_stop' }
+  ]
+}
+
+/** Third turn: write a file, so the edits panel has a real diff to show. */
+function writeTurn() {
+  const scratch = process.env.MOCK_LLM_SCRATCH ?? './demo-scratch.md'
+  return [
+    { type: 'message_start', message: { usage: { input_tokens: 5200, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '把结论写成一个文件，顺便演示 diff 面板。' } },
+    { type: 'content_block_stop', index: 0 },
+    {
+      type: 'content_block_start',
+      index: 1,
+      content_block: {
+        type: 'tool_use',
+        id: 'toolu_03',
+        name: 'write',
+        input: {
+          file_path: scratch,
+          content: '# dsh-live-trace\n\n一个只读的实时看板。\n\n- Host 插件订阅 session/event\n- 归一化后经 unix socket 推送\n- 独立终端渲染\n'
+        }
+      }
+    },
+    { type: 'content_block_stop', index: 1 },
+    { type: 'message_delta', delta: { stop_reason: 'tool_use' }, usage: { output_tokens: 128 } },
+    { type: 'message_stop' }
+  ]
+}
+
+/** Final turn: a markdown answer with prose, a list, and a highlighted fence. */
+function finalTurn() {
+  const answer = [
+    '## 结论',
+    '',
+    '这是一个 **只读** 的实时看板插件：Host 侧订阅 `session/event`，把归一化后的事件通过本地 socket 推给独立终端里的 `dsh-live-trace`。',
+    '',
+    '- 不改动 Harness 核心，不干预 Agent 运行',
+    '- 卸载时 socket、监听器、定时器全部回收',
+    '- 终端里用 `Markdown` 渲染模型输出，并给代码着色',
+    '',
+    '```ts',
+    'export function apply(ctx, config) {',
+    '  return ctx.effect(() => {',
+    '    const dispose = ctx.on("session/event", (session, event) => {',
+    '      hub.onSessionEvent(session, event)',
+    '    })',
+    '    return () => dispose()',
+    '  })',
+    '}',
+    '```',
+    '',
+    '| 面板 | 快捷键 | 内容 |',
+    '| --- | --- | --- |',
+    '| trace | 1 | 事件轨迹 |',
+    '| sessions | 2 | 会话切换 |',
+    '| edits | 3 | 文件改动 |',
+    '| commands | 4 | 命令与输出 |'
+  ].join('\n')
+
+  const events = [
+    { type: 'message_start', message: { usage: { input_tokens: 6100, output_tokens: 0 } } },
+    { type: 'content_block_start', index: 0, content_block: { type: 'thinking', thinking: '' } },
+    { type: 'content_block_delta', index: 0, delta: { type: 'thinking_delta', thinking: '整理结论，用列表和表格说明面板。' } },
+    { type: 'content_block_stop', index: 0 },
+    { type: 'content_block_start', index: 1, content_block: { type: 'text', text: '' } }
+  ]
+  for (const chunk of answer.match(/[\s\S]{1,24}/g) ?? []) {
+    events.push({ type: 'content_block_delta', index: 1, delta: { type: 'text_delta', text: chunk } })
+  }
+  events.push(
+    { type: 'content_block_stop', index: 1 },
+    { type: 'message_delta', delta: { stop_reason: 'end_turn' }, usage: { output_tokens: 320 } },
+    { type: 'message_stop' }
+  )
+  return events
+}
+
+const server = createServer((req, res) => {
+  if (req.method !== 'POST' || !req.url?.startsWith('/v1/messages')) {
+    res.writeHead(404).end('not found')
+    return
+  }
+  let body = ''
+  req.setEncoding('utf8')
+  req.on('data', (chunk) => {
+    body += chunk
+  })
+  req.on('end', async () => {
+    let parsed = {}
+    try {
+      parsed = JSON.parse(body)
+    } catch {
+      /* fall through to the tool turn */
+    }
+    const messages = Array.isArray(parsed.messages) ? parsed.messages : []
+    // Each turn is chosen by how many tool results the conversation already
+    // carries, which walks the agent loop through bash -> bash -> write -> answer.
+    const toolResults = (JSON.stringify(messages).match(/"type":"tool_result"/g) ?? []).length
+    const script = toolResults === 0 ? firstToolTurn() : toolResults === 1 ? commandTurn() : toolResults === 2 ? writeTurn() : finalTurn()
+    process.stderr.write(`mock-llm: request model=${parsed.model} toolResults=${toolResults}\n`)
+
+    res.writeHead(200, {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-cache',
+      connection: 'keep-alive'
+    })
+    await sse(res, script)
+    res.end()
+  })
+})
+
+server.listen(PORT, '127.0.0.1', () => {
+  process.stderr.write(`mock-llm: listening on http://127.0.0.1:${PORT}\n`)
+})