@sema-agent/core
Version:
Stateless, task-oriented AI agent core
85 lines (84 loc) • 6.13 kB
TypeScript
/**
* PrepareTask's MEMORY-ENGINE-SESSION phase, verbatim from the driver: the content-origin
* classification + one-way session pollution wrap section (consolidating several design threads).
* Its arming predicate (a mounted memory session OR an
* upstream recorder channel), the chain-narrowed classification config, the children's provenance seat, the
* declared-MCP-class announcement, the settlement seat, the per-tool wrap with its three record verbs (mark /
* recordExternal / recordIncomplete), the Read tool's recall-taint arm and the delegation arm's three-valued
* attestation judgment all live here; the announcement helper only this section called moved with it. The
* interface is the dependency list the segment had implicitly.
*
* SYNCHRONOUS FUNCTION, SYNCHRONOUS CALL: the stretch has no await of its own (the awaits sit inside the wrappers it
* installs, which run at tool-call time), so the phase adds no yield between the deferred classification before it
* and the prompt assembly after it (a stretch with no await is extracted as a sync function).
* Read-stability of the host handles for the call: {@link RunInternals} (`@contract prepare.deps-read-stable`).
*
* One read changed spelling and nothing else: the declared-class announcement read `mcp?.statuses` while `mcp` had
* long been the protocol-tools phase's non-null handle; the optional chain was dead and is now the plain member read.
*/
import type { LockedPreflight } from "../locked-config.js";
import type { MaterializedMcp } from "../mcp.js";
import { type DelegationContentSafety } from "../memory-engine/delegation-provenance.js";
import type { RunnerDeps, TaskSpec } from "../types.js";
import type { Prepared, RunInternals } from "./contracts.js";
import { RosterBuilder } from "../tool-roster.js";
export interface PrepareMemoryEngineSessionInput {
/** borrowed-readonly — the mounted engine session, or undefined (the ARMING fact's first half). Read: `pollution`
* (the mark face), `contentSafety` (the own half of the narrowing), `settlement` (the seat + the receipt ledger),
* `recallTaint` (the Read arm's judge). Never mutated; the wrappers call `pollution.markPolluted` at tool-call time. */
memoryEngineSession: Prepared["memoryEngineSession"];
/** borrowed-mutable — the trusted spawn-side channel; only `delegationProvenance` (the ARMING fact's second half: the
* recorder channel with the chain's frozen `contentSafety`). Writers: the wrappers this phase installs set
* `delegationProvenance.ref.current.sawExternal` / `.incomplete` at tool-call time (monotonic, never cleared). */
internals: Pick<RunInternals, "delegationProvenance"> | undefined;
/** borrowed-readonly — the doors' per-leg SNAPSHOT of `RunnerDeps.memoryDelegationEvidence` (screened in the
* synchronous pre-await stretch; never a live deps re-read here). */
memoryDelegationEvidence: "static-face" | "attested-only";
/** borrowed-readonly — the run's external-content-target fold (live adapter declaration OR the persisted bit). */
externalContentTargetActive: boolean;
/** borrowed-readonly — the frozen preflight; only `mcp` (the declared entries the announcement walks). */
lockedPreflight: Pick<LockedPreflight, "mcp">;
/** borrowed-readonly — the materialized MCP handle; only `statuses` (the announcement's mounted-tool count). */
mcp: Pick<MaterializedMcp, "statuses">;
/** borrowed-readonly — the acquired session id (notice detail). */
sessionId: string;
/** borrowed-readonly — the run's invocation id (notice detail; the once-per-leg claims are per-RUN claims). */
runId: string;
/** borrowed-readonly — the deployment seats; only `onNotice` (the declared-class line and the waiver notice). */
deps: Pick<RunnerDeps, "onNotice">;
/** borrowed-mutable — the children's provenance seat (the inherited-gate phase mints it; `inheritedGateForChildren`
* reads it late). Writer: THIS phase, once at arming, to the effective (chain-narrowed) config. */
provenanceForChildrenRef: {
current?: DelegationContentSafety;
};
/** borrowed-mutable — the children's settlement seat (the inherited-gate phase mints it). Writer: THIS phase, once at
* arming, when the memory session mounted a settlement (memoryProvenance "carry"). */
delegationSettlementRef: {
current?: {
controlDir: string;
sessionId: string;
};
};
/** borrowed-readonly — the REBOUND spec; only `tools` (the RAW caller specs: caller-tool names and the marker-bearing
* delegation entries — the assembled roster objects carry neither marker). Never mutated. */
spec: Pick<TaskSpec, "tools">;
/** borrowed-readonly — the env-hand roster (membership minted at the mount sites); read by the classification. */
envHandToolNames: ReadonlySet<string>;
/** borrowed-mutable — the run's roster builder. Writer here: the wrap pass REPLACES entries in place
* (`roster.replaceAt(i, wrapped)`, identity-tracked so a re-run never stacks wrappers); see the roster's writer table on
* {@link Prepared.tools}. */
roster: RosterBuilder;
/** borrowed-mutable — the re-runnable wrap pass's seat (the protocol-tools phase mints it; the rebuild seam re-runs it
* after a refresh re-splice). Writer: THIS phase installs the pass and runs it once. */
contentOriginWrapRef: {
current?: () => void;
};
}
export interface PrepareMemoryEngineSessionResult {
/** owned — whether the section ARMED on this leg (a memory session or a recorder channel existed): armed ⇒ every
* roster tool was classified and the polluting/delegation/Read-plane ones wrapped; not armed ⇒ zero wraps, zero
* announcements, both children's seats untouched. */
armed: boolean;
}
/** The M12 phase body — prepareTask's content-origin wrap stretch, verbatim (see the module header). */
export declare function prepareMemoryEngineSession(input: PrepareMemoryEngineSessionInput): PrepareMemoryEngineSessionResult;