@sema-agent/core/dist/core/runner/prepare-tool-disclosure-mount.d.ts

Stateless, task-oriented AI agent core

/**
 * PrepareTask's TOOL-DISCLOSURE-MOUNT phase, verbatim from the driver: the deferred registry
 * and its placeholders, the ToolSearch mount with its serialized activation section, the materialize strategy's
 * two-layer resolution (spec over the env channel, the safety interlock, the loud arms for a discarded env value), the
 * per-tool static exemption with its monotone ledger, the activation seed from the transcript / compaction snapshots /
 * checkpoint, the callable-names accessor the offload preview and ToolSearch share, the delta ref with its failed-server
 * arm, and the RefreshMcpTools rebuild seam's two arms. The env-channel announce ledger (per sink, per line) moved with
 * the segment — only this phase announces through it. The interface is the dependency list the segment had implicitly.
 *
 * ASYNC PHASE: with deferred names present the segment awaits the session's context and branch (the activation seed),
 * exactly where the driver awaited them; with nothing deferred the body has no await of its own. The phase adds no yield
 * BEFORE the first of those awaits (the reserved-name refusal, the env screen and the registry build run synchronously
 * as they did). Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
 *
 * The roster is READ here, never written (the writer table is on {@link Prepared.tools}); `harnessTools` is the derived
 * list the harness is built from, and the placeholders live only in it.
 */
