@sema-agent/core/dist/core/runner/prepare-safety-scan.d.ts

Stateless, task-oriented AI agent core

import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
import type { IrreversibilityTier, ReversibilityProbes } from "./contracts.js";
import type { ToolMarkSource } from "../ask-origin.js";
export interface PrepareSafetyScanInput {
    /** borrowed-readonly — the REBOUND spec (`spec′`, the config-doors result). The scan reads
     *  `tools`, `handsReadOnly` and `enablePlanMode`; it never mutates. */
    spec: TaskSpec;
    /** borrowed-readonly — read only for the hands-enablement fact (`executionEnvFactory`/
     *  `executionEnv` presence gates the hand-band effect preseed). */
    deps: RunnerDeps;
}
/**
 * The scan's outputs. Ownership annotations (four-class form):
 *
 * `ownToolNames` is **borrowed-readonly** — a first-await snapshot with no mutation anywhere after
 * the scan (sandbox containment reads the env-hand roster, not this set).
 *
 * The six collections are **borrowed-mutable**: the driver and later phases fold into them IN
 * PLACE (identity is part of the contract — closures alias these exact objects). Mutation owners
 * after this phase, in driver order:
 *  · the workflow mount (registers the run-workflow tool's write effect);
 *  · the MCP/A2A materialize fold + the runtime refresh seam (protocol-axis tighten registration;
 *    on refresh, `toolEffects.delete` resets a replaced tool's effect record for the fresh fold —
 *    the irreversible/egress sets deliberately KEEP their entries, the tighten-only residue);
 *  · the hands/read-face block's shellGate fold (Bash/Monitor tier escalation + probe seeding);
 *  · the background-task / Monitor / worktree mounts (fixed-name effect registration);
 *  · the prepare-final effect sync (fills MISSING entries from the final tool set — never
 *    overrides a scanned value).
 */
export interface PrepareSafetyScanResult {
    /** borrowed-mutable — per-tool effect registry (alias-complete), the reconcile/path-policy read. */
    toolEffects: Map<string, ToolEffect>;
    /** borrowed-mutable — egress-marked tools (external writes; the gate never auto-allows them). */
    egressTools: Set<string>;
    /** borrowed-mutable — tools whose effect is irreversible (`always`, or `maybe` incl. by probe). */
    irreversibleTools: Set<string>;
    /** borrowed-mutable — static per-tool irreversibility tier (prepare-time resolution). */
    irreversibilityTier: IrreversibilityTier;
    /** borrowed-mutable — explicit NEGATIVE axis judgments (report-face only; `riskAxesOf` reads). */
    axisExplicitNegatives: Map<string, {
        irreversible?: false;
        egress?: false;
    }>;
    /** borrowed-mutable — declared reversibility probes by tool name. */
    reversibilityProbes: ReversibilityProbes;
    /** borrowed-mutable — WHO put each tool's egress / irreversibility mark on its seat (the caller roster's marks are
     *  the deployment's own; the protocol fold adds `mcp_annotation` / `a2a_default`). Read by the gate's class
     *  derivation: a mark with no recorded source reads as the deployment's (fail-closed). */
    toolMarkSources: Map<string, Set<ToolMarkSource>>;
    /** borrowed-readonly — the caller roster's own names, snapshotted before the first await. */
    ownToolNames: ReadonlySet<string>;
}
/** The B-2 phase body — the safety-scan slice, verbatim (see the module header for the contract). */
export declare function prepareSafetyScan(input: PrepareSafetyScanInput): PrepareSafetyScanResult;