@sema-agent/core 7.6.0 → 7.6.2

package/dist/core/gate-fold.d.ts

@@ -0,0 +1,12 @@
+import { type GatePass } from "./runner/gate-exit.js";
+import type { ToolGateResult } from "./hooks.js";
+/**
+ * Run the fold over the pass: adjudicate, fold the hook-ask, tighten. Writes `req` (re-minted over the FINAL
+ * post-screen args), `decision`, `deniedBy` (a direct policy deny's attribution), `policyRewrite` and
+ * `tightenedBy`; reads `currentInput` and `hookAsk`. Async because the adjudication and the reversibility
+ * probe await; the station ORDER is this function's statement order. Ends by handing the pass to the group after
+ * it (`pass.afterFold`, the lanes) in the LAST station's own continuation — no suspension point between the
+ * fourth tighten and the org face's read of its rule state (see the seat's note) — and returns what that group
+ * returns.
+ */
+export declare function runGateFold(pass: GatePass): Promise<ToolGateResult>;

package/dist/core/gate-fold.js

@@ -0,0 +1,158 @@
+import { inlineUntrusted } from "./untrusted-text.js";
+import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
+import { traceHookCrash } from "./runner/gate-exit.js";
+function withProbeTimeout(p, ms, signal) {
+    if (ms === undefined && signal === undefined)
+        return p;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const done = (fn, v) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            fn(v);
+        };
+        const onAbort = () => done(reject, new Error("reversibilityProbe aborted (task ended)"));
+        const timer = ms !== undefined
+            ? setTimeout(() => done(reject, new Error(`reversibilityProbe timed out after ${ms}ms`)), ms)
+            : undefined;
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort);
+        p.then((v) => done(resolve, v), (err) => done(reject, err));
+    });
+}
+const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
+export async function runGateFold(pass) {
+    const { input, toolName, toolCallId, callSignal, ledger, notifier, adjudicate } = pass;
+    pass.req = { toolName, args: pass.currentInput, toolCallId };
+    pass.decision = adjudicate ? await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req)) : { action: "allow" };
+    {
+        const refusedBy = ledger.fromDecision(pass.decision);
+        if (refusedBy !== undefined)
+            pass.deniedBy = refusedBy;
+    }
+    if ((pass.decision.action === "allow" || pass.decision.action === "ask") && pass.decision.updatedInput !== undefined) {
+        pass.policyRewrite = pass.decision.updatedInput;
+    }
+    else if (pass.hookAsk?.updatedInput !== undefined) {
+        pass.policyRewrite = pass.hookAsk.updatedInput;
+    }
+    if (pass.decision.action === "allow" && pass.hookAsk) {
+        pass.decision = {
+            action: "ask",
+            ...(pass.hookAsk.message !== undefined ? { message: pass.hookAsk.message } : {}),
+            decisionReason: "hook",
+            ...(pass.hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+            ...(pass.hookAsk.updatedInput !== undefined ? { updatedInput: pass.hookAsk.updatedInput } : {}),
+        };
+    }
+    else if (pass.decision.action === "ask" && pass.hookAsk) {
+        const hookMessage = pass.hookAsk.message;
+        const foldedMessage = hookMessage !== undefined && hookMessage !== pass.decision.message
+            ? `${pass.decision.message !== undefined ? `${pass.decision.message} ` : ""}(a PreToolUse hook also asks: ${hookMessage})`
+            : pass.decision.message;
+        pass.decision = {
+            ...pass.decision,
+            decisionReason: "hook",
+            ...(foldedMessage !== undefined ? { message: foldedMessage } : {}),
+            ...(pass.hookAsk.requiresRealApproval === true ? { requiresRealApproval: true } : {}),
+        };
+    }
+    if (input.egress && pass.decision.action === "allow") {
+        pass.decision = {
+            action: "ask",
+            message: `tool "${toolName}" performs an external write (egress) — explicit approval required`,
+            decisionReason: "safety",
+        };
+        pass.tightenedBy = "safety";
+    }
+    const alreadyAsking = pass.decision.action === "ask";
+    if ((pass.decision.action === "allow" || alreadyAsking) && (input.irreversibility === "always" || input.irreversibility === "maybe")) {
+        let tighten = !alreadyAsking;
+        let probeReason;
+        let probeCause;
+        let probeMandated;
+        if (input.irreversibility === "maybe" && input.reversibilityProbe) {
+            let reversible = false;
+            const probeArgs = pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput;
+            const suppliedProbeMs = input.approvalTimeoutMs;
+            let probeTimeoutMs;
+            if (suppliedProbeMs === undefined) {
+                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
+            }
+            else if (Number.isFinite(suppliedProbeMs) && suppliedProbeMs >= 0 && suppliedProbeMs <= 2_147_483_647) {
+                probeTimeoutMs = suppliedProbeMs;
+            }
+            else {
+                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
+                traceHookCrash(input, new Error(`approvalTimeoutMs must be a non-negative finite number no greater than 2147483647 (got ${String(suppliedProbeMs)}) — the reversibilityProbe deadline falls back to the ${DEFAULT_PROBE_TIMEOUT_MS}ms default`), notifier);
+            }
+            try {
+                const verdict = await withProbeTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), probeTimeoutMs, input.abortSignal);
+                reversible = verdict?.reversible === true;
+                if (!reversible) {
+                    const raw = verdict?.reason;
+                    if (typeof raw === "string" && raw.trim().length > 0)
+                        probeReason = inlineUntrusted(raw, PROBE_REASON_MAX);
+                    probeCause = normalizeProbeCause(verdict?.cause);
+                    if (verdict?.mandated === true)
+                        probeMandated = true;
+                }
+            }
+            catch (err) {
+                reversible = false;
+                if (input.abortSignal?.aborted !== true)
+                    traceHookCrash(input, err, notifier);
+            }
+            tighten = !alreadyAsking && !reversible;
+        }
+        if (tighten) {
+            pass.decision = {
+                action: "ask",
+                message: `tool "${toolName}" performs an irreversible action — explicit approval required`,
+                decisionReason: "safety",
+                ...(probeReason !== undefined ? { probeReason } : {}),
+                ...(probeCause !== undefined ? { probeCause } : {}),
+                ...(probeMandated === true ? { probeMandated: true } : {}),
+            };
+            pass.tightenedBy = input.shellGated === true ? "shell_gate" : "safety";
+        }
+        else if (alreadyAsking && probeMandated === true && pass.decision.action === "ask") {
+            pass.decision = { ...pass.decision, probeMandated: true };
+        }
+    }
+    const breakerKnownOpen = (d) => {
+        try {
+            return d.breakerOpen();
+        }
+        catch {
+            return false;
+        }
+    };
+    if (input.peerMessage === true && pass.decision.action === "allow" && input.autoMode !== undefined && !breakerKnownOpen(input.autoMode.decider)) {
+        pass.decision = {
+            action: "ask",
+            message: `tool "${toolName}" sends a message to another agent — routed for classifier review in auto mode`,
+            decisionReason: "safety",
+        };
+        pass.tightenedBy = "safety";
+    }
+    if (pass.decision.action === "allow" && input.writeProtectionCheck !== undefined) {
+        const writeProtectedHit = input.writeProtectionCheck(toolName, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput);
+        if (writeProtectedHit !== null) {
+            pass.decision = {
+                action: "ask",
+                message: `tool "${toolName}" writes to a write-protected path (table entry "${writeProtectedHit.name}") — explicit approval required`,
+                decisionReason: "safety",
+            };
+            pass.tightenedBy = "safety";
+        }
+    }
+    return await pass.afterFold(pass);
+}

