@menghuan1918/dsh-apollo 0.0.0-stage → 0.4.0

package/skills/tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

package/src/cli/claude.js

@@ -0,0 +1,166 @@
+/**
+ * Claude Code CLI 适配：纯命令构造 + `--print --output-format stream-json` 事件流解析。
+ * 只产出 argv 与 stdin 正文并翻译事件；spawn/管道/stderr/中断由父 adapter 的
+ * `ctx.subprocess` 掌握（stdin 取 `{data: input}`）。不 import 任何 DSH 包。
+ *
+ * 实测依据（Claude Code 2.1.300，新建 + `--resume` 各一轮真实跑通）：
+ * - `--print` 不给位置参数 prompt 时正文从 stdin 读，所以 argv 里没有 prompt；
+ * - `stream-json` 必须配 `--verbose` 才是完整事件流；
+ * - `--permission-prompts none` = 没人回答权限提问、会被提问的一律自动拒绝，
+ *   正是无人值守管道要的语义（`--permission-mode` 仍决定其余判定）；
+ * - 续接用 `--resume <SESSION_ID>`；**不传** `--no-session-persistence`，否则会话
+ *   不落盘、下一轮无法续接；
+ * - claude **没有** cwd 选项（`--add-dir` 只是追加可写目录），工作目录由进程 cwd
+ *   决定，故本模块接受并忽略 `cwd`，交给父 adapter 的 spawn `cwd`；`profile` 是
+ *   codex 专属概念，同样忽略。
+ *
+ * 事件语义：
+ * - `system`（hook_started / hook_response / init）都带 `session_id`，且前两者出现在
+ *   `init` **之前**——故 remoteId 在「第一个带 session_id 的 system 事件」就回报；
+ * - `assistant` → `message.content[]` 里 `type === 'text'` 的块拼成正文；`tool_use` /
+ *   `thinking` 块**绝不**当作正文；带 `parent_tool_use_id` 的是子代理消息，也不计入；
+ * - `result` → 唯一权威收尾：`subtype === 'success' && is_error !== true` 才算成功；
+ *   `result` 字段是最终答复文本（覆盖累积值），`usage` 是整轮用量。
+ */
+
+import { normalizeUsage, requireEnum, requireEffort, requireId, requirePrompt, requireText, sanitizeError } from './jsonl.js'
+
+/** `claude --permission-mode` 的实测取值（`claude --help`）。 */
+const PERMISSION_MODES = ['acceptEdits', 'auto', 'bypassPermissions', 'manual', 'dontAsk', 'plan']
+
+/**
+ * 构造一轮 `claude --print` 调用。
+ *
+ * @param {object} spec
+ * @param {string} [spec.executable='claude'] - 可执行名或绝对路径。
+ * @param {string} [spec.cwd] - 接受但忽略：claude 无 cwd 选项，请用 spawn 的 cwd。
+ * @param {string} [spec.model] - `--model`，别名（sonnet/opus…）或全名。
+ * @param {string} [spec.effort] - `--effort`，实测取值 low/medium/high/xhigh/max。
+ * @param {string} [spec.profile] - 接受但忽略：codex 专属概念。
+ * @param {string} [spec.permissionMode] - `--permission-mode`。
+ * @param {string} [spec.remoteId] - 已有 session id 时走 `--resume <id>`。
+ * @param {string} spec.prompt - 正文，经 stdin 送入。
+ * @returns {{argv: string[], input: string}}
+ */
+export function buildCommand({ executable = 'claude', model, effort, permissionMode, remoteId, prompt } = {}) {
+  const argv = [requireText(executable, 'executable'), '--print', '--output-format', 'stream-json', '--verbose']
+  if (model !== undefined) argv.push('--model', requireText(model, 'model'))
+  if (effort !== undefined) argv.push('--effort', requireEffort(effort))
+  if (permissionMode !== undefined) argv.push('--permission-mode', requireEnum(permissionMode, PERMISSION_MODES, 'permissionMode'))
+  // 无人值守：任何权限提问都自动拒绝，而不是挂起等一个永远不会来的回答。
+  argv.push('--permission-prompts', 'none')
+  if (remoteId !== undefined) argv.push('--resume', requireId(remoteId, 'remoteId'))
+  // 正文走 stdin（`--print` 无位置参数时读 stdin），argv 里不出现 prompt。
+  return { argv, input: requirePrompt(prompt) }
+}
+
+/**
+ * 创建一个有状态的 claude 事件解析器（一轮子进程一个）。
+ *
+ * @returns {{push: (event: unknown) => ({remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined), finish: () => {text: string, remoteId?: string, usage?: object}}}
+ */
+export function createParser() {
+  let remoteId
+  let text = ''
+  let usage
+  let completed = false
+  let failure
+
+  /** 失败时优先用 provider 给的错误正文，否则退化成 subtype/api_error_status。 */
+  function describeResultFailure(event) {
+    const label = typeof event.subtype === 'string' && event.subtype !== '' ? event.subtype : 'error'
+    const detail = typeof event.result === 'string' && event.result !== '' ? event.result
+      : Array.isArray(event.errors) ? event.errors.filter((item) => typeof item === 'string').slice(0, 3).join('; ') : ''
+    const status = event.api_error_status === undefined ? '' : ` (api_error_status=${event.api_error_status})`
+    return sanitizeError(detail === '' ? `claude result ${label}${status}` : `claude result ${label}${status}: ${detail}`)
+  }
+
+  return {
+    /**
+     * 投喂一个已解析的事件。
+     * @param {unknown} event - `readJsonLines` 产出的单个事件。
+     * @returns {{remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined}
+     *   本次事件产生的动作；无动作返回 undefined。
+     *   `error` 是**信息性**的：只有 `finish()` 抛错才代表这一轮失败。
+     */
+    push(event) {
+      if (event === null || typeof event !== 'object') return undefined
+      switch (event.type) {
+        case 'system': {
+          if (typeof event.session_id !== 'string' || event.session_id === '') return undefined
+          // 只回报一次；实测 hook_started 早于 init，因此这里通常是最早的时机。
+          if (remoteId !== undefined) return undefined
+          remoteId = event.session_id
+          return { remoteId }
+        }
+        case 'assistant': {
+          // 子代理（Task 工具）的消息带 parent_tool_use_id，不能混进主答复。
+          if (typeof event.parent_tool_use_id === 'string' && event.parent_tool_use_id !== '') return undefined
+          const message = event.message
+          if (message === null || typeof message !== 'object' || !Array.isArray(message.content)) return undefined
+          const chunk = message.content
+            .filter((block) => block !== null && typeof block === 'object' && block.type === 'text' && typeof block.text === 'string')
+            .map((block) => block.text)
+            .join('')
+          if (chunk === '') return undefined
+          // 覆盖式：一条 assistant 事件就是一条完整消息，最后一条才是最终答复。
+          text = chunk
+          return { text }
+        }
+        case 'result': {
+          const mapped = mapClaudeUsage(event.usage)
+          if (mapped !== undefined) usage = mapped
+          const succeeded = event.subtype === 'success' && event.is_error !== true
+          if (succeeded) {
+            completed = true
+            if (typeof event.result === 'string' && event.result !== '') text = event.result
+          } else {
+            failure ??= describeResultFailure(event)
+          }
+          return {
+            ...(mapped === undefined ? {} : { usage: mapped }),
+            ...(succeeded ? { completed: true } : { error: failure }),
+            ...(succeeded && typeof event.result === 'string' && event.result !== '' ? { text: event.result } : {}),
+          }
+        }
+        default:
+          // user（工具结果）/ stream_event / 未来新增事件：无语义动作。
+          return undefined
+      }
+    },
+
+    /**
+     * 收流。失败或缺少 `result` 都抛错——「流结束了」不等于「回合成功了」。
+     * 幂等：可重复调用，不改变状态。
+     * @returns {{text: string, remoteId?: string, usage?: object}}
+     */
+    finish() {
+      if (failure !== undefined) throw new Error(`claude 回合失败：${failure}`)
+      if (!completed) throw new Error('claude 流在收到成功的 result 事件之前结束')
+      return {
+        text,
+        ...(remoteId === undefined ? {} : { remoteId }),
+        ...(usage === undefined ? {} : { usage }),
+      }
+    },
+  }
+}
+
+/**
+ * 把 claude 的整轮用量映射成 DSH TokenUsage。
+ *
+ * Anthropic 的 `input_tokens` 本来就**不含**缓存（另给 `cache_read_input_tokens` /
+ * `cache_creation_input_tokens`），与 DSH 约定一致，无需扣减；
+ * `output_tokens_details.thinking_tokens` 映射为 reasoning。
+ */
+function mapClaudeUsage(raw) {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const details = raw.output_tokens_details
+  return normalizeUsage({
+    inputTokens: raw.input_tokens,
+    outputTokens: raw.output_tokens,
+    cacheReadTokens: raw.cache_read_input_tokens,
+    cacheWriteTokens: raw.cache_creation_input_tokens,
+    reasoningTokens: details !== null && typeof details === 'object' ? details.thinking_tokens : undefined,
+  })
+}

