chainlesschain 0.162.177 → 0.162.178

package/src/lib/background-interaction-resolver.js

@@ -1,71 +1,416 @@
 /**
- * background-interaction-resolver — 监听 agent 子进程发来的交互请求，
- * 转发给后台会话 transport 并通过 pendingInteractions 追踪回复。
+ * Background turn interaction protocol.
  *
- * 当 agent 调用 onPrompt/onApprove 等需要用户交互的方法时，子进程通过 IPC
- * 发送 { type: "interaction-request", intId, requestType, prompt, options } 消息。
- * 本模块监听这些消息，加入本地 pending map，并广播给所有 attach 客户端。
+ * A background worker starts the headless turn with a Node IPC channel. The
+ * turn child uses `createBackgroundInteractionClient()` to suspend the active
+ * tool call until the worker resolves it. The worker uses
+ * `attachInteractionRequestHandler()` to validate the request binding, route
+ * it to attach/Desktop/IDE, and return the answer to the same child process.
+ *
+ * Every response is bound to the original background session, agent, turn,
+ * tool call, and monotonically increasing sequence. A stale or cross-session
+ * response is ignored by the child and can never resolve another request.
  */
 
-const INTERACTION_TIMEOUT_MS = 5 * 60 * 1000; // 5 分钟超时
+import { randomUUID } from "node:crypto";
+
+export const BACKGROUND_INTERACTION_PROTOCOL_VERSION = 1;
+export const DEFAULT_BACKGROUND_INTERACTION_TIMEOUT_MS = 60_000;
+
+const MAX_COMPLETED_RESPONSES = 256;
+
+function protocolError(message, code = "INTERACTION_PROTOCOL_ERROR") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function asNullableString(value) {
+  if (value === undefined || value === null || value === "") return null;
+  return String(value);
+}
+
+function normalizeBinding(binding = {}) {
+  return {
+    backgroundAgentId: asNullableString(binding.backgroundAgentId),
+    sessionId: asNullableString(binding.sessionId),
+    turnId: asNullableString(binding.turnId),
+    toolUseId: asNullableString(binding.toolUseId),
+    sequence:
+      Number.isSafeInteger(binding.sequence) && binding.sequence > 0
+        ? binding.sequence
+        : null,
+  };
+}
+
+function sameBinding(left, right) {
+  const a = normalizeBinding(left);
+  const b = normalizeBinding(right);
+  return (
+    a.backgroundAgentId === b.backgroundAgentId &&
+    a.sessionId === b.sessionId &&
+    a.turnId === b.turnId &&
+    a.toolUseId === b.toolUseId &&
+    a.sequence === b.sequence
+  );
+}
+
+function validRequest(message) {
+  return (
+    message &&
+    message.type === "interaction-request" &&
+    message.protocolVersion === BACKGROUND_INTERACTION_PROTOCOL_VERSION &&
+    typeof message.requestId === "string" &&
+    message.requestId.length > 0 &&
+    message.requestId.length <= 256 &&
+    message.payload &&
+    typeof message.payload === "object" &&
+    normalizeBinding(message.binding).sequence !== null
+  );
+}
+
+function sendIpc(target, message, onError = () => {}) {
+  if (!target || typeof target.send !== "function" || target.connected === false)
+    return false;
+  try {
+    target.send(message, (error) => {
+      if (error) onError(error);
+    });
+    return true;
+  } catch (error) {
+    onError(error);
+    return false;
+  }
+}
 
 /**
- * 挂载交互请求监听到 agent 子进程。
+ * Create the turn-child side of the interaction channel.
  *
- * @param {import('node:child_process').ChildProcess} child - agent 子进程实例
- * @param {Map<string, { resolve: Function, reject: Function, timer: NodeJS.Timeout }>} pendingInteractions - 待处理交互映射
- * @param {Function} broadcast - 广播消息给所有 attach 客户端的函数
- * @returns {Function} 卸载函数，调用后停止监听
+ * @param {object} [options]
+ * @param {NodeJS.Process|object} [options.processLike]
+ * @param {string} [options.backgroundAgentId]
+ * @param {string|null} [options.sessionId]
+ * @param {string|null} [options.turnId]
+ * @param {number} [options.defaultTimeoutMs]
+ * @param {()=>string} [options.idFactory]
+ */
+export function createBackgroundInteractionClient(options = {}) {
+  const processLike = options.processLike || process;
+  const backgroundAgentId =
+    options.backgroundAgentId ?? processLike?.env?.CC_BACKGROUND_AGENT_ID;
+  const sessionId = options.sessionId ?? null;
+  const turnId = options.turnId ?? null;
+  const defaultTimeoutMs =
+    Number.isFinite(options.defaultTimeoutMs) && options.defaultTimeoutMs > 0
+      ? options.defaultTimeoutMs
+      : DEFAULT_BACKGROUND_INTERACTION_TIMEOUT_MS;
+  const idFactory = options.idFactory || randomUUID;
+  const enabled =
+    typeof backgroundAgentId === "string" &&
+    backgroundAgentId.trim() !== "" &&
+    typeof processLike?.send === "function";
+  const pending = new Map();
+  let sequence = 0;
+  let closed = false;
+
+  const removeMessageListener = () => {
+    if (typeof processLike?.off === "function") {
+      processLike.off("message", onMessage);
+    } else if (typeof processLike?.removeListener === "function") {
+      processLike.removeListener("message", onMessage);
+    }
+  };
+
+  function settle(entry, action, value) {
+    if (!entry || entry.settled) return;
+    entry.settled = true;
+    clearTimeout(entry.timer);
+    pending.delete(entry.requestId);
+    action(value);
+  }
+
+  function onMessage(message) {
+    if (
+      !message ||
+      message.type !== "interaction-response" ||
+      message.protocolVersion !== BACKGROUND_INTERACTION_PROTOCOL_VERSION
+    ) {
+      return;
+    }
+    const entry = pending.get(message.requestId);
+    if (!entry || !sameBinding(entry.binding, message.binding)) return;
+
+    if (message.status === "resolved") {
+      settle(entry, entry.resolve, message.answer);
+      return;
+    }
+    const error = protocolError(
+      message.error?.message || "Background interaction was rejected",
+      message.error?.code || "INTERACTION_REJECTED",
+    );
+    settle(entry, entry.reject, error);
+  }
+
+  if (enabled && typeof processLike.on === "function") {
+    processLike.on("message", onMessage);
+  }
+
+  return {
+    enabled,
+    pendingCount() {
+      return pending.size;
+    },
+    async request(payload = {}) {
+      if (!enabled || closed) {
+        throw protocolError(
+          "Background interaction IPC channel is unavailable",
+          "USER_NOT_REACHABLE",
+        );
+      }
+
+      sequence += 1;
+      const requestId = `${backgroundAgentId}:${idFactory()}`;
+      const binding = normalizeBinding({
+        backgroundAgentId,
+        sessionId: payload.sessionId ?? sessionId,
+        turnId: payload.turnId ?? turnId,
+        toolUseId: payload.toolUseId,
+        sequence,
+      });
+      const timeoutMs =
+        Number.isFinite(payload.timeoutMs) && payload.timeoutMs > 0
+          ? payload.timeoutMs
+          : defaultTimeoutMs;
+
+      return new Promise((resolve, reject) => {
+        const entry = {
+          requestId,
+          binding,
+          resolve,
+          reject,
+          timer: null,
+          settled: false,
+        };
+        entry.timer = setTimeout(() => {
+          const error = protocolError(
+            "User did not respond before the interaction timed out",
+            "USER_TIMEOUT",
+          );
+          sendIpc(processLike, {
+            type: "interaction-cancel",
+            protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
+            requestId,
+            binding,
+            reason: "timeout",
+          });
+          settle(entry, reject, error);
+        }, timeoutMs);
+        entry.timer.unref?.();
+        pending.set(requestId, entry);
+
+        const sent = sendIpc(
+          processLike,
+          {
+            type: "interaction-request",
+            protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
+            requestId,
+            binding,
+            payload: {
+              kind: payload.kind || "question",
+              question: String(payload.question || payload.prompt || ""),
+              options: Array.isArray(payload.options) ? payload.options : null,
+              multiSelect: payload.multiSelect === true,
+              defaultValue: payload.defaultValue,
+              timeoutMs,
+              policyDigest: asNullableString(payload.policyDigest),
+            },
+          },
+          (error) => {
+            settle(
+              entry,
+              reject,
+              protocolError(
+                `Failed to send background interaction: ${error.message}`,
+                "INTERACTION_CHANNEL_ERROR",
+              ),
+            );
+          },
+        );
+        if (!sent) {
+          settle(
+            entry,
+            reject,
+            protocolError(
+              "Background interaction IPC channel is unavailable",
+              "USER_NOT_REACHABLE",
+            ),
+          );
+        }
+      });
+    },
+    close(reason = "Background interaction channel closed") {
+      if (closed) return;
+      closed = true;
+      removeMessageListener();
+      for (const entry of [...pending.values()]) {
+        settle(
+          entry,
+          entry.reject,
+          protocolError(reason, "INTERACTION_CHANNEL_CLOSED"),
+        );
+      }
+    },
+  };
+}
+
+/**
+ * Attach the worker side of the interaction channel to one turn child.
+ *
+ * @param {import("node:child_process").ChildProcess|object} child
+ * @param {(payload:object, request:object, context:{signal:AbortSignal})=>Promise<any>|any} resolveRequest
+ * @param {object} [options]
+ * @param {string|null} [options.backgroundAgentId]
+ * @param {string|null} [options.sessionId]
+ * @returns {()=>void} detach function
  */
 export function attachInteractionRequestHandler(
   child,
-  pendingInteractions,
-  broadcast,
+  resolveRequest,
+  options = {},
 ) {
-  if (!child) {
-    return () => {};
-  }
+  if (!child || typeof child.on !== "function") return () => {};
 
-  const handler = (message) => {
-    if (!message || typeof message !== "object") return;
-    if (message.type !== "interaction-request") return;
-
-    const { intId, requestType, prompt, options = {} } = message;
-    if (!intId) return;
-
-    // 加入 pending 映射，设置超时
-    const timer = setTimeout(() => {
-      const entry = pendingInteractions.get(intId);
-      if (!entry) return;
-      pendingInteractions.delete(intId);
-      // 超时返回默认值：confirm 返回 false，其他返回 null
-      const defaultAnswer = requestType === "confirm" ? false : null;
-      entry.resolve(defaultAnswer);
-      broadcast?.({
-        type: "interaction-timeout",
-        intId,
-      });
-    }, INTERACTION_TIMEOUT_MS);
-    // 不保持事件循环存活
-    timer.unref?.();
-
-    // 这里不存 resolve/reject — 调用方 (worker) 已经在 agentAskUser 中存了
-    // 我们只负责广播给 attach 客户端
-    // 但为了超时能触发 worker 的 resolve，需要把 entry 透传？不，worker 自己存 entry
-    // 只需要广播消息即可
-    broadcast?.({
-      type: "interaction_request",
-      intId,
-      requestType,
-      prompt,
-      options,
-    });
+  const inflight = new Map();
+  const completed = new Map();
+  let detached = false;
+
+  const rememberCompleted = (requestId, response) => {
+    completed.set(requestId, response);
+    if (completed.size > MAX_COMPLETED_RESPONSES) {
+      completed.delete(completed.keys().next().value);
+    }
+  };
+
+  const sendResponse = (response) => {
+    if (!detached) sendIpc(child, response);
   };
 
-  child.on("message", handler);
+  const rejectRequest = (message, code, detail) => {
+    const response = {
+      type: "interaction-response",
+      protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
+      requestId:
+        typeof message?.requestId === "string" ? message.requestId : "",
+      binding: normalizeBinding(message?.binding),
+      status: "rejected",
+      error: { code, message: detail },
+    };
+    if (response.requestId) rememberCompleted(response.requestId, response);
+    sendResponse(response);
+  };
+
+  const onMessage = (message) => {
+    if (
+      message?.type === "interaction-cancel" &&
+      message.protocolVersion === BACKGROUND_INTERACTION_PROTOCOL_VERSION
+    ) {
+      const active = inflight.get(message.requestId);
+      if (active && sameBinding(active.binding, message.binding)) {
+        inflight.delete(message.requestId);
+        active.controller.abort(message.reason || "cancelled");
+      }
+      return;
+    }
+    if (message?.type !== "interaction-request") return;
+    if (!validRequest(message)) {
+      rejectRequest(
+        message,
+        "INVALID_INTERACTION_REQUEST",
+        "Malformed background interaction request",
+      );
+      return;
+    }
+
+    const binding = normalizeBinding(message.binding);
+    const expectedAgentId = asNullableString(options.backgroundAgentId);
+    const expectedSessionId = asNullableString(options.sessionId);
+    if (
+      (expectedAgentId &&
+        binding.backgroundAgentId !== expectedAgentId) ||
+      (expectedSessionId && binding.sessionId !== expectedSessionId)
+    ) {
+      rejectRequest(
+        message,
+        "INTERACTION_BINDING_MISMATCH",
+        "Background interaction does not belong to this worker/session",
+      );
+      return;
+    }
+
+    const prior = completed.get(message.requestId);
+    if (prior) {
+      sendResponse(prior);
+      return;
+    }
+    if (inflight.has(message.requestId)) return;
+
+    const controller = new AbortController();
+    inflight.set(message.requestId, { binding, controller });
+    Promise.resolve()
+      .then(() =>
+        resolveRequest(message.payload, message, {
+          signal: controller.signal,
+        }),
+      )
+      .then(
+        (answer) => {
+          const active = inflight.get(message.requestId);
+          if (!active || controller.signal.aborted) return;
+          inflight.delete(message.requestId);
+          const response = {
+            type: "interaction-response",
+            protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
+            requestId: message.requestId,
+            binding,
+            status: "resolved",
+            answer,
+          };
+          rememberCompleted(message.requestId, response);
+          sendResponse(response);
+        },
+        (error) => {
+          const active = inflight.get(message.requestId);
+          if (!active || controller.signal.aborted) return;
+          inflight.delete(message.requestId);
+          const response = {
+            type: "interaction-response",
+            protocolVersion: BACKGROUND_INTERACTION_PROTOCOL_VERSION,
+            requestId: message.requestId,
+            binding,
+            status: "rejected",
+            error: {
+              code: error?.code || "INTERACTION_REJECTED",
+              message: error?.message || String(error),
+            },
+          };
+          rememberCompleted(message.requestId, response);
+          sendResponse(response);
+        },
+      );
+  };
 
-  // 返回卸载函数
-  return () => {
-    child.off("message", handler);
+  child.on("message", onMessage);
+  const detach = () => {
+    if (detached) return;
+    detached = true;
+    if (typeof child.off === "function") child.off("message", onMessage);
+    else child.removeListener?.("message", onMessage);
+    for (const active of inflight.values()) {
+      active.controller.abort("child detached");
+    }
+    inflight.clear();
   };
+  child.once?.("exit", detach);
+  child.once?.("disconnect", detach);
+  return detach;
 }

package/src/lib/background-session-transport.js

@@ -261,12 +261,13 @@ export function startBackgroundSessionServer(opts) {
         broadcast: (message) => {
           for (const socket of clients) writeMessage(socket, message);
         },
-        broadcastInteractionRequest: (intId, payload) => {
+        broadcastInteractionRequest: (intId, payload, binding = null) => {
           for (const socket of clients)
             writeMessage(socket, {
               type: "interaction_request",
               intId,
               requestId: intId,
+              binding,
               question:
                 payload.question || payload.prompt || "Agent needs your input",
               prompt: payload.question || payload.prompt || "",
@@ -274,6 +275,7 @@ export function startBackgroundSessionServer(opts) {
               options: payload.options || null,
               multiSelect: payload.multiSelect || false,
               defaultValue: payload.defaultValue,
+              policyDigest: payload.policyDigest || null,
             });
         },
         close: () =>

package/src/lib/context-breakdown.js

@@ -84,14 +84,93 @@ export function breakdownSkillSources(skills, estimateTokens) {
     .map((skill) => ({
       source: skill?.source || "skill",
       skill: String(skill?.id || skill?.displayName || "skill"),
-      tokens: est(
-        `## Persona: ${skill?.displayName || skill?.id || "skill"}\n${skill?.body || ""}`,
-      ),
+      tokens: Number.isFinite(skill?.tokens)
+        ? Math.max(0, skill.tokens)
+        : est(
+            `## Persona: ${skill?.displayName || skill?.id || "skill"}\n${skill?.body || ""}`,
+          ),
     }))
     .filter((row) => row.tokens > 0);
   return { sources, total: sources.reduce((sum, row) => sum + row.tokens, 0) };
 }
 
+/** Normalize the content-free two-tier Skill cache snapshot. */
+export function breakdownSkillCache(cache) {
+  const descriptors = cache?.descriptors || {};
+  const bodies = cache?.bodies || {};
+  const savings = cache?.savings || {};
+  return {
+    descriptors: {
+      resident: Number(descriptors.resident) || 0,
+      scans: Number(descriptors.scans) || 0,
+      cacheHits: Number(descriptors.cacheHits) || 0,
+      estimatedTokens: Number(descriptors.estimatedTokens) || 0,
+    },
+    bodies: {
+      resident: Number(bodies.resident) || 0,
+      cacheHits: Number(bodies.cacheHits) || 0,
+      cacheMisses: Number(bodies.cacheMisses) || 0,
+      entries: Array.isArray(bodies.entries)
+        ? bodies.entries.map((entry) => ({
+            id: String(entry?.id || "skill"),
+            source: String(entry?.source || "skill"),
+            estimatedTokens: Number(entry?.estimatedTokens) || 0,
+            loads: Number(entry?.loads) || 0,
+            cacheHits: Number(entry?.cacheHits) || 0,
+            loadedBecause: Array.isArray(entry?.loadedBecause)
+              ? entry.loadedBecause.map(String)
+              : [],
+          }))
+        : [],
+    },
+    savings: {
+      lazyFileBytes: Number(savings.lazyFileBytes) || 0,
+      estimatedTokensAvoided: Number(savings.estimatedTokensAvoided) || 0,
+    },
+  };
+}
+
+/** Actionable, content-free suggestions derived from the measured sources. */
+export function buildContextOptimizations({
+  instructions = [],
+  mcpSchemas = [],
+  skillCache = null,
+} = {}) {
+  const suggestions = [];
+  if (skillCache?.savings?.estimatedTokensAvoided > 0) {
+    suggestions.push({
+      kind: "skill_lazy_loading",
+      estimatedTokens: skillCache.savings.estimatedTokensAvoided,
+      message:
+        `${skillCache.descriptors.resident} Skill descriptors stayed discoverable while ` +
+        `${skillCache.savings.estimatedTokensAvoided} estimated body tokens remained lazy.`,
+    });
+  }
+  const largestMcp = [...(mcpSchemas || [])].sort(
+    (a, b) => (b.tokens || 0) - (a.tokens || 0),
+  )[0];
+  if (largestMcp?.tokens > 0) {
+    suggestions.push({
+      kind: "mcp_tool_search",
+      estimatedTokens: largestMcp.tokens,
+      source: largestMcp.tool || largestMcp.source,
+      message: `Consider Tool Search or a narrower MCP allow-list for ${largestMcp.tool || largestMcp.source}.`,
+    });
+  }
+  const largestInstruction = [...(instructions || [])].sort(
+    (a, b) => (b.tokens || 0) - (a.tokens || 0),
+  )[0];
+  if (largestInstruction?.tokens > 0) {
+    suggestions.push({
+      kind: "instruction_scope",
+      estimatedTokens: largestInstruction.tokens,
+      source: largestInstruction.source,
+      message: `Scope or split ${largestInstruction.source} if it is not needed for every turn.`,
+    });
+  }
+  return suggestions.slice(0, 5);
+}
+
 // role bucket key → { label, kind } for the ranked source list.
 const MESSAGE_SOURCE_ROWS = [
   ["system", "system messages", "message"],