@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/mods/kernel/site-rules.js

@@ -0,0 +1,296 @@
+import { describe } from "./events.js";
+import { describeFault, isPlainRecord, MODS_PAYLOAD_MODE, receive } from "./receive.js";
+export const MODS_VALUE_DEPTH = 1_000;
+const HANDED_MODE = Object.freeze({ ...MODS_PAYLOAD_MODE, depth: MODS_VALUE_DEPTH + 1, past: "refuse" });
+function payloadMode(isProxy) {
+    return isProxy === undefined ? HANDED_MODE : Object.freeze({ ...HANDED_MODE, isProxy });
+}
+const TOO_DEEP_TO_COMPARE = `too deep to compare (nested past ${MODS_VALUE_DEPTH} levels)`;
+function faultClause(fault) {
+    if (fault.kind !== "too-deep")
+        return describeFault(fault);
+    return `a value nested past ${MODS_VALUE_DEPTH} levels${fault.path.length > 0 ? ` under "${fault.path[0]}"` : ""}`;
+}
+export const MOD_FAILURE_CAUSES = Object.freeze(["threw", "timeout", "violation", "reentry"]);
+export const NEXT_IN_FLIGHT = Object.freeze({ inFlight: true });
+const TOO_DEEP = Object.freeze({ tooDeep: true });
+const OPEN = "open";
+function sameModValue(a0, b0, paired, depth0, homes) {
+    const stack = [];
+    const named = (r) => Object.keys(r).filter((k) => r[k] !== undefined);
+    const meet = (a, b, depth) => {
+        if (a === b || (Number.isNaN(a) && Number.isNaN(b)))
+            return 0;
+        if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+            return false;
+        let row = paired.get(a);
+        const met = row?.get(b);
+        if (met !== undefined) {
+            const height = met === OPEN ? 1 : met;
+            if (depth + height - 1 > MODS_VALUE_DEPTH)
+                throw TOO_DEEP;
+            return height;
+        }
+        if (depth > MODS_VALUE_DEPTH)
+            throw TOO_DEEP;
+        if (row === undefined)
+            paired.set(a, (row = new Map()));
+        row.set(b, OPEN);
+        if (!homes.has(b))
+            homes.set(b, a);
+        if (Array.isArray(a) || Array.isArray(b)) {
+            if (!Array.isArray(a) || !Array.isArray(b) || Object.getPrototypeOf(a) !== Array.prototype || Object.getPrototypeOf(b) !== Array.prototype || a.length !== b.length)
+                return false;
+        }
+        else if (!isPlainRecord(a) || !isPlainRecord(b))
+            return false;
+        const ra = a;
+        const rb = b;
+        const names = named(ra);
+        if (names.length !== named(rb).length)
+            return false;
+        stack.push({ a: ra, b: rb, row, names, depth, next: 0, height: 1 });
+        return undefined;
+    };
+    const top = meet(a0, b0, depth0);
+    if (top !== undefined)
+        return top;
+    for (;;) {
+        const f = stack[stack.length - 1];
+        if (f.next < f.names.length) {
+            const k = f.names[f.next++];
+            if (!Object.hasOwn(f.b, k))
+                return false;
+            const below = meet(f.a[k], f.b[k], f.depth + 1);
+            if (below === false)
+                return false;
+            if (below !== undefined)
+                f.height = Math.max(f.height, below + 1);
+            continue;
+        }
+        f.row.set(f.b, f.height);
+        stack.pop();
+        const holder = stack[stack.length - 1];
+        if (holder === undefined)
+            return f.height;
+        holder.height = Math.max(holder.height, f.height + 1);
+    }
+}
+export function pinnedKeyChanged(pinned, received, passed) {
+    const compared = comparePinned(pinned, received, passed);
+    return "broke" in compared ? compared.broke : undefined;
+}
+function comparePinned(pinned, received, passed) {
+    const paired = new Map();
+    const homes = new Map();
+    for (const key of pinned) {
+        try {
+            if (sameModValue(received[key], passed[key], paired, 1, homes) === false)
+                return { broke: { key } };
+        }
+        catch (err) {
+            return { broke: { key, unproven: err === TOO_DEEP ? TOO_DEEP_TO_COMPARE : "the comparison could not walk it to the end" } };
+        }
+    }
+    return { homes };
+}
+function engineObjects(held) {
+    const found = new Set();
+    const stack = Object.values(held);
+    while (stack.length > 0) {
+        const v = stack.pop();
+        if (typeof v !== "object" || v === null || found.has(v) || !Object.isFrozen(v))
+            continue;
+        if (!isPlainRecord(v) && !(Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype))
+            continue;
+        found.add(v);
+        for (const k of Object.keys(v))
+            stack.push(v[k]);
+    }
+    return found;
+}
+export function engineObjectsOnce(held) {
+    let found;
+    return () => (found ??= engineObjects(held));
+}
+const unprovenCopy = (key, why) => `next() handed on a copy of the pinned key "${key}" that is ${why}; a copy is taken only when proven the same`;
+export function handedOn(pinned, held, passed, engines, isProxy) {
+    const received = receiveRecord(passed, payloadMode(isProxy), engines);
+    if ("refusal" in received) {
+        const key = received.fault?.kind === "too-deep" ? received.fault.path[0] : undefined;
+        return { violation: key !== undefined && pinned.includes(key) ? unprovenCopy(key, TOO_DEEP_TO_COMPARE) : `next() takes the event object: ${received.refusal}` };
+    }
+    return pinnedHandOn(pinned, held, received.payload, engines);
+}
+export function pinnedHandOn(pinned, held, passed, engines) {
+    const compared = comparePinned(pinned, held, passed);
+    if ("broke" in compared) {
+        return { violation: compared.broke.unproven === undefined ? `next() changed the pinned key "${compared.broke.key}"` : unprovenCopy(compared.broke.key, compared.broke.unproven) };
+    }
+    if (pinned.every((k) => Object.hasOwn(passed, k) === Object.hasOwn(held, k) && Object.is(passed[k], held[k])))
+        return { payload: passed };
+    return { payload: rehomed(pinned, held, passed, compared.homes, engines ?? engineObjects(held)) };
+}
+function rehomed(pinned, held, passed, homes, engines) {
+    const swap = new Map();
+    for (const [copy, home] of homes)
+        if (copy !== passed && !engines.has(copy))
+            swap.set(copy, home);
+    const isContainer = (v) => typeof v === "object" && v !== null && !engines.has(v) && !swap.has(v) && (isPlainRecord(v) || (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype));
+    const holders = new Map();
+    const walked = new Set([passed]);
+    const stack = [passed];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        for (const k of Object.keys(node)) {
+            if (node === passed && pinned.includes(k))
+                continue;
+            const v = node[k];
+            if (v !== passed && !swap.has(v) && !isContainer(v))
+                continue;
+            const by = holders.get(v);
+            if (by === undefined)
+                holders.set(v, [node]);
+            else
+                by.push(node);
+            if (isContainer(v) && !walked.has(v)) {
+                walked.add(v);
+                stack.push(v);
+            }
+        }
+    }
+    const twins = new Map([[passed, {}]]);
+    const reach = [passed, ...swap.keys()];
+    while (reach.length > 0) {
+        for (const h of holders.get(reach.pop()) ?? []) {
+            if (twins.has(h))
+                continue;
+            twins.set(h, Array.isArray(h) ? [] : {});
+            reach.push(h);
+        }
+    }
+    const put = (to, k, v) => void Object.defineProperty(to, k, { value: v, enumerable: true, writable: true, configurable: true });
+    const moved = (v) => (typeof v !== "object" || v === null ? v : swap.has(v) ? swap.get(v) : (twins.get(v) ?? v));
+    for (const [from, to] of twins) {
+        const r = from;
+        for (const k of Object.keys(r)) {
+            if (from !== passed || !pinned.includes(k))
+                put(to, k, moved(r[k]));
+            else if (Object.hasOwn(held, k))
+                put(to, k, held[k]);
+        }
+        if (from === passed)
+            for (const k of pinned)
+                if (Object.hasOwn(held, k) && !Object.hasOwn(to, k))
+                    put(to, k, held[k]);
+        if (Array.isArray(from) && Array.isArray(to))
+            to.length = from.length;
+    }
+    for (const to of twins.values())
+        Object.freeze(to);
+    return twins.get(passed);
+}
+export function answerViolation(answer, check, e, by, below) {
+    if (answer === undefined)
+        return "returned no answer (return next(e) to pass the event on)";
+    if (check === undefined)
+        return undefined;
+    try {
+        return check(answer, e, by, below);
+    }
+    catch {
+        return "returned an answer the station cannot read";
+    }
+}
+const denyOf = (a) => (typeof a === "object" && a !== null && Object.prototype.hasOwnProperty.call(a, "deny") ? Reflect.get(a, "deny") : undefined);
+export function methodAnswerViolation(answer, _e, _by, below = []) {
+    if (!isPlainRecord(answer))
+        return "takes { value } or { deny }";
+    const hasValue = Object.prototype.hasOwnProperty.call(answer, "value");
+    const deny = denyOf(answer);
+    if (deny !== undefined) {
+        if (hasValue || typeof deny !== "string" || deny === "")
+            return "takes { value } or { deny: <reason> }";
+        return below.some((b) => denyOf(b) === undefined) ? "a deny after its next() was answered or while it still runs (deny in place of next)" : undefined;
+    }
+    if (!hasValue)
+        return "takes { value } or { deny }";
+    return below.includes(NEXT_IN_FLIGHT) ? "a value while its next() still runs (value in place of next)" : undefined;
+}
+export function matcherViolation(m) {
+    if (typeof m !== "object" || m === null || Array.isArray(m))
+        return `a matcher is an object of top-level fields, not ${describe(m)}`;
+    for (const [k, v] of Object.entries(m)) {
+        if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+            return `matcher field "${k}" is ${describe(v)}; a matcher value is a string, a number or a boolean`;
+    }
+    return undefined;
+}
+export function matcherMatches(m, e) {
+    if (m === undefined)
+        return true;
+    return Object.entries(m).every(([k, v]) => Object.prototype.hasOwnProperty.call(e, k) && e[k] === v);
+}
+function receiveRecord(v, mode, held) {
+    if (mode.isProxy !== undefined && typeof v === "object" && v !== null && mode.isProxy(v))
+        return { refusal: "the payload is a Proxy (refused before any of its traps runs)" };
+    if (!isPlainRecord(v))
+        return { refusal: `an event payload is a plain object, not ${describe(v)}` };
+    const r = receive(v, mode, held);
+    return r.ok ? { payload: Object.freeze(r.value) } : { refusal: `the payload holds ${faultClause(r.fault)}`, fault: r.fault };
+}
+export function receivePayload(v, isProxy, held) {
+    const r = receiveRecord(v, payloadMode(isProxy), held);
+    return "refusal" in r ? { refusal: r.refusal } : r;
+}
+export function receiveEvent(e) {
+    const r = receiveRecord(e, MODS_PAYLOAD_MODE);
+    return "refusal" in r ? { refusal: r.refusal } : r;
+}
+export function answerUpward(v) {
+    if (typeof v !== "object" || v === null || Object.isFrozen(v))
+        return v;
+    if (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype)
+        return Object.freeze([...v]);
+    return isPlainRecord(v) ? Object.freeze({ ...v }) : v;
+}
+export function receiveAnswer(answer, engines, isProxy) {
+    const r = receive(answer, payloadMode(isProxy), engines);
+    return r.ok ? { answer: r.value } : { refusal: `answered ${faultClause(r.fault)}` };
+}
+const DETACHED_MODE = Object.freeze({ accessors: "refuse", depth: Infinity, others: "as-is" });
+export function detachedCopy(e) {
+    const r = receive(e, DETACHED_MODE);
+    if (!r.ok)
+        throw new Error(`the observer's copy of the event could not be made: ${describeFault(r.fault)}`);
+    const copy = r.value;
+    const clones = new Map();
+    const walked = new Set([copy]);
+    const stack = [copy];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        for (const k of Object.keys(node)) {
+            const v = node[k];
+            if (typeof v !== "object" || v === null)
+                continue;
+            if (isPlainRecord(v) || (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype)) {
+                if (!walked.has(v)) {
+                    walked.add(v);
+                    stack.push(v);
+                }
+                continue;
+            }
+            if (!clones.has(v)) {
+                let own = v;
+                try {
+                    own = structuredClone(v);
+                }
+                catch {
+                }
+                clones.set(v, own);
+            }
+            Object.defineProperty(node, k, { value: clones.get(v), enumerable: true, writable: true, configurable: true });
+        }
+    }
+    return copy;
+}

