chainlesschain 0.162.163 → 0.162.164

package/src/lib/side-effect-ledger.js

@@ -66,6 +66,82 @@ export function kindIsIdempotent(kind) {
   return KIND_IDEMPOTENT.get(String(kind || "")) === true;
 }
 
+/** Trim a free-text descriptor to a short, log-safe key. */
+function shortKey(v) {
+  if (v == null) return null;
+  const s = String(v);
+  return s.length > 80 ? s.slice(0, 80) + "…" : s;
+}
+
+/**
+ * Classify one agent tool call into a side-effect kind for the ledger, or null
+ * when the tool issues no irreversible external effect (reads, searches, plain
+ * git status, etc.). PURE. Conservative by design — an opaque shell command is
+ * NON-idempotent so a mid-flight crash forces INSPECT rather than a blind
+ * replay (the P0-2 "started_unknown 风险操作默认 needs_input" invariant).
+ *
+ * Only the tools that can leave a durable external mark are recorded; read-only
+ * and purely-local-recoverable tools return null so a resumed session is not
+ * spammed with false "verify before replay" warnings.
+ *
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {{kind:string, key:string|null}|null}
+ */
+export function classifyToolSideEffect(toolName, args = {}) {
+  const name = String(toolName || "");
+  const a = args && typeof args === "object" ? args : {};
+  switch (name) {
+    case "write_file":
+    case "notebook_edit":
+    case "edit_file":
+      return {
+        kind: "file-write",
+        key: shortKey(a.path || a.file || a.notebook_path),
+      };
+    case "edit_file_hashed":
+      // Hash-guarded: re-applying over an already-changed tree fails safely, so
+      // a replay cannot silently double-apply — idempotent-by-construction.
+      return {
+        kind: "file-write-checkpointed",
+        key: shortKey(a.path || a.file),
+      };
+    case "run_shell":
+    case "run_code":
+      // Opaque command: could be `npm publish`, `rm -rf`, or just `npm test`.
+      // We cannot tell, so fail-closed to a non-idempotent effect.
+      return { kind: "shell", key: shortKey(a.command || a.code) };
+    case "git": {
+      const cmd = String(a.command || "").trim();
+      const verb = cmd.split(/\s+/)[0] || "";
+      if (verb === "push") return { kind: "git-push", key: shortKey(cmd) };
+      // Every other git op (status/diff/commit/branch/fetch/pull/…) is either
+      // read-only or locally recoverable via git — not an irreversible effect.
+      return null;
+    }
+    case "publish_artifact":
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.title || a.path || a.name),
+      };
+    case "schedule":
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.name || a.cron || a.when),
+      };
+    case "notify":
+      return { kind: "network-mutation", key: shortKey(a.title || a.message) };
+    case "browser_act":
+      // A CDP action (click/type/submit) can mutate remote state.
+      return {
+        kind: "network-mutation",
+        key: shortKey(a.action || a.selector),
+      };
+    default:
+      return null;
+  }
+}
+
 function nowFrom(clock) {
   return typeof clock === "function" ? Number(clock()) || 0 : 0;
 }
@@ -271,6 +347,35 @@ export function planOpRecovery(op) {
   }
 }
 
