niceeval 0.1.1 → 0.1.2

package/src/agents/sdk-streams.ts

@@ -0,0 +1,457 @@
+// SDK 原生事件流 → 标准 StreamEvent 的官方转换器(+ 通用 SSE 读帧器)。
+//
+// 定位:各 agent SDK 的流式协议(Claude Agent SDK 的 `SDKMessage`、pi-agent-core 的
+// `AgentEvent`、Codex SDK 的 `ThreadEvent`)是 SDK 定义的通用协议,不是某个应用的私有格式——
+// 这层映射知识属于 niceeval 官方包,adapter 里只该剩传输粘合(应用把流放在哪个端点、
+// 审批走什么端点)。类型全部用结构化的 *Like 声明(同 fromAiSdk 的先例),不依赖任何 SDK 包。
+//
+// 用法(以 Claude Agent SDK 为例):
+//
+// ```typescript
+// import { sseJsonFrames, fromClaudeSdkMessages } from "niceeval/adapter";
+//
+// const frames = sseJsonFrames<SDKMessage>(res.body);
+// const stream = fromClaudeSdkMessages();
+// for (;;) {
+//   const frame = await frames.next();
+//   if (frame === null) break;
+//   events.push(...stream.add(frame));   // 逐帧翻译;认不出的帧返回 []
+// }
+// return { status: stream.failed ? "failed" : "completed", events, usage: stream.usage };
+// ```
+
+import type { JsonValue, StreamEvent, Usage } from "../types.ts";
+
+// ───────────────────────── 通用 SSE 读帧器 ─────────────────────────
+
+export interface SseFrameCursor<T> {
+  /** 下一个 `data:` JSON 帧;流结束返回 null。`data: [DONE]` 哨兵帧自动跳过。 */
+  next(): Promise<T | null>;
+}
+
+/** 标准 SSE(`data: {...}\n\n`)→ 逐帧 JSON。各 adapter 不用再手写 buffer 状态机。 */
+export function sseJsonFrames<T>(body: ReadableStream<Uint8Array>): SseFrameCursor<T> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  async function next(): Promise<T | null> {
+    for (;;) {
+      const sepIndex = buffer.indexOf("\n\n");
+      if (sepIndex !== -1) {
+        const rawEvent = buffer.slice(0, sepIndex);
+        buffer = buffer.slice(sepIndex + 2);
+        const line = rawEvent.split("\n").find((l) => l.startsWith("data: "));
+        if (!line) continue;
+        const payload = line.slice("data: ".length);
+        if (payload === "[DONE]") continue;
+        return JSON.parse(payload) as T;
+      }
+      const { value, done } = await reader.read();
+      if (done) return null;
+      buffer += decoder.decode(value, { stream: true });
+    }
+  }
+
+  return { next };
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+// ───────────────────────── Claude Agent SDK:SDKMessage ─────────────────────────
+
+/** 只声明转换器要读的字段;真实的 SDKMessage 直接喂进来即可。 */
+export interface ClaudeSdkMessageLike {
+  type: string;
+  subtype?: string;
+  session_id?: string;
+  tool_use_id?: string;
+  is_error?: boolean;
+  num_turns?: number;
+  total_cost_usd?: number;
+  usage?: { input_tokens: number; output_tokens: number; cache_read_input_tokens?: number | null; cache_creation_input_tokens?: number | null };
+  message?: { content?: unknown };
+  [key: string]: unknown;
+}
+
+export interface ClaudeSdkStream {
+  /** 逐帧喂 `SDKMessage`,返回这一帧派生的标准事件;认不出的帧(stream_event 等)返回 []。 */
+  add(message: ClaudeSdkMessageLike): StreamEvent[];
+  /** `system`/`init` 帧带回的 session_id(首帧之后可读),回写 `ctx.session.id` 用。 */
+  readonly sessionId: string | undefined;
+  /** `result` 帧的聚合用量。 */
+  readonly usage: Usage | undefined;
+  /** `result` 帧报了 is_error。 */
+  readonly failed: boolean;
+  /**
+   * 拒绝审批后续读前登记:该 tool_use 的 `tool_result` / `permission_denied` 落成
+   * `status: "rejected"`(而不是 failed),且两种帧只产一条 action.result。
+   */
+  markRejected(toolUseId: string): void;
+}
+
+/**
+ * Claude Agent SDK 消息流(`system` / `assistant` / `user` / `result`)→ 标准事件。
+ * `assistant` 的 text/tool_use 块 → message / action.called;`user` 的 tool_result 块 →
+ * action.result;`system`/`permission_denied` → rejected;`stream_event`(逐 token 渲染)
+ * 整个忽略。HITL 的停轮判定(哪个工具被门控)是应用侧的知识,不在这里——扫描 add()
+ * 返回的 action.called 自行决定。
+ */
+export function fromClaudeSdkMessages(): ClaudeSdkStream {
+  let sessionId: string | undefined;
+  let usage: Usage | undefined;
+  let failed = false;
+  const resolvedCallIds = new Set<string>();
+  const rejected = new Set<string>();
+
+  const toolResultText = (content: unknown): string | undefined => {
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) {
+      return content
+        .filter((b): b is { type: "text"; text: string } => isRecord(b) && b.type === "text" && typeof b.text === "string")
+        .map((b) => b.text)
+        .join("");
+    }
+    return undefined;
+  };
+
+  return {
+    get sessionId() {
+      return sessionId;
+    },
+    get usage() {
+      return usage;
+    },
+    get failed() {
+      return failed;
+    },
+    markRejected(toolUseId) {
+      rejected.add(toolUseId);
+    },
+    add(frame) {
+      const events: StreamEvent[] = [];
+      switch (frame.type) {
+        case "system": {
+          if (frame.subtype === "init" && typeof frame.session_id === "string") {
+            sessionId ??= frame.session_id;
+          } else if (frame.subtype === "permission_denied" && typeof frame.tool_use_id === "string") {
+            if (!resolvedCallIds.has(frame.tool_use_id)) {
+              resolvedCallIds.add(frame.tool_use_id);
+              events.push({ type: "action.result", callId: frame.tool_use_id, status: "rejected" });
+            }
+          }
+          break;
+        }
+        case "assistant": {
+          const content: unknown[] = Array.isArray(frame.message?.content) ? frame.message.content : [];
+          for (const block of content) {
+            if (!isRecord(block)) continue;
+            if (block.type === "text" && typeof block.text === "string" && block.text) {
+              events.push({ type: "message", role: "assistant", text: block.text });
+            } else if (block.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string") {
+              events.push({ type: "action.called", callId: block.id, name: block.name, input: block.input as JsonValue });
+            }
+          }
+          break;
+        }
+        case "user": {
+          const content: unknown[] = Array.isArray(frame.message?.content) ? frame.message.content : [];
+          for (const block of content) {
+            if (!isRecord(block) || block.type !== "tool_result" || typeof block.tool_use_id !== "string") continue;
+            if (resolvedCallIds.has(block.tool_use_id)) continue;
+            resolvedCallIds.add(block.tool_use_id);
+            events.push({
+              type: "action.result",
+              callId: block.tool_use_id,
+              output: toolResultText(block.content) as JsonValue,
+              status: rejected.has(block.tool_use_id) ? "rejected" : block.is_error ? "failed" : "completed",
+            });
+          }
+          break;
+        }
+        case "result": {
+          failed = frame.is_error === true;
+          if (frame.usage) {
+            usage = {
+              inputTokens: frame.usage.input_tokens,
+              outputTokens: frame.usage.output_tokens,
+              cacheReadTokens: frame.usage.cache_read_input_tokens ?? undefined,
+              cacheWriteTokens: frame.usage.cache_creation_input_tokens ?? undefined,
+              requests: frame.num_turns,
+              costUSD: frame.total_cost_usd,
+            };
+          }
+          break;
+        }
+        // stream_event(逐 token 渲染)与其它系统/生命周期消息:无对应 StreamEvent。
+        default:
+          break;
+      }
+      return events;
+    },
+  };
+}
+
+// ───────────────────────── pi-agent-core:AgentEvent ─────────────────────────
+
+export interface PiAgentEventLike {
+  type: string;
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: unknown;
+  isError?: boolean;
+  /** content 在 user 消息上是 string、assistant 消息上是 parts 数组——按 unknown 收,防御式解析。 */
+  message?: {
+    role?: string;
+    content?: unknown;
+    usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } };
+  };
+  [key: string]: unknown;
+}
+
+export interface PiAgentStream {
+  /** 逐帧喂 `AgentEvent`,返回这一帧派生的标准事件;生命周期帧(turn_start 等)返回 []。 */
+  add(event: PiAgentEventLike): StreamEvent[];
+  /** assistant `message_end` 逐条累加的用量。 */
+  readonly usage: Usage | undefined;
+  /** 拒绝审批后续读前登记:该调用 `tool_execution_end` 的 isError 判成 "rejected" 而非 "failed"。 */
+  markRejected(toolCallId: string): void;
+}
+
+/**
+ * pi-agent-core 事件流(`message_end` / `tool_execution_start` / `tool_execution_end`)→
+ * 标准事件。message_end 抠 assistant 文本与 thinking、累加 usage;
+ * tool_execution_start/end → action.called / action.result。
+ */
+export function fromPiAgentEvents(): PiAgentStream {
+  let usage: Usage | undefined;
+  const rejected = new Set<string>();
+
+  const partText = (event: PiAgentEventLike, type: "text" | "thinking"): string => {
+    if (event.message?.role !== "assistant" || !Array.isArray(event.message.content)) return "";
+    return event.message.content
+      .filter((part): part is Record<string, unknown> => isRecord(part) && part.type === type)
+      .map((part) => {
+        const v = type === "text" ? part.text : part.thinking;
+        return typeof v === "string" ? v : "";
+      })
+      .join("");
+  };
+
+  return {
+    get usage() {
+      return usage;
+    },
+    markRejected(toolCallId) {
+      rejected.add(toolCallId);
+    },
+    add(event) {
+      const events: StreamEvent[] = [];
+      switch (event.type) {
+        case "message_end": {
+          const text = partText(event, "text");
+          if (text) events.push({ type: "message", role: "assistant", text });
+          const thinking = partText(event, "thinking");
+          if (thinking) events.push({ type: "thinking", text: thinking });
+          const u = event.message?.role === "assistant" ? event.message.usage : undefined;
+          if (u) {
+            usage = {
+              inputTokens: (usage?.inputTokens ?? 0) + u.input,
+              outputTokens: (usage?.outputTokens ?? 0) + u.output,
+              cacheReadTokens: (usage?.cacheReadTokens ?? 0) + u.cacheRead,
+              cacheWriteTokens: (usage?.cacheWriteTokens ?? 0) + u.cacheWrite,
+              requests: (usage?.requests ?? 0) + 1,
+              costUSD: (usage?.costUSD ?? 0) + u.cost.total,
+            };
+          }
+          break;
+        }
+        case "tool_execution_start": {
+          if (typeof event.toolCallId === "string" && typeof event.toolName === "string") {
+            events.push({ type: "action.called", callId: event.toolCallId, name: event.toolName, input: event.args as JsonValue });
+          }
+          break;
+        }
+        case "tool_execution_end": {
+          if (typeof event.toolCallId === "string") {
+            const status = event.isError ? (rejected.has(event.toolCallId) ? "rejected" : "failed") : "completed";
+            events.push({ type: "action.result", callId: event.toolCallId, output: event.result as JsonValue, status });
+          }
+          break;
+        }
+        // agent_start / turn_start / turn_end / message_start / message_update /
+        // tool_execution_update / agent_end:无对应 StreamEvent(message_end 已带完整文本)。
+        default:
+          break;
+      }
+      return events;
+    },
+  };
+}
+
+// ───────────────────────── Codex SDK:ThreadEvent ─────────────────────────
+
+export interface CodexThreadEventLike {
+  type: string;
+  thread_id?: string;
+  item?: { type?: string; text?: string; message?: string; [key: string]: unknown };
+  error?: { message: string };
+  [key: string]: unknown;
+}
+
+export interface CodexThreadStream {
+  /**
+   * 逐帧喂 `ThreadEvent`,返回标准事件:消息类(agent_message → message、reasoning → thinking、
+   * error item / turn.failed → error)+ 工具项(command_execution / mcp_tool_call / web_search /
+   * file_change → action.called + action.result)。usage 从 `turn.completed` 聚合,经 `usage` 读。
+   * 断言依据全部来自这条流;codex CLI 的原生 OTLP span 只用于瀑布图(spanMapper: mapCodexSpans)。
+   */
+  add(event: CodexThreadEventLike): StreamEvent[];
+  /** `thread.started` 带回的 thread_id,回写 `ctx.session.id` 用。 */
+  readonly threadId: string | undefined;
+  /** `turn.completed` 聚合的用量(input/cached/output tokens)。 */
+  readonly usage: Usage | undefined;
+  /** turn.failed / error item 出现过。 */
+  readonly failed: boolean;
+}
+
+/** Codex SDK 线程事件流(`thread.started` / `item.*` / `turn.completed` / `turn.failed`)→ 标准事件。 */
+export function fromCodexThreadEvents(): CodexThreadStream {
+  let threadId: string | undefined;
+  let usage: Usage | undefined;
+  let failed = false;
+  // item.started 已发 action.called 的 id;item.completed 时不重发,只补 result。
+  const startedCallIds = new Set<string>();
+  let synth = 0;
+
+  const callIdOf = (item: Record<string, unknown>, prefix: string): string => {
+    const id = item.id;
+    return typeof id === "string" || typeof id === "number" ? String(id) : `${prefix}_${++synth}`;
+  };
+
+  // 工具项 → action.called(+completed 时的 action.result)。与 o11y/parsers/codex.ts 的
+  // transcript 映射保持同一套语义(字段名以 codex exec --json 的 ThreadItem 为准)。
+  const handleToolItem = (item: Record<string, unknown>, isCompleted: boolean): StreamEvent[] => {
+    const events: StreamEvent[] = [];
+    const emitCall = (callId: string, name: string, input: JsonValue): void => {
+      if (startedCallIds.has(callId)) return;
+      startedCallIds.add(callId);
+      events.push({ type: "action.called", callId, name, input });
+    };
+
+    switch (item.type) {
+      case "command_execution": {
+        const callId = callIdOf(item, "cmd");
+        emitCall(callId, "command_execution", { command: item.command ?? null } as JsonValue);
+        if (isCompleted) {
+          const exit = item.exit_code;
+          const success = exit === 0 || (exit == null && item.status !== "failed" && item.status !== "error");
+          events.push({
+            type: "action.result",
+            callId,
+            output: { output: (item.aggregated_output ?? null) as JsonValue, exit_code: (exit ?? null) as JsonValue },
+            status: success ? "completed" : "failed",
+          });
+        }
+        return events;
+      }
+      case "mcp_tool_call": {
+        const callId = callIdOf(item, "mcp");
+        const tool = String(item.tool ?? "unknown");
+        const name = typeof item.server === "string" ? `${item.server}.${tool}` : tool;
+        emitCall(callId, name, (item.arguments ?? null) as JsonValue);
+        if (isCompleted) {
+          const success = !item.error && item.status !== "failed";
+          events.push({ type: "action.result", callId, output: (item.result ?? null) as JsonValue, status: success ? "completed" : "failed" });
+        }
+        return events;
+      }
+      case "web_search": {
+        const callId = callIdOf(item, "web");
+        emitCall(callId, "web_search", { query: item.query ?? null } as JsonValue);
+        if (isCompleted) events.push({ type: "action.result", callId, output: null, status: "completed" });
+        return events;
+      }
+      case "file_change": {
+        // 补丁类只在 completed 落一次:changes 里每个文件一对 called/result。
+        if (!isCompleted) return events;
+        const baseId = callIdOf(item, "patch");
+        const changes = Array.isArray(item.changes) ? item.changes : [];
+        changes.forEach((ch, i) => {
+          const callId = `${baseId}#${i}`;
+          const change = isRecord(ch) ? { path: ch.path ?? null, kind: ch.kind ?? null } : {};
+          events.push({ type: "action.called", callId, name: "file_change", input: change as JsonValue });
+          events.push({ type: "action.result", callId, output: change as JsonValue, status: "completed" });
+        });
+        return events;
+      }
+      default:
+        return events;
+    }
+  };
+
+  return {
+    get threadId() {
+      return threadId;
+    },
+    get usage() {
+      return usage;
+    },
+    get failed() {
+      return failed;
+    },
+    add(event) {
+      const events: StreamEvent[] = [];
+      switch (event.type) {
+        case "thread.started": {
+          if (typeof event.thread_id === "string") threadId ??= event.thread_id;
+          break;
+        }
+        case "item.started": {
+          if (event.item) events.push(...handleToolItem(event.item, false));
+          break;
+        }
+        case "item.completed": {
+          const item = event.item;
+          if (!item) break;
+          if (item.type === "agent_message" && typeof item.text === "string" && item.text) {
+            events.push({ type: "message", role: "assistant", text: item.text });
+          } else if (item.type === "reasoning" && typeof item.text === "string" && item.text) {
+            events.push({ type: "thinking", text: item.text });
+          } else if (item.type === "error" && typeof item.message === "string") {
+            failed = true;
+            events.push({ type: "error", message: item.message });
+          } else {
+            events.push(...handleToolItem(item, true));
+          }
+          break;
+        }
+        case "turn.completed": {
+          const u = event.usage;
+          if (isRecord(u)) {
+            const num = (v: unknown): number => (typeof v === "number" ? v : 0);
+            usage = {
+              inputTokens: (usage?.inputTokens ?? 0) + num(u.input_tokens),
+              outputTokens: (usage?.outputTokens ?? 0) + num(u.output_tokens),
+              cacheReadTokens: (usage?.cacheReadTokens ?? 0) + num(u.cached_input_tokens),
+              requests: (usage?.requests ?? 0) + 1,
+            };
+          }
+          break;
+        }
+        case "turn.failed": {
+          failed = true;
+          if (event.error?.message) events.push({ type: "error", message: event.error.message });
+          break;
+        }
+        // item.updated(中间态)/ turn.started:忽略,等 completed。
+        default:
+          break;
+      }
+      return events;
+    },
+  };
+}

