chainlesschain 0.162.170 → 0.162.172

package/src/lib/background-agent-supervisor.js

@@ -6,16 +6,21 @@ import {
   openSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   rmSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getHomeDir } from "./paths.js";
 import { deriveSessionState } from "./session-lifecycle.js";
+import {
+  finishAgentWorktree,
+  validateAgentWorktree,
+} from "./agent-worktree.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
@@ -280,6 +285,20 @@ export function writeBackgroundAgentState(state) {
     if (Number(current.pinnedAt || 0) > Number(next.pinnedAt || 0)) {
       next = { ...next, pinned: current.pinned, pinnedAt: current.pinnedAt };
     }
+    // A background worktree is immutable session identity, just like the
+    // conversation id. Heartbeat/finalize/rename writers may race with a stale
+    // snapshot, but no same-id transition is allowed to move the run back to
+    // the main checkout or drop the cleanup metadata.
+    if (current.worktreePath) {
+      next = {
+        ...next,
+        cwd: current.worktreePath,
+        repoRoot: current.repoRoot,
+        worktreePath: current.worktreePath,
+        baseSha: current.baseSha,
+        branch: current.branch,
+      };
+    }
   }
   const tmp = `${target}.${process.pid}.tmp`;
   writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
@@ -500,7 +519,7 @@ export function renameBackgroundAgent(id, title, options = {}) {
  * conversation session is NOT touched — that's `cc session delete`.
  */
 export function removeBackgroundAgent(id, options = {}) {
-  const state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+  let state = effectiveBackgroundAgentState(readBackgroundAgentState(id), {
     now: options.now,
     heartbeatStaleMs: options.heartbeatStaleMs,
   });
@@ -513,15 +532,28 @@ export function removeBackgroundAgent(id, options = {}) {
     }
     try {
       stopBackgroundAgent(id);
+      state =
+        effectiveBackgroundAgentState(readBackgroundAgentState(id), {
+          now: options.now,
+          heartbeatStaleMs: options.heartbeatStaleMs,
+        }) || state;
     } catch {
       /* best-effort — the record removal below is the point of rm --force */
     }
   }
+  const worktree = cleanupBackgroundAgentWorktree(state, {
+    keepWorktree: options.keepWorktree === true,
+  });
   rmSync(statePath(id), { force: true });
   if (options.keepLog !== true) {
     rmSync(logPath(id), { force: true });
   }
-  return { id, removed: true, status: state.status };
+  return {
+    id,
+    removed: true,
+    status: state.status,
+    ...(worktree ? { worktree } : {}),
+  };
 }
 
 /**
@@ -598,6 +630,68 @@ export function buildFollowUpArgv(argv, opts = {}) {
   return out;
 }
 
+function canonicalPath(value) {
+  const absolute = resolve(String(value || ""));
+  try {
+    const real = realpathSync.native
+      ? realpathSync.native(absolute)
+      : realpathSync(absolute);
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  } catch {
+    return process.platform === "win32" ? absolute.toLowerCase() : absolute;
+  }
+}
+
+/**
+ * Normalize and verify worktree metadata before it enters a background job.
+ * The metadata is persisted as top-level state fields for compatibility with
+ * status/IDE consumers: repoRoot/worktreePath/baseSha/branch.
+ */
+export function normalizeBackgroundWorktree(worktree, cwd) {
+  if (!worktree) return null;
+  const normalized = {
+    repoRoot: resolve(String(worktree.repoRoot || "")),
+    worktreePath: resolve(String(worktree.worktreePath || worktree.path || "")),
+    baseSha: String(worktree.baseSha || ""),
+    branch: String(worktree.branch || ""),
+  };
+  if (
+    !normalized.repoRoot ||
+    !normalized.worktreePath ||
+    !normalized.baseSha ||
+    !normalized.branch
+  ) {
+    throw new Error(
+      "Cannot launch background agent: incomplete worktree metadata",
+    );
+  }
+  if (canonicalPath(cwd) !== canonicalPath(normalized.worktreePath)) {
+    throw new Error(
+      "Cannot launch background agent: cwd does not match the persisted worktree path",
+    );
+  }
+  const validation = validateAgentWorktree({
+    ...normalized,
+    path: normalized.worktreePath,
+  });
+  if (!validation.valid) {
+    throw new Error(
+      `Cannot launch background agent: worktree metadata is not usable (${validation.reason})`,
+    );
+  }
+  return normalized;
+}
+
+function persistedWorktree(state) {
+  if (!state?.worktreePath) return null;
+  return {
+    repoRoot: state.repoRoot,
+    worktreePath: state.worktreePath,
+    baseSha: state.baseSha,
+    branch: state.branch,
+  };
+}
+
 /**
  * Continue a finished/crashed background session as a NEW background session
  * on the same conversation (`cc daemon resume <id> <prompt>`). The original
@@ -622,14 +716,27 @@ export function resumeBackgroundAgent(id, prompt, options = {}) {
   }
   const text = String(prompt || "").trim();
   if (!text) throw new Error("resume requires a prompt");
+  const worktree = persistedWorktree(state);
+  if (
+    worktree &&
+    options.cwd &&
+    canonicalPath(options.cwd) !== canonicalPath(worktree.worktreePath)
+  ) {
+    throw new Error(
+      `Background agent ${id} is bound to worktree "${worktree.worktreePath}" and cannot resume in a different cwd`,
+    );
+  }
   const argv = ["agent", "--session", state.sessionId, "-p", text];
   return launchBackgroundAgent({
     argv,
-    cwd: options.cwd || state.cwd || process.cwd(),
+    // Worktree sessions fail closed: never fall back to process.cwd(), which
+    // could silently resume a write task in the main checkout.
+    cwd: worktree?.worktreePath || options.cwd || state.cwd || process.cwd(),
     sessionId: state.sessionId,
     title: options.title || state.title || text.slice(0, 100),
     cliEntry: options.cliEntry,
     followUpArgv: ["agent", "--session", state.sessionId],
+    worktree,
   });
 }
 
@@ -667,8 +774,10 @@ export function launchBackgroundAgent({
   title,
   cliEntry,
   followUpArgv,
+  worktree,
 }) {
   assertUsableCwd(cwd);
+  const worktreeState = normalizeBackgroundWorktree(worktree, cwd);
   const id = createBackgroundAgentId();
   const dir = backgroundAgentsDir();
   const jobFile = join(dir, `${id}.job.${process.pid}.json`);
@@ -683,6 +792,7 @@ export function launchBackgroundAgent({
     title: title || "Background agent",
     cliEntry: cliEntry || process.argv[1],
     logFile: logPath(id),
+    ...(worktreeState || {}),
     // Present = interactive attach can start follow-up turns; absent = the
     // transport rejects prompts (log-only session).
     ...(Array.isArray(followUpArgv) ? { followUpArgv } : {}),
@@ -706,6 +816,7 @@ export function launchBackgroundAgent({
     endedAt: null,
     exitCode: null,
     logFile: job.logFile,
+    ...(worktreeState || {}),
   };
   writeBackgroundAgentState(state);
   let child;
@@ -866,6 +977,84 @@ export function stopBackgroundAgent(id) {
   return { ...next, stopped: true };
 }
 
+function activeWorktreeProcesses(state) {
+  const active = [];
+  if (
+    Number.isInteger(Number(state?.pid)) &&
+    Number(state.pid) > 0 &&
+    isSameProcess(state.pid, state.startedAt)
+  ) {
+    active.push("worker");
+  }
+  if (
+    Number.isInteger(Number(state?.agentPid)) &&
+    Number(state.agentPid) > 0 &&
+    isSameProcess(state.agentPid, state.agentStartedAt)
+  ) {
+    active.push("agent");
+  }
+  return active;
+}
+
+/**
+ * Explicit background-record cleanup owns the worktree teardown. Normal
+ * completion, kill, lost-worker reconciliation, attach and resume all retain
+ * it so a later resume continues in the exact same isolated checkout.
+ */
+export function cleanupBackgroundAgentWorktree(state, options = {}) {
+  const worktree = persistedWorktree(state);
+  if (!worktree) return null;
+  if (options.keepWorktree === true) {
+    return {
+      removed: false,
+      kept: true,
+      reason: "kept by explicit request",
+      path: worktree.worktreePath,
+    };
+  }
+
+  const blockers = [];
+  const active = activeWorktreeProcesses(state);
+  if (active.length) blockers.push(`active ${active.join("+")} process`);
+  if (Number(state?.pendingApprovals || 0) > 0) {
+    blockers.push("pending approval");
+  }
+  if (state?.pendingQuestion) blockers.push("pending user input");
+  if (
+    Number(state?.uncertainSideEffects || 0) > 0 ||
+    state?.phase === "uncertain_side_effect" ||
+    state?.phase === "uncertain-side-effect"
+  ) {
+    blockers.push("unfinished or uncertain side effect");
+  }
+  if (blockers.length) {
+    throw new Error(
+      `Refusing to clean background worktree "${worktree.worktreePath}": ${blockers.join(", ")}`,
+    );
+  }
+
+  if (!existsSync(worktree.worktreePath)) {
+    return {
+      removed: false,
+      kept: false,
+      reason: "worktree path already missing",
+      path: worktree.worktreePath,
+    };
+  }
+
+  const result = finishAgentWorktree({
+    ...worktree,
+    path: worktree.worktreePath,
+  });
+  if (!result.removed) {
+    throw new Error(
+      `Refusing to remove background agent record while its worktree is kept (${result.reason}). ` +
+        "Resolve or preserve the work first, or pass --keep-worktree to remove only the record.",
+    );
+  }
+  return { ...result, path: worktree.worktreePath };
+}
+
 export function openBackgroundLogFile(id) {
   const fd = openSync(logPath(id), "a", 0o600);
   return { fd, close: () => closeSync(fd) };

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";

package/src/lib/execution-trace/metrics-collector.js

@@ -0,0 +1,218 @@
+/**
+ * MetricsCollector - M3 轻量级指标收集器
+ *
+ * 收集CLI运行时的性能指标：
+ * - 执行计数器
+ * - 延迟直方图
+ * - 标签化指标
+ * - 自动与traceId关联
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash, randomBytes } from "node:crypto";
+import { traceContext } from "./trace-context.js";
+
+class MetricsCollector {
+  constructor() {
+    this._counters = new Map();
+    this._histograms = new Map();
+    this._gauges = new Map();
+    this._flushedAt = Date.now();
+  }
+
+  /**
+   * Increment a counter metric
+   * @param {string} name - Metric name
+   * @param {number} value - Value to increment by (default: 1)
+   * @param {Object} labels - Key-value labels
+   */
+  increment(name, value = 1, labels = {}) {
+    const key = this._metricKey(name, labels);
+    const current = this._counters.get(key) || 0;
+    this._counters.set(key, current + value);
+  }
+
+  /**
+   * Record a value in a histogram (latency, sizes, etc.)
+   * @param {string} name - Metric name
+   * @param {number} value - Value to record
+   * @param {Object} labels - Key-value labels
+   */
+  observe(name, value, labels = {}) {
+    const key = this._metricKey(name, labels);
+    const data = this._histograms.get(key) || {
+      count: 0,
+      sum: 0,
+      min: Infinity,
+      max: -Infinity,
+      values: [],
+    };
+    data.count += 1;
+    data.sum += value;
+    data.min = Math.min(data.min, value);
+    data.max = Math.max(data.max, value);
+    // Keep last 1000 values for percentile calculation
+    if (data.values.length > 1000) {
+      data.values.shift();
+    }
+    data.values.push(value);
+    this._histograms.set(key, data);
+  }
+
+  /**
+   * Set a gauge value
+   * @param {string} name - Metric name
+   * @param {number} value - Gauge value
+   * @param {Object} labels - Key-value labels
+   */
+  setGauge(name, value, labels = {}) {
+    const key = this._metricKey(name, labels);
+    this._gauges.set(key, value);
+  }
+
+  /**
+   * Time an async function and record latency
+   * @param {string} name - Metric name
+   * @param {Function} fn - Async function to time
+   * @param {Object} labels - Key-value labels
+   * @returns {Promise<*>} Function result
+   */
+  async time(name, fn, labels = {}) {
+    const start = performance.now();
+    try {
+      const result = await fn();
+      this.observe(name, performance.now() - start, {
+        ...labels,
+        status: "success",
+      });
+      this.increment(`${name}_total`, 1, { ...labels, status: "success" });
+      return result;
+    } catch (err) {
+      this.observe(name, performance.now() - start, {
+        ...labels,
+        status: "error",
+      });
+      this.increment(`${name}_total`, 1, {
+        ...labels,
+        status: "error",
+        errorType: err.name,
+      });
+      throw err;
+    }
+  }
+
+  /**
+   * Get all collected metrics as OTLP-compatible format
+   * @returns {Object} OTLP metrics data
+   */
+  collect() {
+    const metrics = [];
+
+    // Convert counters
+    for (const [key, value] of this._counters) {
+      const { name, labels } = this._parseKey(key);
+      metrics.push({
+        name,
+        type: "counter",
+        value,
+        labels,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Convert histograms
+    for (const [key, data] of this._histograms) {
+      const { name, labels } = this._parseKey(key);
+      data.values.sort((a, b) => a - b);
+      const p50 = data.values[Math.floor(data.values.length * 0.5)];
+      const p95 = data.values[Math.floor(data.values.length * 0.95)];
+      const p99 = data.values[Math.floor(data.values.length * 0.99)];
+      metrics.push({
+        name,
+        type: "histogram",
+        count: data.count,
+        sum: data.sum,
+        min: data.min,
+        max: data.max,
+        avg: data.sum / data.count,
+        p50,
+        p95,
+        p99,
+        labels,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Convert gauges
+    for (const [key, value] of this._gauges) {
+      const { name, labels } = this._parseKey(key);
+      metrics.push({
+        name,
+        type: "gauge",
+        value,
+        labels,
+        timestamp: Date.now(),
+      });
+    }
+
+    return {
+      resourceMetrics: [
+        {
+          resource: {
+            attributes: [
+              {
+                key: "service.name",
+                value: { stringValue: "chainlesschain-cli" },
+              },
+              {
+                key: "service.version",
+                value: { stringValue: "0.10.0-alpha.74" },
+              },
+            ],
+          },
+          scopeMetrics: [
+            {
+              scope: { name: "chainlesschain.cli" },
+              metrics,
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  /**
+   * Reset all metrics
+   */
+  reset() {
+    this._counters.clear();
+    this._histograms.clear();
+    this._gauges.clear();
+    this._flushedAt = Date.now();
+  }
+
+  _metricKey(name, labels) {
+    const labelStr = Object.entries(labels)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([k, v]) => `${k}=${v}`)
+      .join(",");
+    return labelStr ? `${name}{${labelStr}}` : name;
+  }
+
+  _parseKey(key) {
+    const match = key.match(/^([^{]+)(?:\{([^}]+)\})?$/);
+    if (!match) return { name: key, labels: {} };
+    const [, name, labelStr] = match;
+    if (!labelStr) return { name, labels: {} };
+    const labels = {};
+    for (const pair of labelStr.split(",")) {
+      const [k, v] = pair.split("=");
+      if (k) labels[k] = v;
+    }
+    return { name, labels };
+  }
+}
+
+export { MetricsCollector };
+export const metricsCollector = new MetricsCollector();
+export default metricsCollector;