@xyagent/cli 0.0.1

package/src-ext/core/preprocessAttachments.mjs

@@ -0,0 +1,113 @@
+/**
+ * preprocessAttachments.mjs — bridge 侧 text-like mime attachment 预处理
+ *
+ * preprocessAttachmentsToText(blocks, { fetch, log })
+ *   → Promise<block[]>
+ *
+ * 对 type="attachment" 且 mime 命中白名单（text-like）的 block：
+ *   - fetch COS URL → UTF-8 解码 → 替换为 {type:"text", text:"[file: <name>]\n<content>\n"}
+ *   - 超出 1,048,576 字符时截断 + 追加 "\n... [truncated, file too large]"
+ *   - fetch 失败：替换为 {type:"text", text:"[file: <name>] (download failed: <error>)\n"}
+ *
+ * application/pdf：原样保留（各 runtime 自行翻译）
+ * 其他 mime attachment：替换为 {type:"text", text:"[file: <name>] (unsupported mime: <mime>)"}
+ * 非 attachment block（image、text 等）：原样保留
+ *
+ * NOTE (Phase 5 — multimodal-attachment-llm-dispatch):
+ * relay_object blocks (source.kind="url" with attachment_kind field) は
+ * 各 runtime adapter で relayObjectToBlock (_shared/relayObjectToBlock.mjs) に
+ * よって処理される。このモジュール (preprocessAttachmentsToText) は、relay_object
+ * でない旧形式の type=attachment blocks（source.kind≠url、または attachment_kind
+ * フィールドなし）の後方互換処理として引き続き使用される。
+ * relay_object パスは relayObjectToBlock が接管済み。
+ *
+ * spec ref: openspec/changes/openclaw-multimodal-image-passthrough design.md D-attach-A
+ */
+
+const TEXT_LIKE_MIMES = new Set([
+  "text/plain",
+  "text/markdown",
+  "text/csv",
+  "text/html",
+  "application/json",
+]);
+
+const SIZE_CAP_CHARS = 1_048_576; // 1 MB
+
+/**
+ * @param {any[]} blocks - 完整 input blocks 数组
+ * @param {{ fetch?: Function, log?: { info?, warn?, error? } }} opts
+ * @returns {Promise<any[]>} 处理后的 blocks 数组（新数组，原 blocks 不被修改）
+ */
+export async function preprocessAttachmentsToText(blocks, { fetch: fetchFn, log } = {}) {
+  if (!Array.isArray(blocks) || blocks.length === 0) return [];
+
+  // 允许注入 fetch（测试 mock 用），默认用全局 fetch
+  const doFetch = fetchFn ?? globalThis.fetch;
+
+  const result = [];
+  for (const block of blocks) {
+    if (block?.type !== "attachment") {
+      result.push(block);
+      continue;
+    }
+
+    const name = block.name ?? "unknown";
+    const mime = block.mime ?? "";
+    const url = block.source?.url;
+
+    // PDF：原样保留，各 runtime 自行处理
+    if (mime === "application/pdf") {
+      result.push(block);
+      continue;
+    }
+
+    // 非 url source 的 attachment：原样保留（防御）
+    if (!url || block.source?.kind !== "url") {
+      result.push(block);
+      continue;
+    }
+
+    // 其他 mime（非 text-like 非 pdf）：不支持，替换为占位
+    if (!TEXT_LIKE_MIMES.has(mime)) {
+      result.push({
+        type: "text",
+        text: `[file: ${name}] (unsupported mime: ${mime})`,
+      });
+      continue;
+    }
+
+    // text-like mime：fetch → 解码 → 替换为 text block
+    try {
+      const res = await doFetch(url);
+      if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${res.statusText}`);
+      }
+      let text = await res.text();
+
+      let truncated = false;
+      if (text.length > SIZE_CAP_CHARS) {
+        text = text.slice(0, SIZE_CAP_CHARS);
+        truncated = true;
+      }
+
+      const body = truncated
+        ? `[file: ${name}]\n${text}\n... [truncated, file too large]`
+        : `[file: ${name}]\n${text}\n`;
+
+      result.push({ type: "text", text: body });
+    } catch (err) {
+      const errMsg = err?.message ?? String(err);
+      log?.warn?.("preprocess.fetch_failed", `download failed for ${name}`, {
+        url,
+        err: errMsg,
+      });
+      result.push({
+        type: "text",
+        text: `[file: ${name}] (download failed: ${errMsg})\n`,
+      });
+    }
+  }
+
+  return result;
+}

package/src-ext/core/relayWorker.mjs

@@ -0,0 +1,284 @@
+// relayWorker — bridge 端 long-poll 客户端,封装与服务端三个端点的所有通讯:
+//
+//   GET  /v1/gateways/<gw>/requests/next?waitSeconds=<N>
+//   POST /v1/gateways/<gw>/requests/<rid>/events
+//   POST /v1/gateways/<gw>/meta
+//
+// 任何 bridge(hermes / claude / codex)拿到 (relayUrl, gwId, bridgeToken) 后
+// 用 createRelayWorker(...) 起一个 worker,然后 worker.run(handler) 进入主循环。
+// 每条请求由 handler(request, ctx) 处理,ctx.publishEvent(event) 把 native 事件
+// 推回服务端,服务端 adapter 自动翻译为 unified envelope 落库。
+//
+// 与旧的 unified_relay_shim 的本质差异:
+//   - 不再做"legacy kind → unified envelope"的客户端翻译;native event 直送
+//   - 不再走 SSE 订阅;用户消息只通过 long-poll 拉取
+//   - 心跳走 /meta(普通 PUT 接口),不再发 bridge.status envelope
+//   - publishEvent 是 fire-and-forget(失败 log 不抛),保证 handler 简洁
+//
+// 设计参考:src/tunnel_proxy.mjs 的 runHttpAgentLoop。
+
+import { trimSlash } from "./relayWorkerHttp.mjs";
+import {
+  fetchJson,
+  bridgeAuthHeaders,
+  extractError,
+} from "./relayWorkerHttp.mjs";
+
+// long-poll 等待秒数(服务端上限 60s)。多数情况下队列里就有请求,空闲时占用一个连接。
+const POLL_WAIT_SECONDS = 25;
+// 单次请求/响应的硬超时 = wait + buffer。HTTP 客户端比服务端 wait 多 5s 防边界 race。
+const POLL_TIMEOUT_MS = (POLL_WAIT_SECONDS + 5) * 1000;
+// 默认 publishEvent 超时:单条事件 10s 足够(数据通常 < 1MB)。
+const PUBLISH_TIMEOUT_MS = 10_000;
+// 心跳间隔。服务端 gateway meta TTL 是 30s(http_gateway.go::gatewayMetaTTL),
+// 取 1/3 留充足容错(2 次心跳丢失仍保活)。
+export const META_HEARTBEAT_MS = 10_000;
+// 连续 poll 失败时的退避起点 + 上限,避免雪崩重试。
+const POLL_BACKOFF_MS = 1_000;
+const POLL_BACKOFF_MAX_MS = 15_000;
+
+/**
+ * 创建一个 worker 实例。worker 不立即启动,调用方需调 run(handler) 进入主循环。
+ *
+ * @param {{
+ *   relayUrl: string,
+ *   gwId: string,
+ *   bridgeToken: string,
+ *   runtime: "hermes"|"claude"|"codex",
+ *   log: any,
+ * }} opts
+ */
+export function createRelayWorker(opts) {
+  if (!opts || !opts.log) throw new Error("createRelayWorker: log required");
+  if (!opts.relayUrl) throw new Error("createRelayWorker: relayUrl required");
+  if (!opts.gwId) throw new Error("createRelayWorker: gwId required");
+  if (!opts.bridgeToken) throw new Error("createRelayWorker: bridgeToken required");
+  const log = opts.log.child({ comp: "worker" });
+  const base = trimSlash(opts.relayUrl);
+  const gw = encodeURIComponent(opts.gwId);
+  const auth = bridgeAuthHeaders(opts.bridgeToken);
+
+  const stopState = { stopping: false };
+  let metaTimer = null;
+
+  // ---- 拉取下一条 request ----
+  async function readNextRequest() {
+    const url =
+      `${base}/v1/gateways/${gw}/requests/next?waitSeconds=${POLL_WAIT_SECONDS}`;
+    const res = await fetchJson(url, { method: "GET", headers: auth }, POLL_TIMEOUT_MS);
+    if (res.status === 204) return null;
+    if (!res.ok) {
+      // 状态码必须出现在 message 里 — run() 用 /HTTP 40[13]/ 识别永久错误并中止主循环。
+      const detail = extractError(res, "read next request failed");
+      throw new Error(`HTTP ${res.status} ${detail}`);
+    }
+    return res.body?.request ?? null;
+  }
+
+  // ---- 推送 native 事件到服务端 adapter ----
+  // event 形态由 runtime 决定;统一字段 `event`(必填) + 任意 native 字段。
+  // 失败仅 log,不抛;handler 不应感知 publish 失败(adapter 应有重试/兜底)。
+  async function publishEvent(requestId, event) {
+    if (!requestId || !event || typeof event !== "object") return false;
+    if (typeof event.event !== "string" || !event.event) {
+      log.warn("publish.skip", "missing event field", { requestId });
+      return false;
+    }
+    const url = `${base}/v1/gateways/${gw}/requests/${encodeURIComponent(requestId)}/events`;
+    try {
+      const res = await fetchJson(
+        url,
+        { method: "POST", headers: { ...auth, "Content-Type": "application/json" }, body: JSON.stringify(event) },
+        PUBLISH_TIMEOUT_MS,
+      );
+      if (!res.ok) {
+        log.warn("publish.fail", extractError(res, `publish failed (HTTP ${res.status})`), {
+          requestId, event: event.event, status: res.status,
+        });
+        return false;
+      }
+      return true;
+    } catch (err) {
+      log.warn("publish.err", "publish errored", {
+        requestId, event: event.event, err: err?.message || String(err),
+      });
+      return false;
+    }
+  }
+
+  // ---- 周期性心跳 ----
+  //
+  // App 端用 `meta.online ?? meta.connected ?? meta.alive ?? meta.state` 串行
+  // 兜底来判 bridge 是否在线（见 agent_app/matelink-app/lib/src/models/relay_models.dart:477）。
+  // legacy openclaw bridge 的 `buildBridgePresenceMeta` 一直会发这套字段，
+  // ext runtime（hermes / claude / codex / picoclaw）漏发会导致 onlineHint=null
+  // → App UI 兜底显示"离线"（即用户报"配对完显示离线"的根因）。
+  // detail === "stopped" 时表示主动下线，其它（"ready" / "heartbeat" / "alive"）都视为在线。
+  async function sendMeta(detail) {
+    const url = `${base}/v1/gateways/${gw}/meta`;
+    const isAlive = detail !== "stopped";
+    const stateLabel = detail === "stopped" ? "stopped"
+                     : detail === "ready"   ? "running"
+                     : "running";
+    try {
+      const res = await fetchJson(
+        url,
+        {
+          method: "POST",
+          headers: { ...auth, "Content-Type": "application/json" },
+          body: JSON.stringify({
+            runtime: opts.runtime,
+            detail: detail || "alive",
+            collected_at_ms: Date.now(),
+            // ↓ App-facing presence 字段：用任一即可判 online
+            online: isAlive,
+            connected: isAlive,
+            alive: isAlive,
+            state: stateLabel,
+            heartbeatAt: new Date().toISOString(),
+          }),
+        },
+        PUBLISH_TIMEOUT_MS,
+      );
+      if (!res.ok) {
+        log.warn("meta.fail", extractError(res, `meta failed (HTTP ${res.status})`), {
+          status: res.status,
+        });
+        return false;
+      }
+      return true;
+    } catch (err) {
+      log.warn("meta.err", "meta heartbeat errored", { err: err?.message || String(err) });
+      return false;
+    }
+  }
+
+  function startHeartbeat() {
+    if (metaTimer) return;
+    // 立即发一次,让服务端立刻知道 bridge 起来了。
+    void sendMeta("ready");
+    metaTimer = setInterval(() => {
+      if (stopState.stopping) return;
+      void sendMeta("heartbeat");
+    }, META_HEARTBEAT_MS);
+    if (typeof metaTimer.unref === "function") metaTimer.unref();
+  }
+
+  function stopHeartbeat() {
+    if (metaTimer) {
+      clearInterval(metaTimer);
+      metaTimer = null;
+    }
+  }
+
+  // ---- 主循环:long-poll → 派发(rpc 并发 / chat 按会话串行) ----
+  // handler 形态: async (request, ctx) => void
+  //   ctx.publishEvent(event)  把 native 事件推回服务端
+  //   ctx.requestId            当前请求 id(便利字段,等价 request.requestId)
+  //   ctx.signal               关闭信号(基于 AbortController)
+  async function run(handler) {
+    if (typeof handler !== "function") {
+      throw new Error("worker.run: handler must be a function");
+    }
+    // sessionKey → 该会话当前尾部 promise（chat 请求按会话串行、跨会话并行）
+    const sessionLanes = new Map();
+    startHeartbeat();
+    let backoff = POLL_BACKOFF_MS;
+    while (!stopState.stopping) {
+      let request;
+      try {
+        request = await readNextRequest();
+        backoff = POLL_BACKOFF_MS;
+      } catch (err) {
+        const msg = err?.message || String(err);
+        // 401/403 永久错误 — bridge token 失效，直接抛 bridge 主流程退出。
+        // 404/410 = pair session 已被服务端解绑（App 端 deleteContact /
+        //          POST /v1/gateways/<gw>/reset 都走 deleted_at 标记），
+        //          server 长 poll 查不到 session → "gateway session not
+        //          found"。视为对端解绑，标记 revoked + 抛错让上层清理。
+        if (/HTTP 40[13]/.test(msg)) {
+          log.error("poll.auth_fail", "bridge token invalid, aborting", { err: msg });
+          stopState.stopping = true;
+          throw err;
+        }
+        if (/HTTP 404\b|HTTP 410\b/.test(msg) || /gateway session not found/i.test(msg)) {
+          log.error("poll.revoked", "binding revoked by remote, aborting", {
+            err: msg,
+          });
+          stopState.stopping = true;
+          // 把 revoked 标记打到错误对象上,bridge 主流程据此触发自卸载逻辑
+          // (清本地 pair state + spawn `agentlink uninstall` 卸 launchd plist)。
+          err.revoked = true;
+          throw err;
+        }
+        log.warn("poll.err", "long-poll errored, backing off", {
+          err: msg, backoff_ms: backoff,
+        });
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, POLL_BACKOFF_MAX_MS);
+        continue;
+      }
+      if (!request) continue; // 204 — 队列空,继续 poll
+      const requestId = String(request.requestId || "").trim();
+      if (!requestId) {
+        log.warn("poll.bad", "request missing requestId");
+        continue;
+      }
+      log.info("request.recv", "request received", {
+        requestId,
+        sessionKey: request.sessionKey || "",
+        agent: request.agentId || "",
+        stream: !!request.stream,
+      });
+      const ctx = {
+        requestId,
+        publishEvent: (event) => publishEvent(requestId, event),
+      };
+      const runOne = async () => {
+        try {
+          await handler(request, ctx);
+        } catch (err) {
+          const msg = err?.message || String(err);
+          log.error("handler.fail", "request handler threw", { requestId, err: msg });
+          // 未捕获的 handler 错误统一收尾发 error + end,避免 client 永远等不到结束。
+          await publishEvent(requestId, { event: "error", error: msg });
+          await publishEvent(requestId, { event: "end" });
+        }
+      };
+      // 派发策略（P0 停止按钮）：
+      //   - rpc 控制请求(workspaces.scan / sessions.abort 等)立即并发执行——
+      //     否则 abort 会排在正在执行的 chat 后面，永远停不掉。
+      //   - chat 请求按 sessionKey 串行（同会话保序），不同会话并行；
+      //     主循环不再 await handler，long-poll 持续拉取。
+      if (request?.request?.__relayKind === "rpc") {
+        void runOne();
+      } else {
+        const laneKey = String(request.sessionKey || requestId);
+        const tail = sessionLanes.get(laneKey) || Promise.resolve();
+        const next = tail.then(runOne, runOne);
+        sessionLanes.set(laneKey, next);
+        void next.finally(() => {
+          if (sessionLanes.get(laneKey) === next) sessionLanes.delete(laneKey);
+        });
+      }
+    }
+  }
+
+  function stop(reason) {
+    stopState.stopping = true;
+    stopHeartbeat();
+    log.info("worker.stop", "worker stopping", { reason: reason || "" });
+  }
+
+  return {
+    run,
+    stop,
+    publishEvent,
+    sendMeta,
+    isStopping: () => stopState.stopping,
+  };
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src-ext/core/relayWorkerHttp.mjs

@@ -0,0 +1,58 @@
+// relayWorker 的 HTTP 工具(独立文件,便于单测 mock)。
+//
+// fetchJson 是 src/tunnel_state.mjs 同名函数的精简版 — 只做 JSON 请求/响应,
+// 不处理流式、不处理 hop-by-hop。bridge worker 走的全是简单 JSON RPC 形态。
+
+/** 去掉 URL 末尾的多余斜杠,但保留 scheme + host。 */
+export function trimSlash(url) {
+  return String(url || "").replace(/\/+$/, "");
+}
+
+/**
+ * Bearer token header — bridge 端点要求 `Authorization: Bearer <bridgeToken>`。
+ *
+ * 服务端 requireGatewayAuth 接受同一 token 形式;X-Agent-Bridge-Token 是 unified
+ * 协议端点的 producer auth,这里**不**用,我们走 legacy gateway 路径。
+ */
+export function bridgeAuthHeaders(bridgeToken) {
+  return { Authorization: `Bearer ${String(bridgeToken || "")}` };
+}
+
+/**
+ * 简化的 fetch wrapper:
+ *   - 自动 AbortController 超时
+ *   - body 是 JSON 时自动解析,否则保留 raw text
+ *   - 不抛网络错以外的错(HTTP 4xx/5xx 通过 res.ok=false + body 透传)
+ *
+ * @param {string} url
+ * @param {RequestInit} init
+ * @param {number} [timeoutMs] 默认 30s
+ * @returns {Promise<{ok:boolean,status:number,body:any,bodyText:string}>}
+ */
+export async function fetchJson(url, init, timeoutMs = 30_000) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetch(url, { ...init, signal: ctrl.signal });
+  } finally {
+    clearTimeout(t);
+  }
+  const text = await res.text();
+  let body = null;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = null; }
+  }
+  return { ok: res.ok, status: res.status, body, bodyText: text };
+}
+
+/** 从 fetchJson 响应里榨出错误描述 — body.error 优先,否则原文截断。 */
+export function extractError(res, fallback) {
+  if (res?.body && typeof res.body === "object" && typeof res.body.error === "string") {
+    return res.body.error;
+  }
+  if (typeof res?.bodyText === "string" && res.bodyText.trim()) {
+    return res.bodyText.slice(0, 200);
+  }
+  return fallback || "request failed";
+}