package/src/agents/shared.ts

@@ -10,8 +10,9 @@ import {
   parseClaudeCodeTranscript,
   parseBubTranscript,
 } from "../o11y/parsers/index.ts";
-import type { Sandbox } from "../types.ts";
+import type { Sandbox, StreamEvent } from "../types.ts";
 import { t } from "../i18n/index.ts";
+import { shellQuote } from "../sandbox/shell.ts";
 
 /** 每个沙箱里「已经装过的全局包」去重,避免每轮 send 重复 npm i -g。 */
 const installedBySandbox = new WeakMap<Sandbox, Set<string>>();
@@ -36,12 +37,26 @@ async function ensureInstalled(sandbox: Sandbox, cmd: string, args: string[]): P
   set.add(key);
 }
 
-/** 在 dir(可含 ~)下找最新的 *.jsonl,读回其内容;没有则 undefined。 */
+/**
+ * 在 dir(可含 ~)下找 mtime 最新的 *.jsonl,读回其内容;没有则 undefined。
+ * 「最新」是对的:同一沙箱内 send 严格串行,刚跑完的那次一定写在最后 —— 不要改成按
+ * session id 精确定位(claude --resume 会 fork 出新 session id 的新文件,旧 id 的
+ * 文件还在,精确匹配会读到过期 transcript,负断言静默假通过)。
+ * 用沙箱里的 node 递归找全局最新:不依赖 GNU find 的 -printf(BSD / 精简镜像没有),
+ * 也没有 `-exec ls -t +` 的 ARG_MAX 分批陷阱(每批各自排序,head -1 不是全局最新)。
+ * 沙箱必然有 node(agent CLI 靠 npm 装,预制镜像也带)。
+ */
 async function captureLatestJsonl(sandbox: Sandbox, dir: string): Promise<string | undefined> {
+  const script =
+    'const fs=require("fs"),p=require("path");let best=null;' +
+    "const walk=(d)=>{let es;try{es=fs.readdirSync(d,{withFileTypes:true})}catch{return}" +
+    "for(const e of es){const f=p.join(d,e.name);" +
+    "if(e.isDirectory())walk(f);" +
+    'else if(e.name.endsWith(".jsonl")){try{const m=fs.statSync(f).mtimeMs;if(!best||m>best.m)best={f,m}}catch{}}}};' +
+    "walk(process.argv[1]);if(best)process.stdout.write(best.f);";
   try {
-    const find = await sandbox.runShell(
-      `find ${dir} -type f -name '*.jsonl' -printf '%T@\\t%p\\n' 2>/dev/null | sort -nr | head -1 | cut -f2-`,
-    );
+    // dir 不加引号以便 shell 展开 ~;受信内部路径(同 writeFile 的约定)。
+    const find = await sandbox.runShell(`node -e '${script}' ${dir}`);
     const path = find.stdout.trim();
     if (!path) return undefined;
     return await sandbox.readFile(path);
@@ -57,22 +72,36 @@ async function writeFile(sandbox: Sandbox, path: string, content: string): Promi
   await sandbox.runShell(`mkdir -p $(dirname ${path}) && cat > ${path} <<'${delim}'\n${content}\n${delim}\n`);
 }
 
-/** Claude Code 的 transcript JSONL 里抠 sessionId(取最后一个,供下一轮 --resume)。 */
-function sessionIdFromClaudeTranscript(raw: string | undefined): string | undefined {
+/**
+ * JSONL 逐行扫描的唯一骨架:逐行 parse,把每行对象交给 pick 抠值,
+ * 按 mode 取第一个或最后一个非空命中。非 JSON 行跳过。
+ */
+function scanJsonl(
+  raw: string | undefined,
+  pick: (obj: Record<string, unknown>) => string | undefined,
+  mode: "first" | "last" = "first",
+): string | undefined {
   if (!raw) return undefined;
-  let last: string | undefined;
+  let hit: string | undefined;
   for (const line of raw.split("\n")) {
-    const t = line.trim();
-    if (!t) continue;
+    const trimmed = line.trim();
+    if (!trimmed) continue;
     try {
-      const obj = JSON.parse(t) as { sessionId?: unknown; session_id?: unknown };
-      const id = (obj.sessionId ?? obj.session_id) as unknown;
-      if (typeof id === "string" && id) last = id;
+      const v = pick(JSON.parse(trimmed) as Record<string, unknown>);
+      if (typeof v === "string" && v) {
+        if (mode === "first") return v;
+        hit = v;
+      }
     } catch {
       // 跳过非 JSON 行
     }
   }
-  return last;
+  return hit;
+}
+
+/** Claude Code 的 transcript JSONL 里抠 sessionId(取最后一个,供下一轮 --resume)。 */
+function sessionIdFromClaudeTranscript(raw: string | undefined): string | undefined {
+  return scanJsonl(raw, (obj) => (obj.sessionId ?? obj.session_id) as string | undefined, "last");
 }
 
 /** 从混了普通日志的 stdout 里抠出 JSONL(只留看起来是 JSON 对象的行)。 */
@@ -87,35 +116,41 @@ function extractJsonlFromStdout(stdout: string | undefined): string | undefined
 
 /** 从 codex 的 --json stdout 里取 thread_id(thread.started 事件),供下一轮 resume。 */
 function codexThreadId(stdout: string | undefined): string | undefined {
-  if (!stdout) return undefined;
-  for (const line of stdout.split("\n")) {
-    const t = line.trim();
-    if (!t) continue;
-    try {
-      const e = JSON.parse(t) as { type?: string; thread_id?: unknown };
-      if (e.type === "thread.started" && typeof e.thread_id === "string") return e.thread_id;
-    } catch {
-      // 跳过
-    }
-  }
-  return undefined;
+  return scanJsonl(stdout, (obj) =>
+    obj.type === "thread.started" ? (obj.thread_id as string | undefined) : undefined,
+  );
 }
 
 /** 扫 JSONL,返回第一个出现的 field 的字符串值。 */
 function firstJsonField(raw: string | undefined, field: string): string | undefined {
-  if (!raw) return undefined;
-  for (const line of raw.split("\n")) {
-    const t = line.trim();
-    if (!t) continue;
-    try {
-      const obj = JSON.parse(t) as Record<string, unknown>;
-      const v = obj[field];
-      if (typeof v === "string" && v) return v;
-    } catch {
-      // 跳过
-    }
-  }
-  return undefined;
+  return scanJsonl(raw, (obj) => obj[field] as string | undefined);
+}
+
+
+/**
+ * 非零退出的通用诊断:退出码、transcript 有无、事件数、最后一条 error、输出末尾,
+ * 拼成一条可读信息。adapter 在 status=failed 时把它塞进 error 事件——
+ * 否则 transcript 为空时失败原因彻底丢失,用户只能干瞪眼。
+ */
+function diagnoseFailure(
+  res: { exitCode: number; stdout: string; stderr: string },
+  events: readonly StreamEvent[],
+  rawTranscript: string | undefined,
+): string {
+  const parts: string[] = [t("agent.diagnose.exitCode", { code: res.exitCode })];
+  if (rawTranscript === undefined) parts.push(t("agent.diagnose.noTranscript"));
+  else if (events.length === 0) parts.push(t("agent.diagnose.zeroEvents"));
+  const lastErr = [...events].reverse().find((e) => e.type === "error") as
+    | { type: "error"; message: string }
+    | undefined;
+  if (lastErr) parts.push(t("agent.diagnose.lastError", { message: lastErr.message }));
+  const errTail = outputTail(res.stderr) || outputTail(res.stdout);
+  if (errTail) parts.push(t("agent.diagnose.outputTail", { tail: errTail }));
+  return parts.join(" · ");
+}
+
+function outputTail(s: string, n = 6): string {
+  return s.trim().split("\n").filter(Boolean).slice(-n).join(" ⏎ ").slice(0, 600);
 }
 
 /**
@@ -130,6 +165,9 @@ export const shared = {
   extractJsonlFromStdout,
   codexThreadId,
   firstJsonField,
+  /** 把文本包成 shell 单引号字面量(含转义)。与 sandbox 后端同一份实现,别在 adapter 里手写。 */
+  shellQuote,
+  diagnoseFailure,
   /** 原始 codex JSONL → 标准事件流 + 用量 + 压缩计数。 */
   parseCodex(raw: string | undefined): ParsedTranscript {
     return parseCodexTranscript(raw);