+/**
+ * Count COMMITTED side-effects that share an idempotency key beyond the first —
+ * the "resume 后重复副作用 = 0" acceptance metric (P0-2 §11.2). A committed op's
+ * dedup key is `meta.idempotencyKey`; when absent it falls back to the (unique)
+ * `opId`, so un-keyed ops never register as duplicates. A correct resume never
+ * re-commits an already-committed effect, so this must stay `0`.
+ *
+ * @param {SideEffectLedger|{ops:Array}} ledger
+ * @returns {number}
+ */
+export function countDuplicateCommittedEffects(ledger) {
+  const ops =
+    ledger instanceof SideEffectLedger
+      ? ledger.list()
+      : Array.isArray(ledger?.ops)
+        ? ledger.ops
+        : [];
+  const seen = new Map();
+  let duplicates = 0;
+  for (const o of ops) {
+    if (o?.state !== SIDE_EFFECT_STATE.COMMITTED) continue;
+    const key = (o.meta && o.meta.idempotencyKey) || o.opId;
+    const n = (seen.get(key) || 0) + 1;
+    seen.set(key, n);
+    if (n > 1) duplicates++;
+  }
+  return duplicates;
+}
+
 /**
  * Build a recovery plan for every op in a (crash-rebuilt) ledger.
  *

package/src/lib/skill-loader.js

@@ -28,6 +28,7 @@ import { getElectronUserDataDir } from "./paths.js";
 import { findProjectRoot } from "./project-detector.js";
 import { findProjectRoot as findGitRoot } from "./project-instructions.js";
 import { parseSkillMcpServers } from "./skill-mcp.js";
+import { normalizeSkillPaths } from "./skill-path-scope.js";
 import { discoverPluginSkillLayers } from "./plugin-runtime/skills.js";
 import settingsLoader from "./settings-loader.cjs";
 
@@ -467,6 +468,10 @@ export class CLISkillLoader {
           executionMode: data.executionMode || null,
           cliDomain: data.cliDomain || null,
           cliVersionHash: data.cliVersionHash || null,
+          // Optional per-directory path-scope: when set, the skill is only
+          // surfaced/runnable under a matching subtree (large-monorepo lazy
+          // context). null (the default) = applies everywhere.
+          paths: normalizeSkillPaths(data),
           dirName: entry.name,
           hasHandler: fs.existsSync(path.join(skillDir, "handler.js")),
           body,
@@ -515,6 +520,33 @@ export class CLISkillLoader {
     return this._cache;
   }
 
+  /**
+   * Every skill found in every layer, WITHOUT dedup. loadAll() keeps only the
+   * winning copy per id (Map.set overwrite), so a skill id defined in more than
+   * one layer silently shadows — a caller (e.g. `cc doctor`) needs the full,
+   * un-deduped list to detect and report that. Same scan logic as loadAll, no
+   * override collapse.
+   * @returns {Array<{id:string, layer:string, skillDir:string}>}
+   */
+  listSkillLayerEntries(options = {}) {
+    if (allSkillsDisabled(options)) return [];
+    const dropBundled = bundledSkillsDisabled(options);
+    const out = [];
+    for (const { layer, path: layerPath, exists } of this.getLayerPaths()) {
+      if (!exists) continue;
+      if (dropBundled && (layer === "bundled" || layer === "cli-bundled"))
+        continue;
+      for (const skill of this._loadFromDir(layerPath, layer)) {
+        out.push({
+          id: skill.id,
+          layer: skill.source || layer,
+          skillDir: skill.skillDir,
+        });
+      }
+    }
+    return out;
+  }
+
   /**
    * Get resolved skills (uses cache if available)
    * @returns {object[]}

package/src/lib/skill-path-scope.js

@@ -0,0 +1,63 @@
+/**
+ * Per-directory skill path-scoping (P1 large-monorepo lazy context).
+ *
+ * A skill may declare a `paths:` (or `globs:` / `pathScope:`) frontmatter list
+ * so it is only surfaced when the agent is working under a matching subtree —
+ * e.g. a skill scoped to `packages/cli/**` should not clutter discovery or run
+ * when the agent is operating in `android-app/`. This keeps the on-demand skill
+ * surface small in a big monorepo.
+ *
+ * Pure (path math only; the matching semantics are reused from
+ * project-instructions.js's `ruleApplies`, the same prefix-overlap rule used for
+ * path-scoped `.claude/rules`). A skill with no `paths` applies everywhere, so a
+ * skill set with no path-scoped skills is filtered byte-for-byte unchanged.
+ */
+
+import path from "node:path";
+import { ruleApplies } from "./project-instructions.js";
+
+/**
+ * Normalize a skill's raw path-scope frontmatter (`paths` / `globs` /
+ * `pathScope`, string or array) into a non-empty string[] of globs, or null
+ * when the skill declares no scope (→ applies everywhere).
+ */
+export function normalizeSkillPaths(data) {
+  const raw = data?.paths ?? data?.globs ?? data?.pathScope ?? null;
+  if (raw == null) return null;
+  const list = (Array.isArray(raw) ? raw : [raw])
+    .map((g) => String(g == null ? "" : g).trim())
+    .filter(Boolean);
+  return list.length > 0 ? list : null;
+}
+
+/**
+ * The agent's cwd expressed relative to the project root, forward-slashed — the
+ * form `ruleApplies` expects (skill `paths` globs are project-root-relative,
+ * like rule globs). A cwd at (or outside) the root resolves to "" → every skill
+ * applies (never hide skills just because we can't locate the root).
+ */
+export function relCwdForCwd(cwd, root) {
+  if (!cwd || !root) return "";
+  let rel;
+  try {
+    rel = path.relative(root, cwd);
+  } catch {
+    return "";
+  }
+  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return "";
+  return rel.replace(/\\/g, "/");
+}
+
+/**
+ * Does a skill's path-scope apply when the agent runs at `relCwd`? A skill with
+ * no `paths` (null/empty) applies everywhere.
+ */
+export function skillAppliesToCwd(skill, relCwd) {
+  return ruleApplies(skill?.paths || [], relCwd);
+}
+
+/** Filter a skill list to those whose path-scope applies at `relCwd`. */
+export function filterSkillsByRelCwd(skills, relCwd) {
+  if (!Array.isArray(skills)) return skills;
+  return skills.filter((s) => skillAppliesToCwd(s, relCwd));
+}

