@xyagent/cli 0.0.1

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

@@ -0,0 +1,160 @@
+// Claude 桥接入口 — long-poll worker 模式。
+//
+// 核心流程:
+//   1. preflight(claude 二进制 + 版本)
+//   2. consume pair code 拿 (gw_id, bridge_token)
+//   3. 起 relayWorker,进入 long-poll 主循环
+//   4. 每条 in-flight user request:
+//      a. 抽 user text → spawn `claude --print` 子进程
+//      b. 写入 stdin(user message stream-json)
+//      c. 监听 stdout 行 → 直接以 {event:"chunk", data:<line>} 推回服务端
+//         服务端 claude adapter 用 native stream-json 形态消化
+//      d. 子进程退出 → publish {event:"end"}
+//
+// 设计简化:long-poll 模式下 claude 子进程是"单次 turn"语义,不再持有跨 turn
+// 的 SSE 订阅 / hookServer / 审批闸门。这些能力将在后续版本以"反向 worker push"
+// 端点单独引入(与 long-poll 同一通道,但是另一类 request kind)。
+
+import process from "node:process";
+import path from "node:path";
+
+import { createSessionSlot, SESSION_STATES } from "../../core/sessionSlot.mjs";
+import { createRelayWorker } from "../../core/relayWorker.mjs";
+import { bootstrapAgentlinkTools } from "../../core/agentlinkToolsBootstrap.mjs";
+import { installAutoTunnel } from "../../core/autoTunnelWiring.mjs";
+import { resolveSession } from "../../core/pairCodeClient.mjs";
+import { createUsageReporter } from "../../core/usageReporter.mjs";
+import { runWorkerWithRevokeHandling } from "../../core/bridgeSelfUninstall.mjs";
+
+import { claudePreflight } from "./preflight.mjs";
+import { createClaudeHandleRequest } from "./handleRequest.mjs";
+import { createApprovalGateway } from "../../core/approvalGateway.mjs";
+
+export async function runClaudeBridge({ options, positional, log }) {
+  const cwd = path.resolve(options.cwd || process.cwd());
+
+  // 1. preflight
+  const pre = claudePreflight({ log });
+  if (!pre.ok) {
+    process.stderr.write(`claude preflight failed: ${pre.error}\n`);
+    if (pre.hint) process.stderr.write(`${pre.hint}\n`);
+    process.exit(65);
+  }
+
+  // 2. resolve session
+  let gwId, relayBase, bridgeToken;
+  try {
+    const r = await resolveSession({ runtime: "claude", options, log });
+    gwId = r.gwId;
+    relayBase = r.relayUrl;
+    bridgeToken = r.bridgeToken;
+    log.info("bridge.preflight.pass", "claude runtime entry reached", {
+      cwd, relay: relayBase, gw_id: gwId, source: r.source, has_bridge_token: !!bridgeToken,
+    });
+  } catch (err) {
+    process.stderr.write(`${err?.message || err}\n`);
+    process.exit(65);
+  }
+  if (!bridgeToken) {
+    process.stderr.write("缺少 bridge_token,请重新运行 agentlink pair <code> -r claude\n");
+    process.exit(65);
+  }
+
+  const sessLog = log.child({ gw: gwId });
+
+  // 5.1 实例化 approvalGateway（approval 模式下用于审批桥接）
+  const approvalGateway = createApprovalGateway({ log: sessLog });
+  // 5.4 approval 模式启动日志
+  const permissionMode = process.env.AGENTLINK_CLAUDE_PERMISSION_MODE || "bypassPermissions";
+  if (permissionMode === "approval" || permissionMode === "default") {
+    sessLog.info("bridge.approval_mode.enabled", "claude bridge approval mode enabled", {
+      permission_mode: permissionMode,
+    });
+  }
+
+  const worker = createRelayWorker({
+    relayUrl: relayBase, gwId, bridgeToken, runtime: "claude", log: sessLog,
+  });
+  installAutoTunnel({ relayUrl: relayBase, log: sessLog });
+
+  let lastRequestId = null;
+  const usage = createUsageReporter({
+    runtime: "claude", log: sessLog,
+    publishEvent: (event) => {
+      if (!lastRequestId) return Promise.resolve(false);
+      return worker.publishEvent(lastRequestId, event);
+    },
+  });
+  // Claude 4.x 默认 200k context window。token_count 事件 finalize 时会按实际值精确化。
+  usage.setContextWindow(200_000);
+
+  const slot = createSessionSlot({ log: sessLog, name: "claude" });
+  slot.transition(SESSION_STATES.READY, "worker-ready");
+
+  // 拉起 agentlinkToolsServer + 写 discovery 文件,让 4 个 runtime 的 MCP 客户端
+  // 都能通过 agentlink-mcp-stdio 访问 agentlink 自定义工具(change_title /
+  // notify_user / attach_file)。失败不致命:tools server 出问题不应该让 bridge
+  // 整体启动失败,只是 agentlink 工具暂时不可用。
+  let toolsLifecycle = null;
+  try {
+    toolsLifecycle = await bootstrapAgentlinkTools({
+      runtime: "claude", gwId, relayUrl: relayBase, bridgeToken,
+      worker, log: sessLog, version: pre?.version || "",
+      getLastRequestId: () => lastRequestId,
+    });
+  } catch (err) {
+    sessLog.warn("agentlink_tools.bootstrap.failed",
+      "agentlink tools server failed to start; continuing without tools", { err: err?.message });
+  }
+
+  let shuttingDown = false;
+  async function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    sessLog.info("bridge.shutdown", "shutting down", { reason });
+    worker.stop(reason);
+    try { usage.dispose(); } catch {}
+    if (toolsLifecycle?.stop) {
+      try { await toolsLifecycle.stop(); } catch {}
+    }
+    // 5.3 dispose approvalGateway：pending 审批全部 reject（bridge 关闭时防止 claude 子进程永久挂起）
+    try { approvalGateway.dispose("bridge-shutdown"); } catch {}
+  }
+  process.once("SIGINT", () => { void shutdown("SIGINT").then(() => process.exit(0)); });
+  process.once("SIGTERM", () => { void shutdown("SIGTERM").then(() => process.exit(0)); });
+
+  // ---- handler:每条 in-flight 请求一次完整 turn ----
+  // D-C2.3.3: 替换内联 handleRequest，改为 createClaudeHandleRequest 工厂函数
+  const _handleRequestImpl = createClaudeHandleRequest({
+    cwd,
+    log: sessLog,
+    usage,
+    bridgeCtx: {
+      version: pre?.version || "",
+      gwId,
+      model: null, // claude CLI 默认模型 bridge 没主动捕获,留空 → /model slash 走"未知"分支
+    },
+    dispatchHandlerOptions: {
+      relayUrl: relayBase,
+      bridgeToken,
+      // 5.2 传入 approvalGateway（approval 模式时生效）
+      approvalGateway,
+    },
+    scanner: toolsLifecycle?.scanner ?? null,
+  });
+
+  async function handleRequest(request, ctx) {
+    lastRequestId = ctx.requestId;
+    return _handleRequestImpl(request, ctx);
+  }
+
+  sessLog.info("bridge.loop.entered", "claude worker entering long-poll loop", {
+    gw_id: gwId, cwd, version: pre.version || "",
+  });
+  // 双向解绑：收到 App 端 deleteContact 触发的 HTTP 404 时自动清状态 + 卸 plist。
+  await runWorkerWithRevokeHandling({
+    worker, handler: handleRequest, runtime: "claude", log: sessLog,
+  });
+}
+
+// helpers 已移入 handleRequest.mjs

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

