chainlesschain 0.166.103 → 0.166.104

package/src/lib/evolution/skill-decision-projection.js

@@ -0,0 +1,211 @@
+import { types } from "node:util";
+import { createSkillDecisionRequest } from "../decision-layer/contracts.js";
+
+const MAX_BYTES = 256 * 1024;
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+// Capture descriptors before any authority await. Never evaluate source getters
+// or allow caller mutation to change committed evidence or outbound bytes.
+function snapshot(value) {
+  let nodes = 0;
+  let bytes = 0;
+  const seen = new Set();
+  const visit = (entry, depth) => {
+    if (++nodes > 4096 || depth > 16)
+      throw new TypeError("Skill decision input exceeds its structural budget");
+    if (typeof entry === "string") {
+      bytes += Buffer.byteLength(entry, "utf8");
+      if (bytes > MAX_BYTES)
+        throw new TypeError("Skill decision input exceeds its byte budget");
+      return entry;
+    }
+    if (
+      entry === null ||
+      typeof entry === "boolean" ||
+      (typeof entry === "number" && Number.isFinite(entry))
+    )
+      return entry;
+    if (
+      !entry ||
+      typeof entry !== "object" ||
+      types.isProxy(entry) ||
+      seen.has(entry)
+    )
+      throw new TypeError(
+        "Skill decision input must be acyclic plain JSON data",
+      );
+    const array = Array.isArray(entry);
+    if (
+      !array &&
+      ![Object.prototype, null].includes(Object.getPrototypeOf(entry))
+    )
+      throw new TypeError("Skill decision input must use plain objects");
+    const keys = Reflect.ownKeys(entry).filter(
+      (key) => !(array && key === "length"),
+    );
+    if (
+      array &&
+      (keys.length !== entry.length ||
+        keys.some((key, index) => key !== String(index)))
+    )
+      throw new TypeError("Skill decision arrays must be dense data");
+    seen.add(entry);
+    const output = array ? [] : Object.create(null);
+    for (const key of keys) {
+      const property = Object.getOwnPropertyDescriptor(entry, key);
+      if (
+        typeof key !== "string" ||
+        !property?.enumerable ||
+        !("value" in property)
+      )
+        throw new TypeError(
+          "Skill decision input cannot contain accessors or symbols",
+        );
+      bytes += Buffer.byteLength(key, "utf8");
+      if (bytes > MAX_BYTES)
+        throw new TypeError("Skill decision input exceeds its byte budget");
+      Object.defineProperty(output, key, {
+        value: visit(property.value, depth + 1),
+        enumerable: true,
+      });
+    }
+    seen.delete(entry);
+    return Object.freeze(output);
+  };
+  const result = visit(value, 0);
+  if (Buffer.byteLength(JSON.stringify(result), "utf8") > MAX_BYTES)
+    throw new TypeError("Skill decision input exceeds its byte budget");
+  return result;
+}
+
+function exact(value, keys) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.keys(value).sort().join("\0") !== [...keys].sort().join("\0")
+  )
+    throw new TypeError("Skill decision has an unsupported protocol shape");
+}
+
+function text(value) {
+  if (typeof value !== "string" || !value.length)
+    throw new TypeError("Skill decision requires nonempty text");
+}
+
+export function snapshotSkillDecisionPayload(value) {
+  const payload = snapshot(value);
+  exact(payload, ["state", "questions"]);
+  exact(payload.state, ["task", "candidates"]);
+  text(payload.state.task);
+  const candidates = payload.state.candidates;
+  if (
+    !Array.isArray(candidates) ||
+    candidates.length < 1 ||
+    candidates.length > 8
+  )
+    throw new TypeError("Skill decision requires bounded candidates");
+  candidates.forEach((candidate, index) => {
+    exact(candidate, [
+      "candidateId",
+      "name",
+      "description",
+      "category",
+      "tags",
+    ]);
+    if (candidate.candidateId !== `c${index + 1}`)
+      throw new TypeError("Skill decision candidate identity changed");
+    for (const key of ["name", "description", "category"]) text(candidate[key]);
+    if (!Array.isArray(candidate.tags) || candidate.tags.length > 32)
+      throw new TypeError("Skill decision tags are unbounded");
+    candidate.tags.forEach(text);
+  });
+  const ids = candidates.map(({ candidateId }) => candidateId);
+  exact(payload.questions, [
+    "needs_skill",
+    "best_skill",
+    ...ids.map((id) => `fits_${id}`),
+  ]);
+  for (const key of ["needs_skill", ...ids.map((id) => `fits_${id}`)]) {
+    exact(payload.questions[key], ["type", "instructions"]);
+    if (payload.questions[key].type !== "noul")
+      throw new TypeError("Skill decision question type changed");
+    text(payload.questions[key].instructions);
+  }
+  const choice = payload.questions.best_skill;
+  exact(choice, ["type", "instructions", "criteria"]);
+  if (choice.type !== "choice")
+    throw new TypeError("Skill decision question type changed");
+  text(choice.instructions);
+  exact(choice.criteria, [...ids, "none"]);
+  Object.values(choice.criteria).forEach(text);
+  return payload;
+}
+
+export function snapshotSkillDecisionRequest(value) {
+  const request = snapshot(value);
+  const rebuilt = createSkillDecisionRequest({
+    decisionId: request.decisionId,
+    ...request.binding,
+    query: request.payload?.state?.task,
+    candidates: request.candidates,
+  });
+  if (canonical(request) !== canonical(rebuilt))
+    throw new TypeError("Skill decision request identity or contract changed");
+  snapshotSkillDecisionPayload(request.payload);
+  return request;
+}
+
+function textPath(path) {
+  return (
+    /^state\.task$/u.test(path) ||
+    /^state\.candidates\.\d+\.(?:name|description|category|tags\.\d+)$/u.test(
+      path,
+    ) ||
+    /^questions\.best_skill\.criteria\.c[1-8]$/u.test(path)
+  );
+}
+
+export function buildSkillDecisionPayload(original, projection) {
+  if (
+    projection.visibility !== "model-visible" ||
+    projection.truncated ||
+    (projection.redactionSummary?.byType?.["content-truncation"] ?? 0) > 0
+  )
+    throw new Error("Skill decision projection is opaque or truncated");
+  const captured = snapshotSkillDecisionPayload(original);
+  const projected = snapshotSkillDecisionPayload(projection.content);
+  const compare = (before, after, path = "") => {
+    if (
+      typeof before === "string" &&
+      typeof after === "string" &&
+      textPath(path)
+    )
+      return;
+    if (before === null || typeof before !== "object") {
+      if (before !== after)
+        throw new Error("Skill decision projection changed protocol metadata");
+      return;
+    }
+    if (
+      !after ||
+      typeof after !== "object" ||
+      Array.isArray(before) !== Array.isArray(after) ||
+      Object.keys(before).sort().join("\0") !==
+        Object.keys(after).sort().join("\0")
+    )
+      throw new Error("Skill decision projection changed protocol structure");
+    for (const key of Object.keys(before))
+      compare(before[key], after[key], path ? `${path}.${key}` : key);
+  };
+  compare(captured, projected);
+  return projected;
+}

