@xyagent/cli 0.0.1

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

@@ -0,0 +1,174 @@
+// mcpConfigAdapter.mjs — Claude Code 的 MCP server 配置注入器。
+//
+// Claude 读 ~/.claude.json (项目 scope, 在 projectCwd) 或 ~/.claude.json (全
+// 局 fallback)。具体 schema:
+//   {
+//     "mcpServers": {
+//       "<name>": {
+//         "type": "stdio",
+//         "command": "node",
+//         "args": [...]
+//       }
+//     },
+//     ...其它用户 keys
+//   }
+//
+// 操作要求(spec.md Claude Code MCP server registration):
+//   - idempotent (deep-equal check before write)
+//   - non-destructive (其它 mcpServers entry 不动)
+//   - versioned (新 args 含 --agentlink-version,version drift 时覆盖)
+
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+
+export const fileExtension = "json";
+
+const CONFIG_BASENAME = ".claude.json";
+const SERVER_NAME = "agentlink";
+
+/**
+ * 始终用 user-global `~/.claude.json`。
+ *
+ * 为什么不用 project-scoped:
+ *   - Claude Code 默认读 user-global,所有 Claude 项目都能看到 agentlink MCP server
+ *   - project-scoped 只覆盖该项目目录,用户切到别的项目就看不到 agentlink 工具
+ *   - 配对一次 = 让 agentlink 在该用户的所有 Claude 项目里都可用,这是正确语义
+ *   - projectCwd 参数保留向后兼容(忽略不报错),但实际不使用
+ */
+function resolveConfigPath(_projectCwd) {
+  return path.join(os.homedir(), CONFIG_BASENAME);
+}
+
+/**
+ * 读原始文件文本。ENOENT 抛 err.code = "ENOENT" 给 caller 决定怎么处理。
+ */
+export async function read({ projectCwd } = {}) {
+  const cfgPath = resolveConfigPath(projectCwd);
+  return await fs.readFile(cfgPath, "utf8");
+}
+
+/**
+ * idempotent 注册。args 由 fanout core 提供(含 --discovery + --agentlink-version)。
+ */
+export async function register({ projectCwd, args, log } = {}) {
+  const cfgPath = resolveConfigPath(projectCwd);
+  const desired = {
+    type: "stdio",
+    command: "node",
+    args: args.slice(),
+  };
+  const next = await mergeServerEntry(cfgPath, SERVER_NAME, desired);
+  if (!next.changed) {
+    return { changed: false, configPath: cfgPath, mode: "noop_idempotent" };
+  }
+  await fs.writeFile(cfgPath, JSON.stringify(next.config, null, 2) + "\n", { mode: 0o600 });
+  log?.info?.("mcp.fanout.claude.write", "wrote agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function deregister({ projectCwd, log } = {}) {
+  const cfgPath = resolveConfigPath(projectCwd);
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { changed: false, configPath: cfgPath, mode: "noop_no_config" };
+    }
+    throw err;
+  }
+  const cfg = safeParse(raw);
+  if (!cfg || !cfg.mcpServers || !(SERVER_NAME in cfg.mcpServers)) {
+    return { changed: false, configPath: cfgPath, mode: "noop_not_registered" };
+  }
+  delete cfg.mcpServers[SERVER_NAME];
+  await fs.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 });
+  log?.info?.("mcp.fanout.claude.delete", "removed agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function status({ projectCwd } = {}) {
+  const cfgPath = resolveConfigPath(projectCwd);
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { installed: true, registered: false, configPath: cfgPath, reason: "no_config_file" };
+    }
+    return { installed: false, registered: false, error: err?.message };
+  }
+  const cfg = safeParse(raw);
+  const entry = cfg?.mcpServers?.[SERVER_NAME];
+  if (!entry) {
+    return { installed: true, registered: false, configPath: cfgPath };
+  }
+  return {
+    installed: true,
+    registered: true,
+    configPath: cfgPath,
+    version: extractAgentlinkVersion(entry?.args),
+  };
+}
+
+/**
+ * 合并:读 cfg, 检查 mcpServers.agentlink 跟 desired 是否相等;不等就替换。
+ * 返回 { config, changed }。caller 决定写不写。
+ */
+async function mergeServerEntry(cfgPath, name, desired) {
+  let raw = "{}";
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const cfg = safeParse(raw) || {};
+  if (!cfg.mcpServers || typeof cfg.mcpServers !== "object") {
+    cfg.mcpServers = {};
+  }
+  const current = cfg.mcpServers[name];
+  if (deepEqual(current, desired)) {
+    return { config: cfg, changed: false };
+  }
+  cfg.mcpServers[name] = desired;
+  return { config: cfg, changed: true };
+}
+
+function safeParse(raw) {
+  try { return JSON.parse(raw); }
+  catch { return null; }
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const ak = Object.keys(a).sort();
+    const bk = Object.keys(b).sort();
+    if (ak.length !== bk.length) return false;
+    for (let i = 0; i < ak.length; i++) {
+      if (ak[i] !== bk[i]) return false;
+      if (!deepEqual(a[ak[i]], b[ak[i]])) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** 从 args 数组里挖 --agentlink-version 之后那个值,用于 fanout 漂移检测。 */
+function extractAgentlinkVersion(args) {
+  if (!Array.isArray(args)) return null;
+  const idx = args.indexOf("--agentlink-version");
+  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
+  return null;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * mcpConfigWriter.mjs — 任务 2.1 / 2.2
+ *
+ * 向 os.tmpdir() 写入临时 MCP config 文件，供 claude --mcp-config 使用。
+ *
+ * 文件名：agentlink-mcp-<runId>.json
+ * 内容：{ "mcpServers": { "agentlink-permission": { "type": "stdio", "command": "node", "args": [scriptPath] } } }
+ *
+ * 设计：写入 tmpdir（跨平台），不写项目目录，避免 claude 扫描项目结构。
+ * run 结束（finally 块）调用 deleteMcpConfig 清理。
+ */
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * 写入临时 MCP config 文件。
+ *
+ * @param {{ runId: string, serverScriptPath: string }} opts
+ * @returns {Promise<string>}  写入的文件绝对路径
+ */
+export async function writeMcpConfig({ runId, serverScriptPath }) {
+  const fileName = `agentlink-mcp-${runId}.json`;
+  const filePath = path.join(os.tmpdir(), fileName);
+
+  const config = {
+    mcpServers: {
+      "agentlink-permission": {
+        type: "stdio",
+        command: "node",
+        args: [serverScriptPath],
+      },
+    },
+  };
+
+  await fs.writeFile(filePath, JSON.stringify(config, null, 2), { encoding: "utf8" });
+  return filePath;
+}
+
+/**
+ * 删除临时 MCP config 文件。
+ * 文件不存在时静默忽略（ENOENT）。
+ *
+ * @param {string} filePath  writeMcpConfig 返回的路径
+ * @returns {Promise<void>}
+ */
+export async function deleteMcpConfig(filePath) {
+  if (!filePath) return;
+  try {
+    await fs.unlink(filePath);
+  } catch (err) {
+    if (err?.code !== "ENOENT") throw err;
+    // ENOENT: 文件已不存在，静默忽略
+  }
+}

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

@@ -0,0 +1,30 @@
+// 按 claude 模型 ID 查对应上下文窗口大小（tokens）。
+//
+// 数据来源：Anthropic 官方文档 + claude-code /model 输出。
+// 策略：
+//   - 精确前缀匹配优先（opus / sonnet / haiku 各家族）
+//   - 不认识的模型回退到 200k（Claude 家族当前统一默认）
+//   - 特殊：`-1m` / `-1m-beta` 后缀标识 1M 扩展上下文
+//
+// 注意这里不包含 Claude 2.x / 3.x 早期模型 —— claude-code v2.1+ 只用 Claude 4.x 起。
+
+const FAMILY_WINDOWS = [
+  // 1M 扩展上下文（Sonnet 4.5 某些入口支持）
+  { pattern: /-1m(?:-beta)?$/i, window: 1_000_000 },
+  // 标准 200k 上下文（所有 4.x 家族）
+  { pattern: /^claude-(opus|sonnet|haiku)-/i, window: 200_000 },
+  // 用户友好别名（claude-code /model 切换时的短名）
+  { pattern: /^(opus|sonnet|haiku|default|opusplan)$/i, window: 200_000 },
+];
+
+/**
+ * @param {string|null|undefined} model
+ * @returns {number} tokens；未知模型回退 200000（Claude 系列通用）
+ */
+export function pickContextWindow(model) {
+  if (typeof model !== "string" || !model) return 200_000;
+  for (const { pattern, window } of FAMILY_WINDOWS) {
+    if (pattern.test(model)) return window;
+  }
+  return 200_000;
+}

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

@@ -0,0 +1,257 @@
+// Claude 模型列表扫描器。
+//
+// 背景：claude-code CLI 不提供 "list models" 子命令；`/model` 是交互式 REPL
+// 的斜杠命令（在 --print + stream-json 模式下会被当成 unknown skill）。PTY
+// 抓 picker 代价大（~3s 冷启动 + node-pty 原生依赖 + ANSI 解析），而且 picker
+// 展示的就是家族别名（Default/Opus/Haiku 三项），数据量和扫二进制拿到的
+// 家族信息完全重叠。
+//
+// 所以策略：扫二进制提取所有 `claude-<family>-<version>` 模型 id，按家族
+// 分组 → 每个家族输出一个 alias 项（id = 家族名）。alias id 直接对应 CLI
+// 里 `--model sonnet` / `--model opus` 等稳定形式。hint 附上扫到的最新
+// 版本号，跟着二进制升级自动更新。
+//
+// 完全动态：家族名、版本号都从二进制扫出；未来 claude-code 加新家族（如
+// "ultra"），扫描器无需改代码就会发现并展示。
+//
+// 跨平台：PE32 (Windows) / ELF (Linux) / Mach-O (macOS) 二进制里 ASCII 字符
+// 串常量都是明文存放的，latin1 逐字节扫描正则匹配与格式无关。PATH 分隔符
+// 与可执行文件扩展名按 process.platform 分流。
+//
+// 实现要点：
+//   - 流式扫描（chunk + overlap），避免几百 MB 二进制一次性读爆内存
+//   - 结果进程内缓存，key = realpath(bin) + mtime，二进制升级自动失效
+
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+/**
+ * 扫描目标正则：claude-<family>-<version-segments>。
+ * family 用 `[a-z]+` 宽松匹配（不写死 opus/sonnet/haiku），未来新家族自动纳入。
+ * 版本段用 `[\d-]+` 宽松匹配，解析时再识别末段的 8 位日期。
+ */
+const MODEL_ID_RE = /\bclaude-([a-z]+)-([\d-]+)(?=\D|$)/g;
+
+const cache = new Map(); // key -> { at, result }
+
+/**
+ * 返回 { models: [ ... ], default: "<alias>" | null }。扫不到 models 返回空列表。
+ * default 取自 `~/.claude/settings.json` 的 model 字段（已归一化为家族 alias）。
+ */
+export async function listClaudeModels() {
+  const bin = await resolveClaudeBinary();
+  const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+  const binStat = bin ? await safeStat(bin) : null;
+  const settingsStat = await safeStat(settingsPath);
+  const cacheKey = `${bin || ""}:${binStat?.mtimeMs ?? 0}:${settingsStat?.mtimeMs ?? 0}`;
+  const hit = cache.get(cacheKey);
+  if (hit) return hit.result;
+
+  let versions;
+  if (!bin) {
+    versions = new Set();
+  } else {
+    try {
+      versions = await scanBinaryForModelIds(bin);
+    } catch {
+      versions = new Set();
+    }
+  }
+
+  const models = composeModels(versions);
+  const defaultAlias = await readClaudeDefault(settingsPath);
+  const result = { models, default: defaultAlias };
+  cache.set(cacheKey, { at: Date.now(), result });
+  return result;
+}
+
+// 从 ~/.claude/settings.json 读 model 字段并归一化为家族 alias。
+//   - "sonnet" / "opus" / "haiku" / "default" / "opusplan" → 原样返回
+//   - "claude-sonnet-4-6" → 提取家族 "sonnet"
+//   - 没有 / 解析失败 → null
+async function readClaudeDefault(settingsPath) {
+  try {
+    const raw = await fs.readFile(settingsPath, "utf8");
+    const obj = JSON.parse(raw);
+    const m = typeof obj?.model === "string" ? obj.model.trim() : "";
+    if (!m) return null;
+    // full id: claude-<family>-... → 取 family
+    const full = m.match(/^claude-([a-z]+)-/);
+    if (full) return full[1];
+    return m;
+  } catch {
+    return null;
+  }
+}
+
+// ── Pipeline ──────────────────────────────────────────────────────────────
+
+function composeModels(versionStrings) {
+  const byFamily = new Map(); // family -> [parsed]
+  for (const id of versionStrings) {
+    const v = parseId(id);
+    if (!v) continue;
+    if (!byFamily.has(v.family)) byFamily.set(v.family, []);
+    byFamily.get(v.family).push(v);
+  }
+
+  const families = [];
+  for (const [family, list] of byFamily) {
+    // 过滤：家族里至少要存在一个"当代"版本（3 <= major < 1000）才保留。
+    // 这会干掉两类噪音：
+    //   - claude-instant-1 (Claude 1 遗留，CLI 已不支持)
+    //   - claude-code-20250219 (产品 slug 被误匹配，major=20250219)
+    const hasCurrentVersion = list.some((v) => v.major >= 3 && v.major < 1000);
+    if (!hasCurrentVersion) continue;
+
+    list.sort(compareVersionDesc);
+    const latest = list[0];
+    families.push({ family, latest });
+  }
+
+  // 家族展示顺序：按 latest 版本号降序（越新的家族越靠前）
+  families.sort((a, b) => compareVersionDesc(a.latest, b.latest));
+
+  return families.map(({ family, latest }) => ({
+    // alias id 发给 CLI：claude 的 `--model sonnet` / `--model opus` 等家族形式
+    id: family,
+    // label 是"具体版本"（如 `Opus 4.6` / `Haiku 4.5 · 2025-10-01`），扫出的
+    // latest 带日期时一并展示。菜单外的"模型"按钮也会拿到这个 label。
+    label: buildVersionLabel(latest),
+    // hint 是家族定位描述。claude-code 二进制里没有这份元信息 —— 对已知家族
+    // 给一份稳定的本地化描述；未知家族（未来 Anthropic 新家族）返回空。
+    hint: familyDescription(family),
+  }));
+}
+
+function familyDescription(family) {
+  switch (family) {
+    case "opus":   return "最强 · 复杂推理 / 架构";
+    case "sonnet": return "均衡 · 日常编码";
+    case "haiku":  return "最快 · 轻量任务";
+    default:       return "";
+  }
+}
+
+function parseId(id) {
+  const m = id.match(/^claude-([a-z]+)-([\d-]+)$/);
+  if (!m) return null;
+  const parts = m[2].split("-").filter(Boolean);
+  if (parts.length === 0) return null;
+
+  let date = null;
+  if (parts.length > 1 && /^\d{8}$/.test(parts[parts.length - 1])) {
+    date = parts.pop();
+  }
+  const major = Number(parts[0]);
+  if (!Number.isFinite(major)) return null;
+  const minor = parts.length > 1 ? Number(parts[1]) : null;
+  if (minor != null && !Number.isFinite(minor)) return null;
+
+  return { id, family: m[1], major, minor, date };
+}
+
+function compareVersionDesc(a, b) {
+  if (a.major !== b.major) return b.major - a.major;
+  const am = a.minor ?? -1;
+  const bm = b.minor ?? -1;
+  if (am !== bm) return bm - am;
+  const ad = a.date || "00000000";
+  const bd = b.date || "00000000";
+  return bd.localeCompare(ad);
+}
+
+function buildVersionLabel(v) {
+  const ver = v.minor != null ? `${v.major}.${v.minor}` : `${v.major}`;
+  const famName = capitalize(v.family);
+  if (v.date) {
+    return `${famName} ${ver} · ${formatDate(v.date)}`;
+  }
+  return `${famName} ${ver}`;
+}
+
+function capitalize(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function formatDate(yyyymmdd) {
+  return `${yyyymmdd.slice(0, 4)}-${yyyymmdd.slice(4, 6)}-${yyyymmdd.slice(6, 8)}`;
+}
+
+// ── Binary scanning ───────────────────────────────────────────────────────
+
+async function scanBinaryForModelIds(binPath) {
+  const CHUNK = 1 << 20;   // 1MB
+  const OVERLAP = 64;      // 模型 id 最长 ~30 字节，64 字节 overlap 足够
+  const fd = await fs.open(binPath, "r");
+  try {
+    const buf = Buffer.alloc(CHUNK);
+    const found = new Set();
+    let position = 0;
+    let carry = "";
+    while (true) {
+      const { bytesRead } = await fd.read(buf, 0, CHUNK, position);
+      if (bytesRead === 0) break;
+      const hay = carry + buf.slice(0, bytesRead).toString("latin1");
+      MODEL_ID_RE.lastIndex = 0;
+      for (const m of hay.matchAll(MODEL_ID_RE)) {
+        // 完整 id：claude-<family>-<version>
+        found.add(m[0]);
+      }
+      carry = hay.slice(-OVERLAP);
+      position += bytesRead;
+    }
+    return found;
+  } finally {
+    await fd.close();
+  }
+}
+
+// ── Binary resolution ─────────────────────────────────────────────────────
+//
+// 跨平台：
+//   - macOS / Linux：PATH 里找 `claude`（symlink 跟随 realpath）
+//   - Windows：PATH 里找 `claude.exe`（也可能是 `.cmd`/`.bat` wrapper —— 我们
+//     需要真正的二进制，所以也尝试 `.exe`/`.cmd`/`.bat` 的 realpath 并过滤文件
+
+async function resolveClaudeBinary() {
+  const pathDirs = splitPath(process.env.PATH || "");
+  const candidates = binaryCandidateNames();
+  for (const dir of pathDirs) {
+    for (const name of candidates) {
+      const candidate = path.join(dir, name);
+      const real = await safeRealpath(candidate);
+      if (!real) continue;
+      const st = await safeStat(real);
+      if (!st || !st.isFile()) continue;
+      // 过滤 wrapper 脚本（太小，比如 <100KB 的 shell/batch wrapper）
+      // 真实 claude 二进制 ~190MB，阈值留 1MB 即可区分
+      if (st.size < 1024 * 1024) continue;
+      return real;
+    }
+  }
+  return null;
+}
+
+function splitPath(raw) {
+  const sep = process.platform === "win32" ? ";" : ":";
+  return raw.split(sep).filter(Boolean);
+}
+
+function binaryCandidateNames() {
+  if (process.platform === "win32") {
+    // Windows：优先 .exe；.cmd/.bat 是 wrapper，走它们的 realpath 也可能指到真正 .exe
+    return ["claude.exe", "claude.cmd", "claude.bat", "claude"];
+  }
+  return ["claude"];
+}
+
+async function safeStat(p) {
+  try { return await fs.stat(p); } catch { return null; }
+}
+
+async function safeRealpath(p) {
+  try { return await fs.realpath(p); } catch { return null; }
+}

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

@@ -0,0 +1,86 @@
+/**
+ * permissionInterruptBlock.mjs — 任务 3.1
+ *
+ * 构造符合协议的 interrupt block（approval subtype）。
+ * CLI 端直接构造，bypass relay mapApprovalRequest，与 Codex elicitation 同构。
+ *
+ * Wire Format 见 design.md § Wire Format。
+ * v1：不含 scope_options。
+ */
+
+const DANGER_RE = /bash|shell|exec|delete|remove|rm|write|create|overwrite|truncate|drop/i;
+const SUMMARY_MAX = 120;
+
+/**
+ * 判断工具是否"危险"（需 severity=warning，approve is_destructive=true）。
+ * 与 relay mapper 保持一致规则。
+ * @param {string} toolName
+ */
+function isDangerous(toolName) {
+  return DANGER_RE.test(toolName);
+}
+
+/**
+ * 生成命令摘要（最多 120 字符，超出加 …）。
+ * @param {string} toolName
+ * @param {object} toolInput
+ */
+function commandSummary(toolName, toolInput) {
+  let raw;
+  if (/^bash$/i.test(toolName)) {
+    raw = typeof toolInput?.command === "string" ? toolInput.command : JSON.stringify(toolInput);
+  } else {
+    raw = typeof toolInput?.description === "string"
+      ? toolInput.description
+      : JSON.stringify(toolInput);
+  }
+  if (raw.length > SUMMARY_MAX) {
+    return raw.slice(0, SUMMARY_MAX) + "…";
+  }
+  return raw;
+}
+
+/**
+ * 构造 interrupt approval block。
+ *
+ * @param {{
+ *   toolName: string,
+ *   toolInput: object,
+ *   blockId: string,
+ *   runId: string,
+ *   expiresAt?: string,   // ISO8601（测试注入用）；默认 now + 10min
+ * }} opts
+ * @returns {object}  interrupt block（符合协议）
+ */
+export function buildPermissionInterruptBlock({ toolName, toolInput, blockId, runId, expiresAt }) {
+  const dangerous = isDangerous(toolName);
+  const summary = commandSummary(toolName, toolInput || {});
+  const resolvedExpiresAt = expiresAt || new Date(Date.now() + 10 * 60_000).toISOString();
+
+  return {
+    type: "interrupt",
+    subtype: "approval",
+    status: "awaiting",
+    id: blockId,
+    title: toolName,
+    prompt: `${toolName}: ${summary}`,
+    severity: dangerous ? "warning" : "info",
+    on_timeout: "reject",
+    options: [
+      {
+        id: "approve",
+        label: "同意",
+        is_default: true,
+        is_destructive: dangerous,
+      },
+      {
+        id: "reject",
+        label: "拒绝",
+        is_default: false,
+        is_destructive: false,
+      },
+    ],
+    expires_at: resolvedExpiresAt,
+    // v1：不含 scope_options
+  };
+}