@xyagent/cli 0.0.1

package/src-ext/runtime/claude/stdoutParser.mjs

@@ -0,0 +1,365 @@
+// Claude CLI stdout-json 解析器。
+//
+// claude-code CLI 在 `--output-format stream-json --verbose` 模式下，每行
+// 一个 JSON 对象。典型形状（随版本可能微调）：
+//
+//   {"type":"system","subtype":"init","session_id":"...","model":"...",...}
+//   {"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}
+//   {"type":"assistant","message":{"role":"assistant","content":[
+//     {"type":"text","text":"..."},
+//     {"type":"tool_use","id":"toolu_...","name":"Read","input":{...}},
+//   ],"stop_reason":"end_turn"}}
+//   {"type":"result","subtype":"success","total_cost_usd":0.001,"duration_ms":1234,"session_id":"..."}
+//
+// 设计原则：
+//   - 未知 type → 打 warn + 返回 { kind:"unknown" }，绝不 throw。
+//   - 每一个 assistant content 块拆成独立 agentlink 事件：
+//     text → assistant_text ；tool_use → tool_use ；thinking → thinking
+//   - session id / model 等元信息由 init 行带出，单独产生 session_ready。
+
+/**
+ * @typedef {Object} NormalizedEvent
+ * @property {"assistant_text"|"tool_use"|"tool_use_end"|"thinking"|"session_ready"|"session_end"|"error"|"usage_snapshot"|"rate_limit_alert"|"unknown"} kind
+ * @property {Record<string, any>} payload
+ */
+
+/**
+ * 解析一行已经是 object 的 JSON —— caller 负责 `JSON.parse` 和 schema 校验。
+ * 返回 0 ~ N 条 normalized 事件（一条 assistant 可能含多个 content 块）。
+ *
+ * @param {any} line
+ * @returns {NormalizedEvent[]}
+ */
+export function normalizeClaudeLine(line) {
+  if (!line || typeof line !== "object") return [];
+  const type = typeof line.type === "string" ? line.type : "";
+  switch (type) {
+    case "system": {
+      const subtype = line.subtype || "";
+      if (subtype === "init") {
+        return [{
+          kind: "session_ready",
+          payload: {
+            session_id: line.session_id || null,
+            model: line.model || null,
+            cwd: line.cwd || null,
+            tools: Array.isArray(line.tools) ? line.tools : [],
+          },
+        }];
+      }
+      // 其它 system 子类型暂归为 unknown，不产生事件
+      return [];
+    }
+    case "user": {
+      // user 行通常是 echo（plain text），但 tool_result 块携带工具执行结果 —— 推送 tool_use_end
+      const message = line.message || {};
+      const content = Array.isArray(message.content) ? message.content : [];
+      // spec §8.4: parent_tool_use_id 标识"这条 user 消息是某 subagent 的 tool_result
+      // 输入"。透传给 index.mjs,index.mjs 维护 toolu_id → child_run_id 映射。
+      const parentToolUseId = typeof line.parent_tool_use_id === "string"
+        ? line.parent_tool_use_id : null;
+      const out = [];
+      for (const block of content) {
+        if (!block || typeof block !== "object") continue;
+        if (block.type !== "tool_result") continue;
+        out.push({
+          kind: "tool_use_end",
+          payload: {
+            tool_id: block.tool_use_id || null,
+            is_error: block.is_error === true,
+            result: extractToolResultText(block.content),
+            parent_tool_use_id: parentToolUseId,
+          },
+        });
+      }
+      return out;
+    }
+    case "stream_event": {
+      // launcher 开启 --include-partial-messages 后，claude CLI 会按 Anthropic
+      // SDK 形式逐 token 推送 stream_event。我们只关心两类增量：
+      //   - content_block_delta + text_delta  → assistant_text 增量
+      //   - content_block_delta + thinking_delta → thinking 增量
+      // 其它（message_start / content_block_start/stop / message_delta /
+      // message_stop / input_json_delta 等）当前不翻译——message_stop 的
+      // turn_end 信号由后续 `assistant` 行的 stop_reason marker 兜底；
+      // tool_use 完整 input 由 `assistant` 行携带，比 input_json_delta 拼装更可靠。
+      const evt = line.event || {};
+      const parentToolUseId = typeof line.parent_tool_use_id === "string"
+        ? line.parent_tool_use_id : null;
+      if (evt.type !== "content_block_delta") return [];
+      const delta = evt.delta || {};
+      if (delta.type === "text_delta") {
+        const text = typeof delta.text === "string" ? delta.text : "";
+        if (!text) return [];
+        return [{
+          kind: "assistant_text",
+          payload: { text, parent_tool_use_id: parentToolUseId },
+        }];
+      }
+      if (delta.type === "thinking_delta") {
+        const text = typeof delta.thinking === "string" ? delta.thinking : "";
+        if (!text) return [];
+        return [{
+          kind: "thinking",
+          payload: { text, parent_tool_use_id: parentToolUseId },
+        }];
+      }
+      return [];
+    }
+    case "assistant": {
+      const message = line.message || {};
+      const content = Array.isArray(message.content) ? message.content : [];
+      // spec §8.4: parent_tool_use_id 非 null = 这是子 agent (Task tool 启动) 的输出。
+      const parentToolUseId = typeof line.parent_tool_use_id === "string"
+        ? line.parent_tool_use_id : null;
+      // claude 给 slash 命令(/cost /context /usage /init 等)的响应走"synthetic"
+      // 模式: model="<synthetic>", 不走 LLM, 没有 stream_event 增量, **整段
+      // 文本只在这条 assistant 消息的 content[].text 里出现一次**。普通对话
+      // 才会被 --include-partial-messages 的 text_delta 提前推送, 此处需要
+      // 跳过避免翻倍。所以判依据: model="<synthetic>" → 直接 emit; 否则跳。
+      const isSyntheticSlashResponse = message.model === "<synthetic>";
+      const out = [];
+      for (const block of content) {
+        if (!block || typeof block !== "object") continue;
+        const btype = block.type;
+        if (btype === "text") {
+          if (isSyntheticSlashResponse) {
+            // synthetic 模式: 没有 partial delta, 完整文本在 block.text;
+            // 直接 emit 一条 assistant_text, 否则 bridge 收不到任何内容。
+            // 同时把 synthetic 标记带上去, 让 handleRequest 知道这轮 claude 没
+            // 真写 session jsonl, 不要把 session_id 落进 threadSessionMap
+            // (否则下轮 --resume <synthetic-sid> 必报 "No conversation found")。
+            const text = typeof block.text === "string" ? block.text : "";
+            if (text) {
+              out.push({
+                kind: "assistant_text",
+                payload: { text, parent_tool_use_id: parentToolUseId, synthetic: true },
+              });
+            }
+          }
+          // 否则: 启用 --include-partial-messages 后，text 内容已经通过 stream_event
+          // text_delta 逐 token 推过了, assistant 行携带的是 final 完整 text —— 再
+          // emit 一遍会让 envelope_builder 把整段重复拼到同一个 content_block 上,
+          // App 上看到内容翻倍。所以这里跳过。
+          // 注：text 块的 fall-through marker (stop_reason) 仍由下面的代码兜底。
+          continue;
+        } else if (btype === "tool_use") {
+          out.push({
+            kind: "tool_use",
+            payload: {
+              tool_id: block.id || null,
+              name: block.name || "",
+              input: block.input || {},
+              parent_tool_use_id: parentToolUseId,
+            },
+          });
+        } else if (btype === "thinking") {
+          // 同 text：partial 流已经把 thinking 增量推完，跳过 final 完整快照
+          // 防止 App 端 reasoning 段翻倍。
+          continue;
+        }
+        // 未知 content 类型忽略
+      }
+      // 每条 assistant 消息带 usage —— 翻译成 token 增量
+      const tokensDelta = extractTokensDelta(message.usage);
+      if (tokensDelta) {
+        out.push({ kind: "usage_snapshot", payload: { tokens_delta: tokensDelta } });
+      }
+      if (message.stop_reason) {
+        out.push({
+          kind: "assistant_text",
+          payload: { stop_reason: message.stop_reason, _marker: "turn_end" },
+        });
+      }
+      return out;
+    }
+    case "result": {
+      const out = [];
+      // result 行包含本轮累计 cost/turns/duration；把它喂给 usageReporter
+      const cost = extractCost(line);
+      const tokensDelta = extractTokensDelta(line.usage);
+      if (cost || tokensDelta) {
+        out.push({
+          kind: "usage_snapshot",
+          payload: {
+            ...(cost ? { cost } : {}),
+            ...(tokensDelta ? { tokens_delta: tokensDelta } : {}),
+          },
+        });
+      }
+      // 限流 / 失败结果追发一条 error —— 否则 App 只看到自己发的消息没回复，
+      // 不知道是"还在思考"还是"失败了"。claude 把失败分两路下发：
+      //   (1) result 行带 is_error=true / subtype=error_*
+      //   (2) 下游的 rate_limit 独立事件（上面 case "rate_limit" 已处理）
+      // 这里兜第一路。
+      const subtype = typeof line.subtype === "string" ? line.subtype : "";
+      const isError = line.is_error === true
+        || subtype.startsWith("error")
+        || subtype === "rate_limit";
+      if (isError) {
+        const errText = typeof line.result === "string" && line.result.trim()
+          ? line.result.trim()
+          : (typeof line.error === "string" && line.error.trim()
+              ? line.error.trim()
+              : (subtype === "rate_limit"
+                  ? "Claude 已触达配额，请稍后再试。"
+                  : `Claude 本轮失败：${subtype || "unknown"}`));
+        out.push({
+          kind: "error",
+          payload: {
+            stage: "claude.result",
+            subtype,
+            err: errText,
+          },
+        });
+      }
+      out.push({
+        kind: "session_end",
+        payload: {
+          subtype: subtype,
+          cost_usd: typeof line.total_cost_usd === "number" ? line.total_cost_usd : null,
+          duration_ms: typeof line.duration_ms === "number" ? line.duration_ms : null,
+          session_id: line.session_id || null,
+          is_error: line.is_error === true,
+        },
+      });
+      return out;
+    }
+    case "rate_limit":
+    case "rate_limit_event": {
+      // Claude 未来可能推送的配额告警事件；形状未公开，做宽容兜底。
+      const retryAfterMs = toIntOrNull(
+        line.retry_after_ms != null
+          ? line.retry_after_ms
+          : (typeof line.retry_after === "number" ? line.retry_after * 1000 : null)
+      );
+      const msg = typeof line.message === "string"
+        ? line.message
+        : (typeof line.reason === "string" ? line.reason : "");
+      return [{
+        kind: "rate_limit_alert",
+        payload: { retry_after_ms: retryAfterMs, message: msg },
+      }];
+    }
+    default:
+      return [{ kind: "unknown", payload: { raw_type: type } }];
+  }
+}
+
+/**
+ * LineStreamParser：接收 stdout 数据块（字符串或 Buffer），按 `\n` 切行，
+ * 每完整行解析成 object。UTF-8 边界安全（用 TextDecoder incremental）。
+ *
+ * 使用：
+ *   const p = createLineStreamParser({ onObject, onInvalid, log });
+ *   claude.stdout.on("data", (buf) => p.push(buf));
+ *   claude.stdout.on("end", () => p.flush());
+ */
+export function createLineStreamParser({ onObject, onInvalid, log, bufferLimit = 1 << 20 }) {
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+  const pLog = log ? log.child({ comp: "stdout" }) : null;
+
+  function feedLine(line) {
+    const trimmed = line.replace(/\r$/, "");
+    if (trimmed === "") return;
+    let obj;
+    try {
+      obj = JSON.parse(trimmed);
+    } catch (err) {
+      pLog?.warn("stdout.schema.mismatch", "json parse failed", {
+        err: err?.message || String(err),
+        sample: trimmed.slice(0, 200),
+      });
+      if (typeof onInvalid === "function") onInvalid(trimmed);
+      return;
+    }
+    if (!obj || typeof obj !== "object") {
+      pLog?.warn("stdout.schema.mismatch", "non-object line", { sample: trimmed.slice(0, 200) });
+      return;
+    }
+    pLog?.debug("stdout.line.parsed", "line parsed", {
+      type: obj.type || "", has_message: !!obj.message,
+    });
+    try { onObject(obj); }
+    catch (err) {
+      pLog?.error("error.caught", "onObject threw", {
+        where: "stdoutParser.onObject",
+        err: err?.message || String(err),
+      });
+    }
+  }
+
+  return {
+    push(chunk) {
+      const text = typeof chunk === "string"
+        ? chunk
+        : decoder.decode(chunk, { stream: true });
+      buf += text;
+      if (buf.length > bufferLimit) {
+        pLog?.warn("stdout.buffer.overflow", "buffer exceeded limit; truncating", {
+          limit: bufferLimit, size: buf.length,
+        });
+        // 保留最后 half：避免"一行超过 limit" 时死循环
+        buf = buf.slice(-(bufferLimit / 2) | 0);
+      }
+      let idx;
+      while ((idx = buf.indexOf("\n")) >= 0) {
+        const line = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        feedLine(line);
+      }
+    },
+    flush() {
+      if (buf) {
+        feedLine(buf);
+        buf = "";
+      }
+    },
+  };
+}
+
+/**
+ * 从 Claude usage 对象里抽取 token 增量。
+ * Claude 官方 usage 字段：
+ *   input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens
+ * 归一到 usageReporter 接受的形状：{ input, cached_input, output }。
+ * 其中 cache_creation 计入 input（Anthropic 计费按 input 计），cache_read 单独记 cached_input。
+ */
+function extractTokensDelta(usage) {
+  if (!usage || typeof usage !== "object") return null;
+  const input = toIntOrZero(usage.input_tokens) + toIntOrZero(usage.cache_creation_input_tokens);
+  const cached = toIntOrZero(usage.cache_read_input_tokens);
+  const output = toIntOrZero(usage.output_tokens);
+  if (input === 0 && cached === 0 && output === 0) return null;
+  return { input, cached_input: cached, output };
+}
+
+/** 从 result 行提取 cost 段（total_cost_usd / num_turns / duration_ms）。 */
+function extractCost(line) {
+  const totalUsd = typeof line.total_cost_usd === "number" ? line.total_cost_usd : null;
+  const turns = toIntOrNull(line.num_turns);
+  const durationMs = toIntOrNull(line.duration_ms);
+  if (totalUsd == null && turns == null && durationMs == null) return null;
+  return {
+    total_usd: totalUsd,
+    turns: turns,
+    duration_ms: durationMs,
+  };
+}
+
+function toIntOrZero(v) { return Number.isFinite(v) ? Math.trunc(v) : 0; }
+function toIntOrNull(v) { return Number.isFinite(v) ? Math.trunc(v) : null; }
+
+// 从 tool_result 的 content 字段里提取可读文本。
+// content 可以是字符串、text block 数组、或 null。
+function extractToolResultText(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    const parts = content
+      .filter((b) => b && b.type === "text" && typeof b.text === "string")
+      .map((b) => b.text);
+    return parts.length > 0 ? parts.join("\n") : null;
+  }
+  return null;
+}

