@sema-agent/core 7.53.0 → 7.54.0

package/dist/core/runner/cross-boundary-lane.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The device lane's cross-boundary WIRING for one leg: the tree's shared state ref, the session record that carries the state from
+ * one leg of a session to the next, and the gate seat whose ONE obligation reading the station and both exits share.
+ *
+ * WHERE THE STATE LIVES. The tree's state is one object, reached from the tree's opaque token (`RunInternals.crossBoundaryTree`,
+ * `ToolExecuteContext.crossBoundaryTreeForChildren`) through this module alone; each leg joins into it what it knows at prepare (its
+ * environment's declaration, its session's newest record, its posture) and every bit an exit sets lands there before the call
+ * runs. Each leg's session holds a record (`CROSS_BOUNDARY_RECORD_TYPE`) of the state its content was produced under — written only
+ * for an armed tree: at prepare and at an exit (before the call runs) when the state grew past what the session already says, and at
+ * a leg's end (before a suspend's row is put, when the leg settles) also when conversation content follows the newest record. A
+ * write that fails refuses its call (or its row) on a governed tree; a prepare's or a settle's, and any write on a tree that is not
+ * governed, mints `config.cross_boundary_record_unwritten`. A record covers the content before it: a leg that takes over a session
+ * whose content no record covers (none on the branch, or after the newest), on an armed tree, reads that content as off-target.
+ *
+ * THE OBLIGATION of a call is read off three things at the moment it is asked ({@link crossBoundaryObligation}): the legs the
+ * call travels (its roster row's declaration, or what the dispatching code gives per call), whether the environment the `env`
+ * leg reaches declares itself the target NOW, and the tree's state NOW.
+ */
+import type { AgentTool } from "../../internal/harness.js";
+import type { SessionTreeEntry } from "../../internal/harness-types.js";
+import { type CrossBoundaryCheck, type CrossBoundaryPosture, type CrossBoundaryTreeToken } from "../cross-boundary-taint.js";
+import { type ToolRoster } from "../tool-roster.js";
+import type { RunnerDeps } from "../types.js";
+/** A new tree with no bit set, and the token that names it — the one mint of a token. */
+export declare function mintCrossBoundaryTree(): CrossBoundaryTreeToken;
+/** The tree a leg joins: the one its handed token names, or a new one (a root leg) — synchronous, so the phases that hand the token
+ *  down never wait on the session. A token the engine did not mint names no tree it can read: reported, and the leg's tree reads as
+ *  the strictest state. */
+export declare function joinedCrossBoundaryTree(handed: CrossBoundaryTreeToken | undefined, report: (message: string) => void): CrossBoundaryTreeToken;
+/** One leg's cross-boundary wiring (see the module header). */
+export interface CrossBoundaryLane {
+    /** The tree's token — the one the leg's children are handed. */
+    readonly token: CrossBoundaryTreeToken;
+    /** The station and the exits are ENGAGED on this leg: a posture is declared, the leg runs on a target, or its tree is governed —
+     *  each fixed at prepare, so no live consumer flips between two readings mid-run. */
+    readonly stationEngaged: boolean;
+    /** The gate seat, minted once the leg's roster and tool instances exist; undefined on a leg whose station is not engaged. */
+    seat(view: CrossBoundaryLegView): CrossBoundaryCheck | undefined;
+    /** The seat minted by {@link seat}, for the resumed call's exit. */
+    readonly check: CrossBoundaryCheck | undefined;
+    /** Write the record the tree's state owes this leg's session: the new entry's id, or undefined when nothing was owed (or, on a tree
+     *  that is not governed, the write failed and was reported); throws when it cannot be written on a governed tree. With `atLeaf` (a
+     *  suspend: a leg's end), the record also covers the content after the newest one and is written only as the child of that leaf
+     *  (the row then points at it). */
+    owe(atLeaf?: string): Promise<string | undefined>;
+    /** The tree is armed, so the session OWES the tree's record and a parked row says a reader must read it — on a tree that is not
+     *  governed a failed write leaves the record missing (the notice says so), and the reader then reads the content after the newest
+     *  record as off-target. */
+    recorded(): boolean;
+    /** The leg settles: the record that covers what it added is written, a failure reported loudly (the next leg then reads the
+     *  content after the newest record as off-target). */
+    settle(): Promise<void>;
+    /** How many times this leg's record writes have waited on the session store — a station that judged before an exit reads again
+     *  when the count moved across it (the exit's own form: judged again after a wait). */
+    storeWaits(): number;
+}
+/** What the seat reads per call: the live roster (the legs a row declares) and the mounted instances (a `"per_call"` resolver). */
+export interface CrossBoundaryLegView {
+    readonly tools: readonly AgentTool[];
+    readonly roster: {
+        readonly current: ToolRoster | undefined;
+    };
+}
+export interface CrossBoundaryLaneInput {
+    /** The tree this leg joins ({@link joinedCrossBoundaryTree}), or none — a new tree. */
+    token?: CrossBoundaryTreeToken;
+    /** The posture door's reading (`undefined` = undeclared). */
+    posture: CrossBoundaryPosture | undefined;
+    /** The run fold: this leg's environment declares the target, or the row it resumes was minted on one. */
+    externalContentTargetActive: boolean;
+    /** The leg's own environment — read for its CURRENT declaration at each judgment. */
+    env: {
+        readonly externalContentTarget?: boolean;
+    };
+    session: {
+        getBranch(): Promise<ReadonlyArray<SessionTreeEntry>>;
+        getLeafId(): Promise<string | null>;
+        appendCustomEntry(customType: string, data?: unknown): Promise<string>;
+    };
+    resumeLeg: boolean;
+    sessionId: string;
+    runId: string;
+    hostTaskId: string;
+    deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer">;
+}
+/** The leg's lane: the tree ref joined with what this leg knows, the session's record read and (when the state grew) written. */
+export declare function prepareCrossBoundaryLane(input: CrossBoundaryLaneInput): Promise<CrossBoundaryLane>;

package/dist/core/runner/cross-boundary-lane.js

@@ -0,0 +1,190 @@
+import { BOUNDARY_LEGS, CROSS_BOUNDARY_RECORD_TYPE, CROSS_BOUNDARY_TAINT_BITS, STRICTEST_CROSS_BOUNDARY_TREE, crossBoundaryObligation, crossBoundaryPostureUndeclaredNotice, crossBoundaryRecordUnwrittenNotice, crossBoundaryRecordData, crossBoundaryTreeCovers, crossBoundaryTreeGoverned, joinCrossBoundaryTree, readCrossBoundaryRecord, } from "../cross-boundary-taint.js";
+import { deliverEngineNotice } from "../engine-notice.js";
+import { policyCannotAnswer } from "../real-approval.js";
+import { thrownText } from "../thrown-value.js";
+import { rosterEntryNamed } from "../tool-roster.js";
+import { emitTrace } from "../trace.js";
+const TREE_STATE = new WeakMap();
+export function mintCrossBoundaryTree() {
+    const token = Object.freeze(Object.create(null));
+    TREE_STATE.set(token, { current: Object.freeze({}) });
+    return token;
+}
+export function joinedCrossBoundaryTree(handed, report) {
+    if (handed !== undefined && TREE_STATE.has(handed))
+        return handed;
+    const token = mintCrossBoundaryTree();
+    if (handed !== undefined) {
+        report("a cross-boundary tree token the engine did not mint was handed to this leg — it reads its tree as armed, observed and governed");
+        TREE_STATE.get(token).current = STRICTEST_CROSS_BOUNDARY_TREE;
+    }
+    return token;
+}
+const EVERY_LEG = Object.freeze([...BOUNDARY_LEGS]);
+const bitsOf = (t) => CROSS_BOUNDARY_TAINT_BITS.filter((b) => t[b] === true);
+function legsOfCall(view, legEnv, token, call, report) {
+    const roster = view.roster.current;
+    const row = roster !== undefined ? rosterEntryNamed(roster, call.toolName) : undefined;
+    if (row === undefined)
+        return { legs: EVERY_LEG, env: undefined };
+    if (row.boundaryLegs !== "per_call")
+        return { legs: row.boundaryLegs, env: legEnv };
+    const strictest = (why) => (report(`tool "${row.name}" declares its boundary legs per call, and its boundaryLegsFor ${why} — the call reads as every leg, off the target (the strictest reading)`), { legs: EVERY_LEG, env: undefined });
+    const resolve = view.tools.find((t) => t.name === row.name)?.boundaryLegsFor;
+    if (typeof resolve !== "function")
+        return strictest("is missing");
+    let given;
+    try {
+        given = resolve(call.args, { tree: token });
+    }
+    catch (err) {
+        return strictest(`threw (${thrownText(err)})`);
+    }
+    const { legs, env } = (typeof given === "object" && given !== null ? given : {});
+    if (!Array.isArray(legs) || !legs.every((l) => BOUNDARY_LEGS.some((b) => b === l)) || (env !== undefined && (typeof env !== "object" || env === null)))
+        return strictest("answered outside its type ({ legs: a list of boundary legs, env?: an environment })");
+    return { legs: legs, env: env ?? legEnv };
+}
+export async function prepareCrossBoundaryLane(input) {
+    const { posture, externalContentTargetActive, env, session, resumeLeg, sessionId, runId, hostTaskId, deps } = input;
+    const report = (message) => deps.onError?.(new Error(message), { phase: "config", sessionId });
+    const token = input.token ?? mintCrossBoundaryTree();
+    const ref = TREE_STATE.get(token);
+    if (ref === undefined)
+        throw new TypeError("prepareCrossBoundaryLane: the token names no tree (resolve it with joinedCrossBoundaryTree)");
+    let branch;
+    try {
+        branch = await session.getBranch();
+    }
+    catch (err) {
+        report(`the session's cross-boundary record could not be read (${thrownText(err)}) — this leg reads its tree as armed, observed and governed`);
+    }
+    const read = branch !== undefined ? readCrossBoundaryRecord(branch) : undefined;
+    if (read?.kind === "malformed")
+        report(`${read.why} — this leg reads its tree as armed, observed and governed`);
+    const fromRecord = read === undefined ? STRICTEST_CROSS_BOUNDARY_TREE : read.kind === "absent" ? {} : read.tree;
+    let recorded = read?.kind === "recorded" ? read.tree : {};
+    const own = { ...(externalContentTargetActive ? { targetExecutionArmed: true } : {}), ...(posture === "multi_tenant" ? { governed: true } : {}) };
+    let tree = joinCrossBoundaryTree(joinCrossBoundaryTree(ref.current, fromRecord), own);
+    if (tree.targetExecutionArmed === true && read !== undefined && read.kind !== "malformed" && read.uncoveredContent)
+        tree = joinCrossBoundaryTree(tree, { offTargetReadObserved: true });
+    ref.current = tree;
+    const stationEngaged = posture !== undefined || externalContentTargetActive || crossBoundaryTreeGoverned(tree);
+    const unwritten = (phase, err) => deliverEngineNotice(deps.onNotice, crossBoundaryRecordUnwrittenNotice({ sessionId, runId, phase, governed: crossBoundaryTreeGoverned(ref.current), cause: thrownText(err) }));
+    let writing = Promise.resolve();
+    let storeWaits = 0;
+    const write = (phase, atLeaf) => {
+        const next = writing.then(async () => {
+            let leafAt = atLeaf;
+            let cover = phase === "suspend" || phase === "settle";
+            let written;
+            for (;;) {
+                const state = ref.current;
+                if (state.targetExecutionArmed !== true)
+                    return written;
+                const grown = !crossBoundaryTreeCovers(recorded, state);
+                if (!grown && !cover)
+                    return written;
+                try {
+                    if (!grown) {
+                        storeWaits++;
+                        const now = readCrossBoundaryRecord((await session.getBranch()));
+                        if (now.kind !== "malformed" && !now.uncoveredContent) {
+                            cover = false;
+                            continue;
+                        }
+                    }
+                    if (leafAt !== undefined) {
+                        storeWaits++;
+                        if ((await session.getLeafId()) !== leafAt)
+                            throw new Error("the session moved past the row's leaf before its record could be written");
+                    }
+                    storeWaits++;
+                    const entryId = await session.appendCustomEntry(CROSS_BOUNDARY_RECORD_TYPE, crossBoundaryRecordData(state));
+                    if (typeof entryId !== "string" || entryId.length === 0)
+                        throw new Error(`the session store answered the record's append with no entry id (${typeof entryId})`);
+                    if (leafAt !== undefined && (storeWaits++, await session.getLeafId()) !== entryId)
+                        throw new Error("the record the session store appended is not the session's new leaf");
+                    recorded = state;
+                    written = entryId;
+                    if (leafAt !== undefined)
+                        leafAt = entryId;
+                    cover = false;
+                }
+                catch (err) {
+                    if (crossBoundaryTreeGoverned(ref.current))
+                        throw err;
+                    unwritten(phase, err);
+                    recorded = state;
+                    return written;
+                }
+            }
+        });
+        writing = next.catch(() => undefined);
+        return next;
+    };
+    const owe = (atLeaf) => write(atLeaf !== undefined ? "suspend" : "exit", atLeaf);
+    const trace = (phase, call) => emitTrace(deps.tracer, () => ({ kind: "permission.cross_boundary_taint", version: 1, taskId: hostTaskId, runId, phase, taint: bitsOf(ref.current), governed: ref.current.governed === true, ...(call !== undefined ? { toolName: call.toolName, ...(call.toolCallId !== undefined ? { toolCallId: call.toolCallId } : {}) } : {}), ts: Date.now() }));
+    if (tree.targetExecutionArmed === true) {
+        trace(resumeLeg ? "resume" : "prepare");
+        if (posture === undefined && tree.governed !== true)
+            deliverEngineNotice(deps.onNotice, crossBoundaryPostureUndeclaredNotice({ sessionId, runId, tree }));
+        await write("prepare").catch((err) => unwritten("prepare", err));
+    }
+    let check;
+    const lane = {
+        token,
+        stationEngaged,
+        get check() {
+            return check;
+        },
+        seat(view) {
+            if (!stationEngaged)
+                return undefined;
+            const obligationOf = (call, say) => {
+                const { legs, env: reached } = legsOfCall(view, env, token, call, say);
+                try {
+                    return crossBoundaryObligation(legs, reached?.externalContentTarget === true, ref.current);
+                }
+                catch (err) {
+                    say(`the cross-boundary obligation of "${call.toolName}" could not be read (${thrownText(err)}) — the call reads as every leg, off the target`);
+                    return crossBoundaryObligation(EVERY_LEG, false, ref.current);
+                }
+            };
+            const quiet = () => undefined;
+            check = {
+                obligation: (call) => obligationOf(call, report),
+                async exit(call, decidedBy) {
+                    for (;;) {
+                        const now = obligationOf(call, quiet);
+                        if (now.mandate && policyCannotAnswer({ action: "ask", requiresRealApproval: true }, decidedBy)) {
+                            return {
+                                kind: "unconfirmed",
+                                message: `tool "${call.toolName}" needs a person's confirmation: this run executes on a target device${ref.current.offTargetReadObserved === true ? " and has since let content from beyond it in, so a call that reaches beyond the device or back into it" : ", so a call that writes beyond the device"} is put to a person — this call was allowed by a configuration, not a person, and was not executed`,
+                            };
+                        }
+                        if (now.record && ref.current.offTargetReadObserved !== true) {
+                            ref.current = joinCrossBoundaryTree(ref.current, { offTargetReadObserved: true });
+                            trace("observed", call);
+                        }
+                        const judged = ref.current;
+                        try {
+                            await owe();
+                        }
+                        catch (err) {
+                            return { kind: "unrecorded", message: `tool "${call.toolName}" was not executed: the session's cross-boundary record could not be written before it ran (${thrownText(err)}) — on a governed tree a call that owes its record does not run without it; refused fail-closed` };
+                        }
+                        if (ref.current === judged)
+                            return undefined;
+                    }
+                },
+            };
+            return check;
+        },
+        owe,
+        storeWaits: () => storeWaits,
+        recorded: () => ref.current.targetExecutionArmed === true,
+        settle: () => write("settle").then(() => undefined, (err) => unwritten("settle", err)),
+    };
+    return lane;
+}

package/dist/core/runner/decide-continuation.d.ts

@@ -121,9 +121,9 @@ export declare function mintDecideRecord(cp: Checkpoint, facts: HostDecisionFact
 }): GateOutcome;
 /**
  * Capture-time domain check for a decide outcome's TEXT payloads — the review lanes' `editedPlan` /
- * `reason` and the approval lane's deny `reason`. All are persisted (the recorded winner's payload,
- * compared when an `env_failed` reopen replays it) and all are fenced into the model-facing
- * continuation reminder. The declared wire type is a string; a value outside it reads one way in this
+ * `reason`, the approval lane's deny `reason` and its allow `feedback`. All are persisted (the recorded winner's payload,
+ * compared when an `env_failed` reopen replays it) and all reach the model-facing continuation (the plan and the
+ * notes fenced into its reminder, the feedback as the person's own words). The declared wire type is a string; a value outside it reads one way in this
  * process and another after a JSON round-trip, and reaches the reminder as whatever its stringification
  * happens to be. Worse, the pre-CAS tag-hygiene check and the fence BOTH reach the value through
  * `String.prototype.replace`: an object carrying its own `replace` is therefore read twice and may
@@ -133,7 +133,7 @@ export declare function mintDecideRecord(cp: Checkpoint, facts: HostDecisionFact
  * is named in the message only — `CheckpointError`'s structured `detail.field` is a closed set covering
  * the approval lane's payload names, and widening it is a wire-surface change of its own.
  */
