chainlesschain 0.166.103 → 0.166.105

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/file-import-diagnostics.js

@@ -0,0 +1,246 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "acorn";
+
+export const FILE_IMPORT_LIMITS = Object.freeze({
+  contentBytes: 256 * 1024,
+  references: 64,
+  specifierChars: 512,
+});
+
+const JS_EXTENSION = /\.(?:js|mjs|cjs)$/;
+
+function inside(root, target) {
+  const relative = path.relative(root, target);
+  return (
+    relative === "" ||
+    (!path.isAbsolute(relative) &&
+      relative !== ".." &&
+      !relative.startsWith(`..${path.sep}`))
+  );
+}
+
+// Inspect each component before descending. Never stat/realpath a link, read
+// target contents, enumerate directories, or include OS errors in feedback.
+// As with other path-based Node APIs, this is not atomic against directory
+// replacement by another process. The caller supplies its authorized root.
+function inspectPath(root, target) {
+  if (!inside(root, target)) return "outside-workspace";
+  const components = path
+    .relative(root, target)
+    .split(path.sep)
+    .filter(Boolean);
+  let current = root;
+  for (let index = -1; index < components.length; index++) {
+    if (index >= 0) current = path.join(current, components[index]);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      return error?.code === "ENOENT" ? "missing" : "unavailable";
+    }
+    if (stat.isSymbolicLink()) return "symbolic-link";
+    if (index < components.length - 1 && !stat.isDirectory()) {
+      return "missing";
+    }
+    if (index === components.length - 1) {
+      return stat.isFile() ? "file" : "not-file";
+    }
+  }
+  return "not-file";
+}
+
+function inspectReference(root, target, kind) {
+  const state = inspectPath(root, target);
+  if (kind !== "require") return state;
+  // CommonJS can load directories and append extensions even when a request
+  // already has a suffix. Do not claim those uncertain cases are unresolved.
+  if (state === "not-file") return "commonjs-resolution";
+  if (state === "missing") {
+    for (const extension of [".js", ".json", ".node"]) {
+      const fallback = inspectPath(root, target + extension);
+      if (fallback !== "missing" && fallback !== "not-file") {
+        return "commonjs-resolution";
+      }
+    }
+  }
+  return state;
+}
+
+function parseSource(content, extension) {
+  const options = { ecmaVersion: "latest", locations: true };
+  if (extension === ".cjs") {
+    return parse(content, {
+      ...options,
+      sourceType: "script",
+      allowReturnOutsideFunction: true,
+    });
+  }
+  try {
+    return parse(content, { ...options, sourceType: "module" });
+  } catch (error) {
+    if (extension === ".mjs") throw error;
+    return parse(content, {
+      ...options,
+      sourceType: "script",
+      allowReturnOutsideFunction: true,
+    });
+  }
+}
+
+function collectReferences(ast) {
+  const references = [];
+  const pending = [{ node: ast, parent: null }];
+  let uncertainRequire = false;
+  let truncated = false;
+  while (pending.length) {
+    const { node, parent } = pending.pop();
+    // Conservative across the whole file: local bindings, assignments, and
+    // indirect uses make require's meaning uncertain. Imports remain useful.
+    if (
+      (node.type === "Identifier" &&
+        node.name === "require" &&
+        !(parent?.type === "CallExpression" && parent.callee === node)) ||
+      node.type === "WithStatement" ||
+      (node.type === "CallExpression" && node.callee?.name === "eval")
+    ) {
+      uncertainRequire = true;
+    }
+    let source;
+    let kind;
+    if (
+      node.type === "ImportDeclaration" ||
+      node.type === "ExportNamedDeclaration" ||
+      node.type === "ExportAllDeclaration" ||
+      node.type === "ImportExpression"
+    ) {
+      source = node.source;
+      kind = "import";
+    } else if (
+      node.type === "CallExpression" &&
+      !node.optional &&
+      node.callee?.type === "Identifier" &&
+      node.callee.name === "require" &&
+      node.arguments.length === 1
+    ) {
+      source = node.arguments[0];
+      kind = "require";
+    }
+    if (
+      source?.type === "Literal" &&
+      typeof source.value === "string" &&
+      /^\.{1,2}\//.test(source.value) &&
+      JS_EXTENSION.test(source.value) &&
+      !/[\\%?#:\u0000-\u001f\u007f]/.test(source.value)
+    ) {
+      if (references.length < FILE_IMPORT_LIMITS.references) {
+        references.push({ source, kind });
+      } else {
+        truncated = true;
+      }
+    }
+    const children = [];
+    for (const value of Object.values(node)) {
+      if (value?.type) children.push(value);
+      else if (Array.isArray(value)) {
+        for (const child of value) if (child?.type) children.push(child);
+      }
+    }
+    for (let index = children.length - 1; index >= 0; index--) {
+      pending.push({ node: children[index], parent: node });
+    }
+  }
+  return { references, uncertainRequire, truncated };
+}
+
+/**
+ * Best-effort feedback after an authorized write. Only explicit JS relative
+ * runtime references are checked, using supplied content and metadata inside
+ * workspaceRoot. This does not run code, resolve packages, or prove tests pass.
+ * Missing/inaccessible inputs and unsupported syntax never throw to the writer.
+ * line/column are one-based. uncheckedReferences never disclose resolved paths.
+ */
+export function collectFileImportDiagnostics(input) {
+  const result = {
+    status: "skipped",
+    diagnostics: [],
+    checkedReferences: 0,
+    uncheckedReferences: [],
+    truncated: false,
+  };
+  const skip = (reason) => ({ ...result, reason });
+  try {
+    const { filePath, content, workspaceRoot } = input ?? {};
+    if (
+      typeof filePath !== "string" ||
+      !filePath ||
+      filePath.length > 4096 ||
+      typeof workspaceRoot !== "string" ||
+      !workspaceRoot ||
+      workspaceRoot.length > 4096 ||
+      !path.isAbsolute(workspaceRoot) ||
+      typeof content !== "string"
+    ) {
+      return skip("invalid-input");
+    }
+    if (!JS_EXTENSION.test(filePath)) return skip("unsupported-file");
+    if (
+      content.length > FILE_IMPORT_LIMITS.contentBytes ||
+      Buffer.byteLength(content, "utf8") > FILE_IMPORT_LIMITS.contentBytes
+    ) {
+      return skip("content-limit");
+    }
+    const root = path.resolve(workspaceRoot);
+    const file = path.resolve(root, filePath);
+    if (!inside(root, file)) return skip("outside-workspace");
+    const fileState = inspectPath(root, file);
+    if (fileState !== "file") return skip(fileState);
+    let ast;
+    try {
+      ast = parseSource(content, path.extname(file));
+    } catch {
+      return skip("unsupported-syntax");
+    }
+    const { references, uncertainRequire, truncated } = collectReferences(ast);
+    result.status = "checked";
+    result.truncated = truncated;
+    for (const { source, kind } of references) {
+      const location = {
+        specifier: source.value.slice(0, FILE_IMPORT_LIMITS.specifierChars),
+        line: source.loc.start.line,
+        column: source.loc.start.column + 1,
+      };
+      let state;
+      if (source.value.length > FILE_IMPORT_LIMITS.specifierChars) {
+        state = "specifier-limit";
+      } else if (kind === "require" && uncertainRequire) {
+        state = "uncertain-require";
+      } else {
+        state = inspectReference(
+          root,
+          path.resolve(path.dirname(file), source.value),
+          kind,
+        );
+      }
+      if (state === "file" || state === "missing" || state === "not-file") {
+        result.checkedReferences++;
+        if (state !== "file") {
+          result.diagnostics.push({
+            source: "relative-import",
+            code: "UNRESOLVED_RELATIVE_IMPORT",
+            severity: "error",
+            filePath: file,
+            ...location,
+            message: `Relative import ${JSON.stringify(location.specifier)} does not point to an existing file from this file's directory. Verify the importing file's location before running tests.`,
+          });
+        }
+      } else {
+        result.uncheckedReferences.push({ ...location, reason: state });
+      }
+    }
+    return result;
+  } catch {
+    // Do not allow optional feedback to turn a completed mutation into failure.
+    return skip("unavailable");
+  }
+}

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/lib/transport-error-details.js

@@ -0,0 +1,83 @@
+import { types } from "node:util";
+
+const NAMES = new Set([
+  "Error",
+  "TypeError",
+  "AggregateError",
+  "AbortError",
+  "TimeoutError",
+  "ConnectTimeoutError",
+  "HeadersTimeoutError",
+  "BodyTimeoutError",
+  "SocketError",
+  "RequestAbortedError",
+  "ClientDestroyedError",
+  "ClientClosedError",
+]);
+const CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "EPIPE",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "CERT_HAS_EXPIRED",
+  "ABORT_ERR",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_ABORTED",
+  "UND_ERR_DESTROYED",
+  "UND_ERR_CLOSED",
+  "UND_ERR_REQ_CONTENT_LENGTH_MISMATCH",
+  "UND_ERR_RES_CONTENT_LENGTH_MISMATCH",
+]);
+
+// Never invoke accessors, coercion hooks or Proxy traps. Native Error.name is
+// inherited, so inspect a bounded number of prototype data descriptors.
+function data(object, key) {
+  for (let depth = 0; depth < 4 && object !== null; depth++) {
+    if (typeof object !== "object" || types.isProxy(object)) return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor) return "value" in descriptor ? descriptor.value : undefined;
+    object = Object.getPrototypeOf(object);
+  }
+  return undefined;
+}
+
+/** Optional diagnostic projection only: no messages, endpoints or request data. */
+export function transportErrorDetails(error) {
+  try {
+    const name = data(error, "name");
+    const code = data(error, "code");
+    let causeCode;
+    const seen = new Set([error]);
+    let cause = error;
+    for (let depth = 0; depth < 4; depth++) {
+      cause = data(cause, "cause");
+      if (!cause || seen.has(cause)) break;
+      seen.add(cause);
+      const value = data(cause, "code");
+      if (CODES.has(value)) {
+        causeCode = value;
+        break;
+      }
+    }
+    if (!CODES.has(code) && !causeCode) return undefined;
+    return {
+      kind: "transport",
+      ...(NAMES.has(name) ? { name } : {}),
+      ...(CODES.has(code) ? { code } : {}),
+      ...(causeCode ? { causeCode } : {}),
+    };
+  } catch {
+    // Diagnostics must never replace the original error or exit outcome.
+    return undefined;
+  }
+}