@xyagent/cli 0.0.1

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

@@ -0,0 +1,39 @@
+// 巴布(PicoClaw)运行时常量。
+//
+// 部署假设:matelink-cli 与 picoclaw daemon 烧录在同一开发板,
+// cli 默认连本地回环 picoclaw WebSocket。token 烧录时固化,cli 端写死同值。
+//
+// 如需改 token,**两处**(开发板 picoclaw config + 此文件)必须同步,否则连接失败。
+
+import process from "node:process";
+
+// PicoClaw daemon 的 WebSocket 端点(Pico Protocol)。
+// 默认 127.0.0.1:18790/pico/ws,可通过 env 覆盖(开发/调试用)。
+export const PICOCLAW_WS_URL =
+  process.env.PICOCLAW_WS_URL?.trim() || "ws://127.0.0.1:18790/pico/ws";
+
+// PicoClaw Bearer token —— 与开发板 picoclaw config 里 [pico].token 一致。
+// 生产烧录时双方都写死成下面这个固定值;切换值时必须双侧同步。
+export const PICOCLAW_TOKEN =
+  process.env.PICOCLAW_TOKEN?.trim() || "bubu-local-token";
+
+// 巴布配对二维码 PNG 输出路径 —— 屏幕显示模块从这个路径加载图片。
+// 默认写到 /tmp/bubu/pair-qr.png,可通过 env 覆盖。
+export const QR_PNG_OUTPUT_PATH =
+  process.env.BUBU_QR_PNG_PATH?.trim() || "/tmp/bubu/pair-qr.png";
+
+// 配对状态轮询间隔(秒)。服务端建议值在 create 响应里返回,这是兜底。
+export const PAIR_STATUS_POLL_INTERVAL_SEC = 2;
+
+// 配对状态最长等待时间(秒)。超过后 cli 重新生成 QR(配对码已过期)。
+export const PAIR_STATUS_POLL_MAX_SEC = 300;
+
+// 长轮询拉取请求的等待时长(秒)。
+export const LONG_POLL_WAIT_SEC = 30;
+
+// PicoClaw WS 重连退避(毫秒)— 指数退避,上限 30s。
+export const WS_RECONNECT_INITIAL_MS = 1000;
+export const WS_RECONNECT_MAX_MS = 30000;
+
+// runtime 名 — 必须与服务端 RuntimeKindPicoclaw 字符串一致。
+export const RUNTIME_NAME = "picoclaw";

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

