role-os 2.7.1 → 2.9.0

package/src/specialist/capability-gate.mjs

@@ -0,0 +1,124 @@
+/**
+ * Capability gate — deterministic least-privilege (POLA) on IRREVERSIBLE tool calls. The one
+ * security primitive worth owning internally (memory: oversight-specialist-mint-strategy.md,
+ * 2026-06-08 posture): it bounds what any agent action can DO, so a WRONG verdict — an honest crew
+ * mistake OR (later) an adversarial flip — can never trigger an unauthorized irreversible action.
+ * The PREVENTIVE complement to NAMED_COMPENSATORS (which undoes an irreversible action; this stops
+ * the unauthorized one before it happens). Same action set, two halves.
+ *
+ * Grounded in the object-capability model / POLA and CaMeL (Debenedetti et al. 2025,
+ * arXiv:2503.18813: control/data-flow separation + capabilities, model UNMODIFIED). Deterministic,
+ * NO model — least-privilege, not an arms race.
+ *
+ * Safe by construction:
+ *   - OPT-IN, default OFF (ROLEOS_CAPABILITY_GATE). Disabled => never denies (pure no-op), so it can
+ *     never disrupt an existing flow until the director turns it on.
+ *   - Scoped to a SMALL gated set (the NAMED_COMPENSATORS irreversible-action list). Every non-gated
+ *     tool and every read-only tool is untouched.
+ *   - FAIL-CLOSED for the gated set: a gated action with NO matching capability grant is denied, with
+ *     a reason telling the director how to grant it. (Distinct from the conformance floor, which is
+ *     advisory / fail-open — a missed nonconformance is cheap; an unauthorized irreversible action is
+ *     not, so its asymmetry runs the other way.)
+ *
+ * The grant manifest (`.claude/role-os/capabilities.json`, director-authored) maps an action id to a
+ * grant, e.g.: { "npm:publish": { "granted": true, "scope": "@mcptoolshop/roll", "expires": "2026-07-01" } }
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const CAPABILITIES_FILE = ".claude/role-os/capabilities.json";
+
+/** Opt-in flag, mirroring conformanceConsultEnabled(). Default OFF. */
+export function capabilityGateEnabled() {
+  const v = process.env.ROLEOS_CAPABILITY_GATE;
+  return v === "1" || v === "true";
+}
+
+const _bash = (re) => (toolName, call) =>
+  toolName === "Bash" && typeof call?.command === "string" && re.test(call.command);
+
+/**
+ * The GATED SET — the irreversible / world-touching actions from the NAMED_COMPENSATORS standard.
+ * Each entry: { id, label, test(toolName, call) -> boolean }. Detection is deterministic + pattern-
+ * based and errs toward FLAGGING (a benign match just needs a one-line grant), never toward missing
+ * an irreversible action.
+ */
+export const GATED_ACTIONS = [
+  { id: "npm:publish", label: "npm/pnpm/yarn publish", test: _bash(/\b(?:npm|pnpm|yarn)\s+publish\b/) },
+  { id: "pypi:publish", label: "PyPI publish (twine/uv)", test: _bash(/\btwine\s+upload\b|\buv\s+publish\b/) },
+  { id: "gh:release", label: "gh release create", test: _bash(/\bgh\s+release\s+create\b/) },
+  { id: "gh:pr-create", label: "gh pr create", test: _bash(/\bgh\s+pr\s+create\b/) },
+  { id: "gh:repo-edit", label: "gh repo edit/delete", test: _bash(/\bgh\s+repo\s+(?:edit|delete)\b/) },
+  { id: "git:push", label: "git push", test: _bash(/\bgit\s+push\b/) },
+  { id: "pages:deploy", label: "GitHub Pages / gh-pages deploy", test: _bash(/\bgh-pages\b|\bpages\s+deploy\b/) },
+];
+
+/** Read the director's capability manifest, or {} if absent/malformed (=> nothing granted). */
+export function loadCapabilities(cwd) {
+  try {
+    const p = join(cwd, CAPABILITIES_FILE);
+    if (!existsSync(p)) return {};
+    const data = JSON.parse(readFileSync(p, "utf-8"));
+    return data && typeof data === "object" ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Is `actionId` granted (granted:true and not expired) in the manifest? */
+function _granted(manifest, actionId, now) {
+  const g = manifest && manifest[actionId];
+  if (!g || typeof g !== "object" || g.granted !== true) return false;
+  if (typeof g.expires === "string") {
+    const t = Date.parse(g.expires);
+    if (!Number.isNaN(t) && t < now) return false; // grant expired
+  }
+  return true;
+}
+
+/**
+ * Capability gate for a proposed tool call.
+ *
+ * OPT-IN: when disabled it ALWAYS returns { denied:false } (pure no-op). When enabled, a gated
+ * irreversible action is allowed ONLY if the manifest grants its capability id; otherwise it is
+ * DENIED (fail-closed) with a reason telling the director how to grant it.
+ *
+ * @param {string} cwd
+ * @param {string} toolName
+ * @param {object} toolInput
+ * @param {object} [opts] - { force } run the gate regardless of the env flag (tests);
+ *   { capabilities } inject a manifest (tests); { now } epoch ms for expiry (tests)
+ * @returns {{ denied: boolean, action?: string, reason?: string }}
+ */
+export function capabilityGate(cwd, toolName, toolInput, opts = {}) {
+  if (!opts.force && !capabilityGateEnabled()) return { denied: false };
+  let action;
+  try {
+    const call = toolInput && typeof toolInput === "object" ? toolInput : {};
+    action = GATED_ACTIONS.find((a) => a.test(toolName, call));
+    if (!action) return { denied: false }; // not an irreversible action -> allow
+    const manifest = opts.capabilities || loadCapabilities(cwd);
+    const now = typeof opts.now === "number" ? opts.now : Date.now();
+    if (_granted(manifest, action.id, now)) return { denied: false };
+    return {
+      denied: true,
+      action: action.id,
+      reason:
+        `Capability gate: "${action.label}" is an irreversible action requiring an explicit grant. ` +
+        `No capability "${action.id}" is granted in ${CAPABILITIES_FILE}. To authorize it, the ` +
+        `director adds {"${action.id}": {"granted": true}} (optionally with "scope"/"expires").`,
+    };
+  } catch {
+    // A gate that errors must not silently allow an irreversible action: if a gated action matched
+    // but the grant cannot be evaluated, fail CLOSED (deny). If nothing matched, allow.
+    if (action) {
+      return {
+        denied: true,
+        action: action.id,
+        reason: `Capability gate errored evaluating the grant for "${action.id}"; failing closed on an irreversible action.`,
+      };
+    }
+    return { denied: false };
+  }
+}

package/src/specialist/conformance-consult.mjs

@@ -0,0 +1,322 @@
+/**
+ * Conformance consult — the production seam that checks a proposed tool CALL against its TOOL's schema
+ * and documented contract, attaching an ADVISORY conformance verdict + receipt. Oversight wedge #1.
+ *
+ * Two-stage, mirroring prism's deterministic-floor + LLM-ceiling design:
+ *   1. DETERMINISTIC schema floor (L1 type / L2 required / L3 enum-range) — mechanical + infallible,
+ *      NO model. A floor violation short-circuits to `nonconformant` with the offending clause; the
+ *      LLM is never consulted for something a validator can prove.
+ *   2. LLM specialist (L4 semantic-contract / L5 intent-vs-action) via the proven dispatchSpecialist
+ *      fail-open gate — only when the floor passes.
+ *
+ * Safe by construction:
+ *   - OPT-IN, default OFF (ROLEOS_CONFORMANCE_CONSULT). Disabled => `{verdict: null}`, a pure no-op.
+ *   - ADVISORY. It returns a verdict + receipt; it never blocks a dispatch (callers decide).
+ *   - FAIL-OPEN to ABSTAIN (escalate), NEVER to `conformant`. The cost-asymmetric error is a false
+ *     `conformant` (a bad call waved through), so an unavailable/erroring LLM degrades to "I can't
+ *     verify the semantics — escalate", never to "looks fine".
+ */
+
+import { dispatchSpecialist } from "./dispatch.mjs";
+
+export const CONFORMANCE_ROLE = "Tool-Call Conformance";
+
+const _TYPE_OK = {
+  string: (v) => typeof v === "string",
+  integer: (v) => Number.isInteger(v),
+  number: (v) => typeof v === "number",
+  boolean: (v) => typeof v === "boolean",
+  array: (v) => Array.isArray(v),
+  object: (v) => v !== null && typeof v === "object" && !Array.isArray(v),
+};
+
+/**
+ * Deterministic schema floor (L1-L3). Returns { verdict: "nonconformant"|null, violations: string[] }.
+ * `null` verdict = no mechanical violation found -> defer to the LLM for the semantic contract.
+ */
+export function schemaFloor(tool, call) {
+  const params = Array.isArray(tool?.params) ? tool.params : [];
+  const args = call && typeof call === "object" ? call : {};
+  const byName = Object.fromEntries(params.map((p) => [p.name, p]));
+  const violations = [];
+  for (const p of params) {                                   // L2 required
+    if (p.required && !(p.name in args)) violations.push(`missing required '${p.name}'`);
+  }
+  for (const [k, v] of Object.entries(args)) {                // L1 type + L3 enum/range
+    const p = byName[k];
+    if (!p) continue;                                         // unknown arg: not floor-fatal (leave to contract)
+    if (p.type && _TYPE_OK[p.type] && !_TYPE_OK[p.type](v)) violations.push(`'${k}' should be ${p.type}`);
+    if (Array.isArray(p.enum) && !p.enum.includes(v)) violations.push(`'${k}' not in enum ${JSON.stringify(p.enum)}`);
+    if (typeof p.max === "number" && typeof v === "number" && v > p.max) violations.push(`'${k}' exceeds max ${p.max}`);
+  }
+  return violations.length ? { verdict: "nonconformant", violations } : { verdict: null, violations: [] };
+}
+
+/**
+ * Resolve a constraint OPERAND against the call args and (optional) structured state.
+ *  - a bare string  -> a CALL field reference (the common case)
+ *  - { value }      -> a literal
+ *  - { field }      -> an explicit call-field reference
+ *  - { state }      -> a structured-state key (object state only; prose state can't resolve -> undefined)
+ *  - { len }        -> the length of an array/object call field (cardinality)
+ *  - { enum }       -> a literal array
+ *  - anything else  -> the literal itself (number/array/boolean)
+ */
+export function resolveOperand(op, call, state) {
+  if (op && typeof op === "object" && !Array.isArray(op)) {
+    if ("value" in op) return op.value;
+    if ("state" in op) return state && typeof state === "object" ? state[op.state] : undefined;
+    if ("field" in op) return call ? call[op.field] : undefined;
+    if ("len" in op) {
+      const a = call ? call[op.len] : undefined;
+      if (Array.isArray(a)) return a.length;
+      if (a && typeof a === "object") return Object.keys(a).length;
+      return undefined;
+    }
+    if ("enum" in op) return op.enum;
+  }
+  if (typeof op === "string") return call ? call[op] : undefined; // bare = call field ref
+  return op; // numeric / array / boolean literal
+}
+
+const _NUM = (x) =>
+  typeof x === "number" ? x : (typeof x === "string" && x.trim() !== "" && !Number.isNaN(Number(x)) ? Number(x) : NaN);
+const _EPS = 1e-9;
+const _EQ = (a, b) => (typeof a === "number" && typeof b === "number" ? Math.abs(a - b) < _EPS : a === b);
+const _CMP = {
+  lt: (a, b) => a < b, le: (a, b) => a <= b, gt: (a, b) => a > b, ge: (a, b) => a >= b,
+  eq: _EQ, ne: (a, b) => !_EQ(a, b),
+};
+const _opLabel = (op) =>
+  op && typeof op === "object" ? ("len" in op ? `len(${op.len})` : "value" in op ? JSON.stringify(op.value) : "state" in op ? `state.${op.state}` : "field" in op ? op.field : JSON.stringify(op)) : String(op);
+
+function _collectSum(of, call) {
+  if (typeof of === "string") {
+    const v = call ? call[of] : undefined;
+    const arr = Array.isArray(v) ? v : v && typeof v === "object" ? Object.values(v) : null;
+    if (!arr) return null;
+    const nums = arr.map(_NUM);
+    return nums.some(Number.isNaN) ? null : nums;
+  }
+  if (Array.isArray(of)) { // a list of scalar field names to add
+    const nums = of.map((f) => _NUM(call ? call[f] : undefined));
+    return nums.some(Number.isNaN) ? null : nums;
+  }
+  return null;
+}
+
+/**
+ * Deterministic CONTRACT floor (computable L4). Evaluates `tool.constraints` — a small structured DSL
+ * for the relational/arithmetic contracts a 14B LLM does UNRELIABLY (summation, additive bounds,
+ * cardinality, ordering, mutual-exclusion) but a checker does perfectly. v0.3: the diagnosis from the
+ * v0.2 OOD dogfood was that the residual false-conformants are ALL computable — so they belong here,
+ * not in the model. A constraint that cannot be evaluated from (call + state) is SKIPPED (deferred to
+ * the LLM); the floor only ever PROVES a violation, never asserts conformance.
+ * Returns { verdict: "nonconformant"|null, violations: string[] }.
+ */
+export function contractFloor(tool, call, state) {
+  const constraints = Array.isArray(tool?.constraints) ? tool.constraints : [];
+  const args = call && typeof call === "object" ? call : {};
+  const v = [];
+  for (const c of constraints) {
+    if (!c || typeof c !== "object") continue;
+    switch (c.kind) {
+      case "cmp": {
+        const a = resolveOperand(c.left, args, state), b = resolveOperand(c.right, args, state);
+        if (a === undefined || b === undefined) break;
+        const fn = _CMP[c.op]; if (!fn) break;
+        if (["lt", "le", "gt", "ge"].includes(c.op)) {
+          const na = _NUM(a), nb = _NUM(b);
+          if (Number.isNaN(na) || Number.isNaN(nb)) break;
+          if (!fn(na, nb)) v.push(`${_opLabel(c.left)}(${na}) not ${c.op} ${_opLabel(c.right)}(${nb})`);
+        } else if (!fn(a, b)) {
+          v.push(`${_opLabel(c.left)}(${JSON.stringify(a)}) not ${c.op} ${_opLabel(c.right)}(${JSON.stringify(b)})`);
+        }
+        break;
+      }
+      case "sum": {
+        const vals = _collectSum(c.of, args);
+        const cap = _NUM(resolveOperand(c.vs, args, state));
+        if (vals === null || Number.isNaN(cap)) break;
+        const s = vals.reduce((x, y) => x + y, 0);
+        const fn = _CMP[c.op] || _CMP.eq;
+        if (!fn(s, cap)) v.push(`sum(${_opLabel(c.of)})=${s} not ${c.op} ${cap}`);
+        break;
+      }
+      case "present": { // exactly `count` (default 1) of the listed optional fields present
+        const want = c.count == null ? 1 : c.count;
+        const cnt = (c.fields || []).filter((f) => f in args).length;
+        if (cnt !== want) v.push(`expected exactly ${want} of [${(c.fields || []).join(", ")}] present, got ${cnt}`);
+        break;
+      }
+      case "requires": { // conditional co-requirement
+        const w = c.when || {};
+        const val = args[w.field];
+        const hit = "equals" in w ? val === w.equals : Array.isArray(w.in) ? w.in.includes(val) : w.field in args;
+        if (hit) {
+          const missing = (c.require || []).filter((f) => !(f in args));
+          if (missing.length) v.push(`when ${w.field}=${JSON.stringify(val)} requires [${missing.join(", ")}] present`);
+        }
+        break;
+      }
+      case "distinct": {
+        const vals = (c.fields || []).map((f) => args[f]);
+        if (vals.some((x) => x === undefined)) break;
+        const seen = new Set();
+        for (const x of vals) {
+          const k = x && typeof x === "object" ? JSON.stringify(x) : String(x);
+          if (seen.has(k)) { v.push(`fields [${(c.fields || []).join(", ")}] must be distinct (duplicate ${k})`); break; }
+          seen.add(k);
+        }
+        break;
+      }
+      case "member": {
+        const val = args[c.field], set = resolveOperand(c.in, args, state);
+        if (val === undefined || !Array.isArray(set)) break;
+        if (!set.includes(val)) v.push(`'${c.field}'=${JSON.stringify(val)} not in ${JSON.stringify(set)}`);
+        break;
+      }
+      case "char_at": {
+        // `offset` (default 0) adjusts for index bases — e.g. offset:-1 for a 1-based `position`.
+        const s = args[c.string], want = resolveOperand(c.equals, args, state);
+        const idx = _NUM(resolveOperand(c.index, args, state)) + (typeof c.offset === "number" ? c.offset : 0);
+        if (typeof s !== "string" || Number.isNaN(idx) || want === undefined) break;
+        const got = s.substr(idx, String(want).length);
+        if (got !== want) v.push(`${c.string}[${idx}..]='${got}' != expected '${want}'`);
+        break;
+      }
+      default:
+        break; // unknown kind: ignore (forward-compatible), never assert conformance
+    }
+  }
+  return v.length ? { verdict: "nonconformant", violations: v } : { verdict: null, violations: [] };
+}
+
+/** Read the wiring flag. Default OFF — flipping it on is a Mike-gated release decision. */
+export function conformanceConsultEnabled() {
+  const v = process.env.ROLEOS_CONFORMANCE_CONSULT;
+  return v === "1" || v === "true";
+}
+
+/** Serialize a tool (+intent, +state) into the EVIDENCE shape the watcher was TRAINED on. */
+export function evidenceFor(tool, intent, state) {
+  const schema = {};
+  for (const p of Array.isArray(tool?.params) ? tool.params : []) {
+    const { name, ...rest } = p;
+    schema[name] = rest;
+  }
+  let ev = `TOOL: ${tool?.name}\nCONTRACT: ${tool?.contract}\nPARAMS (JSON schema): ${JSON.stringify(schema)}`;
+  const st = state ?? tool?.state;
+  if (st) ev += `\nSTATE: ${typeof st === "string" ? st : JSON.stringify(st)}`;
+  if (intent) ev += `\nINTENT: ${intent}`;
+  return ev;
+}
+
+/** Serialize the proposed CALL into the trained CLAIM shape. */
+export function claimFor(tool, call) {
+  return `CALL: ${tool?.name}(${JSON.stringify(call ?? {})})`;
+}
+
+/**
+ * Enrich a tool definition with its constraints (+ structured state) from a rollout CATALOG keyed by
+ * tool name (tools/conformance-dataset/tool-constraints.json). The production gate calls this before
+ * consultConformance so the deterministic contract floor applies to any catalogued tool. A tool's own
+ * inline `constraints` win if present; an inline `state` is not overwritten.
+ */
+export function withToolConstraints(tool, catalog) {
+  const entry = tool && catalog ? catalog[tool.name] : null;
+  if (!entry) return tool;
+  return {
+    ...tool,
+    constraints: tool.constraints && tool.constraints.length ? tool.constraints : entry.constraints || [],
+    ...(entry.state_struct && tool.state == null ? { state: entry.state_struct } : {}),
+  };
+}
+
+/** Verdict comparator for shadow probes — normalizes string|{verdict} and compares the label. */
+export function conformanceAgree(s, c) {
+  const norm = (v) => (v && typeof v === "object" ? v.verdict : v);
+  return norm(s) === norm(c);
+}
+
+/**
+ * Check one tool-call's conformance. Deterministic floor first, then the LLM specialist via the
+ * fail-open gate. Advisory + opt-in + NEVER throws.
+ *
+ * @param {object} args
+ * @param {object} args.tool    { name, contract, params:[{name,type,required,enum?,max?}] }
+ * @param {object} args.call    the proposed arguments
+ * @param {string} [args.intent] the stated goal (enables the L5 intent check)
+ * @param {object} [opts]
+ * @param {boolean} [opts.enabled]   default: conformanceConsultEnabled()
+ * @param {object}  [opts.paths]     { registry, state, events } for dispatchSpecialist
+ * @param {string}  [opts.nowIso]
+ * @param {string}  [opts.traceId]
+ * @param {Function}[opts.httpFn]    injectable HTTP for the specialist call (tests)
+ * @param {object}  [opts.classifier]
+ * @param {object}  [opts.shadow]
+ * @returns {Promise<{verdict: string|null, source: string, receipt?: object, floor?: object}>}
+ */
+export async function consultConformance({ tool, call, intent, state } = {}, opts = {}) {
+  const { enabled = conformanceConsultEnabled(), paths, nowIso, traceId, httpFn, classifier, shadow } = opts;
+  if (!enabled) return { verdict: null, source: "disabled" };
+
+  const ts = nowIso || new Date().toISOString();
+  const st = state ?? tool?.state;
+
+  // 1) Deterministic floor — a PROVABLE violation never needs the LLM. Two rungs:
+  //    1a schema (L1 type / L2 required / L3 enum-range), 1b computable contract (relational/arithmetic
+  //    L4: ordering, sum-to-cap, additive bounds, cardinality, mutual-exclusion, ...). Either proving a
+  //    violation short-circuits to `nonconformant`; both only ever PROVE, never assert conformance.
+  let floor;
+  try {
+    const schema = schemaFloor(tool, call);
+    const contract = contractFloor(tool, call, st);
+    const violations = [...schema.violations, ...contract.violations];
+    floor = { verdict: violations.length ? "nonconformant" : null, violations,
+              schema: schema.violations, contract: contract.violations };
+  } catch (err) {
+    floor = { verdict: null, violations: [], error: String(err && err.message ? err.message : err) };
+  }
+  if (floor.verdict === "nonconformant") {
+    const reason = floor.contract && floor.contract.length && !(floor.schema && floor.schema.length)
+      ? "contract_violation" : "schema_violation";
+    return {
+      verdict: "nonconformant",
+      source: "floor",
+      floor,
+      receipt: {
+        schema: "roleos-specialist-receipt/v1", role: CONFORMANCE_ROLE, ts, source: "floor",
+        decision: { route: "floor", reason, detail: floor.violations.join("; ") },
+      },
+    };
+  }
+
+  // 2) Floor passed -> consult the LLM specialist (residual semantic-contract + L5 intent).
+  try {
+    const { result, receipt } = await dispatchSpecialist({
+      role: CONFORMANCE_ROLE,
+      input: { tool, call, intent, state: st, evidence: evidenceFor(tool, intent, st), claim: claimFor(tool, call) },
+      // SAFE fail-open: never "conformant" — an unverifiable semantic check escalates, not waves through.
+      claudeFn: async () => ({ verdict: "abstain", source: "floor-pass-llm-unavailable" }),
+      agreeFn: conformanceAgree,
+      traceId: traceId || `conformance-${ts}`,
+      nowIso: ts,
+      ...(paths ? { paths } : {}),
+      ...(httpFn ? { httpFn } : {}),
+      ...(classifier ? { classifier } : {}),
+      ...(shadow ? { shadow } : {}),
+    });
+    const verdict = result && typeof result === "object" && "verdict" in result ? result.verdict : result;
+    return { verdict: verdict ?? "abstain", source: receipt.source, receipt, floor };
+  } catch (err) {
+    // A conformance consult must never break the caller — escalate (abstain), never wave through.
+    return {
+      verdict: "abstain", source: "consult-error", floor,
+      receipt: {
+        schema: "roleos-specialist-receipt/v1", role: CONFORMANCE_ROLE, ts, source: "consult-error",
+        error: String(err && err.message ? err.message : err),
+      },
+    };
+  }
+}