chainlesschain 0.162.177 → 0.162.178

package/src/lib/skill-loader.js

@@ -31,6 +31,7 @@ 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";
+import contextSourceLedger from "./context-source-ledger.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -218,6 +219,40 @@ export function parseSkillMd(content) {
   return { data, body };
 }
 
+/**
+ * Read only enough of SKILL.md to parse its YAML frontmatter. The markdown
+ * body is deliberately not retained during discovery; it is materialized by
+ * CLISkillLoader.materializeSkill() only when a persona or run_skill needs it.
+ */
+function readSkillFrontmatter(skillMd, maxBytes = 256 * 1024) {
+  const fd = fs.openSync(skillMd, "r");
+  const chunks = [];
+  let total = 0;
+  try {
+    while (total < maxBytes) {
+      const chunk = Buffer.allocUnsafe(Math.min(8192, maxBytes - total));
+      const read = fs.readSync(fd, chunk, 0, chunk.length, total);
+      if (read <= 0) break;
+      chunks.push(chunk.subarray(0, read));
+      total += read;
+      const prefix = Buffer.concat(chunks).toString("utf-8").replace(/^\uFEFF/, "");
+      const firstLineEnd = prefix.search(/\r?\n/);
+      if (firstLineEnd >= 0 && prefix.slice(0, firstLineEnd).trim() !== "---") {
+        return {};
+      }
+      const match = prefix.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/);
+      if (match) return parseSkillMd(match[0]).data;
+    }
+    return {};
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function estimateSkillTokens(text) {
+  return Math.ceil(String(text || "").length / 4);
+}
+
 /**
  * Substitute $ARGUMENTS / $1 / $2 / ... placeholders in a skill body.
  * Inspired by open-agents substituteArguments.
@@ -290,8 +325,17 @@ export function prepareSkillBody(skill, args) {
  * Multi-layer CLI skill loader
  */
 export class CLISkillLoader {
-  constructor() {
+  constructor({ contextLedger = contextSourceLedger } = {}) {
     this._cache = null;
+    this._bodyCache = new Map();
+    this._contextLedger = contextLedger;
+    this._cacheStats = {
+      descriptorScans: 0,
+      descriptorCacheHits: 0,
+      bodyCacheHits: 0,
+      bodyCacheMisses: 0,
+      bodyLoads: new Map(),
+    };
   }
 
   /**
@@ -449,8 +493,8 @@ export class CLISkillLoader {
         continue;
       }
       try {
-        const content = fs.readFileSync(skillMd, "utf-8");
-        const { data, body } = parseSkillMd(content);
+        const data = readSkillFrontmatter(skillMd);
+        const stat = fs.statSync(skillMd);
 
         out.push({
           id: data.name || entry.name,
@@ -474,12 +518,17 @@ export class CLISkillLoader {
           paths: normalizeSkillPaths(data),
           dirName: entry.name,
           hasHandler: fs.existsSync(path.join(skillDir, "handler.js")),
-          body,
-          // Skill-Embedded MCP: inline server declarations in a
-          // ```mcp-servers fenced code block. Empty array if absent.
-          mcpServers: parseSkillMcpServers(body),
+          isolation: data.isolation === true,
+          // Two-tier loading: discovery retains only the descriptor. The body
+          // and embedded MCP declarations are populated on first use.
+          body: null,
+          bodyLoaded: false,
+          mcpServers: [],
           source: layer,
           skillDir,
+          skillMdPath: skillMd,
+          skillFileBytes: stat.size,
+          skillFileMtimeMs: stat.mtimeMs,
         });
       } catch {
         // Skip malformed skill files
@@ -487,12 +536,149 @@ export class CLISkillLoader {
     }
   }
 
+  /**
+   * Materialize a descriptor's markdown body and embedded MCP declarations.
+   * Cache entries are invalidated by file size/mtime and never include content
+   * in provenance records.
+   */
+  materializeSkill(skill, context = {}) {
+    if (!skill || !skill.skillMdPath) {
+      throw new TypeError("A discovered skill descriptor is required");
+    }
+    const stat = fs.statSync(skill.skillMdPath);
+    const signature = `${stat.size}:${stat.mtimeMs}`;
+    let cached = this._bodyCache.get(skill.skillMdPath);
+    let cacheRead = false;
+    if (cached?.signature === signature) {
+      this._cacheStats.bodyCacheHits += 1;
+      cacheRead = true;
+    } else {
+      const content = fs.readFileSync(skill.skillMdPath, "utf-8");
+      const { body } = parseSkillMd(content);
+      cached = {
+        signature,
+        body,
+        mcpServers: parseSkillMcpServers(body),
+        rawChars: body.length,
+        estimatedTokens: estimateSkillTokens(body),
+      };
+      this._bodyCache.set(skill.skillMdPath, cached);
+      this._cacheStats.bodyCacheMisses += 1;
+    }
+
+    skill.body = cached.body;
+    skill.mcpServers = cached.mcpServers;
+    skill.bodyLoaded = true;
+    skill.skillFileBytes = stat.size;
+    skill.skillFileMtimeMs = stat.mtimeMs;
+
+    const prior = this._cacheStats.bodyLoads.get(skill.skillMdPath) || {
+      id: skill.id,
+      source: skill.source,
+      rawChars: cached.rawChars,
+      estimatedTokens: cached.estimatedTokens,
+      loads: 0,
+      cacheHits: 0,
+      loadedBecause: [],
+    };
+    prior.loads += 1;
+    if (cacheRead) prior.cacheHits += 1;
+    const reason = context.loadedBecause || "explicit";
+    if (!prior.loadedBecause.includes(reason)) prior.loadedBecause.push(reason);
+    this._cacheStats.bodyLoads.set(skill.skillMdPath, prior);
+
+    try {
+      this._contextLedger?.recordRead?.({
+        sessionId: context.sessionId || "unknown",
+        turnId: context.turnId || "unknown",
+        sourceType: "skill",
+        sourceId: skill.id,
+        permissionMode: context.permissionMode || "agent",
+        tokenCount: cached.estimatedTokens,
+        metadata: {
+          source: skill.source,
+          loadedBecause: reason,
+          cacheRead,
+          bodyIncluded: context.bodyIncluded === true,
+        },
+      });
+    } catch {
+      // Context observability must never make a valid skill unloadable.
+    }
+    return skill;
+  }
+
+  /** Record descriptor text that was actually returned to a model/tool caller. */
+  recordDescriptorUse(skills, context = {}) {
+    for (const skill of Array.isArray(skills) ? skills : []) {
+      const descriptorText = `${skill.id}\n${skill.description || ""}\n${skill.category || ""}`;
+      try {
+        this._contextLedger?.recordRead?.({
+          sessionId: context.sessionId || "unknown",
+          turnId: context.turnId || "unknown",
+          sourceType: "skill_descriptor",
+          sourceId: skill.id,
+          permissionMode: context.permissionMode || "agent",
+          tokenCount: estimateSkillTokens(descriptorText),
+          metadata: {
+            source: skill.source,
+            loadedBecause: context.loadedBecause || "list_skills",
+            bodyLoaded: skill.bodyLoaded === true,
+          },
+        });
+      } catch {
+        // Observability only.
+      }
+    }
+  }
+
+  /** Content-free cache/cost snapshot for `cc context --sources`. */
+  getCacheLedger() {
+    const descriptors = Array.isArray(this._cache) ? this._cache : [];
+    const descriptorChars = descriptors.reduce(
+      (sum, skill) =>
+        sum +
+        `${skill.id}\n${skill.displayName}\n${skill.description}\n${skill.category}`.length,
+      0,
+    );
+    const residentPaths = new Set(this._bodyCache.keys());
+    const lazyFileBytes = descriptors.reduce(
+      (sum, skill) =>
+        sum +
+        (residentPaths.has(skill.skillMdPath) ? 0 : skill.skillFileBytes || 0),
+      0,
+    );
+    const bodyLoads = Array.from(this._cacheStats.bodyLoads.values()).map(
+      (entry) => ({ ...entry, loadedBecause: [...entry.loadedBecause] }),
+    );
+    return {
+      descriptors: {
+        resident: descriptors.length,
+        scans: this._cacheStats.descriptorScans,
+        cacheHits: this._cacheStats.descriptorCacheHits,
+        rawChars: descriptorChars,
+        estimatedTokens: estimateSkillTokens(descriptorChars),
+      },
+      bodies: {
+        resident: this._bodyCache.size,
+        cacheHits: this._cacheStats.bodyCacheHits,
+        cacheMisses: this._cacheStats.bodyCacheMisses,
+        entries: bodyLoads,
+      },
+      savings: {
+        lazyFileBytes,
+        estimatedTokensAvoided: estimateSkillTokens(lazyFileBytes),
+      },
+    };
+  }
+
   /**
    * Load all skills from all layers, applying priority override
    * Higher-priority layers override same-name skills from lower layers.
    * @returns {object[]} Resolved skill list
    */
   loadAll(options = {}) {
+    this._cacheStats.descriptorScans += 1;
     // `cc agent --bare` (CC_SKILLS=0): no skill layer loads at all — cache the
     // empty result so getResolvedSkills stays cheap on every call.
     if (allSkillsDisabled(options)) {
@@ -552,7 +738,10 @@ export class CLISkillLoader {
    * @returns {object[]}
    */
   getResolvedSkills() {
-    if (this._cache) return this._cache;
+    if (this._cache) {
+      this._cacheStats.descriptorCacheHits += 1;
+      return this._cache;
+    }
     return this.loadAll();
   }
 
@@ -560,10 +749,16 @@ export class CLISkillLoader {
    * Get auto-activated persona skills
    * @returns {object[]} skills with category "persona" and activation "auto"
    */
-  getAutoActivatedPersonas() {
-    return this.getResolvedSkills().filter(
-      (s) => s.category === "persona" && s.activation === "auto",
-    );
+  getAutoActivatedPersonas(context = {}) {
+    return this.getResolvedSkills()
+      .filter((s) => s.category === "persona" && s.activation === "auto")
+      .map((skill) =>
+        this.materializeSkill(skill, {
+          ...context,
+          loadedBecause: context.loadedBecause || "persona_auto",
+          bodyIncluded: true,
+        }),
+      );
   }
 
   /**
@@ -571,6 +766,14 @@ export class CLISkillLoader {
    */
   clearCache() {
     this._cache = null;
+    this._bodyCache.clear();
+    this._cacheStats = {
+      descriptorScans: 0,
+      descriptorCacheHits: 0,
+      bodyCacheHits: 0,
+      bodyCacheMisses: 0,
+      bodyLoads: new Map(),
+    };
   }
 }
 

package/src/lib/skill-process-broker.js

@@ -2,6 +2,7 @@ import executionBroker from "./process-execution-broker/index.js";
 
 const defaultRunSync = executionBroker.spawnSync.bind(executionBroker);
 const defaultRunFileSync = executionBroker.execFileSync.bind(executionBroker);
+const defaultRun = executionBroker.spawn.bind(executionBroker);
 
 function skillIdentity(skill = {}) {
   const identity = String(
@@ -31,7 +32,11 @@ function declaresShellExecution(skill = {}) {
  */
 export function createSkillProcessBroker(
   skill,
-  { runSync = defaultRunSync, runFileSync = defaultRunFileSync } = {},
+  {
+    run = defaultRun,
+    runSync = defaultRunSync,
+    runFileSync = defaultRunFileSync,
+  } = {},
 ) {
   if (!declaresShellExecution(skill)) return null;
 
@@ -46,6 +51,14 @@ export function createSkillProcessBroker(
   });
 
   return Object.freeze({
+    run(file, args = [], options = {}) {
+      return run(file, args, {
+        ...options,
+        ...metadata,
+        shell: false,
+      });
+    },
+
     runSync(file, args = [], options = {}) {
       return runSync(file, args, {
         ...options,
@@ -64,6 +77,7 @@ export function createSkillProcessBroker(
 }
 
 export const _skillProcessDefaults = {
+  run: defaultRun,
   runSync: defaultRunSync,
   runFileSync: defaultRunFileSync,
 };

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

@@ -110,6 +110,11 @@ export class SubAgentContext {
     // symlinkDirectories } — only materialize the needed packages and reuse
     // approved dep dirs. null → full checkout (byte-identical default).
     this._worktreeOptions = options.worktreeOptions || null;
+    // Recovery lineage collected from the child agent-loop event stream.
+    // These are provider/runtime identifiers, not reconstructed log labels.
+    this._runId = null;
+    this._checkpointIds = [];
+    this._toolUseIds = [];
 
     // ── Isolated state ──────────────────────────────────────────────
     // Independent message history — never shared with parent
@@ -399,6 +404,22 @@ export class SubAgentContext {
       for await (const event of gen) {
         this._iterationCount++;
 
+        if (event.type === "run-started" && event.runId) {
+          this._runId = String(event.runId);
+        }
+        if (event.type === "checkpoint" && event.id) {
+          const checkpointId = String(event.id);
+          if (!this._checkpointIds.includes(checkpointId)) {
+            this._checkpointIds.push(checkpointId);
+          }
+        }
+        if (event.type === "tool-executing" && event.tool_use_id) {
+          const toolUseId = String(event.tool_use_id);
+          if (!this._toolUseIds.includes(toolUseId)) {
+            this._toolUseIds.push(toolUseId);
+          }
+        }
+
         if (event.type === "token-usage" && this._onUsage) {
           // Forward real usage to the spawner. A nested child's event already
           // carries its own attribution frame — preserve it (deepest wins).
@@ -604,6 +625,26 @@ export class SubAgentContext {
     }
   }
 
+  /**
+   * Serializable child→parent recovery lineage. Worktree paths are included
+   * for local restore UX; executable merge callbacks and tool payloads are not.
+   */
+  recoveryBinding(result = this.result) {
+    const worktree = result?.worktree || null;
+    return {
+      childAgentId: this.id,
+      parentAgentId: this.parentId || null,
+      traceId: this._runId,
+      parentTraceId: this._hookParentTraceId || null,
+      checkpointIds: [...this._checkpointIds],
+      toolUseIds: [...this._toolUseIds],
+      worktreeId:
+        worktree?.branch || this._worktreeBranch || null,
+      worktreePath:
+        worktree?.path || this._worktreePath || null,
+    };
+  }
+
   /**
    * 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
@@ -647,6 +688,7 @@ export class SubAgentContext {
       iterationCount: this._iterationCount,
       createdAt: this.createdAt,
       completedAt: this.completedAt,
+      recoveryBinding: this.recoveryBinding(),
       worktree: this._worktreePath
         ? { path: this._worktreePath, branch: this._worktreeBranch }
         : null,

package/src/lib/turn-binding-store.js

@@ -35,46 +35,85 @@ export const _deps = {
   readEvents: storeReadEvents,
 };
 
+export class TurnBindingPersistenceError extends Error {
+  constructor(operation, sessionId, cause) {
+    const detail = cause?.message || String(cause || "unknown persistence error");
+    super(`Turn binding ${operation} failed for ${sessionId}: ${detail}`, {
+      cause,
+    });
+    this.name = "TurnBindingPersistenceError";
+    this.code =
+      operation === "read"
+        ? "TURN_BINDING_READ_FAILED"
+        : "TURN_BINDING_PERSIST_FAILED";
+    this.operation = operation;
+    this.sessionId = sessionId;
+  }
+}
+
+function persistenceFailure(operation, sessionId, cause, failIfUnavailable) {
+  if (!failIfUnavailable) return false;
+  throw new TurnBindingPersistenceError(operation, sessionId, cause);
+}
+
 /**
  * Append the current binding table as a new chained event. Each call writes the
  * FULL table (append-only snapshot), so the newest event is authoritative — a
  * later `loadTurnBindingLog` never has to merge partial deltas across a chain
  * that a compaction could have truncated.
  *
- * Best-effort: a persistence failure must not crash the turn it is recording, so
- * the caller gets `false` instead of a throw.
+ * Turn/checkpoint binding is Critical state. Persistence fails closed by
+ * default; diagnostic callers may explicitly opt into advisory behavior.
  *
  * @param {string} sessionId
  * @param {TurnBindingLog|object} log  a TurnBindingLog or its toJSON() shape
+ * @param {{failIfUnavailable?:boolean}} [opts]
  * @returns {boolean} true when the snapshot was written
  */
-export function persistTurnBinding(sessionId, log) {
-  if (!sessionId || !log) return false;
-  const snapshot = log instanceof TurnBindingLog ? log.toJSON() : log;
-  if (!snapshot || !Array.isArray(snapshot.turns)) return false;
+export function persistTurnBinding(sessionId, log, opts = {}) {
+  const failIfUnavailable = opts.failIfUnavailable !== false;
+  if (!sessionId || !log) {
+    return persistenceFailure(
+      "write",
+      sessionId || "<missing-session>",
+      new TypeError("sessionId and binding log are required"),
+      failIfUnavailable,
+    );
+  }
   try {
+    const snapshot = log instanceof TurnBindingLog ? log.toJSON() : log;
+    if (!snapshot || !Array.isArray(snapshot.turns)) {
+      throw new TypeError("binding snapshot must contain a turns array");
+    }
     _deps.appendEvent(sessionId, TURN_BINDING_EVENT, snapshot);
     return true;
-  } catch {
-    // Persistence is advisory — never let it break the agent turn.
-    return false;
+  } catch (error) {
+    return persistenceFailure("write", sessionId, error, failIfUnavailable);
   }
 }
 
 /**
  * Rebuild the TurnBindingLog from the LATEST persisted snapshot in a session
- * transcript. Returns an empty log when the session has no binding event (or on
- * any read error) so callers can treat "never persisted" and "unreadable" alike.
+ * transcript. Returns an empty log when the session has no binding event.
+ * Read/corruption errors fail closed unless explicitly marked advisory.
  *
  * @param {string} sessionId
+ * @param {{failIfUnavailable?:boolean}} [opts]
  * @returns {TurnBindingLog}
  */
-export function loadTurnBindingLog(sessionId) {
+export function loadTurnBindingLog(sessionId, opts = {}) {
+  const failIfUnavailable = opts.failIfUnavailable !== false;
   let events = [];
   try {
     events = _deps.readEvents(sessionId) || [];
-  } catch {
-    return new TurnBindingLog();
+  } catch (error) {
+    const fallback = persistenceFailure(
+      "read",
+      sessionId || "<missing-session>",
+      error,
+      failIfUnavailable,
+    );
+    if (fallback === false) return new TurnBindingLog();
   }
   // Newest snapshot wins — scan backwards for the first well-formed one.
   for (let i = events.length - 1; i >= 0; i--) {
@@ -85,7 +124,17 @@ export function loadTurnBindingLog(sessionId) {
       e.data &&
       Array.isArray(e.data.turns)
     ) {
-      return TurnBindingLog.fromJSON(e.data);
+      try {
+        return TurnBindingLog.fromJSON(e.data);
+      } catch (error) {
+        const fallback = persistenceFailure(
+          "read",
+          sessionId || "<missing-session>",
+          error,
+          failIfUnavailable,
+        );
+        if (fallback === false) return new TurnBindingLog();
+      }
     }
   }
   return new TurnBindingLog();