-export declare function assertOutcomeText(value: string | undefined, field: "editedPlan" | "reason"): void;
+export declare function assertOutcomeText(value: string | undefined, field: "editedPlan" | "reason" | "feedback"): void;
 /**
  * The continuation prompt for a resumed run. The vendored harness only exposes
  * `prompt(text)` (it always appends a user message — there is no "continue from tool results" entry), so

package/dist/core/runner/decide-continuation.js

@@ -8,6 +8,7 @@ import { facetOf, isGateKind, isQuestionGate } from "../pause-registry.js";
 import { humanRefusalSentence, policyCannotAnswer, screenApproverAttribution } from "../tool-policy.js";
 import { mintGateOutcome } from "./gate-exit.js";
 import { delimitUntrusted, REVIEWER_NOTE_MAX_BODY } from "../untrusted-text.js";
+import { writtenFeedback } from "./approval-feedback.js";
 import { engineCardOf } from "../tool-roster.js";
 export function resumeDecisionWasNegative(resume) {
     const o = resume.outcome;
@@ -52,7 +53,8 @@ export function sameWinner(incoming, persisted) {
         incoming.decision === persisted.decision &&
         deepJsonEqual(incoming.updatedInput, persisted.updatedInput) &&
         deepJsonEqual(incoming.answer, persisted.answer) &&
-        (persisted.reason === undefined || incoming.reason === persisted.reason));
+        (persisted.reason === undefined || incoming.reason === persisted.reason) &&
+        (persisted.feedback === undefined || writtenFeedback(incoming.feedback) === writtenFeedback(persisted.feedback)));
 }
 export function pendingContentAskCallId(cp) {
     return cp.pendingAction.kind === "tool_approval" && engineCardOf(cp.pendingAction) === "question" ? cp.pendingAction.toolCallId : undefined;

package/dist/core/runner/gate-exit.d.ts

@@ -118,12 +118,16 @@ export declare function createSettlementLedger(call: {
  */
 export declare function cloneObserverInput(input: unknown): unknown;
 /**
- * The input a gate exit decided on, as the call's record keeps it ({@link ToolGateResult.finalInput}): a deep,
- * FROZEN copy — never the live object the tool receives (a tool or a later layer writing into its own arguments
- * must not rewrite what the gate decided), and never writable by a reader; the deny observer gets a writable
- * {@link cloneObserverInput} of it. A graph `structuredClone` refuses (functions, handles) is kept as a shallow
- * copy frozen at its own top level only — its members are the live arguments' own, and freezing those would
- * freeze the call's input under the tool.
+ * The input a gate exit decided on, as the call's record keeps it ({@link ToolGateResult.finalInput}): a PLAIN-DATA PROJECTION of
+ * it, deep and FROZEN — never the live input (a tool, a later layer or the caller writing into its own arguments cannot rewrite
+ * what the gate decided), and never writable by a reader; the deny observer gets a writable {@link cloneObserverInput} of it. Read
+ * by the engine's one receipt ({@link RECORD_RECEIPT}), so nothing of the caller's runs: every record and list copied off its own
+ * enumerable data members, and every member that is not data replaced by a marker naming what it was (`[not recorded: …]`) — a
+ * Map, a Date, a class instance, a function or a bigint by a marker, never by reference; a symbol-keyed member's marker joins its
+ * container's list of them (`[not recorded: symbol-keyed members]`, under a key no data member holds). On an ALLOW exit too: the
+ * record is the projection while the call runs with the value itself — the gate's own copy (`ownArgs`: records and lists, a getter
+ * already read into data) recorded as it is save a bigint, the member closing a cycle and containers past the bound, which are
+ * markers. A value the receipt refuses whole (a Proxy, a function, a Map in place of the arguments) is recorded as its marker.
  */
 export declare function frozenInputSnapshot(input: unknown): unknown;
 /** What one `classic.PreToolUse` screening came to: an answer the receipt took (`undefined` = no opinion), or the
@@ -211,9 +215,10 @@ export interface GatePass {
      *  behind the policy's answer could not land in between. Returns the gate result (a park's suspension or the
      *  exit's record). Writer: the dispatch (`runToolGate`, which wires `runGateLanes`). Reader: the fold's tail. */
     readonly afterFold: (pass: GatePass) => Promise<ToolGateResult>;