@@ -0,0 +1,289 @@
+/**
+ * handleRequest.mjs — D-C2
+ *
+ * Extracted from picoclaw/index.mjs so it can be unit-tested independently.
+ *
+ * createPicoHandleRequest({ wsHolder, log, dispatchHandlerOptions })
+ *   → async (request, ctx) => void
+ *
+ * Routing:
+ *   1. If request.__kind == "agent.run.dispatch" → unifiedDispatchHandler (returns true) → done
+ *   2. Otherwise → original picoclaw ws path (extractUserText + wsHolder.send)
+ */
+
+import { createUnifiedDispatchHandler } from "../../core/unifiedDispatchHandler.mjs";
+import { buildMessageSend } from "./wsClient.mjs";
+import { createTurnState, translatePicoMessage, forceFinalize } from "./translator.mjs";
+import { relayObjectToBlock } from "../_shared/relayObjectToBlock.mjs";
+import { openclawChatAbort } from "../../core/openclawGatewayClient.mjs";
+
+// ── multimodal helpers (exported for unit tests) ──────────────────────────────
+
+/**
+ * 从 blocks 中筛出 image blocks 和 PDF attachment blocks。
+ *
+ * Phase 5 (multimodal-attachment-llm-dispatch): この関数は後方互換のために残す。
+ * WS dispatch path では relayObjectToBlock を使う（下記 createPicoHandleRequest 内参照）。
+ *
+ * @param {any[]} blocks
+ * @returns {{ imageBlocks: any[], pdfBlocks: any[] }}
+ */
+export function extractPicoBlocks(blocks) {
+  if (!Array.isArray(blocks)) return { imageBlocks: [], pdfBlocks: [] };
+  const imageBlocks = blocks.filter(
+    (b) => b?.type === "image" && b?.source?.kind === "url" && b?.source?.url
+  );
+  const pdfBlocks = blocks.filter(
+    (b) =>
+      b?.type === "attachment" &&
+      b?.mime === "application/pdf" &&
+      b?.source?.kind === "url" &&
+      b?.source?.url
+  );
+  return { imageBlocks, pdfBlocks };
+}
+
+/**
+ * 构造 media.create 帧（用于发送图片到 picoclaw daemon）。
+ *
+ * @param {string} sessionId
+ * @param {{ source: { url: string, media_type?: string } }} imageBlock
+ */
+export function buildMediaCreate(sessionId, imageBlock) {
+  return {
+    type: "media.create",
+    id: randomPicoID(),
+    session_id: sessionId,
+    timestamp: Date.now(),
+    payload: {
+      url: imageBlock.source.url,
+      media_type: imageBlock.source?.media_type || "image/jpeg",
+      kind: "image",
+    },
+  };
+}
+
+/**
+ * 构造 message.send 的 content 文本：原始 input + PDF inline 行。
+ *
+ * @param {string} input 用户输入文本
+ * @param {any[]} pdfBlocks PDF attachment blocks
+ * @returns {string}
+ */
+export function buildPicoMessageContent(input, pdfBlocks) {
+  if (!pdfBlocks || pdfBlocks.length === 0) return input;
+  const pdfLines = pdfBlocks
+    .map((b) => `[file: ${b.name}] ${b.source.url}`)
+    .join("\n");
+  if (!input) return pdfLines;
+  return `${input}\n${pdfLines}`;
+}
+
+function randomPicoID() {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+
+// 延迟读取以允许测试环境通过 process.env 覆盖
+function getTurnTimeoutMs() {
+  return Number(process.env.PICOCLAW_TURN_TIMEOUT_MS || 120000);
+}
+
+/**
+ * @param {{
+ *   wsHolder: { isOpen(): boolean, connectOnce(): Promise<void>, send(msg): void, onMessage(fn): () => void },
+ *   log: { info, warn, error },
+ *   activeTurnRef: { current: any },   // shared mutable ref so ws messages can resolve the turn
+ *   publishEventFn: (event: any) => Promise<void>,
+ *   dispatchHandlerOptions: {
+ *     relayUrl: string,
+ *     bridgeToken: string,
+ *     producerFactory?: Function,
+ *     openclawInvoke?: Function,
+ *   },
+ * }} opts
+ *
+ * Note: activeTurnRef and publishEventFn are only required when wsHolder is actually used
+ * (i.e. non-dispatch requests). Tests for dispatch path can omit them.
+ */
+export function createPicoHandleRequest({
+  wsHolder,
+  log,
+  activeTurnRef,
+  dispatchHandlerOptions,
+}) {
+  // 允许测试注入 openclawChatAbort 实现（避免真实 WS 依赖）
+  const _chatAbortFn = dispatchHandlerOptions?._openclawChatAbortFn ?? openclawChatAbort;
+
+  const unifiedHandler = createUnifiedDispatchHandler({
+    ...dispatchHandlerOptions,
+    log,
+  });
+
+  return async function handleRequest(request, ctx) {
+    // Step 0: RPC 分支 — sessions.abort / chat.abort（openclaw gateway WS 直连）
+    if (request?.request?.__relayKind === "rpc") {
+      const method = request.request.method;
+      const params = request.request.params ?? {};
+      let result;
+      try {
+        if (method === "sessions.abort" || method === "chat.abort") {
+          const sessionKey = params.key ?? params.sessionKey ?? "";
+          result = await _chatAbortFn({ sessionKey, log });
+        } else {
+          // 其余 RPC 方法（workspaces.scan 等）picoclaw 不处理，返回 unknown
+          result = { ok: false, error: `unknown rpc method: ${method}` };
+        }
+      } catch (err) {
+        result = { ok: false, error: err?.message ?? String(err) };
+      }
+      const bodyJson = JSON.stringify(result);
+      await ctx.publishEvent({
+        event: "response",
+        statusCode: 200,
+        contentType: "application/json; charset=utf-8",
+        body: bodyJson,
+      });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    // Step 1: Try unified dispatch handler first.
+    const handled = await unifiedHandler(request, ctx);
+    if (handled) return;
+
+    // Step 2: Original picoclaw ws path.
+    // Phase 5 (multimodal-attachment-llm-dispatch): relay_object blocks を
+    // relayObjectToBlock を通して処理する（runtimeHint="picoclaw", modelCaps=null）。
+    // image → url_ref → buildMediaCreate（URL をそのまま picoclaw daemon に送る）
+    // document/text/binary → input_text → メッセージに text として追加
+    const userText = extractUserText(request);
+    const blocks = request?.request?.blocks ?? [];
+
+    // relay_object blocks の処理（attachment_kind ベース）
+    const urlRefBlocks = [];   // image → url_ref blocks
+    const textInlineLines = []; // non-image → input_text の text
+
+    for (const block of blocks) {
+      if (!block?.source?.kind || block.source.kind !== "url" || !block.source.url) continue;
+      // image か attachment のみ relay_object
+      if (block.type !== "image" && block.type !== "attachment") continue;
+
+      const result = await relayObjectToBlock(block, {
+        runtimeHint: "picoclaw",
+        modelCaps: null,  // picoclaw: caps check をスキップ
+        fetchAndBase64Encode: async () => { throw new Error("picoclaw does not fetch bytes"); },
+      });
+
+      if (result.error) {
+        // エラーは text inline に追加
+        textInlineLines.push(`[attachment] (error: ${result.error.message})`);
+      } else if (result.type === "url_ref") {
+        // image → url_ref → buildMediaCreate 用に保存
+        urlRefBlocks.push({ url: result.url, media_type: result.media_type });
+      } else if (result.type === "input_text") {
+        // document / text / binary → inline text
+        textInlineLines.push(result.text);
+      }
+    }
+
+    const hasMedia = urlRefBlocks.length > 0;
+    // buildPicoMessageContent 互換：textInlineLines を userText に追加
+    let messageContent = userText;
+    if (textInlineLines.length > 0) {
+      messageContent = userText
+        ? `${userText}\n${textInlineLines.join("\n")}`
+        : textInlineLines.join("\n");
+    }
+
+    // 纯图片 + 无 PDF + 无文字：只发 media.create，不发 message.send
+    const shouldSendMessage = messageContent.trim().length > 0;
+    const shouldSendAnyMedia = hasMedia;
+
+    if (!shouldSendMessage && !shouldSendAnyMedia) {
+      log.warn("turn.skip", "no user text or blocks", { requestId: ctx.requestId });
+      await ctx.publishEvent({ event: "error", error: "empty user input" });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    if (!wsHolder.isOpen()) {
+      try { await wsHolder.connectOnce(); }
+      catch (err) {
+        await ctx.publishEvent({ event: "error", error: `picoclaw connect failed: ${err?.message || err}` });
+        await ctx.publishEvent({ event: "end" });
+        return;
+      }
+    }
+
+    const translatorState = createTurnState();
+    let resolveTurn;
+    const turnDone = new Promise((r) => { resolveTurn = r; });
+
+    if (activeTurnRef) {
+      activeTurnRef.current = { ctx, translatorState, resolve: resolveTurn };
+    }
+
+    const sessionId = `bubu-${ctx.requestId}`;
+    try {
+      // 先发所有 media.create（图片 url_ref），再发 message.send（如有文本或非 image）
+      for (const urlRef of urlRefBlocks) {
+        // url_ref → buildMediaCreate 互換オブジェクト
+        wsHolder.send(buildMediaCreate(sessionId, {
+          source: { url: urlRef.url, media_type: urlRef.media_type },
+        }));
+      }
+      if (shouldSendMessage) {
+        wsHolder.send(buildMessageSend({
+          sessionId,
+          content: messageContent,
+          requestId: ctx.requestId,
+        }));
+      }
+    } catch (err) {
+      if (activeTurnRef) activeTurnRef.current = null;
+      await ctx.publishEvent({ event: "error", error: `picoclaw send failed: ${err?.message || err}` });
+      await ctx.publishEvent({ event: "end" });
+      return;
+    }
+
+    const turnTimeoutMs = getTurnTimeoutMs();
+    const timeoutP = new Promise((r) => setTimeout(() => r("__timeout__"), turnTimeoutMs));
+    const winner = await Promise.race([turnDone.then(() => "__done__"), timeoutP]);
+    if (winner === "__timeout__") {
+      log.warn("picoclaw.turn.timeout", "turn timed out", { requestId: ctx.requestId, ms: turnTimeoutMs });
+      const events = forceFinalize(translatorState);
+      for (const e of events) {
+        if (e) await ctx.publishEvent(e);
+      }
+      if (activeTurnRef) activeTurnRef.current = null;
+    }
+  };
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function extractUserText(request) {
+  const input = request?.request?.input;
+  if (typeof input === "string") return input.trim();
+  if (Array.isArray(input)) {
+    const parts = [];
+    for (const item of input) {
+      if (typeof item === "string") parts.push(item);
+      else if (item && typeof item === "object") {
+        if (typeof item.text === "string") parts.push(item.text);
+        else if (Array.isArray(item.content)) {
+          for (const c of item.content) {
+            if (c && typeof c === "object" && typeof c.text === "string") parts.push(c.text);
+          }
+        } else if (typeof item.content === "string") parts.push(item.content);
+      }
+    }
+    return parts.join("\n").trim();
+  }
+  if (input && typeof input === "object") {
+    if (typeof input.text === "string") return input.text.trim();
+    if (typeof input.content === "string") return input.content.trim();
+  }
+  if (typeof request?.clientPreviewText === "string") return request.clientPreviewText.trim();
+  return "";
+}

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

@@ -0,0 +1,314 @@
+// 巴布(PicoClaw)桥接入口 — daemon 主循环。
+//
+// 与 hermes/claude/codex 的差异:
+//   - 配对流程不是 `agentlink pair <code>` 由用户在 cli 输入,而是 daemon 启动后
+//     自动调 server `/v1/pair-codes/picoclaw/create` 拿 QR PNG → 写到本地约定路径
+//     由屏幕显示模块独立读取 → App 扫码 → server consume → cli 通过 fetch_token
+//     poll status 拿到 bridge_token。全程零命令行交互。
+//
+//   - 与本地的 PicoClaw daemon (默认 ws://127.0.0.1:18790/pico/ws) 建立 WebSocket
+//     连接,把用户消息翻译为 message.send 发出去;接收 message.create / .update
+//     翻译成 OpenClaw 风格 native event 透传给服务端 long-poll 通道。
+//
+//   - daemon 主循环:
+//       1. readState() 拿 bridge_token
+//       2. 没有 → pair flow → writeState
+//       3. 有 → 启 worker(long-poll + WS),失败/被撤销时 clearState 回到 1
+//
+// 使用入口: `agentlink-agent picoclaw`
+
+import process from "node:process";
+
+import { createLogger } from "../../../src-shared/logger.mjs";
+import { newCid } from "../../../src-shared/correlation.mjs";
+import { createSessionSlot, SESSION_STATES } from "../../core/sessionSlot.mjs";
+import { createRelayWorker } from "../../core/relayWorker.mjs";
+import { installAutoTunnel } from "../../core/autoTunnelWiring.mjs";
+import { createUsageReporter } from "../../core/usageReporter.mjs";
+import { resolveRelayUrl } from "../../core/pairCodeClient.mjs";
+
+import {
+  PAIR_STATUS_POLL_INTERVAL_SEC,
+  PAIR_STATUS_POLL_MAX_SEC,
+  RUNTIME_NAME,
+  WS_RECONNECT_INITIAL_MS,
+  WS_RECONNECT_MAX_MS,
+} from "./constants.mjs";
+import { readState, writeState, clearState } from "./state.mjs";
+import {
+  createPairCode,
+  pollPairStatus,
+  writeQRImage,
+  clearQRImage,
+  writeDevPairInfo,
+  clearDevPairInfo,
+} from "./pairFlow.mjs";
+import { connect as wsConnect } from "./wsClient.mjs";
+import { translatePicoMessage } from "./translator.mjs";
+import { createPicoHandleRequest } from "./handleRequest.mjs";
+import { createPicoTodoTranslator } from "./todoTranslator.mjs";
+
+export async function runPicoclawBridge({ options, positional, log }) {
+  const relayBase = resolveRelayUrl(options.relay);
+  const log0 = log || createLogger({ comp: "bridge", cid: newCid() }).child({ rt: RUNTIME_NAME });
+  log0.info("bridge.preflight.pass", "picoclaw daemon entering main loop", { relay: relayBase });
+
+  let shuttingDown = false;
+  process.once("SIGINT", () => { shuttingDown = true; });
+  process.once("SIGTERM", () => { shuttingDown = true; });
+
+  // daemon 主循环 — 每次循环代表一次"配对 + 长轮询"周期。
+  // 解绑或鉴权失效会导致内层 worker 退出并清 state,主循环回到 0 重新生成 QR。
+  while (!shuttingDown) {
+    let st = readState();
+    if (!st) {
+      // 没绑定 → 走 pair flow
+      try {
+        st = await runPairFlow({ relayBase, options, log: log0 });
+      } catch (err) {
+        log0.warn("picoclaw.pair.failed", "pair flow failed; retry in 5s", { err: String(err?.message || err) });
+        await sleep(5000);
+        continue;
+      }
+      writeState(st);
+      log0.info("picoclaw.pair.persisted", "bridge_token saved, entering worker", { gw_id: st.gw_id });
+    }
+    // 启 worker — 内部异常或 token 撤销返回 reason
+    let exitReason;
+    try {
+      exitReason = await runWorkerWithBridge({ state: st, log: log0 });
+    } catch (err) {
+      log0.error("picoclaw.worker.fatal", "worker fatal", { err: String(err?.message || err) });
+      exitReason = "fatal";
+    }
+    log0.info("picoclaw.worker.exited", "worker exited", { reason: exitReason });
+    if (exitReason === "revoked" || exitReason === "auth-failed") {
+      clearState();
+      log0.info("picoclaw.state.cleared", "bridge_token revoked; back to pair loop");
+      continue;
+    }
+    if (shuttingDown) break;
+    // 网络抖动等 — 不清 state,直接重启 worker
+    await sleep(2000);
+  }
+  log0.info("bridge.shutdown", "picoclaw daemon exiting");
+}
+
+// ── pair flow ────────────────────────────────────────────────────
+
+async function runPairFlow({ relayBase, options, log }) {
+  // 1. 调 server 创建 pair-code
+  const created = await createPairCode({
+    relayUrl: relayBase,
+    label: options.label,
+    deviceId: options.deviceId || process.env.PICOCLAW_DEVICE_ID || "",
+    fetchImpl: globalThis.fetch,
+    log,
+  });
+  // 2. 写 QR PNG 到约定路径(屏幕模块读)
+  const qrPath = writeQRImage(created.qr_png_base64, options.qrPath);
+  log.info("picoclaw.pair.qr.written", "qr image written", { path: qrPath, code: created.code });
+  // 2.5 dev 测试钩子:把 code + fetch_token + relay + 完整 deeplink 写到本地,
+  //      让 e2e 测试脚本 / iOS 模拟器粘贴测试扮演 App 角色用。
+  //      (仅当 BUBU_DEV_DUMP_PAIR_INFO=1 时生效;生产环境严禁开启)
+  const devPath = writeDevPairInfo({
+    code: created.code,
+    fetch_token: created.fetch_token,
+    relay: relayBase,
+    label: options.label,
+    expires_at: created.expires_at,
+    qr_payload: created.qr_payload, // 完整 deeplink,粘贴到 App 输入框直接绑定
+  });
+  if (devPath) {
+    log.info("picoclaw.pair.devinfo.written", "dev pair-info written for test", { path: devPath });
+  }
+  // 3. poll status
+  try {
+    const result = await pollPairStatus({
+      relayUrl: relayBase,
+      code: created.code,
+      fetchToken: created.fetch_token,
+      intervalSec: created.poll_interval_seconds || PAIR_STATUS_POLL_INTERVAL_SEC,
+      maxSec: PAIR_STATUS_POLL_MAX_SEC,
+      log,
+    });
+    // 4. 配对成功 — 清 QR 图(屏幕切换为已绑定画面;具体显示模块自己处理)
+    clearQRImage(options.qrPath);
+    clearDevPairInfo();
+    return {
+      gw_id: result.gw_id,
+      bridge_token: result.bridge_token,
+      relay_url: relayBase,
+      client_user_id: result.client_user_id,
+      label: result.label,
+    };
+  } catch (err) {
+    clearQRImage(options.qrPath);
+    clearDevPairInfo();
+    throw err;
+  }
+}
+
+// ── worker(long-poll + WS) ─────────────────────────────────────
+
+async function runWorkerWithBridge({ state, log }) {
+  const sessLog = log.child({ gw: state.gw_id });
+  const worker = createRelayWorker({
+    relayUrl: state.relay_url,
+    gwId: state.gw_id,
+    bridgeToken: state.bridge_token,
+    runtime: RUNTIME_NAME,
+    log: sessLog,
+  });
+  installAutoTunnel({ relayUrl: state.relay_url, log: sessLog });
+
+  // ── PicoClaw WS — 自带重连 ──
+  const wsHolder = createReconnectingWS({ log: sessLog });
+
+  // 当前 in-flight turn 的 ctx — handleRequest 期间唯一非空
+  const activeTurnRef = { current: null };
+  const slot = createSessionSlot({ log: sessLog, name: RUNTIME_NAME });
+  slot.transition(SESSION_STATES.READY, "picoclaw-no-spawn");
+
+  const usage = createUsageReporter({
+    runtime: RUNTIME_NAME,
+    log: sessLog,
+    publishEvent: (event) => {
+      if (!activeTurnRef.current) return Promise.resolve(false);
+      return worker.publishEvent(activeTurnRef.current.ctx.requestId, event);
+    },
+  });
+
+  // 连 WS
+  try {
+    await wsHolder.connectOnce();
+  } catch (err) {
+    sessLog.warn("picoclaw.ws.first_connect.err", "initial ws connect failed", { err: String(err?.message || err) });
+    // 不致命 — handleRequest 时会再触发重连。
+  }
+
+  // todo translator（ws 路径）：拦截 update_plan，阻止透传原始 tool_call 事件
+  // ws 路径不走 envelope 系统，所以只做拦截（不发 todo_list block）
+  const wsTodoTranslator = createPicoTodoTranslator("ws_path");
+
+  // 把 ws 收到的消息分发给当前 turn
+  wsHolder.onMessage((picoMsg) => {
+    const activeTurn = activeTurnRef.current;
+    if (!activeTurn) {
+      sessLog.warn("picoclaw.ws.msg.no_turn", "received pico message but no active turn", { type: picoMsg?.type });
+      return;
+    }
+    // todo translator 拦截：update_plan 消息不透传（阻止 function_call_arguments.delta chunk）
+    const intercepted = wsTodoTranslator.intercept(picoMsg);
+    if (intercepted.length > 0 && intercepted[0] !== picoMsg) {
+      // 拦截到 update_plan，静默丢弃（ws 路径无 envelope 能力）
+      return;
+    }
+    const events = translatePicoMessage(picoMsg, activeTurn.translatorState);
+    if (!events.length) return;
+    void publishEvents(activeTurn, events).catch((err) => {
+      sessLog.warn("picoclaw.publish.err", "publish failed", { err: String(err?.message || err) });
+    });
+    if (activeTurn.translatorState.finalized) {
+      const turn = activeTurnRef.current;
+      activeTurnRef.current = null;
+      turn.resolve(); // wake the awaiting handleRequest
+    }
+  });
+
+  // ── handleRequest: dispatch 走 unifiedHandler，普通请求走原有 ws 路径 ──
+  const handleRequest = createPicoHandleRequest({
+    wsHolder,
+    log: sessLog,
+    activeTurnRef,
+    dispatchHandlerOptions: {
+      relayUrl: state.relay_url,
+      bridgeToken: state.bridge_token,
+    },
+  });
+
+  // Wrap to add usage tracking for non-dispatch turns.
+  const handleRequestWithUsage = async (request, ctx) => {
+    const turnStartedAt = Date.now();
+    await handleRequest(request, ctx);
+    usage.addCost({ turns: 1, duration_ms: Date.now() - turnStartedAt });
+    usage.schedulePublish("picoclaw.turn_end");
+  };
+
+  // 启 long-poll 循环。worker.run() 在 401/410 时会抛带特征的错误。
+  let exitReason = "loop-exit";
+  try {
+    await worker.run(handleRequestWithUsage);
+  } catch (err) {
+    const msg = String(err?.message || err);
+    if (/401|403|410|revoked|unauthorized/i.test(msg)) {
+      exitReason = "revoked";
+    } else {
+      exitReason = "fatal";
+      sessLog.error("picoclaw.worker.err", "worker errored", { err: msg });
+    }
+  } finally {
+    try { wsHolder.close("worker-exit"); } catch {}
+    try { usage.dispose(); } catch {}
+  }
+  return exitReason;
+}
+
+// ── helpers ──────────────────────────────────────────────────────
+
+async function publishEvents({ ctx }, events) {
+  for (const e of events) {
+    if (!e) continue;
+    await ctx.publishEvent(e);
+  }
+}
+
+function createReconnectingWS({ log }) {
+  let conn = null;
+  const messageHandlers = new Set();
+  let backoff = WS_RECONNECT_INITIAL_MS;
+
+  async function connectOnce() {
+    if (conn && conn.readyState === 1) return conn;
+    conn = await wsConnect({ log });
+    backoff = WS_RECONNECT_INITIAL_MS;
+    conn.onMessage((m) => {
+      for (const h of messageHandlers) {
+        try { h(m); } catch (err) {
+          log.warn("picoclaw.ws.handler.err", "handler threw", { err: String(err?.message || err) });
+        }
+      }
+    });
+    conn.onClose(() => {
+      conn = null;
+      // 异步重连,不阻塞 ws.onClose 回调
+      setTimeout(() => {
+        connectOnce().catch((err) => {
+          log.warn("picoclaw.ws.reconnect.err", "reconnect failed", { err: String(err?.message || err) });
+          backoff = Math.min(backoff * 2, WS_RECONNECT_MAX_MS);
+        });
+      }, backoff);
+    });
+    return conn;
+  }
+
+  return {
+    connectOnce,
+    isOpen() { return conn && conn.readyState === 1; },
+    send(msg) {
+      if (!conn || conn.readyState !== 1) {
+        throw new Error("picoclaw ws not open");
+      }
+      conn.send(msg);
+    },
+    onMessage(fn) { messageHandlers.add(fn); return () => messageHandlers.delete(fn); },
+    close(reason) {
+      try { conn?.close(reason); } catch {}
+      conn = null;
+    },
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}