chainlesschain 0.162.171 → 0.162.172

package/src/lib/agent-ipc-bus.js

@@ -0,0 +1,331 @@
+/**
+ * Agent IPC Bus — M2: 后台Agent实时交互总线
+ * 对应文档 §2.2
+ *
+ * 解决后台agent运行期间不能提问/confirm/elicit的问题:
+ * - child agent 通过 IPC 发送 interaction_request
+ * - parent 路由给 UI/REPL/headless resolver
+ * - 结果通过 interaction_response 返回child
+ * - 支持超时、取消、默认值
+ */
+
+import { EventEmitter } from "node:events";
+import crypto from "node:crypto";
+
+/**
+ * @typedef {Object} InteractionRequest
+ * @property {string} requestId
+ * @property {string} agentId - child agent id
+ * @property {string} sessionId
+ * @property {string} turnId
+ * @property {'permission_prompt'|'human_input'|'question'|'confirm'|'elicit'|'mcp_elicit'} type
+ * @property {string} prompt
+ * @property {string[]} [choices]
+ * @property {any} [defaultValue]
+ * @property {number} [timeoutMs]
+ * @property {Object} [metadata]
+ */
+
+class AgentIPCBus extends EventEmitter {
+  constructor() {
+    super();
+    /** @type {Map<string, {req: InteractionRequest, resolve: Function, reject: Function, timer?: NodeJS.Timeout}>} */
+    this._pendingRequests = new Map();
+    /** @type {Map<string, Function>} resolvers by agentId */
+    this._agentResolvers = new Map();
+  }
+
+  /**
+   * Register an agent worker's send function so bus can route responses back
+   * @param {string} agentId
+   * @param {(msg: any) => void} sendToWorker
+   */
+  registerAgent(agentId, sendToWorker) {
+    this._agentResolvers.set(agentId, sendToWorker);
+    this.emit("agent:registered", { agentId });
+  }
+
+  unregisterAgent(agentId) {
+    this._agentResolvers.delete(agentId);
+    // Reject all pending for this agent
+    for (const [reqId, entry] of this._pendingRequests.entries()) {
+      if (entry.req.agentId === agentId) {
+        if (entry.timer) clearTimeout(entry.timer);
+        entry.reject(new Error(`Agent ${agentId} disconnected while waiting for response`));
+        this._pendingRequests.delete(reqId);
+      }
+    }
+    this.emit("agent:unregistered", { agentId });
+  }
+
+  /**
+   * Child agent calls this to request human interaction
+   * @param {string} agentId
+   * @param {Partial<InteractionRequest>} req
+   * @returns {Promise<any>}
+   */
+  requestInteraction(agentId, req) {
+    const requestId = crypto.randomUUID();
+    const fullReq = {
+      requestId,
+      agentId,
+      sessionId: req.sessionId,
+      turnId: req.turnId,
+      type: req.type || "question",
+      prompt: req.prompt,
+      choices: req.choices,
+      defaultValue: req.defaultValue,
+      timeoutMs: req.timeoutMs || 300000, // 5min default
+      metadata: req.metadata || {},
+    };
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pendingRequests.delete(requestId);
+        if (fullReq.defaultValue !== undefined) {
+          resolve(fullReq.defaultValue);
+        } else {
+          reject(new Error(`Interaction request ${requestId} timed out after ${fullReq.timeoutMs}ms`));
+        }
+        this.emit("request:timeout", fullReq);
+      }, fullReq.timeoutMs);
+
+      this._pendingRequests.set(requestId, { req: fullReq, resolve, reject, timer });
+      this.emit("request", fullReq);
+    });
+  }
+
+  /**
+   * Parent/UI calls this to respond to a pending request
+   * @param {string} requestId
+   * @param {any} response
+   */
+  respond(requestId, response) {
+    const entry = this._pendingRequests.get(requestId);
+    if (!entry) return false;
+    if (entry.timer) clearTimeout(entry.timer);
+    this._pendingRequests.delete(requestId);
+    entry.resolve(response);
+    this.emit("request:resolved", { requestId, response });
+    return true;
+  }
+
+  /**
+   * Reject/cancel a pending request
+   * @param {string} requestId
+   * @param {Error} [err]
+   */
+  cancel(requestId, err) {
+    const entry = this._pendingRequests.get(requestId);
+    if (!entry) return false;
+    if (entry.timer) clearTimeout(entry.timer);
+    this._pendingRequests.delete(requestId);
+    entry.reject(err || new Error("Interaction cancelled by user"));
+    this.emit("request:cancelled", { requestId });
+    return true;
+  }
+
+  /** Get pending interaction requests for UI */
+  getPendingRequests() {
+    return Array.from(this._pendingRequests.values()).map(e => e.req);
+  }
+
+  /** Number of pending requests */
+  get pendingCount() {
+    return this._pendingRequests.size;
+  }
+
+  /**
+   * Spawn a child agent process with standardized JSON-RPC over stdio protocol
+   * Aligned with Claude Code sub-agent spawn specification
+   * @param {string} command - Agent executable/script path
+   * @param {string[]} args - Command arguments
+   * @param {object} options - Spawn options
+   * @returns {Promise<{process: ChildProcess, agentId: string}>}
+   */
+  async spawnAgentProcess(command, args = [], options = {}) {
+    const { spawn } = await import("node:child_process");
+    const agentId = options.agentId || crypto.randomUUID();
+    const heartbeatMs = options.heartbeatMs || 30000;
+
+    return new Promise((resolve, reject) => {
+      const child = spawn(command, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          CHAINLESSCHAIN_AGENT_ID: agentId,
+          CHAINLESSCHAIN_AGENT_MODE: "subagent",
+          CHAINLESSCHAIN_IPC_PROTOCOL: "jsonrpc-stdio-v1",
+          ...options.env,
+        },
+        ...options.spawnOptions,
+      });
+
+      let buffer = "";
+      let initialized = false;
+      let heartbeatTimer = null;
+
+      // Handle stdout: line-delimited JSON-RPC
+      child.stdout.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || ""; // Keep incomplete line in buffer
+
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const msg = JSON.parse(line);
+            this._handleIncomingMessage(agentId, msg, child);
+            if (msg.method === "initialize" && !initialized) {
+              initialized = true;
+              this.registerAgent(agentId, (outMsg) => {
+                child.stdin.write(JSON.stringify(outMsg) + "\n");
+              });
+              // Send initialize response
+              child.stdin.write(JSON.stringify({
+                jsonrpc: "2.0",
+                id: msg.id,
+                result: {
+                  protocolVersion: "1.0",
+                  agentId,
+                  capabilities: { interaction: true, tools: true },
+                },
+              }) + "\n");
+              // Setup heartbeat
+              heartbeatTimer = setInterval(() => {
+                if (child.exitCode !== null) {
+                  clearInterval(heartbeatTimer);
+                  return;
+                }
+                child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "heartbeat" }) + "\n");
+              }, heartbeatMs);
+              resolve({ process: child, agentId });
+            }
+          } catch (e) {
+            this.emit("protocol:error", { agentId, error: e, raw: line });
+          }
+        }
+      });
+
+      // Handle stderr: pass through to logger
+      child.stderr.on("data", (chunk) => {
+        this.emit("agent:stderr", { agentId, data: chunk.toString("utf8") });
+        if (options.captureStderr !== false) {
+          process.stderr.write(`[agent:${agentId}] ${chunk}`);
+        }
+      });
+
+      child.on("error", (err) => {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        if (!initialized) reject(err);
+        this.emit("agent:error", { agentId, error: err });
+      });
+
+      child.on("exit", (code, signal) => {
+        if (heartbeatTimer) clearInterval(heartbeatTimer);
+        this.unregisterAgent(agentId);
+        this.emit("agent:exit", { agentId, code, signal });
+      });
+
+      // Timeout for initialization
+      setTimeout(() => {
+        if (!initialized) {
+          child.kill();
+          reject(new Error(`Agent ${agentId} initialization timed out`));
+        }
+      }, options.initTimeoutMs || 10000);
+    });
+  }
+
+  /**
+   * Handle incoming JSON-RPC message from child agent
+   * @private
+   */
+  _handleIncomingMessage(agentId, msg, child) {
+    if (!msg.jsonrpc || msg.jsonrpc !== "2.0") {
+      this.emit("protocol:warning", { agentId, msg, reason: "missing jsonrpc version" });
+      return;
+    }
+
+    // Handle requests (method + id)
+    if (msg.method && msg.id) {
+      if (msg.method === "interaction_request") {
+        this.requestInteraction(agentId, msg.params).then((result) => {
+          child.stdin.write(JSON.stringify({
+            jsonrpc: "2.0",
+            id: msg.id,
+            result,
+          }) + "\n");
+        }).catch((err) => {
+          child.stdin.write(JSON.stringify({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: { code: -32000, message: err.message },
+          }) + "\n");
+        });
+      } else if (msg.method === "log") {
+        this.emit("agent:log", { agentId, params: msg.params });
+        // Acknowledge log
+        child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: true }) + "\n");
+      } else {
+        this.emit("agent:request", { agentId, msg });
+      }
+    }
+    // Handle notifications (method, no id)
+    else if (msg.method && !msg.id) {
+      if (msg.method === "heartbeat") {
+        this.emit("agent:heartbeat", { agentId });
+      } else if (msg.method === "progress") {
+        this.emit("agent:progress", { agentId, params: msg.params });
+      } else {
+        this.emit("agent:notification", { agentId, method: msg.method, params: msg.params });
+      }
+    }
+    // Handle responses (id + result/error)
+    else if (msg.id) {
+      this.emit("agent:response", { agentId, msg });
+    }
+  }
+
+  /**
+   * Send a JSON-RPC request to a spawned agent via stdio
+   * @param {string} agentId
+   * @param {string} method
+   * @param {any} params
+   * @param {number} [timeoutMs=30000]
+   * @returns {Promise<any>}
+   */
+  sendRequest(agentId, method, params = {}, timeoutMs = 30000) {
+    const sendToWorker = this._agentResolvers.get(agentId);
+    if (!sendToWorker) {
+      return Promise.reject(new Error(`Agent ${agentId} not registered`));
+    }
+    const id = crypto.randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.removeAllListeners(`response:${id}`);
+        reject(new Error(`Request ${method} to agent ${agentId} timed out`));
+      }, timeoutMs);
+
+      const onResponse = (respMsg) => {
+        if (respMsg.msg.id === id) {
+          clearTimeout(timer);
+          this.off("agent:response", onResponse);
+          if (respMsg.msg.error) {
+            reject(new Error(respMsg.msg.error.message));
+          } else {
+            resolve(respMsg.msg.result);
+          }
+        }
+      };
+      this.on("agent:response", onResponse);
+
+      sendToWorker({ jsonrpc: "2.0", id, method, params });
+    });
+  }
+}
+
+// Singleton
+const ipcBus = new AgentIPCBus();
+export default ipcBus;
+export { AgentIPCBus };