import type { AgentHarness, AgentTool } from "../../internal/harness.js";
import { type ToolFingerprintInput } from "../cache-break-detector.js";
import type { MaterializedMcp, McpServerStatus } from "../mcp.js";
import type { StoredSession } from "../session.js";
import type { RunnerDeps, TaskSpec } from "../types.js";
import type { Prepared, PrepareResume } from "./contracts.js";
import { type ToolDisclosureSeat } from "./deferral-census.js";
export interface PrepareToolDisclosureMountInput {
    /** borrowed-readonly — the REBOUND spec. Read: `toolMaterializeStrategy` (the requested strategy, spec wins) and
     *  `deferSelfResolve` (the direct-call lane, the interlock). Never mutated. */
    spec: Pick<TaskSpec, "toolMaterializeStrategy" | "deferSelfResolve">;
    /** borrowed-readonly — the deployment seats: only `onNotice` (the env-channel discard announcements). */
    deps: Pick<RunnerDeps, "onNotice">;
    /** borrowed-readonly — the gate policy the classification was MEASURED under, carried from the classify phase; NOT re-resolved here (awaits sit between). */
    toolSearchPolicy: import("../tool-search-setting.js").ResolvedToolSearch;
    /** borrowed-readonly — the acquired session: `buildContext` and `getBranch` seed the activation set (deferred names only). */
    session: Pick<StoredSession, "buildContext" | "getBranch">;
    /** borrowed-readonly — the resume leg, or undefined: `seed.activeTools` is the authoritative activation reseed. */
    resume: Pick<PrepareResume, "seed"> | undefined;
    /** borrowed-readonly — the deferred classification (post-exclusion names): read for size, membership and iteration. */
    deferred: ReadonlySet<string>;
    /** borrowed-readonly — the run's shared roster (`Prepared.tools`): READ here — the registry build, the reserved-name
     *  check, the live resolution the placeholders and the static face perform at call time. Never written by this phase. */
    tools: readonly AgentTool[];
    /** borrowed-readonly — the once-per-session ledger's failed-server projection (current failures minus the pairs this
     *  session already announced). */
    onceLedger: {
        mcpFailuresToAnnounce(statuses: ReadonlyArray<McpServerStatus>): Array<{
            name: string;
            error?: string;
        }>;
    };
    /** borrowed-readonly — the materialized MCP handle; only `statuses` (the failed-server arm's source). */
    mcp: Pick<MaterializedMcp, "statuses">;
    /** borrowed-mutable — the assembled-prompt manifest (`Prepared.promptManifest`). Writer here: ONE assignment of
     *  `toolDisclosure` (deferred names only). */
    promptManifest: Prepared["promptManifest"];
    /** borrowed-mutable — the offload preview's reachability accessor seat. Writer here: `current` ← the callable-names
     *  accessor (deferred names only); the offload wrappers read it at each offload. */
    offloadReachableToolsRef: {
        current?: () => ReadonlySet<string>;
    };
    /** borrowed-readonly — the content-origin wrap seat; both rebuild arms CALL `current` at run time, never write it. */
    contentOriginWrapRef: {
        current?: () => void;
    };
    /** borrowed-mutable — the RefreshMcpTools rebuild seam. Writer here: `current` ← the deferred arm's rematerialize or the
     *  default arm's bare setTools (exactly one of the two, decided by `deferred.size`). */
    rebuildHarnessToolsRef: {
        current?: () => Promise<void>;
    };
    /** borrowed-readonly — the harness seat; the rebuild arms and the direct-call lane read `current` at run time. */
    harnessRef: {
        current?: AgentHarness;
    };
}
export interface PrepareToolDisclosureMountResult {
    /** owned — the activation set (`Prepared.activeTools`): seeded here; ToolSearch and the direct lane add at run time. */
    activeTools: Set<string>;
    /** borrowed-mutable — the cache-fingerprint seat. Writer: the driver, once, when the fingerprint is built; the rebuild
     *  arms refresh its `tools` at run time. */
    fpRef: {
        current?: {
            systemPrompt: string;
            tools: ToolFingerprintInput[];
        };
    };
    /** borrowed-mutable — the turn-snapshot identity seat. Writer: the driver's turn wiring, once; the rebuild arms call
     *  `refreshTools` on it at run time. */
    turnSnapshotRef: {
        current?: import("../../prompt-assembly/turn-snapshot.js").TurnPromptSnapshot;
    };
    /** owned — the list the harness is built from: the roster with placeholders in the deferred slots plus ToolSearch (or the
     *  roster itself when nothing is deferred). */
    harnessTools: readonly AgentTool[];
    /** owned — the ToolSearch instance the deferred arm appended to the harness list (absent when nothing is deferred): the
     *  driver mounts it on the roster's ENGINE LANE so the roster carries every name the model can call. */
    toolSearch?: AgentTool;
    /** owned — the boundary delta ref (`Prepared.toolsDeltaRef`), minted when anything is deferred OR a server failed. */
    toolsDeltaRef: Prepared["toolsDeltaRef"];
    /** owned — the effective strategy (`Prepared.toolMaterializeStatic`). */
    toolMaterializeStatic: boolean;
    /** owned — the direct-call lane's presence (`Prepared.deferDirectCall`). */
    deferDirectCall: boolean;
    /** owned — the per-tool static exemption seat (`Prepared.staticFaceFor` reads its `current`). */
    staticFaceForRef: {
        current?: (name: string) => boolean;
    };
    /** borrowed-mutable — the listing-ride seam: the ToolSearch tool and the direct lane call `current` at run time. Writer:
     *  the listings phase, once, after the roster face is classified. */
    listingRideRef: {
        current?: (newly: readonly string[]) => string | undefined;
    };
    /** owned — the deferral census seat, minted ONLY when something is deferred; absent ⇒ no `tool_disclosure` frame at all. */
    toolDisclosureSeat?: ToolDisclosureSeat;
}
/** Test seam (mirrors `__resetToolModelGateAnnouncements`): never called by production code.
 *  Re-arms BOTH arms (a WeakMap has no clear — it is re-minted). */
export declare function __resetMaterializeEnvAnnouncements(): void;
/** The M14 phase body — prepareTask's tool-disclosure-mount stretch, verbatim (see the module header). */
export declare function prepareToolDisclosureMount(input: PrepareToolDisclosureMountInput): Promise<PrepareToolDisclosureMountResult>;