package/dist/core/mods/stations.d.ts

@@ -0,0 +1,344 @@
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { AssistantMessage, Message, Model, Usage } from "../../internal/llm.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import { type PermissionResult, type ToolCallRequest } from "../tool-policy.js";
+import type { HookInvocationIdentity, PermissionDeniedPayload } from "../hooks.js";
+import type { PermissionMode } from "../ask-origin.js";
+import type { RunnerDeps } from "../runner-deps.js";
+import type { TaskSpec } from "../task-spec.js";
+import { type ModBus, type ModMountedHandler, type ModDispatchOutcome, type ModEventName, type ModEventPayload, type ModRegistration } from "./kernel/index.js";
+import { type SourcedOverlay } from "../../prompt-assembly/overlay.js";
+import type { BandId } from "../../prompt-assembly/catalog/schema.js";
+import type { ModParticipant } from "./kernel/dispatch.js";
+import { type EngineDollar, type ModelCompleteRequest, type ModelCompleteResult, type ModSeatView } from "./dollar.js";
+/**
+ * What the engine's core answers at the bottom of every classic chain: the engine itself has nothing to add.
+ * Frozen and empty, so it reads as "no opinion" in every classic station's answer form, and a handler that
+ * builds on it (`{ ...(await next(e)), additionalContext }`) builds a well-formed answer.
+ */
+export declare const ENGINE_CORE_ANSWER: Readonly<Record<string, never>>;
+/** The classic chains' bottom. */
+export declare function engineCore(): Readonly<Record<string, never>>;
+/** The leg's bus seat, as the stations read it. */
+export type LegModBus = Pick<ModBus, "hasHandlers" | "dispatch">;
+/**
+ * The id a delegated leg's events carry as `agentId` (the leg's task id — the key its `task_progress` frames
+ * and its parent's fleet row use). A top-level leg carries none.
+ */
+export declare function agentIdOf(identity: HookInvocationIdentity | undefined): string | undefined;
+/**
+ * The stop event a leg raises when its run would otherwise end: `classic.SubagentStop` on a delegated child's leg — the
+ * delegation fact, which a child resumed from its checkpoint keeps — else `classic.Stop`. Not the leg kind: a resumed
+ * leg's kind reads `"resume"` whoever it runs as.
+ */
+export declare function stopEventOf(identity: Pick<HookInvocationIdentity, "isDelegatedChild"> | undefined): "classic.Stop" | "classic.SubagentStop";
+/**
+ * The args as a judging handler receives them: the gate pass's own immutable value ({@link ownArgs} — the value itself when
+ * the gate already took it, which is every call the gate raises an event over), so the bytes a handler judges are the bytes
+ * that run — an in-place edit throws instead of moving what executes, or what a handler further down judges (a rewrite is
+ * an answer's `updatedInput`). A graph the copy refuses is handed as is (the gate refuses such args at its entry).
+ */
+export declare function judgedInputOf(args: unknown): unknown;
+/** One link of a leg's chain as a constraint entry names it: a registration the leg's admission mounted, with the handlers it hung. */
+export interface ModChainLink {
+    readonly registration: ModRegistration<EngineDollar>;
+    readonly handlers: readonly ModMountedHandler[];
+}
+/**
+ * A bus's chain identity: the registrations its admission MOUNTED (a refused one judges nothing there), in run order, each
+ * with the handlers it actually hung (pattern, matcher, observe, `.catch`, in hang order). Two legs that offered the same
+ * registrations but admitted — or hung — differently are different chains: an inherited entry collapses into a child's phase
+ * 1 only when the child mounted the very same. A handler's code is not compared (each leg's `register` builds its own
+ * closures); what it was hung on is. Every engine admission records it once ({@link chainOfBus}).
+ */
+export declare function admittedChainOf(bus: Pick<ModBus, "records" | "mounted">, spec: Pick<TaskSpec, "mods">, deps: Pick<RunnerDeps, "mods">): readonly ModChainLink[];
+/** The chain identity a bus's admission recorded, or `undefined` for a bus no engine admission mounted (its chain cannot be
+ *  read, so it is the same chain as none). */
+export declare function chainOfBus(bus: object): readonly ModChainLink[] | undefined;
+/** Whether two chains are the same links: the same registration objects, in the same order, having hung the same handlers. */
+export declare function sameModChain(a: readonly ModChainLink[], b: readonly ModChainLink[]): boolean;
+/**
+ * Whether the leg's chain JUDGES a tool call: a judging handler on either event a call is judged on — `classic.PreToolUse`
+ * (the gate's phase 1) or `tool.check` (the gate's verdict read). Such a chain is what a leg hands its children as a
+ * screening constraint, and what a child's own gate stands in for when it mounted the same.
+ */
+export declare function chainJudges(bus: LegModBus): boolean;
+/** Record what the constraint mint minted `policy` over. */
+export declare function recordScreeningChain(policy: object, chain: LegModBus): void;
+/** The chain a screening constraint was minted over, or `undefined` when the mint did not make this object. */
+export declare function screeningChainOf(policy: object): LegModBus | undefined;
+/** How an inherited installation's question is settled: under the context its installation froze (its approver, its durable
+ *  mandates, its classifier — the settlement its `classic.PreToolUse` ask takes in the fold), never at this leg's approver. An
+ *  allow carrying `updatedInput` is a person's approval of an edit; an ask is one the settlement floated (the call is marked for
+ *  the park). */
+export type InstallationAskSettlement = (ask: Extract<PermissionResult, {
+    action: "ask";
+}>, call: ToolCallRequest, signal: AbortSignal | undefined) => Promise<PermissionResult>;
+/** An inherited installation as a leg's gate raises `tool.check` on it: the bus that mounted that chain, which of its handlers
+ *  judge here, and how its question is settled. */
+export interface InheritedToolCheck {
+    readonly bus: LegModBus;
+    readonly judges: (p: ModParticipant) => boolean;
+    readonly settle: InstallationAskSettlement;
+}
+/** An inherited chain entry as its installation identity reads it: the policy (whose mint names the bus, whose admission names
+ *  the chain), the approver it froze, its two durable mandates, the environment it was installed against, its classifier. */
+export interface InstallationEntry {
+    readonly policy: object;
+    readonly onAsk?: unknown;
+    readonly durableMandate?: boolean;
+    readonly contentMandate?: boolean;
+    readonly hookEnv?: unknown;
+    readonly autoMode?: {
+        readonly decider: unknown;
+    };
+}
+/** A leg's own installation context: its chain identity, its frozen approver, its two durable mandates, the environment its
+ *  phase 1 runs in, its classifier instance. */
+export interface LegInstallation {
+    readonly chain: readonly ModChainLink[];
+    readonly onAsk: unknown;
+    readonly durableMandate: boolean;
+    readonly contentMandate: boolean;
+    readonly hookEnv: unknown;
+    readonly decider: unknown;
+}
+/**
+ * Whether an inherited entry IS a leg's installation — the ONE installation identity. The chain is read off the entry's own
+ * bus (the one its policy was minted over, as that bus's admission recorded it), never off a list the entry carries: an entry
+ * whose policy the mint did not make, or whose bus no engine admission mounted, is no leg's installation. The rest is the
+ * context its questions are settled in: the same approver ({@link askApproverIdentity}), the same two durable mandates, the
+ * same environment, the same classifier instance. Readers: chain assembly (a leg already on the chain is not appended again)
+ * and {@link standsInFor} (the fold's pass-through and the `tool.check` raise).
+ */
+export declare function sameInstallation(pc: InstallationEntry, leg: LegInstallation): boolean;
+/**
+ * Whether a leg's own gate stands in for an inherited entry: the leg's chain judges, and the entry is the leg's installation
+ * settled with no durable mandate — its phase 1 then judges the call with the same chain, and its questions go to the same
+ * approver under no mandate, so the entry adds nothing on either judging event. The fold's pass-through for the entry's
+ * `classic.PreToolUse` and the skip of its `tool.check` raise are this one test (an entry it does not hold for is judged under
+ * its own context on both: a second judgment, never a lost one).
+ */
+export declare function standsInFor(pc: InstallationEntry, leg: Omit<LegInstallation, "durableMandate" | "contentMandate">, legChainJudges: boolean): boolean;
+/** An inherited screening installation as the carrier check reads it: the bus its policy was minted over (absent when the mint
+ *  did not make the policy) and the chain the entry declares (its `mods`; absent when it declares none). The declaration is read
+ *  for one thing — a guard the leg cannot raise ({@link unraisableGuardsOf}); identity is read off the bus ({@link sameInstallation}). */
+export interface ScreeningInstallation {
+    readonly bus: LegModBus | undefined;
+    readonly chain: readonly ModChainLink[] | undefined;
+}
+/** The screening installations among a chain's entries, in the chain's order: every entry whose policy the mint made or that
+ *  declares a chain. */
+export declare function screeningInstallationsOf(entries: ReadonlyArray<{
+    readonly policy: object;
+    readonly mods?: readonly ModChainLink[];
+}>): readonly ScreeningInstallation[];
+/** Why an inherited chain cannot hold its guards, or `undefined`: an entry that names a judging `tool.check` handler beside a
+ *  policy the mint did not make has no bus to raise that guard on. Read where the chain enters a leg — before a resume's claim
+ *  and at the leg's prepare — so it is refused, never run without the guard. */
+export declare function unraisableGuardsOf(installations: readonly ScreeningInstallation[]): string | undefined;
+/**
+ * The inherited installations a leg's gate raises `tool.check` on after its own bus — the rule's one home. Every entry whose
+ * policy the mint made is one installation, raised whole in the chain's order (the order its `classic.PreToolUse` folds in),
+ * except one the leg's own gate stands in for (`standsIn` — the fold's pass-through test, {@link standsInFor}). Raised whole
+ * because a handler's answer depends on the chain it sits in (an outer handler may answer without calling `next`, or rule on
+ * what an inner one answered), so a registration the leg also mounts in a chain of its own judges again inside the ancestor's
+ * chain, as the PreToolUse constraint judges it (a second judgment, never a lost one). Each carries its entry's settlement of a
+ * question (`settleOf`): an installation's `ask` goes where its PreToolUse ask goes. Observe handlers never take part (a
+ * constraint carries no observer). An entry that cannot raise its guard is refused (`config.mods_invalid`, {@link unraisableGuardsOf}).
+ */
+export declare function inheritedToolChecks<E extends InstallationEntry & {
+    readonly mods?: readonly ModChainLink[];
+}>(entries: readonly E[], standsIn: (pc: E) => boolean, settleOf: (pc: E) => InstallationAskSettlement): readonly InheritedToolCheck[];
+/** The members every classic `e` of a leg carries: the identity envelope, the delegated leg's `agentId`, the leg's observed mode. */
+export declare function classicEventBase(identity: HookInvocationIdentity | undefined, permissionMode?: PermissionMode): ModEventPayload;
+/**
+ * Raise an observation event (a skip-on-failure event whose answer no station reads): no handler, no dispatch.
+ * Its failures are the bus's to report; a rejected dispatch (an engine fault, never a handler's) is swallowed —
+ * an observation must never change what it observes.
+ */
+export declare function observeClassic(bus: LegModBus, event: ModEventName, e: ModEventPayload, signal: AbortSignal | undefined): Promise<void>;
+/**
+ * Raise a classic event whose answer the station reads: `undefined` when no handler hangs on it (the station
+ * runs as if the bus were not there), else the dispatch outcome. A rejection is an engine fault, never a
+ * handler's (handlers fail into the outcome); a decision station fails closed on it, an observation swallows it.
+ */
+export declare function dispatchClassic(bus: LegModBus, event: ModEventName, e: ModEventPayload, options: {
+    readonly signal?: AbortSignal;
+    readonly checkAnswer?: (answer: unknown) => string | undefined;
+}): Promise<ModDispatchOutcome | undefined>;
+/** The answer form of a classic event whose answer is an object of optional string members (`block`, `additionalContext`, …). */
+export declare function stringMembersAnswer(event: string, members: readonly string[]): (answer: unknown) => string | undefined;
+/** The string members of an answer the station reads (a member of any other type reads as absent — the answer check has already refused it). */
+export declare function stringMembersOf<M extends string>(answer: unknown, members: readonly M[]): {
+    [K in M]?: string;
+};
+/** The clause a fail-closed station puts in its sentence for the handler that failed it: `crashed (extension "x" threw boom)`. */
+export declare function failedHandlerClause(f: Extract<ModDispatchOutcome, {
+    kind: "failed";
+}>): string;
+/**
+ * The PermissionDenied station: the leg's `classic.PermissionDenied` handlers, then a host's own raw observer (a host
+ * driving the tool gate itself) as one more observe handler of the same event on a bus of its own — so every observer
+ * of a deny runs under that station's columns (the handler's budget, skipped on a failure, a short grace past an
+ * abort) and none can hold the deny it reports. The raw observer's failure goes to `onHostObserverFailure`.
+ */
+export declare function observePermissionDenied(input: {
+    readonly legBus: LegModBus | undefined;
+    readonly hostObserver: ((payload: PermissionDeniedPayload) => void | Promise<void>) | undefined;
+    readonly payload: PermissionDeniedPayload;
+    readonly signal: AbortSignal | undefined;
+    readonly onHostObserverFailure: (err: Error) => void;
+}): Promise<void>;
+/** What a `classic.UserPromptSubmit` screen came to, as the four entrances read it. */
+export type PromptScreen = {
+    readonly kind: "answered";
+    readonly block?: string;
+    readonly additionalContext?: string;
+} | Extract<ModDispatchOutcome, {
+    kind: "failed";
+}> | {
+    readonly kind: "aborted";
+};
+/**
+ * Raise `classic.UserPromptSubmit` (undefined when no handler hangs on it). A decision event: a handler that throws,
+ * runs past its budget or breaks the site's contract ends the screen `failed`, and every entrance fails closed on it;
+ * a cancelled screen ends `aborted` at once. A dispatch the engine itself could not run is `failed` too.
+ */
+export declare function screenUserPrompt(bus: LegModBus, e: ModEventPayload, signal: AbortSignal | undefined): Promise<PromptScreen | undefined>;
+/** The three words a `tool.check` verdict speaks. */
+export declare const TOOL_CHECK_DECISIONS: readonly ["allow", "ask", "deny"];
+export type ToolCheckDecision = (typeof TOOL_CHECK_DECISIONS)[number];
+/**
+ * The gate's standing verdict as the bottom of the `tool.check` chain answers it — what a handler reads from `next(e)`.
+ * Never `deny` (a standing refusal raises nothing). On an ask: its classes, and `mandated` — true when an `allow`
+ * answer cannot clear it at this point of the gate. `ceiling` mirrors `e.ceiling`. Read-only metadata: the gate reads
+ * the answer's `decision` and `reason` and nothing else of it.
+ */
+export interface ToolCheckProjection {
+    readonly decision: "allow" | "ask";
+    readonly reason?: string;
+    readonly classes?: readonly string[];
+    readonly mandated?: boolean;
+    readonly ceiling?: "ask";
+}
+/** What one `tool.check` raise came to: the chain's verdict (`by` = the registration whose answer the chain returned;
+ *  absent when no handler spoke and the gate's own verdict came back up), a handler's failure, or a cancel. */
+export type ToolCheckOutcome = {
+    readonly kind: "answered";
+    readonly decision: ToolCheckDecision;
+    readonly reason?: string;
+    readonly by?: string;
+} | Extract<ModDispatchOutcome, {
+    kind: "failed";
+}> | {
+    readonly kind: "aborted";
+};
+/**
+ * Raise `tool.check` over the gate's standing verdict (undefined when no handler hangs on it — nothing is raised). A
+ * refusing event: a handler that throws, runs past its budget or answers out of the site's form ends the raise
+ * `failed`, a cancel ends it `aborted`, and the gate refuses the call on either. A dispatch the engine itself could not
+ * run is `failed` too. `judges` = which handlers take part (absent ⇒ every handler on the bus: the leg's own raise; an
+ * inherited installation's raise passes its {@link InheritedToolCheck.judges}).
+ */
+export declare function raiseToolCheck(bus: LegModBus, e: ModEventPayload, projection: ToolCheckProjection, signal: AbortSignal | undefined, judges?: (p: ModParticipant) => boolean): Promise<ToolCheckOutcome | undefined>;
+/** What a `prompt.compose` raise came to: each source class's overlays in application order, and the operator lines
+ *  for every handler whose answer was skipped. */
+export interface PromptComposeOutcome {
+    readonly deploy: readonly SourcedOverlay[];
+    readonly task: readonly SourcedOverlay[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Raise `prompt.compose` — the collection point of the deploy and task source classes' overlays — over the leg's
+ * bus (nothing is raised when no handler hangs on it). A collecting event: a handler's contribution is what its
+ * answer adds after what its `next(e)` returned, and what `next(e)` returned must stand unchanged, in order, at the
+ * head of its answer — a handler that answers without its `next(e)` (or before it returned), rewrites or removes a
+ * lower contribution, or adds an overlay the band table does not grant its seat's class (or one that carries locked
+ * text, or one that is not data), is skipped, and what is below it stands (runs in its place, when it never called
+ * `next`). The engine records, at each handler's boundary, the overlays as it validated them and who contributed
+ * each (the registration and its seat: the deployment seat is the deploy class, the task seat the task class); what
+ * applies is that record, never the answer read again. Each class applies its contributions in chain order, so a
+ * later registration's overlay on the same target wins.
+ *
+ * `lowerAdds` — the entries the classes below deploy already added (the only entries a deploy `drop` may name
+ * besides a built-in section).
+ */
+export declare function raisePromptCompose(bus: LegModBus, e: ModEventPayload, options: {
+    readonly lowerAdds: ReadonlyMap<string, BandId>;
+    readonly signal?: AbortSignal;
+}): Promise<PromptComposeOutcome>;
+/** The seats behind the engine facade, bound once the leg has them. Every member is read at its call. */
+export interface LegFacadeSeats {
+    readonly exec: ModSeatView["env"]["exec"];
+    complete(request: ModelCompleteRequest, signal: AbortSignal): Promise<ModelCompleteResult>;
+    readonly sessionId: string;
+    /** The run's account of side model calls ({@link ModSeatView.book}). */
+    book: ModSeatView["book"];
+    cwd(): string;
+    root(): string;
+    model(): string;
+    messages(): readonly Message[];
+    now(): number;
+    tools(): readonly string[];
+    agents(): readonly string[];
+}
+/** The leg's admitted bus, its chain identity (the one its admission recorded, {@link chainOfBus}) and the binding of the
+ *  facade its `$` reaches. */
+export interface LegMods {
+    readonly bus: ModBus;
+    readonly chain: readonly ModChainLink[];
+    /** Bind the engine facade once the leg is prepared. Until then a `$` call throws, naming the method. */
+    bindFacade(seats: LegFacadeSeats): void;
+}
+/**
+ * Admit the leg's bus: both seats (`RunnerDeps.mods`, `TaskSpec.mods`), screened and put to `plugin.register`.
+ * Called once per leg, at that leg's own prepare (a delegated child and a resumed leg each admit their own);
+ * each refused registration becomes one `mods.registration_refused` notice. Throws `config.mods_invalid` for a
+ * registration the kernel cannot take.
+ */
+export declare function admitLegMods(input: {
+    readonly spec: Pick<TaskSpec, "mods">;
+    readonly deps: Pick<RunnerDeps, "mods" | "onError" | "onNotice">;
+    readonly sessionId: string;
+}): Promise<LegMods>;
+/** What a leg hands {@link legFacadeSeats}: the seats it already has. */
+export interface LegFacadeInput {
+    readonly deps: Pick<RunnerDeps, "brain" | "models" | "now">;
+    readonly spec: Pick<TaskSpec, "getApiKeyAndHeaders">;
+    readonly sessionId: string;
+    readonly model: Model;
+    readonly executionEnv: Pick<ExecutionEnv, "exec">;
+    readonly taskRoot: string;
+    readonly cwdRef: CwdRef | undefined;
+    /** The leg's latest model request as recorded at the provider seam (the session's messages as the model last saw them). */
+    readonly lastBrainContext: () => {
+        readonly messages: readonly Message[];
+    } | undefined;
+    readonly activeTools: ReadonlySet<string>;
+    readonly agentListing: {
+        readonly entries: ReadonlyArray<{
+            readonly name: string;
+        }>;
+    } | undefined;
+    /** The run's one account of side model calls (the same entry the classifier's side calls book on), handed the model a
+     *  `$.model.complete` call resolved to, the usage its reply reported (absent ⇒ none reported) and the reply's
+     *  diagnostics when it carried any (a degraded brain's fallback is priced by them). */
+    readonly book: (model: Model, reply: {
+        readonly usage: Usage | undefined;
+        readonly diagnostics?: AssistantMessage["diagnostics"];
+    }) => void;
+}
+/** The engine facade's seats over a prepared leg — each one a seat the leg already has (no new capability). */
+export declare function legFacadeSeats(input: LegFacadeInput): LegFacadeSeats;
+/**
+ * A chain admitted outside any leg — what a host rebuilds to re-supply an inherited screening entry on a fresh Runner
+ * (a cross-process resume hands back `createPreToolUseConstraintPolicy(chain, env)` over the same registrations). The
+ * same admission a leg runs (both seats, `plugin.register`); no leg exists, so its `$` facade is never bound and a `$`
+ * call throws. Handler failures go to `onError` (absent ⇒ unreported). Its chain identity is recorded as a leg's is
+ * ({@link chainOfBus}), so an entry minted over it is read by what it mounted — whatever list the entry carries.
+ */
+export declare function admitModChain(seats: {
+    readonly deployment?: readonly ModRegistration<EngineDollar>[];
+    readonly task?: readonly ModRegistration<EngineDollar>[];
+}, onError?: (err: Error) => void): Promise<ModBus>;