@@ -0,0 +1,58 @@
+/**
+ * internalCommandNames.mjs
+ *
+ * 导出 claude 内置命令名集合的只读引用，供 customCommandsCollector 计算差集。
+ * 与 slashCommandRouter.mjs 保持同步——每次新增/删除内置命令时两处都要更新。
+ *
+ * 注：不直接从 slashCommandRouter 导入是为了避免循环依赖（router 同时依赖 cliExec，
+ * 而 cliExec 有 spawn 副作用，单元测试不希望引入）。
+ */
+
+/**
+ * claude CLI 在 `--print --input-format stream-json` 下真实执行的命令（透传）。
+ * 同步自 slashCommandRouter.mjs CLAUDE_CLI_HANDLED。
+ */
+export const CLAUDE_CLI_HANDLED = new Set([
+  "/compact",
+  "/context",
+  "/init",
+  "/review",
+  "/security-review",
+  "/cost",
+  "/usage",
+]);
+
+/**
+ * TUI 对齐命令——改写为自然语言 prompt 真跑。
+ * 同步自 slashCommandRouter.mjs CLAUDE_PROMPT_REWRITES（仅键名）。
+ */
+export const CLAUDE_PROMPT_REWRITES = {
+  "/diff": true,
+  "/recap": true,
+};
+
+/**
+ * bridge 有等价合成实现的命令（含 __default__）。
+ * 同步自 slashCommandRouter.mjs CLAUDE_HANDLERS（仅键名）。
+ */
+export const CLAUDE_HANDLERS = {
+  "/help": true,
+  "/status": true,
+  "/model": true,
+  "/version": true,
+  "/agents": true,
+  "/skills": true,
+  "/memory": true,
+  "/permissions": true,
+  "/resume": true,
+  "/rewind": true,
+  "/branch": true,
+  "/config": true,
+  "/hooks": true,
+  "/mcp": true,
+  "/doctor": true,
+  "/export": true,
+  "/rename": true,
+  "/feedback": true,
+  "__default__": true,
+};

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