package/dist/core/gate-lanes.d.ts

@@ -0,0 +1,93 @@
+import { type GatePass } from "./runner/gate-exit.js";
+import type { OrgGateVerdict, PersistedRuleAnswer, PersistedRuleHit, ToolGateResult } from "./hooks.js";
+/**
+ * design/252 review r3 — read a foreign {@link OrgGateVerdict} the way the personal-rule answer is read:
+ * OWN DATA properties only, never the prototype chain, never an accessor.
+ *
+ * Unlike the personal-rule normalizer below, this one accepts ANY non-array object as the carrier —
+ * not only a plain record. The two seams tighten in opposite directions when a shape is refused: the
+ * personal lane is a LOOSENING seam, so refusing a class instance degrades toward asking; this answer
+ * carries the org's DENY, and folding a structurally valid `{status:"available", verdict:{behavior:
+ * "deny"}}` class instance into `unavailable` would LOOSEN it — from a deny nobody can approve into a
+ * real-approval ask a person can clear. A class instance's fields are its own data properties, so the
+ * own-data read below already gives the full pollution guarantee (inherited members never authorize);
+ * the prototype test added nothing here but the downgrade.
+ *
+ * The two seams are the same class of trust boundary and were not being read the same way. What that
+ * cost here is worse than on the personal lane, because this answer is GOVERNANCE:
+ *  · an inherited `revision` (a polluted `Object.prototype`) stamped a fabricated snapshot version onto
+ *    a human's approval request — a WRONG record, which is worse than an absent one;
+ *  · an inherited `verdict` invented an org rule, and with it an org ask or deny the lane never gave;
+ *  · an answer that is not a record at all read as "available, nothing to say", i.e. the governance
+ *    fail-open the availability contract exists to prevent.
+ * Anything this function cannot read as a well-formed answer becomes `unavailable` — the fail-CLOSED
+ * word, never the empty one.
+ */
+export declare function normalizeOrgGateVerdict(answer: unknown, unreadable: string): OrgGateVerdict;
+/**
+ * Normalize the accepted {@link ToolGateInput.persistedRules} answers into one reading.
+ *
+ * `{}` = a clean negative (no rule admits this call). `{ unreadable: true }` = the lane could not read
+ * its source. `{ hit }` = a match, whose `rules` is the non-empty coverage set (design/375). An answer
+ * outside every accepted shape — a number, `null`, an object with neither `rules` nor `unreadable`, an
+ * EMPTY `rules` array, the retired pre-375 `{ rule, dots? }` single-rule object — is read as a clean
+ * negative rather than a match: this is a LOOSENING seam, so an answer nobody can name degrades toward
+ * asking, never toward an allow built on it. All-or-nothing across the set's TEXTS for the same
+ * reason: a set with one unreadable member is a different (smaller) claim than the lane made, and a
+ * decision must not stand on a claim nobody made — one bad member drops the whole answer to the clean
+ * negative. Per-member DOTS stay individually optional (identity lost ⇒ `"not_reported"`, exactly the
+ * single-rule contract).
+ *
+ * The hit's dots are COPIED, not aliased. The array travels onto an ask that may sit in front of a
+ * person for a long time; a lane that retains and mutates its own array would otherwise change what the
+ * approver is looking at, and what an audit later reads, after the evidence was stamped.
+ */
+export declare function normalizePersistedRuleHit(hit: PersistedRuleAnswer): {
+    hit?: PersistedRuleHit;
+    unreadable?: true;
+    coverage?: readonly import("./permission-rule-model.js").SegmentCoverage[];
+};
+/**
+ * The mandate provenance of one call, judged from the SAME mark inputs the gate is driven with —
+ * the single source for "could a persisted allow rule clear this ask?". Allow rules silence the
+ * classifier's questions, never a mandated one, and this predicate is the mandated-family half of
+ * that boundary (the real-approval/governance half rides the decision's own `requiresRealApproval`
+ * bit, which the org layer stamps):
+ *  · `probeMandated` — this CALL's own reversibility probe declared its demotion STRUCTURAL
+ *    (`"probe_mandate"`), judged FIRST because it is the only per-call member here: the three below
+ *    are properties of the TOOL and are true of every call on the seat, so a mandate that is true of
+ *    this one call must not be shadowed by the tier that happens to carry it (#502: the built-in
+ *    shell probe raises it for a listed reader naming a path outside the session's roots — a boundary
+ *    the deployment declared, which is exactly what the classify tier alone cannot say);
+ *  · `egress` — the tool's own external-write mark, judged next: it is the tool's declaration even
+ *    when the coarse doctrine also installed a shell tier on the same seat;
+ *  · `shellGated` + tier `"always"` — the operator's per-call confirmation doctrine
+ *    (`"operator_always"`); the classify doctrine installs `"maybe"`, and THOSE asks stay the rule
+ *    lane's home turf (`undefined`) — that is the don't-ask-again main case, and the per-call member
+ *    above is deliberately the ONLY thing that carves a mandate out of it;
+ *  · a tool's OWN `"always"`/`"maybe"` irreversibility tier without the doctrine (`"tool_marks"`).
+ *
+ * Two consumers, one derivation: the gate's silencing arm (a matching rule is disclosed as shadowed
+ * instead of clearing the ask) and the runner's suggestion factory (a mandated ask offers no
+ * "stop asking me this" option — a rule minted from it would never clear it). A drift between the
+ * two would let a card offer a rule the lane then refuses to honor. The per-call member reaches both
+ * the same way every other per-call fact does: the gate stamps it on the surviving ask, the
+ * synchronous sites read it off the decision they spread, and the park leg threads its own parameter.
+ */
+export declare function persistedRuleMandateOf(marks: {
+    egress?: boolean;
+    shellGated?: boolean;
+    irreversibility?: "never" | "maybe" | "always";
+    /** #502: the surviving ask's engine-stamped `probeMandated` — see
+     *  {@link import("./types.js").ReversibilityVerdict.mandated}. */
+    probeMandated?: boolean;
+}): "operator_always" | "tool_marks" | "probe_mandate" | undefined;
+/**
+ * Run the lanes over the pass: the org layer over the fold's verdict, then — for a surviving ask — the rewrite
+ * merge, the rule lane, the stamp, the classifier, the sandbox leg, the parks, the content lane, the resolution
+ * and the edit chain. Returns the gate result when a park SUSPENDED the call (the three park sites' early
+ * exits), otherwise undefined with the pass holding a standing deny or allow for the exit. Reads every fold
+ * cell; writes `decision`, `deniedBy`, `currentInput`, `req.args`, `parkFailed`, `preToolContext`, and the
+ * ledger through its own methods. The station ORDER is this function's statement order.
+ */
+export declare function runGateLanes(pass: GatePass): Promise<ToolGateResult>;