package/src/lib/context-source-ledger.js

@@ -0,0 +1,164 @@
+/**
+ * Context Source Ledger — M4-1: 上下文来源归因系统
+ * 对应文档 §2.5
+ *
+ * 统一追踪每段上下文的来源、工具调用、权限模式、置信度，
+ * 让"AI 为什么此刻知道这件事"完全可追溯
+ */
+
+import crypto from "node:crypto";
+
+/**
+ * @typedef {Object} ContextEntry
+ * @property {string} entryId
+ * @property {string} sessionId
+ * @property {string} turnId
+ * @property {string} sourceType - slash_command|mcp|tool|hook|skill|agent|file|memory|prompt|plugin
+ * @property {string} sourceId - tool name, mcp server name, hook id, etc.
+ * @property {'system'|'developer'|'plugin'|'user'|'agent'} permissionMode
+ * @property {number} confidence - 0-1
+ * @property {string} [summary]
+ * @property {any} [metadata]
+ * @property {number} tokenCount
+ * @property {Date} insertedAt
+ * @property {string[]} tags
+ */
+
+class ContextSourceLedger {
+  constructor() {
+    /** @type {Map<string, ContextEntry>} */
+    this._entries = new Map();
+    /** @type {Map<string, ContextEntry[]>} turnIndex: turnId -> entries */
+    this._byTurn = new Map();
+    /** @type {Map<string, ContextEntry[]>} sessionIndex: sessionId -> entries */
+    this._bySession = new Map();
+  }
+
+  /**
+   * Record a context source entry
+   * @param {Partial<ContextEntry>} entry
+   * @returns {string} entryId
+   */
+  record(entry) {
+    const entryId = entry.entryId || crypto.randomUUID();
+    const full = {
+      entryId,
+      sessionId: entry.sessionId || "unknown",
+      turnId: entry.turnId || "unknown",
+      sourceType: entry.sourceType || "unknown",
+      sourceId: entry.sourceId || "unknown",
+      permissionMode: entry.permissionMode || "agent",
+      confidence: entry.confidence ?? 0.8,
+      summary: entry.summary,
+      metadata: entry.metadata,
+      tokenCount: entry.tokenCount || 0,
+      insertedAt: new Date(),
+      tags: entry.tags || [],
+    };
+
+    this._entries.set(entryId, full);
+
+    // Index by turn
+    if (!this._byTurn.has(full.turnId)) this._byTurn.set(full.turnId, []);
+    this._byTurn.get(full.turnId).push(full);
+
+    // Index by session
+    if (!this._bySession.has(full.sessionId)) this._bySession.set(full.sessionId, []);
+    this._bySession.get(full.sessionId).push(full);
+
+    return entryId;
+  }
+
+  /**
+   * Get all context entries for a given turn
+   * @param {string} turnId
+   * @returns {ContextEntry[]}
+   */
+  getTurnContext(turnId) {
+    return this._byTurn.get(turnId) || [];
+  }
+
+  /**
+   * Get all context entries for a session
+   * @param {string} sessionId
+   * @returns {ContextEntry[]}
+   */
+  getSessionContext(sessionId) {
+    return this._bySession.get(sessionId) || [];
+  }
+
+  /**
+   * Generate context provenance summary for a turn
+   * Shows exactly where each piece of context came from
+   * @param {string} turnId
+   * @returns {Object} provenance report
+   */
+  getTurnProvenance(turnId) {
+    const entries = this.getTurnContext(turnId);
+    const byType = {};
+    const byPermission = {};
+    const bySource = {};
+    let totalTokens = 0;
+    let avgConfidence = 0;
+
+    for (const e of entries) {
+      byType[e.sourceType] = (byType[e.sourceType] || 0) + 1;
+      byPermission[e.permissionMode] = (byPermission[e.permissionMode] || 0) + 1;
+      bySource[e.sourceId] = (bySource[e.sourceId] || 0) + 1;
+      totalTokens += e.tokenCount;
+      avgConfidence += e.confidence;
+    }
+
+    avgConfidence = entries.length > 0 ? avgConfidence / entries.length : 0;
+
+    return {
+      turnId,
+      totalEntries: entries.length,
+      totalTokens,
+      avgConfidence: Math.round(avgConfidence * 100) / 100,
+      byType,
+      byPermission,
+      bySource,
+      entries: entries.map(e => ({
+        sourceType: e.sourceType,
+        sourceId: e.sourceId,
+        permissionMode: e.permissionMode,
+        confidence: e.confidence,
+        tokenCount: e.tokenCount,
+        summary: e.summary,
+        tags: e.tags,
+      })),
+    };
+  }
+
+  /**
+   * Clear entries for a session
+   * @param {string} sessionId
+   */
+  clearSession(sessionId) {
+    const entries = this._bySession.get(sessionId) || [];
+    for (const e of entries) {
+      this._entries.delete(e.entryId);
+      const turnEntries = this._byTurn.get(e.turnId);
+      if (turnEntries) {
+        const idx = turnEntries.findIndex(x => x.entryId === e.entryId);
+        if (idx >= 0) turnEntries.splice(idx, 1);
+      }
+    }
+    this._bySession.delete(sessionId);
+  }
+
+  /** Get stats */
+  getStats() {
+    return {
+      totalEntries: this._entries.size,
+      sessionsTracked: this._bySession.size,
+      turnsTracked: this._byTurn.size,
+    };
+  }
+}
+
+// Singleton
+const ledger = new ContextSourceLedger();
+export default ledger;
+export { ContextSourceLedger };

package/src/lib/execution-trace/index.js

@@ -0,0 +1,10 @@
+/**
+ * ExecutionTrace - M3 执行追踪统一导出
+ *
+ * 包含分布式追踪和指标收集功能：
+ * - TraceContext: W3C Trace Context 兼容的上下文传播
+ * - MetricsCollector: 轻量级性能指标收集
+ */
+
+export * from "./trace-context.js";
+export * from "./metrics-collector.js";