package/src/cli/codex.js

@@ -0,0 +1,164 @@
+/**
+ * Codex CLI 适配：纯命令构造 + `codex exec --json` 事件流解析。
+ * 只产出 argv 与 stdin 正文并翻译事件；spawn/管道/stderr/中断由父 adapter 的
+ * `ctx.subprocess` 掌握（stdin 取 `{data: input}`）。不 import 任何 DSH 包。
+ *
+ * 实测依据（codex-cli 0.162.1，新建 + 续接各一轮真实跑通）：
+ * - 根选项 `-p/-s/-a/-C` 必须在 `exec` **之前**：`codex exec resume` 自己不接受
+ *   这四项，续接时只有根位置能让权限与 cwd 生效。
+ * - `resume <SESSION_ID>` 紧跟 `exec`，其余选项随后（clap 允许选项交错）。
+ * - 正文走 stdin：末尾 `-` 表示从 stdin 读；argv 不经 shell 解释，所以
+ *   `-c model_reasoning_effort="high"` 里的双引号是**字面量**。
+ *
+ * 事件语义：
+ * - `thread.started` 的 `thread_id` 即 remoteId，立刻回报给父落 KV；
+ * - `item.completed` 且 `item.type === 'agent_message'` → 最终助手文本（覆盖式）；
+ * - `item.type === 'reasoning'` / 工具类 item → **绝不**当作正文；
+ * - `item.type === 'error'` → 实测是配置告警（"ignoring N unrecognized configuration
+ *   settings"），**非致命**，只作信息回报；
+ * - `turn.completed` → 唯一成功完成标志，带 turn 用量；
+ * - `turn.failed` / 顶层 `error` → 致命，`finish()` 抛错。
+ */
+
+import { normalizeUsage, requireEffort, requireEnum, requireId, requirePrompt, requireText, sanitizeError } from './jsonl.js'
+
+/** `codex -s/--sandbox` 的实测取值（`codex --help`）。 */
+const SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access']
+
+/**
+ * 构造一轮 `codex exec` 调用。
+ *
+ * @param {object} spec
+ * @param {string} [spec.executable='codex'] - 可执行名或绝对路径。
+ * @param {string} [spec.cwd] - 工作根，落到根选项 `-C`。
+ * @param {string} [spec.model] - `-m` 模型 id。
+ * @param {string} [spec.effort] - 拼进 `-c model_reasoning_effort="…"`。
+ * @param {string} [spec.profile] - 根选项 `-p`；留空请传 undefined。
+ * @param {string} [spec.permissionMode] - 根选项 `-s`，只接受三种 sandbox 模式。
+ * @param {string} [spec.remoteId] - 已有 thread id 时走 `exec resume <id>`。
+ * @param {string} spec.prompt - 正文，经 stdin 送入。
+ * @returns {{argv: string[], input: string}}
+ */
+export function buildCommand({ executable = 'codex', cwd, model, effort, profile, permissionMode, remoteId, prompt } = {}) {
+  const argv = [requireText(executable, 'executable')]
+  // —— 根选项：必须在 `exec` 之前，否则续接时 `exec resume` 会拒绝它们 ——
+  if (profile !== undefined) argv.push('-p', requireText(profile, 'profile'))
+  if (permissionMode !== undefined) argv.push('-s', requireEnum(permissionMode, SANDBOX_MODES, 'permissionMode'))
+  // 非交互：任何审批请求都会挂住管道，所以恒定 never。
+  argv.push('-a', 'never')
+  if (cwd !== undefined) argv.push('-C', requireText(cwd, 'cwd'))
+  argv.push('exec')
+  if (remoteId !== undefined) argv.push('resume', requireId(remoteId, 'remoteId'))
+  argv.push('--json', '--skip-git-repo-check')
+  if (model !== undefined) argv.push('-m', requireText(model, 'model'))
+  if (effort !== undefined) argv.push('-c', `model_reasoning_effort="${requireEffort(effort)}"`)
+  // 位置参数 `-`：正文从 stdin 读，避免超长 prompt 撑爆 argv/命令行长度上限。
+  argv.push('-')
+  return { argv, input: requirePrompt(prompt) }
+}
+
+/**
+ * 创建一个有状态的 codex 事件解析器（一轮子进程一个）。
+ *
+ * @returns {{push: (event: unknown) => ({remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined), finish: () => {text: string, remoteId?: string, usage?: object}}}
+ */
+export function createParser() {
+  let remoteId
+  let text = ''
+  let usage
+  let completed = false
+  let failure
+
+  return {
+    /**
+     * 投喂一个已解析的事件。
+     * @param {unknown} event - `readJsonLines` 产出的单个事件。
+     * @returns {{remoteId?: string, text?: string, usage?: object, completed?: boolean, error?: string}|undefined}
+     *   本次事件产生的动作；无动作返回 undefined。
+     *   `error` 是**信息性**的：只有 `finish()` 抛错才代表这一轮失败。
+     */
+    push(event) {
+      if (event === null || typeof event !== 'object') return undefined
+      switch (event.type) {
+        case 'thread.started': {
+          if (typeof event.thread_id !== 'string' || event.thread_id === '') return undefined
+          // 只回报一次：父 adapter 在第一次拿到时就落到自己的 KV。
+          if (remoteId !== undefined) return undefined
+          remoteId = event.thread_id
+          return { remoteId }
+        }
+        case 'item.completed':
+        case 'item.updated': {
+          const item = event.item
+          if (item === null || typeof item !== 'object') return undefined
+          if (item.type === 'agent_message') {
+            if (typeof item.text !== 'string' || item.text === '') return undefined
+            // 覆盖式：一轮里可能有多条 agent_message，最后一条才是最终答复。
+            text = item.text
+            return { text }
+          }
+          if (item.type === 'error') {
+            // 实测这里是配置告警，不是回合失败，所以不设置 failure。
+            return { error: sanitizeError(item.message) }
+          }
+          // reasoning / command_execution / file_change / mcp_tool_call … 都不是正文。
+          return undefined
+        }
+        case 'turn.completed': {
+          completed = true
+          usage = mapCodexUsage(event.usage)
+          return usage === undefined ? { completed: true } : { usage, completed: true }
+        }
+        case 'turn.failed': {
+          failure ??= sanitizeError(event.error ?? event)
+          return { error: failure }
+        }
+        case 'error': {
+          failure ??= sanitizeError(event.message ?? event)
+          return { error: failure }
+        }
+        default:
+          // turn.started / item.started / 未来新增事件：无语义动作。
+          return undefined
+      }
+    },
+
+    /**
+     * 收流。失败或缺少完成标志都抛错——「流结束了」不等于「回合成功了」。
+     * 幂等：可重复调用，不改变状态。
+     * @returns {{text: string, remoteId?: string, usage?: object}}
+     */
+    finish() {
+      if (failure !== undefined) throw new Error(`codex 回合失败：${failure}`)
+      if (!completed) throw new Error('codex 流在收到 turn.completed 之前结束')
+      return {
+        text,
+        ...(remoteId === undefined ? {} : { remoteId }),
+        ...(usage === undefined ? {} : { usage }),
+      }
+    },
+  }
+}
+
+/**
+ * 把 codex 的 turn 用量映射成 DSH TokenUsage。
+ *
+ * codex 沿用 OpenAI 语义：`input_tokens` **已含**缓存命中的 prompt token，而 DSH 约定
+ * `inputTokens` 不含缓存（见 dsh-llm-pi-ai），故这里做同样扣减；`totalTokens` 由
+ * normalizeUsage 按 `input + output + cacheRead + cacheWrite` 还原成完整调用量。
+ */
+function mapCodexUsage(raw) {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const cacheRead = raw.cached_input_tokens
+  const cacheWrite = raw.cache_write_input_tokens
+  const prompt = typeof raw.input_tokens === 'number' && Number.isFinite(raw.input_tokens) ? raw.input_tokens : 0
+  const cacheReadCount = typeof cacheRead === 'number' && Number.isFinite(cacheRead) && cacheRead > 0 ? cacheRead : 0
+  const cacheWriteCount = typeof cacheWrite === 'number' && Number.isFinite(cacheWrite) && cacheWrite > 0 ? cacheWrite : 0
+  return normalizeUsage({
+    inputTokens: Math.max(0, prompt - cacheReadCount - cacheWriteCount),
+    outputTokens: raw.output_tokens,
+    cacheReadTokens: cacheReadCount,
+    cacheWriteTokens: cacheWriteCount,
+    reasoningTokens: raw.reasoning_output_tokens,
+  })
+}

