@xyagent/cli 0.0.1

package/src-shared/README.md

@@ -0,0 +1,44 @@
+# `src-shared/` — 纯基础设施
+
+新老功能都可以 import 的**纯工具**。
+
+## 准入规则
+
+一个模块要放进 `src-shared/`，必须同时满足：
+
+1. **纯函数或只读单例** —— 无跨模块业务状态
+2. **不 import** `../src/**`（OpenClaw bridge / tunnel）或 `../src-ext/**`（External Agents）
+3. **无外部服务调用** —— 不直接连 relay、不 spawn 子进程、不读业务配置
+4. 有充分单测覆盖
+
+违反任一条 → 放回 `src/` 或 `src-ext/`。
+
+## 当前内容
+
+| 模块                  | 用途                                       |
+| --------------------- | ------------------------------------------ |
+| `logger.mjs`          | 结构化 JSON 日志（见 `docs/LOGGING.md`）   |
+| `correlation.mjs`     | cid 生成 / 解析                            |
+| `relay-defaults.json` | 默认 relay URL 等只读常量                  |
+
+## 历史变更
+
+重构后**已移除**以下子目录（事实清单，便于追旧 PR）：
+
+- `src-shared/protocol/unified/` —— 之前放统一 Agent SSE 协议的 JS 类型定义 +
+  envelope producer 工具。CLI bridge 重构后不再做协议翻译，所以 producer 工具
+  整体不需要了；类型定义如果其他工程仍要复用，请直接引用 `docs/protocol/`
+  下的 JSON Schema / Protobuf 源（`agentlink-server/docs/protocol/`）。
+- `src-shared/agent-client/` —— 之前的 `/v1/agents/*` HTTP + SSE 客户端 SDK。
+  CLI bridge 不再调统一协议端点（改走 `/v1/gateways/<gw>/requests/next` +
+  `POST events`），整目录删除。
+
+## 依赖方向
+
+```
+src-ext/*    ──> src-shared/*        ✅
+src/*        ──> src-shared/*        ✅（OpenClaw bridge 也可用）
+src-shared/* ──> (anything else)     ❌
+```
+
+破坏依赖方向 = PR 拒绝。

package/src-shared/chat_push_normalizer.mjs