package/src/lib/sub-agent-context.js

@@ -140,8 +140,13 @@ export class SubAgentContext {
     this._onUsage =
       typeof options.onUsage === "function" ? options.onUsage : null;
 
-    // Optional abort signal for cancellation
+    // Optional EXTERNAL abort signal for cancellation (e.g. a parent-provided
+    // AbortSignal). In addition, every context owns an INTERNAL controller so a
+    // single sub-agent can be cancelled precisely by id via `abort()` (the
+    // registry's `cancel(id)`), independent of any external signal.
     this._signal = options.signal || null;
+    this._abortController = new AbortController();
+    this._cancelReason = null;
 
     // Optional MCP / external tool plumbing. These are forwarded into the
     // agentLoop options so MCP-backed tools (e.g. from a cowork template's
@@ -430,9 +435,9 @@ export class SubAgentContext {
           }
         }
 
-        // Check abort signal
-        if (this._signal?.aborted) {
-          this.forceComplete("cancelled", {
+        // Check abort signal (external OR this context's own `abort()`)
+        if (this.isAborted()) {
+          this.forceComplete(this._cancelReason || "cancelled", {
             partialContent: lastContent,
             artifacts,
           });
@@ -581,6 +586,33 @@ export class SubAgentContext {
     }
   }
 
+  /**
+   * True when this sub-agent has been asked to stop — either via an external
+   * abort signal or via this context's own `abort()` (precise single-agent
+   * cancel). The agent loop checks this each iteration and winds down
+   * cooperatively (force-completes with the partial work it has).
+   */
+  isAborted() {
+    return Boolean(
+      this._signal?.aborted || this._abortController.signal.aborted,
+    );
+  }
+
+  /**
+   * Precisely cancel THIS sub-agent: trip its internal abort signal so the loop
+   * stops at its next iteration and hands back partial work. Idempotent. The
+   * `reason` surfaces in the force-completed summary. Returns true if the abort
+   * was newly requested, false if it was already aborted / not active.
+   */
+  abort(reason = "cancelled") {
+    if (this.status !== "active" || this._abortController.signal.aborted) {
+      return false;
+    }
+    this._cancelReason = reason;
+    this._abortController.abort();
+    return true;
+  }
+
   /**
    * Get a serializable snapshot of this context (for debugging/logging).
    */

package/src/lib/sub-agent-registry.js

@@ -188,6 +188,25 @@ export class SubAgentRegistry {
     }
   }
 
+  /**
+   * Precisely cancel a SINGLE active sub-agent by id (the per-agent sibling of
+   * `forceCompleteAll`). Trips the context's abort signal so its loop stops at
+   * the next iteration and hands back partial work; the normal completion path
+   * then moves it to history. Cooperative — a loop blocked on a long call winds
+   * down at its next check.
+   *
+   * @param {string} id - Sub-agent id to cancel
+   * @param {string} [reason="cancelled"] - Surfaced in the force-completed summary
+   * @returns {{ found: boolean, cancelled: boolean }}
+   */
+  cancel(id, reason = "cancelled") {
+    const subCtx = this._active.get(id);
+    if (!subCtx) return { found: false, cancelled: false };
+    const cancelled =
+      typeof subCtx.abort === "function" ? subCtx.abort(reason) : false;
+    return { found: true, cancelled };
+  }
+
   /**
    * Clean up stale entries older than maxAgeMs.
    * @param {number} [maxAgeMs=600000] - Max age in ms (default: 10 minutes)

package/src/lib/telemetry/span-recorder.js

@@ -12,6 +12,8 @@
  * `summary()` renders them. The clock is injected so tests are deterministic.
  */
 
+import { redactSecrets } from "../secret-scan.js";
+
 let _seq = 0;
 function spanId() {
   _seq = (_seq + 1) % Number.MAX_SAFE_INTEGER;
@@ -187,8 +189,19 @@ export class TelemetryRecorder {
     };
   }
 
-  /** OTLP/JSON-shaped export (resourceSpans) — ingestible by an OTel collector. */
-  toOtlp() {
+  /**
+   * OTLP/JSON-shaped export (resourceSpans) — ingestible by an OTel collector.
+   *
+   * §8.1 export gate: a span attribute or an exception message can carry a
+   * provider token / JWT / connection string (a tool `command` attribute, an
+   * error string, a redirect URL). A trace is shipped to a collector that may be
+   * external, so string values are secret-redacted by default (recall-first —
+   * an export must fail toward "no leak"). Only true secret substrings are
+   * replaced, so a span with no secret is byte-identical. `{ redact: false }`
+   * keeps raw values for a fully-trusted local collector.
+   */
+  toOtlp({ redact = true } = {}) {
+    const scrub = redact ? (v) => redactSecrets(String(v)) : (v) => String(v);
     return {
       resourceSpans: [
         {
@@ -219,14 +232,14 @@ export class TelemetryRecorder {
                       ? { doubleValue: v }
                       : typeof v === "boolean"
                         ? { boolValue: v }
-                        : { stringValue: String(v) },
+                        : { stringValue: scrub(v) },
                 })),
                 events: s.events.map((e) => ({
                   name: e.name,
                   timeUnixNano: String(Math.round(e.time * 1e6)),
                   attributes: Object.entries(e.attributes).map(([k, v]) => ({
                     key: k,
-                    value: { stringValue: String(v) },
+                    value: { stringValue: scrub(v) },
                   })),
                 })),
               })),

package/src/lib/terminal-context.js

@@ -0,0 +1,195 @@
+/**
+ * Terminal-context policy core — the pure-logic half of P1-2 (交互终端) of
+ * CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md.
+ *
+ * P1-2 asks for an embedded interactive PTY inside an Agent Session: continuous
+ * ANSI output, scrollback trimming, search/copy, user takeover, "把选中输出附加
+ * 到下一轮", background commands surfacing PID / port / health, and — critically —
+ * "Agent 不得把 Terminal 中的敏感输出默认加入模型上下文" (terminal output must NOT
+ * enter the model context by default).
+ *
+ * This module is that policy + text layer, NOT a PTY: it never spawns a shell,
+ * allocates a pseudo-terminal, or touches fs / clock / RNG / process. A caller
+ * (the real PTY host) feeds captured bytes and a selection intent and reads back
+ * what — if anything — is safe to hand the model.
+ *
+ * Two invariants give it teeth, mirroring the other gap cores:
+ *   1. Terminal output fails CLOSED out of the model context: `selectTerminal
+ *      ContextForModel` returns null unless the user EXPLICITLY opted this turn's
+ *      output in. Ambient scrollback never leaks into a prompt.
+ *   2. Whatever DOES get opted in is ANSI-stripped and secret-redacted (via
+ *      [[secret-scan.js]]) and scrollback-capped, so a printed token or a control
+ *      sequence can't ride into the context.
+ *
+ * PURE: no fs / clock / RNG / process / PTY.
+ */
+
+import { redactSecrets } from "./secret-scan.js";
+
+/**
+ * Match ANSI/VT control sequences: CSI (ESC [ … final byte), OSC (ESC ] … BEL or
+ * ST) and the standalone two/three-byte escapes. Kept explicit rather than a
+ * dependency so the strip is auditable (ESC = U+001B, CSI = U+009B, BEL = U+0007).
+ * A fresh RegExp is compiled per call to avoid the /g lastIndex
+ * hazard across invocations.
+ */
+function ansiRegex() {
+  return new RegExp(
+    [
+      "[\\u001B\\u009B][[\\]()#;?]*" +
+        "(?:(?:(?:[a-zA-Z\\d]*(?:;[a-zA-Z\\d]*)*)?\\u0007)" +
+        "|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PRZcf-ntqry=><~]))",
+    ].join(""),
+    "g",
+  );
+}
+
+/**
+ * Remove ANSI/VT escape sequences from terminal output, leaving human-readable
+ * text (for search, copy, and — importantly — before the text ever reaches a
+ * model, so escape codes can't smuggle intent or bloat the context). Non-string
+ * input → "".
+ */
+export function stripAnsi(text) {
+  if (typeof text !== "string") return "";
+  return text.replace(ansiRegex(), "");
+}
+
+/** Default scrollback cap — how many trailing lines survive truncation. */
+export const DEFAULT_SCROLLBACK_LINES = 400;
+
+/**
+ * Cap a captured buffer to its last `maxLines` lines (the live tail is what
+ * matters for a running process). Marks the elision so the reader — and any
+ * model — knows output was dropped rather than seeing a silently-truncated head.
+ *
+ * @returns {{text:string, truncated:boolean, droppedLines:number, totalLines:number}}
+ */
+export function truncateScrollback(text, maxLines = DEFAULT_SCROLLBACK_LINES) {
+  const src = typeof text === "string" ? text : "";
+  const cap =
+    Number.isInteger(maxLines) && maxLines > 0
+      ? maxLines
+      : DEFAULT_SCROLLBACK_LINES;
+  const lines = src.split("\n");
+  const total = lines.length;
+  if (total <= cap) {
+    return { text: src, truncated: false, droppedLines: 0, totalLines: total };
+  }
+  const kept = lines.slice(total - cap);
+  const dropped = total - cap;
+  return {
+    text: `…(${dropped} earlier lines elided)\n${kept.join("\n")}`,
+    truncated: true,
+    droppedLines: dropped,
+    totalLines: total,
+  };
+}
+
+/**
+ * Decide what terminal output may be attached to the next model turn — the
+ * fail-closed core of "Agent 不得把 Terminal 中的敏感输出默认加入模型上下文".
+ *
+ * Returns `null` (attach NOTHING) unless the user explicitly opted in this turn
+ * (`optIn === true`). When opted in, a supplied `selection` (the user's
+ * highlighted region) is preferred over the full `output` — "把选中输出附加到下
+ * 一轮". Whatever is chosen is ANSI-stripped, secret-redacted and scrollback-
+ * capped before it becomes context.
+ *
+ * @param {object} args
+ * @param {string} [args.output]     full captured terminal buffer
+ * @param {string} [args.selection]  user-highlighted region (preferred)
+ * @param {boolean} [args.optIn]     explicit "include this in context" intent
+ * @param {number} [args.maxLines]   scrollback cap for the attached text
+ * @returns {null | {source:"selection"|"output", text:string, truncated:boolean, redacted:boolean}}
+ */
+export function selectTerminalContextForModel(args = {}) {
+  const a = args && typeof args === "object" ? args : {};
+  if (a.optIn !== true) {
+    return null; // fail-closed: no ambient terminal output in the prompt
+  }
+  const hasSelection =
+    typeof a.selection === "string" && a.selection.trim() !== "";
+  const source = hasSelection ? "selection" : "output";
+  const raw = hasSelection ? a.selection : a.output;
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return null; // opted in but nothing to attach
+  }
+
+  const clean = stripAnsi(raw);
+  const redactedText = redactSecrets(clean);
+  const capped = truncateScrollback(redactedText, a.maxLines);
+  return {
+    source,
+    text: capped.text,
+    truncated: capped.truncated,
+    redacted: redactedText !== clean,
+  };
+}
+
+/** Canonical health states for a backgrounded terminal command. */
+export const HEALTH_STATUS = Object.freeze({
+  STARTING: "starting",
+  RUNNING: "running",
+  HEALTHY: "healthy",
+  UNHEALTHY: "unhealthy",
+  EXITED: "exited",
+  UNKNOWN: "unknown",
+});
+
+const HEALTH_ALIASES = new Map([
+  ["starting", HEALTH_STATUS.STARTING],
+  ["running", HEALTH_STATUS.RUNNING],
+  ["up", HEALTH_STATUS.RUNNING],
+  ["healthy", HEALTH_STATUS.HEALTHY],
+  ["ok", HEALTH_STATUS.HEALTHY],
+  ["unhealthy", HEALTH_STATUS.UNHEALTHY],
+  ["degraded", HEALTH_STATUS.UNHEALTHY],
+  ["exited", HEALTH_STATUS.EXITED],
+  ["stopped", HEALTH_STATUS.EXITED],
+  ["dead", HEALTH_STATUS.EXITED],
+]);
+
+/** Normalize a health label; anything unrecognized → UNKNOWN (fail-closed). */
+export function normalizeHealthStatus(value) {
+  if (typeof value !== "string") return HEALTH_STATUS.UNKNOWN;
+  return (
+    HEALTH_ALIASES.get(value.trim().toLowerCase()) || HEALTH_STATUS.UNKNOWN
+  );
+}
+
+function normalizePorts(ports) {
+  const list = Array.isArray(ports) ? ports : [];
+  const out = [];
+  for (const p of list) {
+    const n = Number(p);
+    if (Number.isInteger(n) && n > 0 && n <= 65535 && !out.includes(n)) {
+      out.push(n);
+    }
+  }
+  return out;
+}
+
+/**
+ * Build a safe descriptor for a backgrounded terminal command — the "后台命令显示
+ * PID、端口、健康状态并可安全停止" surface. The command string is secret-redacted
+ * (a `FOO=token cmd` invocation must not leak the token into a status pill), PID
+ * is coerced to a positive integer or null, ports are validated, and the health
+ * status is normalized fail-closed. `stoppable` is true only when we hold a real
+ * PID to signal.
+ *
+ * @param {object} cmd {command?, pid?, ports?, status?}
+ * @returns {{command:string|null, pid:number|null, ports:number[], status:string, stoppable:boolean}}
+ */
+export function describeBackgroundCommand(cmd = {}) {
+  const c = cmd && typeof cmd === "object" ? cmd : {};
+  const pidNum = Number(c.pid);
+  const pid = Number.isInteger(pidNum) && pidNum > 0 ? pidNum : null;
+  return {
+    command: typeof c.command === "string" ? redactSecrets(c.command) : null,
+    pid,
+    ports: normalizePorts(c.ports),
+    status: normalizeHealthStatus(c.status),
+    stoppable: pid !== null,
+  };
+}