package/src/cli/jsonl.js

@@ -0,0 +1,216 @@
+/**
+ * CLI 适配层的公共底座：JSONL 切行 + 事件校验/去敏/用量归一。
+ *
+ * 为什么需要：两个 CLI 都按「一行一个 JSON 事件」输出，而 stdout 的分块边界与行边界
+ * 毫无关系——一个 chunk 可能含半行、多行，或正好切在某个 UTF-8 多字节字符中间。
+ * 切行只在这里做一次，两个 backend 就只需关心事件语义。
+ *
+ * 契约：
+ * - 只跳过**空白行**（CLI 收尾换行必然切出一个空串）；非空但非法 JSON 一律抛
+ *   SyntaxError——静默丢弃会让调用方把「畸形流」误判成「回合正常结束」。
+ * - Buffer 走 StringDecoder，跨 chunk 多字节字符不乱码；单行超 `maxLineBytes` 抛 RangeError。
+ * - 只读一个流：stderr 由父 adapter 自己收集。
+ *
+ * 顶层只依赖 node 内置模块，不 import 任何 DSH 包——子进程生命周期归父 adapter。
+ */
+
+import { StringDecoder } from 'node:string_decoder'
+
+/** 单行上限 1 MiB：CLI 事件远小于此，超过即视为协议被破坏。 */
+export const DEFAULT_MAX_LINE_BYTES = 1048576
+
+/** 错误文本上限：既保证日志有界，也避免把大段原始输出回灌进会话。 */
+export const MAX_ERROR_CHARS = 400
+
+/** 空白行没有 JSON 值可产出，用哨兵与「合法的 null 事件」区分。 */
+const SKIP = Symbol('jsonl.skip')
+
+/**
+ * 把可读流切成 JSON 行并逐个产出解析后的值。
+ *
+ * @param {AsyncIterable<Buffer|Uint8Array|string>} readable - 子进程 stdout（或任意异步可迭代）。
+ * @param {{maxLineBytes?: number}} [options] - 单行字节上限。
+ * @returns {AsyncGenerator<unknown>} 解析后的事件，按流序产出。
+ */
+export async function* readJsonLines(readable, { maxLineBytes = DEFAULT_MAX_LINE_BYTES } = {}) {
+  if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes <= 0) {
+    throw new TypeError(`readJsonLines: maxLineBytes 必须是正的安全整数，收到 ${maxLineBytes}`)
+  }
+  if (readable === null || typeof readable !== 'object' || typeof readable[Symbol.asyncIterator] !== 'function') {
+    throw new TypeError('readJsonLines: readable 必须是产出 Buffer 或 string 的异步可迭代对象')
+  }
+  const decoder = new StringDecoder('utf8')
+  let pending = ''
+  let lineNumber = 0
+  for await (const chunk of readable) {
+    // string chunk 说明上游已解码：先冲掉解码器里的残余字节，再直接拼接。
+    pending += typeof chunk === 'string' ? decoder.end() + chunk : decoder.write(chunk)
+    let index = pending.indexOf('\n')
+    while (index !== -1) {
+      const line = pending.slice(0, index)
+      pending = pending.slice(index + 1)
+      lineNumber += 1
+      const value = parseLine(line, lineNumber, maxLineBytes)
+      if (value !== SKIP) yield value
+      index = pending.indexOf('\n')
+    }
+    // 还没等到换行就已经超限：不必等到整行结束才报错。
+    if (Buffer.byteLength(pending) > maxLineBytes) {
+      throw new RangeError(`readJsonLines: 第 ${lineNumber + 1} 行超过 maxLineBytes（${maxLineBytes}）`)
+    }
+  }
+  // 尾行：流结束时最后一行可能没有换行符，仍需产出。
+  pending += decoder.end()
+  if (pending !== '') {
+    lineNumber += 1
+    const value = parseLine(pending, lineNumber, maxLineBytes)
+    if (value !== SKIP) yield value
+  }
+}
+
+/** 解析一行：空白行返回哨兵，非法 JSON 抛 SyntaxError（带行号）。 */
+function parseLine(line, lineNumber, maxLineBytes) {
+  const text = line.endsWith('\r') ? line.slice(0, -1) : line
+  if (text.trim() === '') return SKIP
+  if (Buffer.byteLength(text) > maxLineBytes) {
+    throw new RangeError(`readJsonLines: 第 ${lineNumber} 行超过 maxLineBytes（${maxLineBytes}）`)
+  }
+  try {
+    return JSON.parse(text)
+  } catch (error) {
+    throw new SyntaxError(`readJsonLines: 第 ${lineNumber} 行不是合法 JSON：${error.message}`)
+  }
+}
+
+/**
+ * 归一成 DSH TokenUsage（契约见 dsh-llm 的 `TokenUsage`：`inputTokens` / `outputTokens` /
+ * `totalTokens?` / `cacheReadTokens?` / `cacheWriteTokens?` / `reasoningTokens?`）。
+ *
+ * 与 dsh-llm-pi-ai 同约定：`inputTokens` **不含**缓存命中/写入；
+ * `totalTokens = input + output + cacheRead + cacheWrite`；为 0 的可选字段省略。
+ * 非法数字按 0 处理而不抛错——用量异常不该毁掉一整轮。
+ *
+ * @param {{inputTokens?: unknown, outputTokens?: unknown, cacheReadTokens?: unknown, cacheWriteTokens?: unknown, reasoningTokens?: unknown}} raw
+ * @returns {{inputTokens: number, outputTokens: number, totalTokens: number, cacheReadTokens?: number, cacheWriteTokens?: number, reasoningTokens?: number}}
+ */
+export function normalizeUsage({ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens } = {}) {
+  const input = count(inputTokens)
+  const output = count(outputTokens)
+  const cacheRead = count(cacheReadTokens)
+  const cacheWrite = count(cacheWriteTokens)
+  const reasoning = count(reasoningTokens)
+  const usage = {
+    inputTokens: input,
+    outputTokens: output,
+    totalTokens: input + output + cacheRead + cacheWrite,
+  }
+  if (cacheRead > 0) usage.cacheReadTokens = cacheRead
+  if (cacheWrite > 0) usage.cacheWriteTokens = cacheWrite
+  if (reasoning > 0) usage.reasoningTokens = reasoning
+  return usage
+}
+
+/** 取一个非负有限数；其余（undefined/NaN/负数/字符串）一律折成 0。 */
+function count(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0
+}
+
+/** 去敏 + 有界的错误文本：抹掉凭据形状、压掉控制字符/换行、按字符数截断。 */
+const REDACTIONS = [
+  // Bearer / Authorization 头
+  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, '$1 [redacted]'],
+  // 显式键名后的取值（api_key=、token:、password 等）
+  [/\b(api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|auth[_-]?token|secret|password|passwd|token)(\s*[":=]\s*)["']?[A-Za-z0-9._~+/=-]{8,}["']?/gi, '$1$2[redacted]'],
+  // 常见前缀凭据
+  [/\b(sk|rk|pk|ghp|gho|ghu|ghs|ghr|xoxb|xoxp|xapp|glpat|AIza|AKIA)[-_][A-Za-z0-9_-]{8,}/g, '[redacted]'],
+  // 通用长随机串（JWT / 裸密钥 / 长 base64）
+  [/[A-Za-z0-9+/=_-]{64,}/g, '[redacted]'],
+]
+
+/** 去掉 NUL 与其余 C0/C1 控制字符（含换行），保证错误是单行文本。 */
+const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]+/g
+
+/**
+ * 把任意错误载荷压成一条可直接进日志/会话文本的安全字符串。
+ * @param {unknown} value - 原始错误（字符串、Error、事件字段……）。
+ * @returns {string} 去敏且不超过 {@link MAX_ERROR_CHARS} 的单行文本。
+ */
+export function sanitizeError(value) {
+  let text = typeof value === 'string' ? value : value instanceof Error ? value.message : safeStringify(value)
+  for (const [pattern, replacement] of REDACTIONS) text = text.replace(pattern, replacement)
+  text = text.replace(CONTROL_CHARS, ' ').replace(/\s+/g, ' ').trim()
+  if (text === '') return '未知错误'
+  return text.length > MAX_ERROR_CHARS ? `${text.slice(0, MAX_ERROR_CHARS)}…` : text
+}
+
+/**
+ * 兜底序列化：循环引用、undefined、函数等都不该让解析器崩掉，
+ * 也绝不能让 `undefined` 变成字面量字符串 "undefined" 混进错误文本。
+ */
+function safeStringify(value) {
+  if (value === undefined || value === null) return ''
+  try {
+    const text = JSON.stringify(value)
+    return typeof text === 'string' ? text : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 校验「非空字符串且不含控制字符」的 argv 取值。argv 不经 shell 解释，只需拦空值与换行。 */
+export function requireText(value, name) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`${name} 必须是非空字符串，收到 ${describe(value)}`)
+  }
+  if (/[\u0000-\u001f\u007f]/.test(value)) {
+    throw new TypeError(`${name} 不能包含控制字符`)
+  }
+  return value
+}
+
+/**
+ * 校验**位置参数**取值（如 `codex exec resume <id>`）。
+ * 额外拒绝前导 `-`：否则一个形如 `--json` 的 id 会被 CLI 当成选项解析。
+ */
+export function requireId(value, name) {
+  const text = requireText(value, name)
+  if (text.startsWith('-')) {
+    throw new TypeError(`${name} 不能以 "-" 开头（会被 CLI 当作选项），收到 ${JSON.stringify(text)}`)
+  }
+  return text
+}
+
+/**
+ * 校验 reasoning effort 档位。刻意用严格 token 正则：codex 侧它会被拼进
+ * `-c model_reasoning_effort="…"`，绝不能含 `"`、`\` 或空白（等于往 TOML 注入）。
+ * 实测取值 codex = minimal/low/medium/high，claude = low/medium/high/xhigh/max；
+ * 不做枚举硬编码，以免上游加档位就炸。
+ */
+export function requireEffort(value, name = 'effort') {
+  if (typeof value !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(value)) {
+    throw new TypeError(`${name} 必须是形如 low/medium/high/xhigh/max 的档位标识，收到 ${describe(value)}`)
+  }
+  return value
+}
+
+/** 校验枚举型取值，把「CLI 后期才报错」提前成构造期的清晰 TypeError。 */
+export function requireEnum(value, allowed, name) {
+  if (!allowed.includes(value)) {
+    throw new TypeError(`${name} 必须是 ${allowed.join(' / ')} 之一，收到 ${describe(value)}`)
+  }
+  return value
+}
+
+/** 校验 stdin 正文：只要求是字符串，内容原样透传（可以含换行，空串也合法）。 */
+export function requirePrompt(value) {
+  if (typeof value !== 'string') {
+    throw new TypeError(`prompt 必须是字符串（作为子进程 stdin 正文），收到 ${describe(value)}`)
+  }
+  return value
+}
+
+/** 给报错用的短描述，避免把整个超长 prompt 打进错误里。 */
+function describe(value) {
+  if (typeof value === 'string') return JSON.stringify(value.length > 60 ? `${value.slice(0, 60)}…` : value)
+  return String(value)
+}