@xyagent/cli 0.0.1

package/src-ext/core/unifiedDispatchHandler.mjs

@@ -0,0 +1,439 @@
+/**
+ * unifiedDispatchHandler.mjs — D-C1
+ *
+ * createUnifiedDispatchHandler({ relayUrl, bridgeToken, log, producerFactory?, openclawInvoke? })
+ *   → async (request, ctx) => boolean
+ *
+ * Returns true if the request was consumed (agent.run.dispatch), false otherwise.
+ * The handler is idempotent per run_id (in-memory Set, process-scoped).
+ *
+ * Injection points for testing:
+ *   producerFactory({ relayUrl, bridgeToken, threadId }) → { postEvents }
+ *   openclawInvoke({ input, onChunk }) → async void   (default: picoclaw wsHolder)
+ *   flushPolicy({ size, timeMs }) → 控制 micro-batched flush 触发阈值（默认 {size:1, timeMs:0} —— 即来即发，保流式体验）
+ */
+
+import { createHookedUnifiedProducer } from "../../src/unified_producer.mjs";
+import {
+  translateOpenClawChunkToEnvelope,
+  buildRunCompleted,
+  buildRunFailed,
+  newBlockState,
+} from "../../src-shared/envelope_builder.mjs";
+import { applyIncomingHooks } from "./bridgeHooks.mjs";
+import { preprocessAttachmentsToText } from "./preprocessAttachments.mjs";
+import { BoundedSet } from "./boundedMap.mjs";
+import { resolveCosImageRefs } from "../runtime/_shared/cosTextRefs.mjs";
+import { signGetCosObject } from "./cosUploadClient.mjs";
+
+// Streaming-first policy: size:1 means every envelope (especially
+// content_block.delta) posts immediately, so the App SSE stream receives
+// chunks as the runtime produces them rather than in 8-envelope batches.
+// Tests/picoclaw replay can override via flushPolicy if they want fewer POSTs.
+const DEFAULT_FLUSH_POLICY = Object.freeze({ size: 1, timeMs: 0 });
+const STREAM_DEBUG = process.env.BUBBO_DEBUG_STREAM === "1";
+
+/**
+ * createEnvelopeFlusher — micro-batched fire-and-forget envelope publisher.
+ *
+ * Solves Bug #2-streaming: previous implementation accumulated all envelopes
+ * into a single array and POSTed once per turn → "fake streaming" experience.
+ * The flusher enqueues envelopes and flushes when either size threshold or
+ * time threshold fires (whichever comes first). flush calls `postEvents`
+ * fire-and-forget; `waitAll()` lets the caller await all in-flight POSTs
+ * before declaring the turn complete.
+ *
+ * Retry: a single failed `postEvents` call pushes its snapshot into
+ * `retryQueue`; the next flush drains retryQueue before mainQueue so order
+ * is preserved (modulo server-side ord field which is authoritative).
+ *
+ * @param {{
+ *   postEvents: (envelopes: any[]) => Promise<any>,
+ *   flushPolicy?: { size?: number, timeMs?: number },
+ *   log?: { info?: Function, warn?: Function, error?: Function },
+ * }} opts
+ */
+export function createEnvelopeFlusher({ postEvents, flushPolicy, log }) {
+  if (typeof postEvents !== "function") {
+    throw new Error("createEnvelopeFlusher: postEvents required");
+  }
+  const policy = {
+    size: flushPolicy?.size ?? DEFAULT_FLUSH_POLICY.size,
+    timeMs: flushPolicy?.timeMs ?? DEFAULT_FLUSH_POLICY.timeMs,
+  };
+
+  const mainQueue = [];
+  const retryQueue = [];
+  const inFlight = new Set();
+  let timer = null;
+  let retriedOnce = false; // 整 turn 最多 retry 1 次（per design D4.5）
+  // postChain 是串行 POST tail —— 每次 flushNow 把自己 chain 到上一个 POST
+  // 的 .finally 后面再发，确保 server 看到的 envelope 顺序与 enqueue 顺序一致。
+  // 这是为了配合 size:1 的真流式：之前 fire-and-forget 的并发 POST 会被 JS
+  // event loop 乱序投递到 relay，导致 content_block.delta 早于
+  // content_block.started 到达 → server §9.4 orphan-delta 400 → run.completed
+  // 也跟着乱序，App 端 reducer 的 cursor 单调过滤把整轮事件全跳过 → 永远 loading。
+  let postChain = Promise.resolve();
+
+  function debugLog(msg, extra) {
+    if (STREAM_DEBUG && log?.info) {
+      log.info(msg, "stream.flush", { ts: Date.now(), ...extra });
+    }
+  }
+
+  function startTimerIfNeeded() {
+    if (timer != null) return;
+    if (mainQueue.length === 0 && retryQueue.length === 0) return;
+    timer = setTimeout(() => {
+      timer = null;
+      flushNow();
+    }, policy.timeMs);
+    // Don't keep event loop alive solely for this timer.
+    if (typeof timer?.unref === "function") timer.unref();
+  }
+
+  function clearTimer() {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  /**
+   * splitAndRetry — 413 binary split recursive retry.
+   * When a batch returns 413 (stream.payload_too_large), split into halves and
+   * retry each independently. Stops at size=1 and logs stream.envelope_too_large.
+   * Does NOT consume the turn-level retriedOnce quota.
+   *
+   * @param {any[]} envelopes
+   * @returns {Promise<void>}
+   */
+  async function splitAndRetry(envelopes) {
+    if (envelopes.length === 0) return;
+
+    if (envelopes.length === 1) {
+      // Terminal: single envelope still 413 → log error, skip it
+      const env = envelopes[0];
+      log?.error?.("stream.envelope_too_large", "single envelope exceeds relay size limit — skipping", {
+        event: "stream.envelope_too_large",
+        envelope_type: env?.type,
+        envelope_index: env?.index,
+      });
+      return;
+    }
+
+    // Split into two halves
+    const mid = Math.floor(envelopes.length / 2);
+    const first = envelopes.slice(0, mid);
+    const second = envelopes.slice(mid);
+
+    for (const half of [first, second]) {
+      try {
+        await postEvents(half);
+      } catch (err) {
+        if (err?.code === "stream.payload_too_large") {
+          // Recurse
+          await splitAndRetry(half);
+        } else {
+          // Non-413 error: re-throw or handle as regular failure
+          log?.warn?.("stream.post_failed", "postEvents failed during split retry", {
+            err: err?.message || String(err),
+            batch_size: half.length,
+          });
+          // Don't consume retriedOnce here; treat like a transient failure
+          if (!retriedOnce) {
+            retryQueue.unshift(...half);
+            retriedOnce = true;
+            startTimerIfNeeded();
+          } else {
+            log?.error?.("stream.post_failed.final", "postEvents failed in split retry — giving up", {
+              err: err?.message || String(err),
+              batch_size: half.length,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  function flushNow() {
+    clearTimer();
+    const fromRetry = retryQueue.splice(0, retryQueue.length);
+    const fromMain = mainQueue.splice(0, mainQueue.length);
+    const snapshot = [...fromRetry, ...fromMain];
+    if (snapshot.length === 0) return;
+
+    debugLog("flushing snapshot", { size: snapshot.length });
+    // 串行化：等前一个 POST 完结（成功 / 失败都行）再发本次 POST，避免顺序乱。
+    const p = postChain
+      .catch(() => {}) // 上一次失败不阻断后续
+      .then(() => postEvents(snapshot))
+      .catch(async (err) => {
+        if (err?.code === "stream.payload_too_large") {
+          // 413: binary split and retry — does NOT consume retriedOnce quota
+          debugLog("413 split retry", { size: snapshot.length });
+          await splitAndRetry(snapshot);
+          return;
+        }
+        log?.warn?.("stream.post_failed", "postEvents failed in flush", {
+          err: err?.message || String(err),
+          batch_size: snapshot.length,
+        });
+        // Retry once per turn: push the failed snapshot back into retryQueue
+        // so the next flush drains it before any new envelope.
+        if (!retriedOnce) {
+          retryQueue.unshift(...snapshot);
+          retriedOnce = true;
+          startTimerIfNeeded();
+        } else {
+          log?.error?.("stream.post_failed.final", "postEvents failed twice — giving up", {
+            err: err?.message || String(err),
+            batch_size: snapshot.length,
+          });
+        }
+      })
+      .finally(() => inFlight.delete(p));
+    inFlight.add(p);
+    postChain = p; // 下一次 flush 会等这次 settle 再发
+  }
+
+  function enqueue(envelopes) {
+    if (!envelopes || envelopes.length === 0) return;
+    for (const env of envelopes) mainQueue.push(env);
+    if (mainQueue.length + retryQueue.length >= policy.size) {
+      flushNow();
+    } else {
+      startTimerIfNeeded();
+    }
+  }
+
+  async function waitAll() {
+    // Keep flushing until both queues are drained AND no in-flight POSTs.
+    // A retry can push envelopes back into retryQueue after the first flush,
+    // so a single flush+await pair is insufficient. The loop bounds itself
+    // because retry is capped at once per turn (retriedOnce gate).
+    while (mainQueue.length > 0 || retryQueue.length > 0 || inFlight.size > 0) {
+      if (mainQueue.length > 0 || retryQueue.length > 0) {
+        flushNow();
+      }
+      if (inFlight.size > 0) {
+        await Promise.allSettled([...inFlight]);
+      }
+    }
+  }
+
+  return { enqueue, flushNow, waitAll, _policy: policy };
+}
+
+/**
+ * @param {{
+ *   relayUrl: string,
+ *   bridgeToken: string,
+ *   log: { info, warn, error },
+ *   producerFactory?: (opts: { relayUrl, bridgeToken, threadId }) => { postEvents },
+ *   openclawInvoke?: (opts: { input, onChunk }) => Promise<void>,
+ *   flushPolicy?: { size?: number, timeMs?: number },
+ *   gatewayId?: string,           // 提供后启用正文 agentlink-cos:// 图片引用解析（sign-get）
+ *   _signGetImpl?: Function,      // 测试注入：(cosObjectKey) => Promise<{getUrl}>
+ * }} opts
+ * @returns {(request: any, ctx: any) => Promise<boolean>}
+ */
+export function createUnifiedDispatchHandler({
+  relayUrl,
+  bridgeToken,
+  log,
+  producerFactory,
+  openclawInvoke,
+  flushPolicy,
+  gatewayId,
+  _signGetImpl,
+}) {
+  // Default producer factory uses createHookedUnifiedProducer so outgoing hooks
+  // (e.g. bridge-auto-tunnel URL rewriting) apply to every postEvents call.
+  const mkProducer = producerFactory ?? (({ relayUrl: ru, bridgeToken: bt, threadId }) =>
+    createHookedUnifiedProducer({ relayUrl: ru, bridgeToken: bt, threadId, logger: log })
+  );
+
+  // In-memory dedup set — process-scoped, cleared on restart.
+  // audit 修复：长驻 bridge 上无界 Set 必膨胀，改 LRU+TTL（幂等窗口 24h 足够：
+  // relay 重投递只发生在分钟级，超窗重放按新 run 处理也无害——envelope 落库幂等）。
+  const dispatchedRunIds = new BoundedSet({ maxSize: 50_000, ttlMs: 24 * 60 * 60 * 1000 });
+
+  return async function handleUnifiedDispatch(request, _ctx) {
+    const kind = request?.request?.__kind;
+    if (kind !== "agent.run.dispatch") {
+      return false; // not a dispatch request — let caller handle it
+    }
+
+    const { thread_id, run_id, input, blocks = [], workspace_path } = request.request ?? {};
+
+    // Idempotency check
+    if (dispatchedRunIds.has(run_id)) {
+      log.warn("dispatch.duplicate", "run already dispatched, skipping", { run_id });
+      return true;
+    }
+    dispatchedRunIds.add(run_id);
+
+    const producer = mkProducer({ relayUrl, bridgeToken, threadId: thread_id });
+    const flusher = createEnvelopeFlusher({
+      postEvents: (envs) => producer.postEvents(envs),
+      flushPolicy,
+      log,
+    });
+
+    // Incoming hook: intercept chat-side commands (e.g. /tunnel ls) before runtime dispatch.
+    // 失败 / 抛错由 applyIncomingHooks 自己吞 + 兜底走 pass-through，这里只看返回值。
+    let hookResult;
+    try {
+      hookResult = await applyIncomingHooks({ thread_id, run_id, input }, { logger: log });
+    } catch (err) {
+      // 防御：applyIncomingHooks 本身 throw（理论上不会）→ 兜底 pass-through
+      log.warn("dispatch.incoming_hook_err", "incoming hooks threw, falling back to runtime", {
+        run_id, err: String(err?.message || err),
+      });
+      hookResult = { intercept: false };
+    }
+    if (hookResult && hookResult.intercept === true) {
+      try {
+        if (Array.isArray(hookResult.replies) && hookResult.replies.length > 0) {
+          // Intercept replies typically a small fixed batch — flush via flusher
+          // for consistent semantics + retry / waitAll guarantees.
+          flusher.enqueue(hookResult.replies);
+          await flusher.waitAll();
+        }
+      } catch (err) {
+        log.error("dispatch.intercept_post_failed", "failed to post intercept replies", {
+          run_id, err: String(err?.message || err),
+        });
+      }
+      return true; // 请求已消费，跳过 runtime 派发
+    }
+
+    try {
+      // Task 2.5: 预处理 text-like mime attachment，替换为 text block；
+      // PDF / image / 其他 block 原样保留，由各 runtime 自行处理。
+      let processedBlocks = await preprocessAttachmentsToText(blocks, { log });
+
+      // P0「读取笔记内图片失败」：正文中的 agentlink-cos:// 图片引用
+      // → sign-get 换临时 URL → 合成 image block，正文替换为占位文案。
+      let effectiveInput = input;
+      const signGet = _signGetImpl ?? (gatewayId
+        ? (key) => signGetCosObject({ baseUrl: relayUrl, gatewayId, token: bridgeToken }, key)
+        : null);
+      if (signGet) {
+        const resolvedRefs = await resolveCosImageRefs({
+          input: effectiveInput, blocks: processedBlocks, signGet, log,
+        });
+        if (resolvedRefs.resolved > 0) {
+          log.info("dispatch.cos_refs", "resolved inline cos image refs", {
+            run_id, resolved: resolvedRefs.resolved,
+          });
+        }
+        effectiveInput = resolvedRefs.input;
+        processedBlocks = resolvedRefs.blocks;
+      }
+
+      let blockState = newBlockState();
+      let runEndedFromRuntime = false;
+      // run.paused（HITL interrupt，如 /resume picker）意味着 run 的生命周期
+      // 移交给了异步 resume listener（收到 run.resumed 后才补 block.completed
+      // + run.completed）。此时绝不能合成收尾——paused 后 21ms 跟一条
+      // run.completed 会让 App 端「run 终态移除 interrupt 卡」的兜底立即删掉
+      // 刚渲染的选择卡（P0 /resume 无反应）。
+      let runPausedFromRuntime = false;
+
+      if (typeof openclawInvoke === "function") {
+        // Injected (test mode or picoclaw ws integration)
+        // thread_id 透传给 runtime adapter，让需要"按 thread 维护原生 session
+        // 续接"的 runtime（如 claude --resume <sid>）可以做 mapping。
+        await openclawInvoke({
+          thread_id,
+          run_id,
+          input: effectiveInput,
+          blocks: processedBlocks,
+          workspace_path: workspace_path || null,
+          // relay 信封顶层 sessionKey（App 侧 abort RPC 用它定位要杀的 run）
+          session_key: request.sessionKey || null,
+          onChunk: async (chunk) => {
+            const { envelopes, blockState: next } = translateOpenClawChunkToEnvelope(
+              chunk,
+              run_id,
+              blockState,
+            );
+            blockState = next;
+            for (const env of envelopes) {
+              if (env.type === "run.completed" || env.type === "run.failed") {
+                runEndedFromRuntime = true;
+              }
+              // 只认本 run 的 paused/resumed（hermes __envelopes 透传的
+              // child-run 信封带不同 run_id，不影响父 run 的收尾判定）。
+              if (env.run_id === run_id) {
+                if (env.type === "run.paused") runPausedFromRuntime = true;
+                if (env.type === "run.resumed") runPausedFromRuntime = false;
+              }
+            }
+            flusher.enqueue(envelopes);
+          },
+        });
+      }
+
+      // If runtime didn't emit response.completed itself, feed a synthetic
+      // one through translate. This both (a) emits content_block.completed
+      // for any open text/thinking blocks and (b) emits run.completed —
+      // matching the protocol contract that all blocks must close before
+      // run.completed.
+      //
+      // Exception: run paused awaiting an interrupt → the async resume
+      // listener owns the run's terminal envelopes; skip synthesis entirely.
+      if (runPausedFromRuntime && !runEndedFromRuntime) {
+        log.info?.("dispatch.run.paused", "run paused awaiting interrupt; skipping synthetic completion", {
+          run_id,
+        });
+      } else if (!runEndedFromRuntime) {
+        const { envelopes } = translateOpenClawChunkToEnvelope(
+          { event: "response.completed" },
+          run_id,
+          blockState,
+        );
+        // If no blocks were ever opened (e.g. zero chunks), translate returns
+        // only run.completed; if blocks were open, it returns [block_completed*, run.completed].
+        if (envelopes.length === 0) {
+          // Safety net: no blocks, no synthetic event produced (shouldn't
+          // happen with the current translate impl, but guard anyway).
+          flusher.enqueue([buildRunCompleted(run_id, "end_turn")]);
+        } else {
+          flusher.enqueue(envelopes);
+        }
+      }
+
+      // Drain queue + await all in-flight POSTs before returning.
+      await flusher.waitAll();
+    } catch (err) {
+      log.error("dispatch.invoke.error", "openclaw invocation failed", {
+        run_id,
+        err: String(err?.message || err),
+      });
+      // CRITICAL: await all in-flight envelopes BEFORE posting run.failed to
+      // avoid out-of-order arrival (envelope after run.failed).
+      try {
+        await flusher.waitAll();
+      } catch (waitErr) {
+        log.warn("dispatch.flush.wait_err", "waitAll before run.failed errored (continuing)", {
+          run_id, err: String(waitErr?.message || waitErr),
+        });
+      }
+      try {
+        await producer.postEvents([
+          buildRunFailed(run_id, "runtime.crash", String(err?.message || err)),
+        ]);
+      } catch (postErr) {
+        log.error("dispatch.post_failed.error", "failed to post run.failed envelope", {
+          run_id,
+          err: String(postErr?.message || postErr),
+        });
+      }
+    }
+
+    return true;
+  };
+}

package/src-ext/core/usageReporter.mjs

@@ -0,0 +1,207 @@
+// usageReporter — 三个 runtime 共用的"用量快照累加器 + 节流发布器"。
+//
+// 设计原则(第一性原理):
+//   - 所有字段都是真数据 — runtime 能拿到什么就填什么,拿不到就 null
+//   - 节流:同一会话内 usage_report 连续触发时只发一次(默认 800ms debounce),
+//     带 force 标志的(rate_limit / TUI probe)立即发
+//   - 调用方只管 update/patch,节流/序列化/发送都在本模块
+//
+// 与旧版本差异:
+//   - 不再持有 sessionId / appendEvent,改持有 publishEvent(event) 单一回调
+//   - publishEvent 由调用方注入,通常是 relayWorker 的 publishEvent;但
+//     usage 是"被动累积 + 周期 flush",没有 requestId 上下文,所以调用方需要
+//     在每次 flush 前给一个 fallback requestId(例如 latest in-flight request)
+//   - 发出去的 native event:
+//       { event: "usage_report", payload: <UsageSnapshot 同 schema> }
+//     服务端 adapter 看到 event="usage_report" 时透传到 unified usage.report。
+//
+// 字段:
+//   tokens.{input,cached_input,output,reasoning_output,total}
+//   context.window
+//   rate_limits.{primary,secondary,plan_type,reached_type}
+//   cost.{total_usd, turns, duration_ms}
+//   rate_limit_alert.{retry_after_ms, message, triggered_at}
+
+const SCHEMA_VERSION = 1;
+const DEFAULT_DEBOUNCE_MS = 800;
+
+/**
+ * @param {{
+ *   publishEvent: (event:object)=>Promise<any>,
+ *   runtime: "claude" | "codex" | "hermes",
+ *   log: any,
+ *   debounceMs?: number,
+ * }} opts
+ */
+export function createUsageReporter({ publishEvent, runtime, log, debounceMs = DEFAULT_DEBOUNCE_MS }) {
+  if (typeof publishEvent !== "function") {
+    throw new Error("createUsageReporter: publishEvent function required");
+  }
+  if (
+    runtime !== "claude" &&
+    runtime !== "codex" &&
+    runtime !== "hermes" &&
+    runtime !== "picoclaw"
+  ) {
+    throw new Error(`createUsageReporter: bad runtime ${runtime}`);
+  }
+  const rLog = log ? log.child({ comp: "usage" }) : null;
+
+  const state = {
+    tokens: { input: 0, cached_input: 0, output: 0, reasoning_output: 0, total: 0 },
+    context: { window: null },
+    rate_limits: null,
+    cost: { total_usd: 0, turns: 0, duration_ms: 0 },
+    rate_limit_alert: null,
+    account: null,
+    hasTokens: false,
+    hasContext: false,
+    hasCost: false,
+  };
+
+  let debounceTimer = null;
+  let pendingFlush = false;
+  let disposed = false;
+
+  function addTokensIncrement(delta) {
+    if (!delta || typeof delta !== "object") return;
+    const add = (k) => { if (Number.isFinite(delta[k])) state.tokens[k] += delta[k]; };
+    add("input"); add("cached_input"); add("output"); add("reasoning_output");
+    if (Number.isFinite(delta.total)) {
+      state.tokens.total += delta.total;
+    } else {
+      state.tokens.total += (delta.input || 0) + (delta.output || 0);
+    }
+    state.hasTokens = true;
+  }
+
+  function setTokensAbsolute(snap) {
+    if (!snap || typeof snap !== "object") return;
+    for (const k of ["input", "cached_input", "output", "reasoning_output", "total"]) {
+      if (Number.isFinite(snap[k])) state.tokens[k] = snap[k];
+    }
+    state.hasTokens = true;
+  }
+
+  function setContextWindow(n) {
+    if (Number.isFinite(n) && n > 0) {
+      state.context.window = n;
+      state.hasContext = true;
+    }
+  }
+
+  function setRateLimits(rl) {
+    if (rl === null) { state.rate_limits = null; return; }
+    if (!rl || typeof rl !== "object") return;
+    state.rate_limits = {
+      primary:   normalizeWindow(rl.primary),
+      secondary: normalizeWindow(rl.secondary),
+      plan_type: typeof rl.plan_type === "string" ? rl.plan_type : null,
+      reached_type: typeof rl.reached_type === "string" ? rl.reached_type : null,
+    };
+  }
+
+  function normalizeWindow(w) {
+    if (!w || typeof w !== "object") return null;
+    const out = {};
+    if (Number.isFinite(w.used_percent)) out.used_percent = w.used_percent;
+    else return null;
+    if (Number.isFinite(w.window_minutes)) out.window_minutes = Math.trunc(w.window_minutes);
+    if (Number.isFinite(w.resets_at)) out.resets_at = Math.trunc(w.resets_at);
+    return out;
+  }
+
+  function addCost({ total_usd, turns, duration_ms }) {
+    if (Number.isFinite(total_usd)) state.cost.total_usd += total_usd;
+    if (Number.isFinite(turns)) state.cost.turns += turns;
+    if (Number.isFinite(duration_ms)) state.cost.duration_ms += duration_ms;
+    state.hasCost = true;
+  }
+
+  function setRateLimitAlert({ retry_after_ms, message }) {
+    state.rate_limit_alert = {
+      retry_after_ms: Number.isFinite(retry_after_ms) ? Math.trunc(retry_after_ms) : 0,
+      message: typeof message === "string" ? message.slice(0, 400) : "",
+      triggered_at: Math.floor(Date.now() / 1000),
+    };
+  }
+
+  function clearRateLimitAlert() { state.rate_limit_alert = null; }
+
+  function setAccount(email) {
+    if (typeof email === "string" && email.trim()) {
+      state.account = email.trim().slice(0, 200);
+    } else if (email === null) {
+      state.account = null;
+    }
+  }
+
+  function buildPayload() {
+    return {
+      schema_version: SCHEMA_VERSION,
+      runtime,
+      collected_at: Math.floor(Date.now() / 1000),
+      tokens: state.hasTokens ? { ...state.tokens } : null,
+      context: state.hasContext ? { window: state.context.window } : null,
+      rate_limits: state.rate_limits ? { ...state.rate_limits } : null,
+      cost: state.hasCost ? { ...state.cost } : null,
+      rate_limit_alert: state.rate_limit_alert,
+      account: state.account,
+    };
+  }
+
+  async function publishNow(reason) {
+    if (disposed) return;
+    if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; }
+    pendingFlush = false;
+    const payload = buildPayload();
+    try {
+      await publishEvent({ event: "usage_report", payload });
+      rLog?.info("usage.publish", "usage report published", {
+        reason,
+        has_tokens: !!payload.tokens,
+        has_context: !!payload.context,
+        context_window: payload.context?.window ?? 0,
+        has_rate_limits: !!payload.rate_limits,
+        has_cost: !!payload.cost,
+        account: payload.account || null,
+        alert: !!payload.rate_limit_alert,
+      });
+    } catch (err) {
+      rLog?.warn("usage.publish.failed", "publish failed", {
+        err: err?.message || String(err),
+      });
+    }
+  }
+
+  function schedulePublish(reason) {
+    if (disposed) return;
+    pendingFlush = true;
+    if (debounceTimer) return;
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      if (pendingFlush) void publishNow(reason || "debounce");
+    }, debounceMs);
+    debounceTimer.unref?.();
+  }
+
+  function dispose() {
+    disposed = true;
+    if (debounceTimer) { clearTimeout(debounceTimer); debounceTimer = null; }
+  }
+
+  return {
+    addTokensIncrement,
+    setTokensAbsolute,
+    setContextWindow,
+    setRateLimits,
+    addCost,
+    setRateLimitAlert,
+    clearRateLimitAlert,
+    setAccount,
+    publishNow,
+    schedulePublish,
+    dispose,
+    _snapshot: () => buildPayload(),
+  };
+}