package/src-ext/runtime/claude/todoTranslator.mjs

@@ -0,0 +1,66 @@
+/**
+ * todoTranslator.mjs — Claude runtime TodoWrite → todo_list block translator
+ *
+ * 按 translator-spec.md 和 npm-cli-todo-translator-claude spec 实现：
+ *   - 识别 kind==="tool_use" && name==="TodoWrite"
+ *   - 转写为 content_block.started + content_block.completed (todo_list block)
+ *   - 对应的 tool_use_end 静默丢弃
+ *   - 其他事件原样透传
+ */
+
+import {
+  buildBlockStarted,
+  buildBlockCompleted,
+  newBlockId,
+} from "../../../src-shared/envelope_builder.mjs";
+import { buildTodoItems } from "../_shared/todoTranslatorUtils.mjs";
+
+/**
+ * 创建 Claude TodoWrite translator 实例。
+ *
+ * @param {string} runId  当前 run 的 run_id，用于构造 envelope
+ * @returns {{ intercept(event: object): object[] }}
+ */
+export function createClaudeTodoTranslator(runId) {
+  // 已拦截的 tool_call_id 集合，用于静默丢弃对应的 tool_use_end
+  const interceptedIds = new Set();
+
+  return {
+    /**
+     * @param {object} event  normalized event（kind + payload）
+     * @returns {object[]}    0~2 个 envelope 或原始事件
+     */
+    intercept(event) {
+      if (!event || typeof event !== "object") return [event];
+
+      // 拦截 TodoWrite tool_use
+      if (event.kind === "tool_use" && event.payload?.name === "TodoWrite") {
+        const toolId = event.payload.tool_id;
+        if (toolId) interceptedIds.add(toolId);
+
+        const rawTodos = Array.isArray(event.payload?.input?.todos)
+          ? event.payload.input.todos
+          : [];
+        const items = buildTodoItems(rawTodos);
+        const blockId = newBlockId();
+        const block = { id: blockId, type: "todo_list", items };
+
+        return [
+          buildBlockStarted(runId, block),
+          buildBlockCompleted(runId, { ...block }),
+        ];
+      }
+
+      // 静默丢弃已拦截的 tool_use_end
+      if (event.kind === "tool_use_end") {
+        const toolId = event.payload?.tool_id;
+        if (toolId && interceptedIds.has(toolId)) {
+          return [];
+        }
+      }
+
+      // 其他事件原样透传
+      return [event];
+    },
+  };
+}