@sema-agent/core/dist/core/runner/prepare-offload-wrappers.d.ts

Stateless, task-oriented AI agent core

/**
 * (The offload half of the prelude) — prepareTask's nested-usage accumulator, the
 * large-tool-result offload store resolution and the THREE offload wrappers every later mount site
 * applies (caller tools, first-party hand tools, remote MCP/A2A peers), verbatim from the driver.
 *
 * SYNCHRONOUS by construction: the segment held no await in the driver, and a phase that yields where
 * the driver did not would open a microtask window between two steps that used to be adjacent (the
 * posture). Nothing here touches the store — the wrappers close over it and only the
 * wrapped tools' `execute` reach it, at run time.
 *
 * What stays in the driver: the trust-axis choice of `offloadScope` (`spec.principal ?? "default"`)
 * and its disclosure, and the reserved-name door that FOLLOWS these wrappers (it awaits a bounded
 * session forget, so it belongs with the driver's other refusal legs).
 */
import { type ToolResultStore } from "../tool-result-store.js";
import type { AgentTool } from "../../internal/harness.js";
import type { NestedUsage, NestedUsageAccum, RunnerDeps, TaskSpec } from "../types.js";
import type { PrepareResume } from "./contracts.js";
export interface PrepareOffloadWrappersInput {
    /** borrowed-readonly — the REBOUND spec (the config-doors result); read for the per-task coarse
     *  offload knob only. */
    spec: Pick<TaskSpec, "toolResultThresholdChars">;
    /** borrowed-readonly — the deployment's coarse offload knob and its injected store (used AS-IS when
     *  present; a Runner-shared instance is viewed per task, see the body). */
    deps: Pick<RunnerDeps, "toolResultThresholdChars" | "toolResultStore">;
    /** borrowed-readonly — the resume leg, read for the checkpoint seed's nested-usage snapshot so
     *  delegated cost spent before a suspend is not lost; `undefined` on a fresh run. */
    resume: Pick<PrepareResume, "seed"> | undefined;
    /** borrowed-readonly — the run's TRUST identity (`spec.principal ?? "default"`, minted by the
     *  driver): the namespace a Runner-shared store is scoped under. Never the registry domain. */
    offloadScope: string;
    /** borrowed-readonly — the acquired session id, the offload wrapper's ref-minting coordinate. */
    sessionId: string;
}
export interface PrepareOffloadWrappersResult {
    /** borrowed-mutable — the run's nested sub-run usage accumulator (`Prepared.nestedStats`).
     *  Mutation owners after this call: `reportUsage` below (the only writer — every delegation tool
     *  reports through it via the tool ctx); the driver reads it into `Prepared`. */
    nestedStats: NestedUsageAccum;
    /** borrowed-readonly — the one writer of `nestedStats`; the driver threads it onto the tool ctx. */
    reportUsage: (u: NestedUsage) => void;
    /** borrowed-readonly — the store the wrappers close over, or `undefined` when offload is disabled
     *  (threshold 0 / non-finite). The driver reads it for the reserved-name door, the ReadToolResult
     *  mount, the durable-suspend gate and the compaction lane. Not a resource: nothing to release. */
    offloadStore: ToolResultStore | undefined;
    /** borrowed-mutable — the LIVE "currently callable tools" accessor cell the offload preview's
     *  pageback hint reads. Mutation owners after this call: the deferred-disclosure branch of the
     *  driver sets `.current` once the deferred/active sets exist; nothing else writes it. */
    offloadReachableToolsRef: {
        current?: () => ReadonlySet<string>;
    };
    /** borrowed-readonly — wrap a CALLER tool (per-tool `offload` / `offloadThresholdChars` honored). */
    maybeOffload: (tool: AgentTool, perTool?: {
        offload?: boolean;
        offloadThresholdChars?: number;
    }) => AgentTool;
    /** borrowed-readonly — wrap a FIRST-PARTY mount (the per-tool persistence table; Read/Write exempt). */
    firstPartyOffload: (tool: AgentTool) => AgentTool;
    /** borrowed-readonly — wrap a REMOTE-PEER mount (MCP `_meta` size declaration, else 50K). */
    remoteToolOffload: (tool: AgentTool) => AgentTool;
}
export declare function prepareOffloadWrappers(input: PrepareOffloadWrappersInput): PrepareOffloadWrappersResult;