package/src/lib/evolution/skill-retrieval-revocation-authority.js

@@ -239,9 +239,19 @@ export async function openSkillRetrievalRevocationAuthority({
     ) {
       throw new Error("Retrieval revocation load is not authoritative");
     }
-    state = loaded.found
+    const loadedState = loaded.found
       ? verifySkillRetrievalRevocationState(loaded.state, tenantId)
       : null;
+    if (
+      state !== null &&
+      (loadedState === null ||
+        loadedState.revision < state.revision ||
+        (loadedState.revision === state.revision &&
+          loadedState.stateDigest !== state.stateDigest))
+    ) {
+      throw new Error("Retrieval revocation state regressed");
+    }
+    state = loadedState;
     return state;
   }
 
@@ -265,6 +275,10 @@ export async function openSkillRetrievalRevocationAuthority({
         receiptDigest: entry?.propagationRequestDigest ?? null,
       });
     },
+    async refresh() {
+      const current = await reload();
+      return current?.stateDigest ?? null;
+    },
     async invalidateRetrieval(input) {
       const request = normalizeRequest(input, tenantId);
       const contentDigest = request.dependency.digest;
@@ -351,7 +365,8 @@ export function captureSkillRetrievalRevocationReader(reader) {
   if (
     !readerBrand.has(reader) ||
     reader.schema !== SKILL_RETRIEVAL_REVOCATION_READER_SCHEMA ||
-    typeof reader.inspect !== "function"
+    typeof reader.inspect !== "function" ||
+    typeof reader.refresh !== "function"
   ) {
     throw new TypeError(
       "A branded Skill retrieval revocation reader is required",

package/src/lib/skill-loader.js

@@ -392,6 +392,7 @@ export class CLISkillLoader {
       throw new TypeError("reauthorizeSkill must be a function or null");
     }
     this._cache = null;
+    this._lastLoadOptions = null;
     bindSkillRuntimeAdmission(this, skillRuntimeAdmission, {
       required: skillRuntimeAdmissionRequired,
     });
@@ -1264,6 +1265,12 @@ export class CLISkillLoader {
    */
   loadAll(options = {}) {
     this._cacheStats.descriptorScans += 1;
+    // Preserve explicit layer policy for a later freshness scan. In particular,
+    // refreshing an opt-in decision must not re-enable a disabled skill layer.
+    this._lastLoadOptions = {
+      ...options,
+      ...(options.env ? { env: { ...options.env } } : {}),
+    };
     // `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)) {
@@ -1336,6 +1343,14 @@ export class CLISkillLoader {
     return this.loadAll();
   }
 
+  /** Rescan the same layers under the options used for the current cache. */
+  refreshResolvedSkills() {
+    // A failed scan must not leave a previous descriptor set available as if
+    // it were current on the next lookup.
+    this._cache = null;
+    return this.loadAll(this._lastLoadOptions ?? {});
+  }
+
   /**
    * Get auto-activated persona skills
    * @returns {object[]} skills with category "persona" and activation "auto"
@@ -1367,6 +1382,7 @@ export class CLISkillLoader {
    */
   clearCache() {
     this._cache = null;
+    this._lastLoadOptions = null;
     this._bodyCache.clear();
     this._cacheStats = {
       descriptorScans: 0,

package/src/repl/agent-repl.js

@@ -86,7 +86,9 @@ import {
 } from "../lib/session-host-snapshot.js";
 import { acquireSessionHostLease } from "../lib/session-host-lease.js";
 import {
+  normalizeSessionBudgetRootConfig,
   openProductionSessionBudgetRoot,
+  readProductionSessionBudget,
   sessionBudgetAdmissionError,
 } from "../lib/session-budget-production-root.js";
 import {
@@ -2265,9 +2267,25 @@ export function prepareReplJsonlResumeCandidate(sessionId, dependencies = {}) {
       error.code = "CC_REPL_SESSION_AUTHORITY_MISMATCH";
       throw error;
     }
+    const declaredBudget = dataDescriptorValue(
+      stateDescriptors,
+      "sessionBudgetRoot",
+      "REPL session host resume state",
+      { required: false },
+    );
+    const sessionBudgetRoot =
+      declaredBudget == null
+        ? null
+        : normalizeSessionBudgetRootConfig(
+            snapshotReplMessageValue(
+              declaredBudget,
+              "REPL session budget declaration",
+            ),
+          );
     return brandedFrozenCandidate(REPL_JSONL_RESUME_CANDIDATES, {
       ok: true,
       sessionId,
+      sessionBudgetRoot,
       rebuiltMessages,
       replayMessages: normalizedReplay.replayMessages,
       canonicalSystemMessages: normalizedReplay.canonicalSystemMessages,
@@ -2786,8 +2804,60 @@ export async function runReplStartupBoundary(options, startupDependencies) {
   ) {
     leaseScope.lease = acquireHostLease(leaseSessionId, { hostKind: "repl" });
   }
-  let workspaceOptions = options;
-  if (options.sessionBudgetRoot?.enabled === true) {
+  const injectedBudgetReader = dependencyDataFunction(
+    startupDependencies,
+    "readProductionSessionBudget",
+    null,
+  );
+  const sidecar =
+    leaseSessionId &&
+    (process.platform === "linux" || injectedBudgetReader !== null)
+      ? synchronousReplRecoveryValue(
+          (injectedBudgetReader || readProductionSessionBudget)(leaseSessionId),
+          "REPL budget sidecar",
+        )
+      : null;
+  let effectiveBudgetConfig = options.sessionBudgetRoot;
+  const declaredBudgetConfig = startupCandidate?.sessionBudgetRoot;
+  const requestedBudgetConfig = options.sessionBudgetRoot?.enabled
+    ? normalizeSessionBudgetRootConfig(options.sessionBudgetRoot)
+    : null;
+  if (startupCandidate?.ok === true) {
+    if (declaredBudgetConfig?.enabled) {
+      if (!sidecar) {
+        throw Object.assign(
+          new Error("budgeted REPL session is missing its budget sidecar"),
+          { code: "CC_SESSION_BUDGET_SIDECAR_REQUIRED" },
+        );
+      }
+      if (
+        requestedBudgetConfig &&
+        JSON.stringify(requestedBudgetConfig) !==
+          JSON.stringify(declaredBudgetConfig)
+      ) {
+        throw Object.assign(
+          new Error("REPL budget does not match its JSONL declaration"),
+          { code: "CC_SESSION_BUDGET_CONFIG_MISMATCH" },
+        );
+      }
+      effectiveBudgetConfig = declaredBudgetConfig;
+    } else if (requestedBudgetConfig || sidecar) {
+      throw Object.assign(
+        new Error("existing REPL session has no canonical budget declaration"),
+        { code: "CC_SESSION_BUDGET_JSONL_REQUIRED" },
+      );
+    }
+  } else if (sidecar) {
+    throw Object.assign(
+      new Error("budget sidecar has no canonical REPL session"),
+      { code: "CC_SESSION_BUDGET_JSONL_REQUIRED" },
+    );
+  }
+  let workspaceOptions = {
+    ...options,
+    sessionBudgetRoot: effectiveBudgetConfig,
+  };
+  if (effectiveBudgetConfig?.enabled === true) {
     if (!leaseSessionId || !leaseScope?.lease) {
       throw Object.assign(
         new Error(
@@ -2813,10 +2883,10 @@ export async function runReplStartupBoundary(options, startupDependencies) {
         "CC_REPL_STARTUP_DEPENDENCY_INVALID",
       );
     }
-    const root = openBudgetRoot(leaseSessionId, options.sessionBudgetRoot, {
+    const root = openBudgetRoot(leaseSessionId, effectiveBudgetConfig, {
       persist: true,
       signal: combineReplSignals(options.signal, leaseScope.lease.signal),
-      table: options.sessionBudgetRoot.table,
+      table: effectiveBudgetConfig.table,
     });
     if (
       root?.enabled !== true ||
@@ -2850,7 +2920,7 @@ export async function runReplStartupBoundary(options, startupDependencies) {
       throw admissionError;
     }
     budgetScope.root = root;
-    workspaceOptions = { ...options, ...root.options };
+    workspaceOptions = { ...workspaceOptions, ...root.options };
   }
   const trustedWorkspaceRoot = readCwd();
   return enterWorkspace(trustedWorkspaceRoot, () =>
@@ -2867,11 +2937,17 @@ export function startReplJsonlSession(
   options = {},
 ) {
   const requireDurable =
-    observabilityScope != null || options.requireDurable === true;
+    observabilityScope != null ||
+    options.requireDurable === true ||
+    options.sessionBudgetRoot?.enabled === true;
   try {
+    const budgetDeclaration = options.sessionBudgetRoot?.enabled
+      ? normalizeSessionBudgetRootConfig(options.sessionBudgetRoot)
+      : null;
     const sessionId = startSession(requestedId, {
       ...meta,
       ...(observabilityScope != null ? { observabilityScope } : {}),
+      ...(budgetDeclaration ? { sessionBudgetRoot: budgetDeclaration } : {}),
     });
     if (requireDurable && (typeof sessionId !== "string" || !sessionId)) {
       throw new Error("JSONL session creation returned no durable session id");
@@ -3966,7 +4042,10 @@ async function startAgentReplInWorkspaceOwned(
         options.sessionId || null,
         meta,
         options.observabilityScope,
-        { requireDurable: Boolean(_sessionBudget) },
+        {
+          requireDurable: Boolean(_sessionBudget),
+          sessionBudgetRoot: options.sessionBudgetRoot,
+        },
       );
       if (
         sessionId &&

package/src/runtime/agent-core.js

@@ -9289,24 +9289,122 @@ async function executeToolInner(
             ? null
             : captureSkillDecisionRuntime(skillDecisionRuntime);
         if (decisionRuntime !== null && routing.candidates.length > 0) {
-          const decision = await decisionRuntime.suggest({
-            query: args.query,
-            candidates: routing.candidates.slice(0, 5).map((candidate) => {
-              const descriptor = byDigest.get(candidate.digest);
+          const decisionInputsFor = (result, descriptors) => {
+            const descriptorsByDigest = new Map(
+              descriptors.map((skill) => [
+                skill.executionIdentity?.contentDigest,
+                skill,
+              ]),
+            );
+            return result.candidates.slice(0, 5).map((candidate) => {
+              const descriptor = descriptorsByDigest.get(candidate.digest);
               return {
-                id: candidate.id,
-                displayName: candidate.displayName,
-                description: descriptor?.description || candidate.displayName,
-                category: candidate.category,
-                digest: candidate.digest,
-                tags: Array.isArray(descriptor?.tags) ? descriptor.tags : [],
+                candidate: {
+                  id: candidate.id,
+                  displayName: candidate.displayName,
+                  description: descriptor?.description || candidate.displayName,
+                  category: candidate.category,
+                  digest: candidate.digest,
+                  tags: Array.isArray(descriptor?.tags)
+                    ? [...descriptor.tags]
+                    : [],
+                },
+                // Scope and compatibility are local routing inputs. They never
+                // leave the process, but changes invalidate the old advice.
+                identity: {
+                  namespace: candidate.namespace,
+                  version: candidate.version,
+                  paths: descriptor?.paths ?? null,
+                  os: descriptor?.os ?? null,
+                  capabilities: descriptor?.capabilities ?? null,
+                },
               };
-            }),
+            });
+          };
+          const decisionInputs = decisionInputsFor(routing, skills);
+          const snapshotFor = (result, inputs) =>
+            JSON.stringify({
+              candidates: inputs,
+              selectedDigest: result.selected?.digest ?? null,
+              conflicts: result.conflicts,
+            });
+          const decisionSnapshot = snapshotFor(routing, decisionInputs);
+          const contextRevision = `routing-${createHash("sha256")
+            .update(
+              JSON.stringify({
+                query: args.query,
+                category: args.category ?? null,
+                cwd,
+                turnId: turnId || toolCallId || "list-skills",
+                toolCallId: toolCallId ?? null,
+                decisionSnapshot,
+              }),
+            )
+            .digest("hex")}`;
+          const decision = await decisionRuntime.suggest({
+            query: args.query,
+            candidates: decisionInputs.map(({ candidate }) => candidate),
             turnId: turnId || toolCallId || "list-skills",
-            contextRevision: "skill-routing-v1",
+            contextRevision,
             signal,
           });
-          if (decision.visible) {
+          signal?.throwIfAborted();
+          // The provider result belongs to the captured candidate set. Recheck
+          // the persisted revocations and live loader before exposing advice.
+          await skillRetrievalRevocationReader?.refresh();
+          signal?.throwIfAborted();
+          const refreshedSkills =
+            typeof skillLoader.refreshResolvedSkills === "function"
+              ? await skillLoader.refreshResolvedSkills()
+              : skillLoader.getResolvedSkills();
+          signal?.throwIfAborted();
+          let currentSkills = await filterSkillsByCwd(
+            refreshedSkills.filter(skillAllowed),
+            cwd,
+          );
+          if (args.category) {
+            currentSkills = currentSkills.filter(
+              (s) => s.category.toLowerCase() === args.category.toLowerCase(),
+            );
+          }
+          // The vector index can change while the decision provider is in
+          // flight. Score the refreshed corpus again before comparing routing.
+          vector =
+            vectorAuthority === null
+              ? null
+              : await vectorAuthority.score({
+                  query: args.query,
+                  skills: currentSkills,
+                });
+          signal?.throwIfAborted();
+          const currentRouting = routeSkillDescriptors({
+            skills: currentSkills,
+            query: args.query,
+            target: { os: process.platform },
+            vectorScores: vector?.scores ?? null,
+            outcomeMetrics: outcomeAuthority.metrics,
+            revocationReader: skillRetrievalRevocationReader ?? null,
+            topK: Math.min(64, Math.max(1, currentSkills.length)),
+          });
+          const currentByDigest = new Map(
+            currentSkills.map((skill) => [
+              skill.executionIdentity?.contentDigest,
+              skill,
+            ]),
+          );
+          const currentDecisionSnapshot = snapshotFor(
+            currentRouting,
+            decisionInputsFor(currentRouting, currentSkills),
+          );
+          routing = currentRouting;
+          skills = routing.candidates
+            .map(({ digest }) => currentByDigest.get(digest))
+            .filter(Boolean);
+          signal?.throwIfAborted();
+          if (
+            decision.visible &&
+            currentDecisionSnapshot === decisionSnapshot
+          ) {
             routing = Object.freeze({
               ...routing,
               decisionSuggestion: Object.freeze({