@xyagent/cli 0.0.1

package/src-ext/runtime/picoclaw/pairFlow.mjs

@@ -0,0 +1,224 @@
+// 巴布配对流程。
+//
+// 步骤(daemon 主循环未持有 token 时执行):
+//
+//   1. POST <relay>/v1/pair-codes/picoclaw/create
+//      Body: { label, ttl_seconds, device_id }
+//      Resp: { code, qr_payload, qr_png_base64, fetch_token, expires_at, poll_interval_seconds }
+//
+//   2. 把 qr_png_base64 解码写到 QR_PNG_OUTPUT_PATH(通常 /tmp/bubu/pair-qr.png)。
+//      巴布开发板的屏幕显示模块独立读取这个文件,在屏幕上展示 QR。
+//
+//   3. 每 poll_interval_seconds 调一次:
+//      GET <relay>/v1/pair-codes/picoclaw/<code>/status
+//      Header: X-Pair-Fetch-Token: <fetch_token>
+//      Resp:
+//        { state: "pending", expires_at }
+//        { state: "consumed", gw_id, bridge_token, client_user_id, runtime, label }
+//        { state: "expired" }
+//
+//   4. consumed 命中 → 返回 {gw_id, bridge_token, client_user_id, label, relay_url}
+//      expired   → 抛错,主循环重新走步骤 1
+//      poll 超时 → 抛错,主循环重新走步骤 1
+//
+// 全程不需要用户在 cli 上输入任何东西;所有信息走二维码 ↔ App。
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import {
+  PAIR_STATUS_POLL_INTERVAL_SEC,
+  PAIR_STATUS_POLL_MAX_SEC,
+  QR_PNG_OUTPUT_PATH,
+  RUNTIME_NAME,
+} from "./constants.mjs";
+
+const PAIR_LABEL_DEFAULT = "我的巴布";
+
+/**
+ * 调 server 创建一个 picoclaw pair-code。
+ * @returns {Promise<{code, qr_payload, qr_png_base64, fetch_token, expires_at, poll_interval_seconds}>}
+ */
+export async function createPairCode({ relayUrl, label, deviceId, ttlSeconds, fetchImpl, log }) {
+  const f = fetchImpl || globalThis.fetch;
+  const url = `${trimRight(relayUrl)}/v1/pair-codes/picoclaw/create`;
+  const body = {
+    label: label || PAIR_LABEL_DEFAULT,
+    device_id: deviceId || "",
+    ttl_seconds: ttlSeconds > 0 ? ttlSeconds : undefined,
+  };
+  const res = await f(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await safeText(res);
+    throw new Error(`picoclaw pair-code create failed: HTTP ${res.status} ${text}`);
+  }
+  const j = await res.json();
+  if (!j || j.status !== "ok" || !j.code || !j.fetch_token || !j.qr_png_base64) {
+    throw new Error(`picoclaw pair-code create: malformed response ${JSON.stringify(j).slice(0, 200)}`);
+  }
+  if (log) {
+    log.info("picoclaw.pair.created", "pair-code created", {
+      code: j.code, expires_at: j.expires_at,
+    });
+  }
+  return j;
+}
+
+/**
+ * 把 base64 PNG 写到约定路径,屏幕模块读取。
+ */
+export function writeQRImage(b64, outputPath) {
+  const target = outputPath || QR_PNG_OUTPUT_PATH;
+  const dir = path.dirname(target);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {}
+  const buf = Buffer.from(b64, "base64");
+  fs.writeFileSync(target, buf);
+  return target;
+}
+
+/**
+ * 删除 QR 图片(配对成功后清理)。
+ */
+export function clearQRImage(outputPath) {
+  const target = outputPath || QR_PNG_OUTPUT_PATH;
+  try {
+    fs.unlinkSync(target);
+  } catch {}
+}
+
+/**
+ * dev 测试钩子:把 code + fetch_token + relay 等关键信息以 plain JSON 写到本地,
+ * 让端到端测试脚本能扮演 App 角色拿到 code 调 consume。
+ *
+ * 仅当环境变量 `BUBU_DEV_DUMP_PAIR_INFO=1` 时才写。
+ * **生产环境严禁开启** —— fetch_token 落地会被任何能读这台机器文件的进程拿走。
+ *
+ * 输出路径默认 /tmp/bubu/pair-info.json,可由 `BUBU_DEV_PAIR_INFO_PATH` 覆盖。
+ */
+export function writeDevPairInfo(info) {
+  if (process.env.BUBU_DEV_DUMP_PAIR_INFO !== "1") return null;
+  const target =
+    process.env.BUBU_DEV_PAIR_INFO_PATH?.trim() || "/tmp/bubu/pair-info.json";
+  const dir = path.dirname(target);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {}
+  const obj = {
+    code: info.code,
+    fetch_token: info.fetch_token,
+    relay: info.relay,
+    label: info.label || "",
+    expires_at: info.expires_at || "",
+    // qr_payload 是完整 deeplink(agentlink://pair/picoclaw?...),直接粘到
+    // App 输入框就能完成绑定,省去自己拼 URL 的麻烦。
+    qr_payload: info.qr_payload || "",
+    written_at: new Date().toISOString(),
+    warning: "BUBU_DEV_DUMP_PAIR_INFO=1; do NOT enable in production.",
+  };
+  try {
+    fs.writeFileSync(target, JSON.stringify(obj, null, 2) + "\n", "utf8");
+    return target;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 删除 dev pair-info(配对成功后清理 fetch_token 落地文件)。
+ */
+export function clearDevPairInfo() {
+  if (process.env.BUBU_DEV_DUMP_PAIR_INFO !== "1") return;
+  const target =
+    process.env.BUBU_DEV_PAIR_INFO_PATH?.trim() || "/tmp/bubu/pair-info.json";
+  try {
+    fs.unlinkSync(target);
+  } catch {}
+}
+
+/**
+ * 轮询 status 端点直到 consumed 或 expired。
+ * @returns {Promise<{gw_id, bridge_token, client_user_id, runtime, label}>} consumed payload
+ */
+export async function pollPairStatus({ relayUrl, code, fetchToken, intervalSec, maxSec, fetchImpl, log, signal }) {
+  const f = fetchImpl || globalThis.fetch;
+  const interval = (intervalSec > 0 ? intervalSec : PAIR_STATUS_POLL_INTERVAL_SEC) * 1000;
+  const maxMs = (maxSec > 0 ? maxSec : PAIR_STATUS_POLL_MAX_SEC) * 1000;
+  const startedAt = Date.now();
+  const url = `${trimRight(relayUrl)}/v1/pair-codes/picoclaw/${encodeURIComponent(code)}/status`;
+  for (;;) {
+    if (signal?.aborted) {
+      throw new Error("picoclaw pair poll aborted");
+    }
+    let res;
+    try {
+      res = await f(url, {
+        method: "GET",
+        headers: { "X-Pair-Fetch-Token": fetchToken },
+      });
+    } catch (err) {
+      // 网络抖动 — 等下次重试,日志一下
+      if (log) log.warn("picoclaw.pair.poll.err", "status poll error", { err: String(err?.message || err) });
+      await sleep(interval);
+      continue;
+    }
+    if (res.status === 401) {
+      throw new Error("picoclaw pair status: fetch_token rejected (401)");
+    }
+    if (!res.ok) {
+      const text = await safeText(res);
+      if (log) log.warn("picoclaw.pair.poll.bad", "non-ok status", { status: res.status, text });
+      await sleep(interval);
+      continue;
+    }
+    const j = await res.json().catch(() => null);
+    if (!j || typeof j.state !== "string") {
+      await sleep(interval);
+      continue;
+    }
+    if (j.state === "consumed") {
+      if (!j.bridge_token || !j.gw_id) {
+        throw new Error("picoclaw pair status: consumed but missing bridge_token/gw_id");
+      }
+      return {
+        gw_id: j.gw_id,
+        bridge_token: j.bridge_token,
+        client_user_id: j.client_user_id || "",
+        runtime: j.runtime || RUNTIME_NAME,
+        label: j.label || "",
+      };
+    }
+    if (j.state === "expired") {
+      throw new Error("picoclaw pair-code expired before consume");
+    }
+    // pending
+    if (Date.now() - startedAt >= maxMs) {
+      throw new Error("picoclaw pair-code poll timeout");
+    }
+    await sleep(interval);
+  }
+}
+
+// ── helpers ──────────────────────────────────────────────────────
+
+function trimRight(s) {
+  return String(s || "").replace(/\/+$/, "");
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function safeText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}

package/src-ext/runtime/picoclaw/state.mjs

@@ -0,0 +1,78 @@
+// 巴布(PicoClaw)本地配对状态持久化。
+//
+// 文件: ~/.agentlink/picoclaw-state.json
+//
+// 内容:
+//   {
+//     gw_id, bridge_token, relay_url, client_user_id, label, runtime: "picoclaw",
+//     saved_at: <ISO timestamp>
+//   }
+//
+// 缺/损坏时返回 null,daemon 主循环会触发新一轮 pair-code create + QR 显示。
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const STATE_DIR = path.join(os.homedir(), ".agentlink");
+const STATE_FILE = path.join(STATE_DIR, "picoclaw-state.json");
+
+function ensureDir() {
+  try {
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readState() {
+  try {
+    const raw = fs.readFileSync(STATE_FILE, "utf8");
+    const obj = JSON.parse(raw);
+    if (!obj || typeof obj !== "object") return null;
+    if (obj.runtime !== "picoclaw") return null;
+    const gwId = String(obj.gw_id || "").trim();
+    const relayUrl = String(obj.relay_url || "").trim();
+    const bridgeToken = String(obj.bridge_token || "").trim();
+    if (!gwId || !relayUrl || !bridgeToken) return null;
+    return {
+      gw_id: gwId,
+      bridge_token: bridgeToken,
+      relay_url: relayUrl,
+      client_user_id: String(obj.client_user_id || "").trim(),
+      label: String(obj.label || "").trim(),
+      saved_at: obj.saved_at || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeState(state) {
+  if (!ensureDir()) return false;
+  const obj = {
+    runtime: "picoclaw",
+    gw_id: state.gw_id,
+    bridge_token: state.bridge_token,
+    relay_url: state.relay_url,
+    client_user_id: state.client_user_id || "",
+    label: state.label || "",
+    saved_at: new Date().toISOString(),
+  };
+  try {
+    fs.writeFileSync(STATE_FILE, JSON.stringify(obj, null, 2) + "\n", "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function clearState() {
+  try {
+    fs.unlinkSync(STATE_FILE);
+    return true;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,67 @@
+/**
+ * todoTranslator.mjs — picoclaw runtime update_plan → todo_list block translator
+ *
+ * 按 translator-spec.md 和 npm-cli-todo-translator-picoclaw spec 实现：
+ *   - 识别 PicoMessage type==="message.update" && payload.kind==="tool_calls"
+ *   - 检查 tool_calls 中是否含 update_plan
+ *   - 若含：转写为 content_block.started + content_block.completed，拦截不透传
+ *   - 否则：原样透传（返回 [msg]）
+ */
+
+import {
+  buildBlockStarted,
+  buildBlockCompleted,
+  newBlockId,
+} from "../../../src-shared/envelope_builder.mjs";
+import { buildTodoItems } from "../_shared/todoTranslatorUtils.mjs";
+
+/**
+ * 创建 picoclaw update_plan translator 实例。
+ *
+ * @param {string} runId  当前 run 的 run_id，用于构造 envelope
+ * @returns {{ intercept(msg: object): object[] }}
+ */
+export function createPicoTodoTranslator(runId) {
+  return {
+    /**
+     * @param {object} msg  PicoMessage（{ type, id, session_id, payload }）
+     * @returns {object[]}  2 个 envelope（update_plan）或 [msg]（透传）
+     */
+    intercept(msg) {
+      if (!msg || typeof msg !== "object") return [msg];
+
+      // 只处理 message.update(kind=tool_calls)
+      if (msg.type !== "message.update") return [msg];
+      const payload = msg.payload;
+      if (!payload || payload.kind !== "tool_calls") return [msg];
+
+      // 从 tool_calls 数组中找 update_plan
+      const toolCalls = Array.isArray(payload.tool_calls)
+        ? payload.tool_calls
+        : (Array.isArray(payload.content) ? payload.content : []);
+      const updatePlanCall = toolCalls.find(
+        (tc) => tc && typeof tc === "object" && tc.name === "update_plan",
+      );
+      if (!updatePlanCall) return [msg];
+
+      // 解析 arguments
+      let args = {};
+      if (updatePlanCall.arguments) {
+        try {
+          args = JSON.parse(String(updatePlanCall.arguments));
+        } catch { /* 保持空对象 */ }
+      }
+
+      // plan 数组映射为 TodoItem[]（explanation 忽略）
+      const rawPlan = Array.isArray(args.plan) ? args.plan : [];
+      const items = buildTodoItems(rawPlan);
+      const blockId = newBlockId();
+      const block = { id: blockId, type: "todo_list", items };
+
+      return [
+        buildBlockStarted(runId, block),
+        buildBlockCompleted(runId, { ...block }),
+      ];
+    },
+  };
+}

package/src-ext/runtime/picoclaw/translator.mjs

@@ -0,0 +1,272 @@
+// Pico Protocol ↔ OpenAI Responses API 风格 native event 翻译器。
+//
+// CLI 把巴布(PicoClaw)WebSocket 上的 PicoMessage 翻译成服务端
+// `internal/adapter/picoclaw` 期望的 native event 流(与 openclaw 共享 mapper)。
+//
+// PicoMessage 格式:
+//   { type, id, session_id, timestamp, payload }
+//
+// CLI 出参格式(与 openclaw bridge 现有产物对齐):
+//   { event: "start" }
+//   { event: "chunk", data: JSON.stringify({ type: "response.output_text.delta", delta: "..." }) }
+//   { event: "chunk", data: JSON.stringify({ type: "response.reasoning_summary_text.delta", delta: "..." }) }
+//   { event: "chunk", data: JSON.stringify({ type: "response.function_call_arguments.delta", call_id, name, arguments }) }
+//   { event: "chunk", data: JSON.stringify({ type: "response.output_text.done", text: "<full>" }) }
+//   { event: "end" }
+//   { event: "error", error: "msg" }
+//
+// **Pico → OpenClaw 映射表**:
+//
+// | Pico (server→client) | OpenClaw native (CLI emits) |
+// |----------------------|------------------------------|
+// | message.create       | { event: "start" }(每个 turn 起头一次)|
+// | message.update (default kind, payload.content) | response.output_text.delta(算 delta) |
+// | message.update (kind=thought)                  | response.reasoning_summary_text.delta |
+// | message.update (kind=tool_calls)               | response.function_call_arguments.delta(简化:把 tool_calls JSON 序列化进 arguments) |
+// | typing.stop / 最后一条 update                  | response.output_text.done + { event: "end" } |
+// | media.create                                   | 一期降级:转成 response.output_text.delta 加占位文本(支持 base64/url 二期) |
+// | error                                          | { event: "error", error: msg } + { event: "end" } |
+// | pong                                           | drop                          |
+//
+// **Delta 计算**: PicoClaw 的 message.update 通常发"累积全文",CLI 通过比对
+// 内部 lastText 字段算出 delta 增量再发。如果服务端遇到回退场景(content
+// 比上次短),按"重置 + 全量重发"处理(不应发生,但写防御代码)。
+
+const KIND_THOUGHT = "thought";
+const KIND_TOOL_CALLS = "tool_calls";
+
+// 单条 turn 的累积状态。每个 turn 一个,`reset()` 后复用。
+export function createTurnState() {
+  return {
+    started: false,
+    finalized: false,
+    // 主回复正文的累积值
+    textAccum: "",
+    // 思考链的累积值
+    thoughtAccum: "",
+    // tool_calls 列表的累积 JSON(上次发送的)
+    toolCallsAccum: "",
+    // 上次响应的 PicoClaw message_id
+    lastMessageID: "",
+  };
+}
+
+/**
+ * 翻译一条 PicoMessage 为 0..N 个 native event。
+ *
+ * @param {object} msg PicoMessage `{ type, id, session_id, timestamp, payload }`
+ * @param {object} state createTurnState() 返回的状态
+ * @returns {Array<{event:string, data?:string, error?:string}>} native events
+ */
+export function translatePicoMessage(msg, state) {
+  if (!msg || typeof msg !== "object") return [];
+  // Bug 4 防御:turn 已 finalized 后再来 update/media 等都直接丢弃,避免发出
+  // 服务端 run 已 completed 之后的 delta 导致状态机错位。pong/error 仍处理
+  // (error 即使在 finalize 后也要透传)。
+  if (state.finalized && msg.type !== "error" && msg.type !== "pong") {
+    return [];
+  }
+  const out = [];
+  switch (msg.type) {
+    case "message.create": {
+      // 一个 turn 的起始 — 服务端 openclaw mapper 期望 "start"。
+      if (!state.started) {
+        state.started = true;
+        out.push({ event: "start" });
+      }
+      // payload.content 可能携带初始文本,按 update 处理一次。
+      const content = readContent(msg);
+      if (content) {
+        emitDeltaForKind(out, state, msg, content);
+      }
+      return out;
+    }
+    case "message.update": {
+      if (!state.started) {
+        state.started = true;
+        out.push({ event: "start" });
+      }
+      const content = readContent(msg);
+      if (content !== null && content !== undefined) {
+        emitDeltaForKind(out, state, msg, content);
+      }
+      return out;
+    }
+    case "media.create": {
+      // 一期:把 media 描述 inline 成正文占位文字,告诉用户"这里有一张图"。
+      // 二期会接 /pico/media/<id> 下载 + 转 base64 + response.output_text.delta with image。
+      if (!state.started) {
+        state.started = true;
+        out.push({ event: "start" });
+      }
+      const placeholder = describeMedia(msg);
+      if (placeholder) {
+        appendDelta(out, state, "text", placeholder);
+      }
+      return out;
+    }
+    case "typing.stop": {
+      // 流结束信号 — 收到后 finalize。
+      finalizeTurn(out, state);
+      return out;
+    }
+    case "error": {
+      const errMsg = (msg.payload && (msg.payload.message || msg.payload.error)) || "picoclaw error";
+      out.push({ event: "error", error: String(errMsg) });
+      // error 后强制 end,避免服务端 adapter 觉得 turn 悬空
+      if (!state.finalized) {
+        state.finalized = true;
+        out.push({ event: "end" });
+      }
+      return out;
+    }
+    case "typing.start":
+    case "pong":
+      return [];
+    default:
+      // 未识别消息类型 — 一期忽略,日志侧记录(translator 不持有 logger;调用方记)。
+      return [];
+  }
+}
+
+/**
+ * 在调用方决定 turn 已结束时(比如 WS 端关闭、超时、显式 typing.stop 都没拿到),
+ * 强制 finalize。幂等。
+ */
+export function forceFinalize(state) {
+  const out = [];
+  finalizeTurn(out, state);
+  return out;
+}
+
+// ── internal ────────────────────────────────────────────────────
+
+function emitDeltaForKind(out, state, msg, content) {
+  const kind = readKind(msg);
+  if (kind === KIND_THOUGHT) {
+    appendDelta(out, state, "thought", content);
+    return;
+  }
+  if (kind === KIND_TOOL_CALLS) {
+    // tool_calls 的 content 期望是 JSON(数组或对象);序列化成 arguments string。
+    const argsJSON = typeof content === "string" ? content : safeJSON(content);
+    if (argsJSON !== state.toolCallsAccum) {
+      state.toolCallsAccum = argsJSON;
+      out.push({
+        event: "chunk",
+        data: JSON.stringify({
+          type: "response.function_call_arguments.delta",
+          call_id: String(msg.id || msg.session_id || ""),
+          name: pickToolName(msg) || "tool_call",
+          arguments: argsJSON,
+        }),
+      });
+    }
+    return;
+  }
+  // 默认:正文 delta
+  appendDelta(out, state, "text", content);
+}
+
+function appendDelta(out, state, kind, content) {
+  const text = typeof content === "string" ? content : String(content);
+  let delta;
+  if (kind === "text") {
+    delta = computeDelta(state.textAccum, text);
+    if (delta == null) return;
+    state.textAccum = text;
+    out.push({
+      event: "chunk",
+      data: JSON.stringify({
+        type: "response.output_text.delta",
+        delta,
+      }),
+    });
+  } else if (kind === "thought") {
+    delta = computeDelta(state.thoughtAccum, text);
+    if (delta == null) return;
+    state.thoughtAccum = text;
+    out.push({
+      event: "chunk",
+      data: JSON.stringify({
+        type: "response.reasoning_summary_text.delta",
+        delta,
+      }),
+    });
+  }
+}
+
+// computeDelta: 优先按"累积全文"模型计算增量;若新文本比旧短(异常 reset),
+// 把 prev 当空,delta = full new。返回 null 表示没增量(同文本)。
+function computeDelta(prev, next) {
+  if (next === prev) return null;
+  if (next.startsWith(prev)) return next.slice(prev.length);
+  // 回退/重置 — 直接整段重发
+  return next;
+}
+
+function finalizeTurn(out, state) {
+  if (state.finalized) return;
+  state.finalized = true;
+  if (state.started && state.textAccum) {
+    out.push({
+      event: "chunk",
+      data: JSON.stringify({
+        type: "response.output_text.done",
+        text: state.textAccum,
+      }),
+    });
+  }
+  if (state.started) {
+    out.push({ event: "end" });
+  }
+}
+
+function readContent(msg) {
+  if (!msg || typeof msg.payload !== "object" || msg.payload === null) return null;
+  const c = msg.payload.content;
+  if (c === undefined || c === null) return null;
+  if (typeof c === "string") return c;
+  return c; // 留给 emitDeltaForKind 决定如何处理(tool_calls 用 JSON)
+}
+
+function readKind(msg) {
+  if (!msg || typeof msg.payload !== "object" || msg.payload === null) return "";
+  const k = msg.payload.kind;
+  if (typeof k === "string") return k.trim().toLowerCase();
+  // legacy: payload.thought=true
+  if (msg.payload.thought === true) return KIND_THOUGHT;
+  return "";
+}
+
+function pickToolName(msg) {
+  if (!msg || typeof msg.payload !== "object" || msg.payload === null) return "";
+  if (Array.isArray(msg.payload.tool_calls) && msg.payload.tool_calls[0]) {
+    const t = msg.payload.tool_calls[0];
+    if (t && typeof t === "object") {
+      if (typeof t.name === "string") return t.name;
+      if (t.function && typeof t.function.name === "string") return t.function.name;
+    }
+  }
+  return "";
+}
+
+function describeMedia(msg) {
+  if (!msg || typeof msg.payload !== "object" || msg.payload === null) return "";
+  const p = msg.payload;
+  if (typeof p.url === "string" && p.url.length > 0) {
+    return `\n[media: ${p.url}]\n`;
+  }
+  if (typeof p.id === "string" && p.id.length > 0) {
+    return `\n[media:${p.id}]\n`;
+  }
+  return "\n[media]\n";
+}
+
+function safeJSON(v) {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return "";
+  }
+}