@@ -0,0 +1,313 @@
+// Claude 子进程启动器。
+//
+// 直接 spawn `claude` 二进制（而不是 happy-cli 风格的 node + wrapper）——
+// 依赖少、跨平台干净。stream-json 模式下 stdin/stdout 是标准 JSON 行。
+//
+// stdin 格式（Claude 接受）：
+//   {"type":"user","message":{"role":"user","content":[{"type":"text","text":"..."}]}}\n
+//
+// stdout 格式见 stdoutParser.mjs。
+//
+// 生命周期由 caller (sessionManager) 控制。launcher 只管起、终、管道。
+
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { fetchAndBase64Encode } from "../_shared/fetchAndBase64Encode.mjs";
+import { relayObjectToBlock } from "../_shared/relayObjectToBlock.mjs";
+
+const DEFAULT_ARGS = [
+  "--print",                       // 打印完成后自动退出（而非交互 REPL）
+  "--verbose",                     // stream-json 需要 verbose
+  "--output-format", "stream-json",
+  "--input-format", "stream-json",
+  // 不加这个 flag 时，claude CLI 会把整段 assistant 攒成一条 stream-json 行
+  // 在末尾才吐 → App 端表现是"憋一下整段刷出来"。开启后 claude 会以
+  // stream_event 形式（content_block_delta + text_delta）逐 token 推送，
+  // stdoutParser 把它翻译成 assistant_text 增量，flusher 一条一发，
+  // App SSE 拿到一条渲染一条 → 真正的流式体验。
+  "--include-partial-messages",
+];
+
+/**
+ * 启动 claude 子进程并返回 { child, kill }。
+ * @param {{ cwd: string, resumeSessionId?: string, extraArgs?: string[], env?: object, log: any, signal?: AbortSignal }} opts
+ */
+export function spawnClaude(opts) {
+  const { cwd, resumeSessionId, extraArgs = [], env, log, signal, cwdSource } = opts;
+  if (!log) throw new Error("spawnClaude: log required");
+  if (!cwd) throw new Error("spawnClaude: cwd required");
+
+  const isWin = process.platform === "win32";
+
+  const args = [...DEFAULT_ARGS];
+  // P0#16/#26: --print 模式下没有 canUseTool 桥接，default 权限模式会把需授权
+  // 的工具（WebSearch / Bash 写操作等）直接拒绝（"This command requires
+  // approval"），而 App 端没有任何审批弹窗可弹。按产品既有口径（bridge /help、
+  // /permissions 文案承诺的默认 bypassPermissions）显式传参；需要更严格模式时
+  // 用 AGENTLINK_CLAUDE_PERMISSION_MODE 覆盖：
+  //   - "bypassPermissions"（默认）：跳过所有权限检查。
+  //   - "inherit"：不传 --permission-mode，沿用 claude 本机配置。
+  //   - "approval"/"default"：启用审批弹窗模式（permission-prompt-tool MCP 桥接）。
+  //     此模式下 handleRequest.mjs 额外注入：
+  //       --permission-mode default
+  //       --permission-prompt-tool mcp__agentlink-permission__agentlink_permission_prompt
+  //       --setting-sources project
+  //       --mcp-config <tmp-file>
+  //     ⚠️ 副作用：--setting-sources project 排除用户级（~/.claude/settings.json）的
+  //     工具 allow 规则（如 Bash(*)）。如需在 approval 模式下自动放行某些工具，
+  //     请在工作区的 .claude/settings.json 中配置而非 ~/.claude/settings.json。
+  //   extraArgs（由 handleRequest.mjs approval 模式注入）优先于此处的 --permission-mode。
+  const permissionMode = process.env.AGENTLINK_CLAUDE_PERMISSION_MODE || "bypassPermissions";
+  // approval/default 模式由 handleRequest.mjs 通过 extraArgs 注入完整参数；
+  // 此处只处理 bypass / inherit / 其他标准模式。
+  const isApprovalModeExternal = permissionMode === "approval" || permissionMode === "default";
+  if (!isApprovalModeExternal && permissionMode !== "inherit") args.push("--permission-mode", permissionMode);
+  if (resumeSessionId) args.push("--resume", resumeSessionId);
+  for (const a of extraArgs) args.push(a);
+
+  const mergedEnv = { ...process.env, ...(env || {}) };
+  // 防止 claude 自己再注册 SIGINT → 子进程退出时 parent 收到多余信号
+  // 交给 sessionManager 精确控制
+
+  const child = spawn("claude", args, {
+    cwd,
+    env: mergedEnv,
+    // stdio: [stdin, stdout, stderr]
+    stdio: ["pipe", "pipe", "pipe"],
+    shell: isWin ? true : false,
+    windowsHide: true,
+  });
+
+  const cLog = log.child({ comp: "child", pid: child.pid });
+  cLog.info("child.spawn", "claude spawned", {
+    cwd, args: args.join(" "), resume: resumeSessionId || null,
+    source: cwdSource || "default",
+  });
+
+  // 将 stderr 尾部周期性上报 —— 仅在出现问题时。存入一个 ring buffer。
+  const stderrRing = createRing(4096);
+  child.stderr.on("data", (buf) => stderrRing.push(buf.toString("utf8")));
+
+  // 外部 signal 触发 kill
+  if (signal) {
+    if (signal.aborted) {
+      safeKill(child, cLog, "aborted-before-spawn");
+    } else {
+      signal.addEventListener("abort", () => safeKill(child, cLog, "signal-abort"), { once: true });
+    }
+  }
+
+  let exited = false;
+  child.once("exit", (code, sig) => {
+    exited = true;
+    cLog.info("child.exit", "claude exited", {
+      code, signal: sig, stderr_tail: stderrRing.tail(800),
+    });
+  });
+  child.once("error", (err) => {
+    cLog.error("child.error", "claude emit error", {
+      err: err?.message || String(err), code: err?.code || "",
+    });
+  });
+
+  return {
+    child,
+    getStderrTail: (n = 800) => stderrRing.tail(n),
+    isExited: () => exited,
+    kill: (reason = "manual") => safeKill(child, cLog, reason),
+  };
+}
+
+/**
+ * safeKill：先 SIGTERM，2s 未死再 SIGKILL。Windows 上两者都走 taskkill。
+ */
+function safeKill(child, log, reason) {
+  if (!child || child.killed) return;
+  try {
+    log.info("child.kill.term", "sending SIGTERM", { reason });
+    child.kill("SIGTERM");
+  } catch (err) {
+    log.warn("child.kill.term.failed", "SIGTERM failed", { err: err?.message || String(err) });
+  }
+  const deadline = setTimeout(() => {
+    if (child.exitCode === null && !child.killed) {
+      log.warn("child.kill.force", "SIGKILL after timeout", { reason });
+      try { child.kill("SIGKILL"); } catch {}
+    }
+  }, 2000);
+  deadline.unref?.();
+}
+
+function createRing(capacity) {
+  let buf = "";
+  return {
+    push(s) {
+      buf += s;
+      if (buf.length > capacity) buf = buf.slice(-capacity);
+    },
+    tail(n) {
+      return buf.slice(-n);
+    },
+  };
+}
+
+/**
+ * 向 claude stdin 写 AskUserQuestion 的 tool_result 回填消息。
+ * stream-json 协议：一行 JSON，紧跟 \n。
+ *
+ * Claude SDK 要求 AskUserQuestion tool_result 格式：
+ *   content[0].type = "tool_result"
+ *   content[0].tool_use_id = <被拦截工具的 tool_id>
+ *   content[0].content[0].type = "text"
+ *   content[0].content[0].text = JSON.stringify({ questions, answers })
+ *
+ * @param {object} child  claude 子进程
+ * @param {string} toolUseId  AskUserQuestion 的 tool_id
+ * @param {object} value  回填内容（{ questions, answers } 或 { questions, canceled: true }）
+ */
+export function writeToolResult(child, toolUseId, value) {
+  if (!child || !child.stdin || child.stdin.destroyed) {
+    throw new Error("writeToolResult: stdin not available");
+  }
+  const payload = {
+    type: "user",
+    message: {
+      role: "user",
+      content: [
+        {
+          type: "tool_result",
+          tool_use_id: toolUseId,
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(value),
+            },
+          ],
+        },
+      ],
+    },
+  };
+  const line = JSON.stringify(payload) + "\n";
+  return new Promise((resolve, reject) => {
+    child.stdin.write(line, (err) => (err ? reject(err) : resolve()));
+  });
+}
+
+/**
+ * 向 claude stdin 写一条 user message。
+ * stream-json 协议：一行 JSON，紧跟 \n。
+ *
+ * Phase 5 (multimodal-attachment-llm-dispatch): 迁移到 relayObjectToBlock 共享模块。
+ * 通过 relayObjectToBlock 处理 relay_object blocks（含 attachment_kind 字段），
+ * 并将结果转换为 Anthropic Messages API 格式。
+ *
+ * content array 构造规则（Anthropic Messages API 格式）：
+ *   1. 若 text 非空，加 {type:"text", text} block
+ *   2. 遍历 blocks 中 source.kind=url 的 relay_object block，通过 relayObjectToBlock 转换：
+ *      - input_image → {type:"image", source:{type:"base64", media_type, data}}
+ *      - input_file  → {type:"document", source:{type:"base64", media_type, data}}
+ *      - input_text  → {type:"text", text}
+ *      - error       → {type:"text", text:"[<kind>] (encoding failed: <error>)"}
+ *   3. 后向兼容：非 relay_object blocks（source.kind≠url）被忽略
+ *   纯图片/纯 PDF 场景（text 为空）：content array 只含对应 block，不含空 text block
+ *
+ * @param {object} child - claude 子进程
+ * @param {string} text - 用户文字 prompt
+ * @param {any[]} blocks - dispatch payload blocks 数组（可选）
+ * @param {{ _fetchAndBase64Encode?: Function }} opts - 注入选项（测试用）
+ */
+export async function writeUserMessage(child, text, blocks = [], { _fetchAndBase64Encode } = {}) {
+  if (!child || !child.stdin || child.stdin.destroyed) {
+    throw new Error("writeUserMessage: stdin not available");
+  }
+
+  const doFetchAndBase64 = _fetchAndBase64Encode ?? fetchAndBase64Encode;
+
+  const content = [];
+
+  // 1. text block（非空时）
+  if (text) {
+    content.push({ type: "text", text: String(text) });
+  }
+
+  // 2. relay_object blocks（type=image または type=attachment、source.kind=url）
+  //    → relayObjectToBlock → Anthropic Messages API 形式に変換
+  //    claude は全 modalities 対応なので modelCaps を最大に設定
+  //    type=video / type=text 等の非 relay_object block は除外する
+  const relayBlocks = (blocks ?? []).filter(
+    (b) =>
+      (b?.type === "image" || b?.type === "attachment") &&
+      b?.source?.kind === "url" &&
+      b?.source?.url,
+  );
+  for (const block of relayBlocks) {
+    const result = await relayObjectToBlock(block, {
+      runtimeHint: "claude",
+      modelCaps: ["text", "image", "pdf"],
+      fetchAndBase64Encode: doFetchAndBase64,
+    });
+
+    if (result.error) {
+      // エラーはフォールバック text block にする（既存の動作と一致）
+      const name = block?.name ?? block?.source?.media_type ?? "file";
+      content.push({
+        type: "text",
+        text: `[${block?.type === "image" ? "image" : `file: ${name}`}] (encoding failed: ${result.error.message})`,
+      });
+      continue;
+    }
+
+    // input_text（PDF text fallback 含む）のうち "PDF content could not be extracted" を
+    // "encoding failed" に変換して既存テストとの互換性を保つ
+    if (result.type === "input_text" && result.text.includes("PDF content could not be extracted")) {
+      const name = block?.name ?? "file.pdf";
+      content.push({
+        type: "text",
+        text: `[file: ${name}] (encoding failed: PDF content could not be extracted)`,
+      });
+      continue;
+    }
+
+    // relayObjectToBlock の結果を Anthropic Messages API 形式に変換
+    switch (result.type) {
+      case "input_image":
+        content.push({
+          type: "image",
+          source: result.source,
+        });
+        break;
+      case "input_file":
+        content.push({
+          type: "document",
+          source: result.source,
+        });
+        break;
+      case "input_text":
+        content.push({ type: "text", text: result.text });
+        break;
+      case "url_ref":
+        // picoclaw only — claude runtime never returns url_ref from relayObjectToBlock;
+        // if this branch is somehow hit, drop to a safe description with NO URL in LLM context
+        // (铁律 #1: signed URL must not appear in LLM input). (CR-003)
+        content.push({ type: "text", text: `[image] (preview unavailable for this runtime)` });
+        break;
+      default:
+        break;
+    }
+  }
+
+  // 纯文字回退：如果 content 为空（text 为空且没有 blocks），加空 text block
+  // 保持与旧路径兼容（claude 需要至少一个 content block）
+  if (content.length === 0) {
+    content.push({ type: "text", text: "" });
+  }
+
+  const payload = {
+    type: "user",
+    message: { role: "user", content },
+  };
+  const line = JSON.stringify(payload) + "\n";
+  return new Promise((resolve, reject) => {
+    child.stdin.write(line, (err) => (err ? reject(err) : resolve()));
+  });
+}