@@ -0,0 +1,113 @@
+// chat_push_normalizer.mjs
+//
+// Reshape OpenClaw `chat.push` WS frames so the relay + app contract stays
+// stable across daemon protocol versions.
+//
+// OpenClaw 2026.5.12-beta.5 switched chat.push payloads from "full text per
+// frame" (v3, snapshot-style) to explicit `deltaText` / `replace` deltas (v4)
+// so SDK clients no longer have to diff locally. Downstream consumers in this
+// project (go_relay + the Flutter app) still expect the v3 `text` field. The
+// bridge buffers per-stream deltas here and re-emits a v3-shaped snapshot:
+//
+//   - v3 daemon (≤ 2026.5.12-beta.4): params.text present → passthrough, also
+//     latched into the buffer so a subsequent v4 delta could continue cleanly.
+//   - v4 daemon (≥ 2026.5.12-beta.5): params.replace resets the buffer;
+//     params.deltaText is adaptive — observed daemons in the wild send
+//     accumulating snapshots in this field (each frame includes everything
+//     that came before plus a small tail). When the incoming `deltaText`
+//     starts with the buffered prefix and is at least as long, we treat it
+//     as a snapshot replace; otherwise we fall back to the spec'd "append
+//     pure delta" semantics. Both cases synthesize `text = <full buffer>`
+//     before forwarding. The original `deltaText` / `replace` fields are
+//     kept on the forwarded payload so v4-aware consumers can opt in later.
+//
+// Buffer is keyed by (sessionKey, runId, blockId|index) and cleared on
+// terminal-state frames. LRU-bounded so a misbehaving daemon cannot leak
+// unbounded memory in a long-lived bridge process.
+
+const DEFAULT_BUFFER_MAX = 256;
+
+const TERMINAL_STATES = new Set([
+  "completed", "complete", "done", "finished",
+  "failed", "stopped", "aborted", "canceled", "cancelled", "error",
+]);
+
+function bufferKey(payload) {
+  const sk = String(payload?.sessionKey ?? "").trim();
+  const rid = String(payload?.runId ?? "").trim();
+  const bid = String(payload?.blockId ?? payload?.index ?? "").trim();
+  return `${sk}|${rid}|${bid}`;
+}
+
+function isTerminalState(payload) {
+  const s = typeof payload?.state === "string" ? payload.state.toLowerCase().trim() : "";
+  return TERMINAL_STATES.has(s);
+}
+
+export function createChatPushNormalizer({ bufferMax = DEFAULT_BUFFER_MAX } = {}) {
+  const buf = new Map();
+
+  function touch(key, value) {
+    // Re-insertion moves the entry to the most-recent end of the Map iteration
+    // order, so iterating .keys() starts with the LRU entry for eviction.
+    if (buf.has(key)) buf.delete(key);
+    buf.set(key, value);
+    if (buf.size > bufferMax) {
+      const oldest = buf.keys().next().value;
+      if (oldest !== undefined) buf.delete(oldest);
+    }
+  }
+
+  function normalize(params) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) return params;
+    const key = bufferKey(params);
+
+    // v3 snapshot path — `text` already carries text-so-far. Latch + passthrough.
+    if (typeof params.text === "string" && params.text.length > 0) {
+      touch(key, params.text);
+      if (isTerminalState(params)) buf.delete(key);
+      return params;
+    }
+
+    // v4 full-replacement path — `replace` resets the buffer to the new value.
+    if (typeof params.replace === "string") {
+      touch(key, params.replace);
+      const out = { ...params, text: params.replace };
+      if (isTerminalState(params)) buf.delete(key);
+      return out;
+    }
+
+    // v4 incremental path — `deltaText` semantics in the wild differ from
+    // the spec: OpenClaw 2026.5.x daemons emit accumulating snapshots in
+    // this field (each frame ≈ "everything-so-far + a small tail"). Naïvely
+    // appending caused exponential text pile-up in the app ("编程编程编程
+    // 任务，任务，任务…"). Adaptive rule:
+    //   - if deltaText starts with the buffered prefix AND is ≥ as long,
+    //     treat as snapshot (text = deltaText)
+    //   - else fall back to spec'd append (text = prev + deltaText)
+    // Buffer starts empty so the very first frame always falls through the
+    // append branch — same observable result as before for a fresh stream.
+    if (typeof params.deltaText === "string") {
+      const prev = buf.get(key) ?? "";
+      const dt = params.deltaText;
+      const isSnapshot =
+        prev.length > 0 && dt.length >= prev.length && dt.startsWith(prev);
+      const next = isSnapshot ? dt : prev + dt;
+      touch(key, next);
+      const out = { ...params, text: next };
+      if (isTerminalState(params)) buf.delete(key);
+      return out;
+    }
+
+    // Heartbeat / terminal-only frame with no text payload — clean up if last.
+    if (isTerminalState(params)) buf.delete(key);
+    return params;
+  }
+
+  return {
+    normalize,
+    // Test-only introspection. Not part of the bridge runtime contract.
+    _size: () => buf.size,
+    _peek: (payload) => buf.get(bufferKey(payload)),
+  };
+}

package/src-shared/correlation.mjs

@@ -0,0 +1,25 @@
+// Correlation ID 生成与规范化。
+//
+// cid 贯穿 app → server → CLI → agent 全链路。格式：
+//   "c_" + 8 位十六进制
+// 如果上游传来的值不符合，生成一个新的；合法值原样沿用。
+
+import { randomBytes } from "node:crypto";
+
+const CID_RE = /^c_[0-9a-f]{8,}$/;
+
+export function newCid() {
+  return "c_" + randomBytes(4).toString("hex");
+}
+
+export function normalizeCid(raw) {
+  if (typeof raw !== "string") return newCid();
+  const trimmed = raw.trim();
+  if (!trimmed) return newCid();
+  if (!CID_RE.test(trimmed)) return newCid();
+  return trimmed;
+}
+
+export function isValidCid(value) {
+  return typeof value === "string" && CID_RE.test(value);
+}