-    /** borrowed-mutable — the FINAL args, always the pass's own immutable value (`ownArgs`): the model's input as taken at
-     *  the entry, rewritten by the phase-1 hook, by the policy rewrite on the ask path and by the exits' rewrite fold.
-     *  Writers: the dispatch (phase 1), the lanes, the exits. */
+    /** borrowed-mutable — the FINAL args, the pass's own immutable value (`ownArgs`): the model's input as taken at the entry,
+     *  rewritten by the phase-1 hook, by the policy rewrite on the ask path and by the exits' rewrite fold — save on a refusal
+     *  of a value nothing took ({@link untakenValueExit}), where it holds that value as given and only the deny exit's receipt
+     *  reads it. Writers: the dispatch (phase 1), the lanes, the exits. */
     currentInput: unknown;
     /** borrowed-mutable — the adjudication request. Minted over the pass's args so the record is whole from
      *  the first station, and RE-MINTED by the adjudication station over the FINAL post-screen args (the
@@ -341,9 +346,24 @@ export declare function engineFailClosedExit(pass: GatePass, reason: string): Pr
 /** The refusal sentence for args the gate could not take into its own copy (`ownArgs` refused them), naming what. */
 export declare const unownedArgsMessage: (subject: string, reason: string) => string;
 /**
- * The model's args could not be taken into the pass's own copy (a function, a shared buffer, a typed array): nobody judged
- * them, so nothing may run them. The single deny exit (the observer fires), in the policy layer's word — the value is the
- * deployment's own (a host driving the gate; the runner's calls are always clonable).
+ * A value nothing took — the model's args the pass could not take into its own copy (`ownArgs`: a function, a shared buffer, a
+ * typed array; {@link unownedArgsMessage}), or a resolution's edit no approval can be bound to (`bindableArgsOf`) — is refused
+ * here, through the single deny exit (the observer fires): nobody judged it, so nothing may run it, and it is no args of the
+ * call, so no reading of the tool's runs over it. The refusal carries no judged bytes (no `updatedInput`): the pass holds the
+ * value as given, and the deny exit's one receipt records it (`finalInput`, its plain-data projection — one marker when the
+ * receipt refuses it whole: a Map, a Date, a class instance, a Proxy or a function in place of the arguments). In the refusing
+ * layer's word: the resolution's for an edit (the lanes mint its `presentation_failed` record), the policy layer's for the
+ * model's args ({@link unownedArgsExit}).
+ */
+export declare function untakenValueExit(pass: GatePass, untaken: {
+    readonly value: unknown;
+    readonly message: string;
+    readonly deniedBy: Extract<DeniedBy, "policy" | "ask_resolution">;
+}): Promise<ToolGateResult>;
+/**
+ * The model's args could not be taken into the pass's own copy (a function, a shared buffer, a typed array): the dispatch seeded
+ * the pass with them as given, and they leave through the exit for a value nothing took, in the policy layer's word — the value is
+ * the deployment's own (a host driving the gate; the runner's calls are always clonable).
  */
 export declare function unownedArgsExit(pass: GatePass, reason: string): Promise<ToolGateResult>;
 /** The hook's OWN deny in phase 1. A PreToolUse hook deny does NOT fire `permissionDenied`

package/dist/core/runner/gate-exit.js

@@ -2,13 +2,15 @@ import { screenGateOutcome, SETTLEMENT_IS_REFUSAL } from "../gate-outcome.js";
 import { askFaceOf, classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
 import { wireOf } from "../tool-name-readings.js";
 import { isProtectedWrite } from "../tool-registry.js";
-import { attestationOf, decisionText } from "../tool-policy.js";
+import { attestationOf, decisionText, licenseCovers } from "../tool-policy.js";
 import { pathDenialCardOf } from "../../tools/fs/safety.js";
-import { boundInputHashOf } from "../canonical-json.js";
-import { argsAsTheToolReads, argsReadFrom } from "../effective-path-target.js";
+import { argsAsTheToolReads } from "../effective-path-target.js";
 import { askUnresolvableRemedySeat } from "../ask-unresolvable-notice.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { formatHookFeedback } from "../reminder-mint.js";
+import { types } from "node:util";
+import { receive } from "../mods/kernel/receive.js";
+import { describeBindingFault, MAX_DEPTH } from "../canonical-json.js";
 export function mintGateOutcome(facts) {
     const settlement = facts.settled !== undefined ? Object.freeze({ ...facts.settled.settlement, who: Object.freeze({ ...facts.settled.settlement.who }) }) : undefined;
     const attribution = facts.classifier !== undefined ? Object.freeze({ ...facts.classifier, ...(facts.classifier.fallback !== undefined ? { fallback: Object.freeze({ ...facts.classifier.fallback }) } : {}) }) : undefined;
@@ -82,12 +84,7 @@ export function createSettlementLedger(call) {
                     `(\`attestation\`), never a resolver's member; denied fail-closed rather than recording a settlement nobody can attribute`, contractRefusal(origin));
             }
             const edited = resolved.action === "allow" && resolved.updatedInput !== undefined;
-            const licensed = () => {
-                if (edited)
-                    return record.inputDigest === boundInputHashOf(resolved.updatedInput);
-                const askedDigest = boundInputHashOf(req.args);
-                return record.inputDigest === askedDigest && (resolved.presentedInput === undefined || boundInputHashOf(resolved.presentedInput) === askedDigest);
-            };
+            const licensed = () => edited ? licenseCovers(record.inputDigest, resolved.updatedInput) : licenseCovers(record.inputDigest, req.args) && (resolved.presentedInput === undefined || licenseCovers(record.inputDigest, resolved.presentedInput));
             const bound = record?.settlement !== undefined && record.origin === origin && sameClasses(record.classes, asked.classes) ? record.settlement : undefined;
             const refusal = bound !== undefined && SETTLEMENT_IS_REFUSAL[bound.kind] ? bound : undefined;
             if (resolved.action === "allow") {
@@ -128,7 +125,7 @@ export function createSettlementLedger(call) {
             return { decision, deniedBy: refusal ? "ask_resolution" : "policy" };
         },
         keepForBytes(runs) {
-            if (settled !== undefined && settled.licensed !== boundInputHashOf(runs) && settled.licensed !== boundInputHashOf(argsReadFrom(runs)))
+            if (settled !== undefined && !licenseCovers(settled.licensed, runs))
                 settled = undefined;
         },
         causeOf(decision) {
@@ -154,32 +151,63 @@ export function cloneObserverInput(input) {
         return input;
     }
 }
+const RECORD_RECEIPT = Object.freeze({ accessors: "refuse", depth: MAX_DEPTH, others: "refuse", contain: true, isProxy: (v) => types.isProxy(v) });
 export function frozenInputSnapshot(input) {
-    try {
-        return deepFreeze(structuredClone(input));
+    const received = receive(input, RECORD_RECEIPT);
+    if (!received.ok)
+        return notRecorded(input, received.fault);
+    const record = received.value;
+    const symbolMarkers = new Map();
+    for (const fault of received.faults ?? []) {
+        const above = fault.path.slice(0, -1);
+        const holder = memberAt(record, above);
+        const last = fault.path[fault.path.length - 1];
+        if (typeof holder !== "object" || holder === null || last === undefined)
+            continue;
+        const rawHolder = memberAt(input, above);
+        const symbolKeyed = fault.kind === "hidden" && (Object.hasOwn(holder, last) || typeof rawHolder !== "object" || rawHolder === null || !Object.hasOwn(rawHolder, last));
+        if (symbolKeyed) {
+            const listed = symbolMarkers.get(holder);
+            if (listed === undefined)
+                symbolMarkers.set(holder, [notRecorded(input, fault)]);
+            else
+                listed.push(notRecorded(input, fault));
+        }
+        else
+            Object.defineProperty(holder, last, { value: notRecorded(input, fault), enumerable: true, writable: true, configurable: true });
     }
-    catch {
-        return Object.freeze(Array.isArray(input) ? [...input] : input !== null && typeof input === "object" ? { ...input } : input);
+    for (const [holder, markers] of symbolMarkers) {
+        let key = "[not recorded: symbol-keyed members]";
+        while (Object.hasOwn(holder, key))
+            key += "'";
+        Object.defineProperty(holder, key, { value: markers, enumerable: true, writable: true, configurable: true });
     }
+    return freezeRecord(record);
 }
-function deepFreeze(value) {
-    if (value === null || typeof value !== "object" || Object.isFrozen(value))
-        return value;
-    Object.freeze(value);
-    for (const key of Reflect.ownKeys(value)) {
-        const d = Object.getOwnPropertyDescriptor(value, key);
-        if (d !== undefined && "value" in d)
-            deepFreeze(d.value);
+function freezeRecord(record) {
+    const pending = [record];
+    for (let at = pending.pop(); at !== undefined || pending.length > 0; at = pending.pop()) {
+        if (typeof at !== "object" || at === null || Object.isFrozen(at))
+            continue;
+        Object.freeze(at);
+        for (const member of Object.values(at))
+            pending.push(member);
     }
-    return value;
+    return record;
+}
+const notRecorded = (input, fault) => `[not recorded: ${describeBindingFault(input, fault)}]`;
+function memberAt(value, path) {
+    let at = value;
+    for (const key of path)
+        at = typeof at === "object" && at !== null ? at[key] : undefined;
+    return at;
 }
 const PARK_FAILURE_CAUSE_MAX = 600;
-function withParkFailureCause(reason, parkFailed) {
+function withParkFailureCause(reason, parkFailed, nobodyJudged) {
     if (parkFailed === undefined)
         return reason;
-    return (`${reason} — note: a durable approval park was attempted for this call FIRST and could not be minted ` +
-        `(${inlineUntrusted(parkFailed, PARK_FAILURE_CAUSE_MAX)}), so the refusal above is what the fallback had ` +
-        `left to say, not the reason the call stopped.`);
+    const note = `${reason} — note: a durable approval park was attempted for this call and could not be minted (${inlineUntrusted(parkFailed, PARK_FAILURE_CAUSE_MAX)})`;
+    return nobodyJudged ? `${note}; with nobody to judge the call, that is why it stopped — it can be issued again once its park can be minted.` : `${note}.`;
 }
 export function passAskFace(pass) {
     return askFaceOf(wireOf("gate.askFace", pass.req));
@@ -192,11 +220,15 @@ export async function engineFailClosedExit(pass, reason) {
     return { block: true, reason: formatHookFeedback(reason, input.reminderMark), gate, finalInput, preToolContext: pass.preToolContext };
 }
 export const unownedArgsMessage = (subject, reason) => `${subject} could not be taken into the gate's own copy (${reason}) — denied fail-closed`;
-export async function unownedArgsExit(pass, reason) {
-    pass.decision = { action: "deny", message: unownedArgsMessage(`the arguments of "${pass.toolName}"`, reason) };
-    pass.deniedBy = "policy";
+export async function untakenValueExit(pass, untaken) {
+    pass.currentInput = untaken.value;
+    pass.decision = { action: "deny", message: untaken.message };
+    pass.deniedBy = untaken.deniedBy;
     return await exitGate(pass);
 }
+export async function unownedArgsExit(pass, reason) {
+    return await untakenValueExit(pass, { value: pass.currentInput, message: unownedArgsMessage(`the arguments of "${pass.toolName}"`, reason), deniedBy: "policy" });
+}
 export function hookDenyExit(pass, deniedReason) {
     const { input } = pass;
     return {
@@ -236,11 +268,13 @@ export async function exitGate(pass) {
         const unresolvable = foldCause ?? unresolvableCauseOfSettlement(gate);
         const tableSeat = unresolvable !== undefined ? askUnresolvableRemedySeat(unresolvable) : undefined;
         const remedySeat = tableSeat === "absent" && input.askSeatForm === "declared_none" && pass.askClassification?.classes.has("content_question") !== true ? "declared_none" : tableSeat;
-        const remedy = remedySeat !== undefined ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: foldCause !== undefined ? ANCESTOR_UNRESOLVED_CLASSIFICATION : pass.askClassification, approverSeat: remedySeat, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
-        const denyReason = withParkFailureCause(`${decisionText(pass.decision) ?? `tool "${toolName}" denied by policy`}${remedy !== undefined ? ` — ${remedy}` : ""}`, pass.parkFailed);
+        const bindingRefusal = attestationOf(pass.decision, { toolCallId, toolName })?.bindingRefusal;
+        const remedy = bindingRefusal !== undefined ? undefined : remedySeat !== undefined ? headlessApprovalRemedy({ mode: input.permissionMode?.(), classification: foldCause !== undefined ? ANCESTOR_UNRESOLVED_CLASSIFICATION : pass.askClassification, approverSeat: remedySeat, coveredWrite: isProtectedWrite(pass.req), ...(pass.shellUnplacedOptions !== undefined ? { unplacedOptions: pass.shellUnplacedOptions } : {}) }) : undefined;
+        const denyReason = withParkFailureCause(`${decisionText(pass.decision) ?? `tool "${toolName}" denied by policy`}${remedy !== undefined ? ` — ${remedy}` : ""}`, pass.parkFailed, unresolvable !== undefined);
         if (unresolvable !== undefined) {
             const cause = unresolvable;
-            pass.notifier.notify(() => input.onAskUnresolvable?.({ toolName, toolCallId, cause, parkLaneExisted: pass.suspendAsk !== undefined, ...(remedy !== undefined ? { remedy } : {}) }), "toolGate.onAskUnresolvable");
+            const noticeRemedy = bindingRefusal ?? remedy;
+            pass.notifier.notify(() => input.onAskUnresolvable?.({ toolName, toolCallId, cause, parkLaneExisted: pass.suspendAsk !== undefined, ...(noticeRemedy !== undefined ? { remedy: noticeRemedy } : {}) }), "toolGate.onAskUnresolvable");
         }
         const finalInput = frozenInputSnapshot(pass.currentInput);
         await notifyPermissionDenied({
@@ -269,6 +303,14 @@ export async function exitGate(pass) {
             pass.currentInput = argsAsTheToolReads(pass.req, rw);
     }
     ledger.keepForBytes(pass.currentInput);
+    const crossBoundary = await input.crossBoundaryCheck?.exit({ toolName, args: pass.currentInput, toolCallId }, ledger.settled?.settlement.who.party === "person" ? "person" : "policy");
+    if (crossBoundary !== undefined) {
+        pass.decision = { action: "deny", message: crossBoundary.message, decisionReason: "safety" };
+        pass.deniedBy = crossBoundary.kind === "unconfirmed" ? "ask_resolution" : "policy";
+        if (crossBoundary.kind === "unconfirmed")
+            ledger.set({ settlement: { kind: "blanket_allow_refused", who: { party: "none" }, when: Date.now() }, origin: ledger.settled?.origin ?? "safety_tighten" });
+        return exitGate(pass);
+    }
     const release = pass.arbitration?.kind === "released" ? pass.arbitration : (() => { if (ledger.settled !== undefined)
         return undefined; const a = pass.arbitration === undefined ? input.ancestorArbitrationOf?.(toolCallId) : undefined; return a?.kind === "released" ? a : undefined; })();
     return {

package/dist/core/runner/inherited-ask-grants.js

@@ -1,6 +1,6 @@
 import { primaryActivityArg } from "../arg-summary.js";
 import { askApproverIdentity, attest, attestationOf } from "../tool-policy.js";
-import { boundInputHashOf } from "../canonical-json.js";
+import { exactBoundInputHashOf } from "../canonical-json.js";
 export function askGrantCovers(granted, asked) {
     return asked !== undefined && asked.length > 0 && granted.length > 0 && asked.every((c) => c === "ordinary" || granted.includes(c));
 }
@@ -34,5 +34,5 @@ export function consumeInheritedAskGrant(grants, onAsk, humanReviewRef, decision
     const settlement = attestationOf(grant.settled, req)?.settlement;
     if (settlement === undefined || decision.action !== "ask")
         return reused;
-    return attest(reused, req, { settlement, ...(decision.origin !== undefined ? { origin: decision.origin } : {}), ...(decision.classes !== undefined ? { classes: decision.classes } : {}), inputDigest: boundInputHashOf(grant.presented) });
+    return attest(reused, req, { settlement, ...(decision.origin !== undefined ? { origin: decision.origin } : {}), ...(decision.classes !== undefined ? { classes: decision.classes } : {}), inputDigest: exactBoundInputHashOf(grant.presented) });
 }

package/dist/core/runner/person-path-rows.d.ts

@@ -14,8 +14,8 @@
  *
  * Every read's outcome lands in the run's unit, per personal partition (the durable one — its user and project rows — and
  * the session one), and only where it is newer, by the order the reads STARTED: a read that answers late never replaces
- * a later one. The prepare read is the unit's first write. A reader that is not a call (the compaction summary's working-file
- * reader, the user-attachment seat's reader, the Artifact tool's local read, a read root's grant eligibility, the classifier's table, a language server's session read)
+ * a later one. The prepare read is the unit's first write. A reader that is not a call (the compaction's kept-tail
+ * normalizer, the user-attachment seat's reader (the compaction restore's too), the Artifact tool's local read, a read root's grant eligibility, the classifier's table, a language server's session read)
  * reads the unit's newest tables: while the rows the unit last took are compiling it waits for them (within
  * {@link PATH_TABLES_READY_BOUND_MS}), and a read of tables still compiling, or that could not be compiled, refuses —
  * never the tables of rows the unit has since replaced.

package/dist/core/runner/prepare-acquire-reconcile.d.ts

@@ -38,10 +38,9 @@ export interface PrepareAcquireReconcileInput {
      *  suspension point BEFORE reconcile) and `suspendedBatch` (wake-reconcile SKIPS those calls —
      *  they are resumed, not crash-interrupted). Absent for a fresh/non-durable run. */
     resume: Pick<PrepareResume, "leafId" | "suspendedBatch"> | undefined;
-    /** borrowed-readonly here — the safety scan's effect registry (its mutation-owner table lives on
-     *  {@link import("./prepare-safety-scan.js").PrepareSafetyScanResult}); reconcile classifies an
-     *  orphaned call's retry-safety by it. */
-    toolEffects: Map<string, ToolEffect>;
+    /** borrowed-readonly — the safety scan's pre-mount reading ({@link import("./prepare-safety-scan.js").PrepareSafetyScanResult.wakeEffects}):
+     *  this reconcile runs before any tool mounts, so a contested name reads its least repeat-safe member; it classifies an orphan's retry-safety. */
+    wakeEffects: Map<string, ToolEffect>;
     /** borrowed-readonly — subagent transcript persistence: the trusted spawner's placement
      *  declaration for THIS run's session ({@link RunInternals.sessionPlacement}), forwarded verbatim
      *  into the create-form acquire so the store creates the child's transcript into its subagent