@sema-agent/core/dist/core/runner/prepare-turn-wiring.d.ts

Stateless, task-oriented AI agent core

import type { AgentHarness, AgentTool, ExecutionEnv, ThinkingLevel } from "../../internal/harness.js";
import type { Model } from "../../internal/llm.js";
import { type AssembledPrompt, type AssembleInputs } from "../../prompt-assembly/assemble.js";
import { type PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
import type { EpochDeclaredSections } from "../../prompt-assembly/epoch.js";
import { type TurnPromptSnapshot } from "../../prompt-assembly/turn-snapshot.js";
import type { PromptTextDeclaration } from "../../prompts/default.js";
import { CacheBreakDetector, type ToolFingerprintInput } from "../cache-break-detector.js";
import type { ToolPolicy } from "../tool-policy.js";
import { type SyntheticReadJudge } from "../synthetic-read-verdict.js";
import type { RunnerDeps, TaskSpec } from "../types.js";
import type { CwdRef } from "../../tools/fs/fs-shared.js";
import { type ContainmentFace } from "../../tools/fs/index.js";
import type { PlacedReadDenyMatcher } from "../../tools/fs/read-deny-home.js";
import { type ReadFileState } from "../../tools/fs/safety.js";
import type { Prepared } from "./contracts.js";
export interface PrepareTurnWiringInput {
    /** borrowed-readonly — the deployment seats: `cacheBreakDetection` (the detector knob), `onError` (the attachment-skip
     *  degraded line), `promptSource` (the center candidate's state and current artifact). Receiver preserved. */
    deps: Pick<RunnerDeps, "cacheBreakDetection" | "onError" | "promptSource">;
    /** borrowed-mutable — the LIVE system prompt (the prompt-assembly phase's accessor cell). Read: the fingerprint, the
     *  snapshot's stable text, the overhead term. Writer here: the center candidate's `apply` (the boundary swap). */
    systemPromptSeat: {
        current: string;
    };
    /** borrowed-readonly — the FINAL wire tool list (the fingerprint's and the snapshot's tool wire, the overhead sum). */
    harnessTools: ReadonlyArray<AgentTool>;
    /** borrowed-mutable — the fingerprint ref the tool-disclosure phase minted. Writers: THIS phase seeds `current`; the
     *  candidate's `apply` rewrites `current.systemPrompt`; the disclosure phase's rebuild seam refreshes `current.tools`. */
    fpRef: {
        current?: {
            systemPrompt: string;
            tools: ToolFingerprintInput[];
        };
    };
    /** borrowed-readonly — the task model: `provider` / `id` / `maxTokens` / `api` (the snapshot's identity elements). */
    model: Pick<Model, "provider" | "id" | "maxTokens" | "api">;
    /** borrowed-readonly — the resolved epoch's artifact digest (the snapshot's identity element). */
    epochArtifactDigestForSnapshot: string;
    /** borrowed-readonly — the resolved prompt profile (a snapshot element). */
    promptProfile: "simple" | "classic";
    /** borrowed-readonly — the fable mitigations switch (a snapshot element). */
    fableMitigations: boolean;
    /** borrowed-readonly — the assembled prompt's physical block face, or undefined (the snapshot's layout groups). */
    systemBlocks: AssembledPrompt["systemBlocks"];
    /** borrowed-readonly — the resolved thinking level, or undefined (a snapshot element). */
    thinking: ThinkingLevel | undefined;
    /** borrowed-readonly — the REBOUND spec; only `outputSchema` (presence) and `taskId` (the snapshot's identity). */
    spec: Pick<TaskSpec, "outputSchema" | "taskId">;
    /** borrowed-readonly — the acquired session id (the snapshot; the attachment-skip attribution). */
    sessionId: string;
    /** borrowed-mutable — the snapshot ref the tool-disclosure phase minted. Writers: THIS phase seeds `current`; the candidate's
     *  `apply` calls `refreshStableSystem`; the disclosure phase's rebuild seam calls `refreshTools`; the run loop assigns
     *  `current.onChange` (the snapshot-changed trace emitter) once Prepared is built. */
    turnSnapshotRef: {
        current?: TurnPromptSnapshot;
    };
    /** borrowed-mutable — the composition manifest (`Prepared.promptManifest`). Writer here: the identity/lowering BACKFILL
     *  (the snapshot needs the final wire list, which exists only now). */
    promptManifest: Prepared["promptManifest"];
    /** borrowed-readonly — the model's structural coefficient (the context lane's), the overhead term's coordinate. */
    charsPerToken: number;
    /** borrowed-readonly — whether an execution env is wired (every reader exists only then). */
    handsEnabled: boolean;
    /** borrowed-readonly — the run's resolved env (the readers read and stat through it). */
    executionEnv: ExecutionEnv;
    /** borrowed-readonly — the canonical attachment root, or undefined (the readers' containment fence). */
    attachmentRootCanonical: string | undefined;
    /** borrowed-readonly — the canonical extra write roots (the fence's root set). */
    additionalRootsCanonical: ReadonlyArray<string>;
    /** borrowed-readonly — the canonical extra read roots (the fence's root set). */
    additionalReadRootsCanonical: ReadonlyArray<string>;
    /** borrowed-readonly — the compiled read-deny judge, or undefined (the reader's withheld arm). */
    readDenyMatcher: PlacedReadDenyMatcher | undefined;
    /** borrowed-readonly — the resolved read face, or undefined (the fence's ninth argument). */
    resolvedReadFace: ContainmentFace | undefined;
    /** borrowed-readonly — the tracked-cwd seat, read per call by the kept-tail normalizer (never written here). */
    handsCwdRef: CwdRef | undefined;
    /** borrowed-mutable — the live read-file state, or undefined. Writers here, at RUN time: `detectExternalChanges` evicts a
     *  not-found entry; `onCompactionApplied` applies a landed compaction to it. The hands phase mints it. */
    readFileStateForCheckpoint: ReadFileState | undefined;
    /** borrowed-readonly — the deny-narrowing fold, or undefined (a layer of the synthetic-Read judge). */
    denyNarrowingPolicy: ToolPolicy | undefined;
    /** borrowed-readonly — the skill lane: the run's skill deny rows (a layer of the judge; only `denying` is read). */
    skillGrants: Prepared["skillGrants"];
    /** borrowed-readonly — the deployment's caller policy as resolved through the lock layer, or undefined (a layer of the
     *  judge, consulted with an aborted signal — never an approver). */
    callerPolicy: ToolPolicy | undefined;
    /** borrowed-readonly — each live inherited parent policy (a layer of the judge, consulted like the caller policy). */
    inheritedPolicies: readonly ToolPolicy[];
    /** borrowed-readonly — the person's persisted-rule lane, or undefined (a layer of the judge). */
    persistedRuleLane: Prepared["persistedRuleLane"];
    /** borrowed-readonly — the org rule lane, or undefined (a layer of the judge). */
    orgRuleLane: Prepared["permissionRuleOrg"];
    /** borrowed-readonly — the run's abort controller; only `signal` (the deny door's and the stat's signal). */
    abortController: Pick<AbortController, "signal">;
    /** borrowed-readonly — the per-task identity (the background listing's owner). */
    hostTaskId: string;
    /** borrowed-readonly — the registry scope the background listing reads under. */
    taskScope: string;
    /** borrowed-readonly — the prompt-assembly phase's re-invokable assemble-inputs builder (the candidate re-assembles). */
    buildAssembleInputs: (centerDecls?: PromptTextDeclaration[]) => AssembleInputs;
    /** borrowed-mutable — the LIVE center adoption (the prompt-assembly phase's accessor cell). Read: the candidate's arming and
     *  same-artifact test. Writer here: the candidate's `apply` (the boundary swap / the explicit-disable rollback). */
    centerAdoptionRef: {
        current: {
            artifact: PromptEpochArtifact;
            sourceRevision?: string;
        } | undefined;
    };
    /** borrowed-readonly — the harness ref (the candidate's `apply` calls `setSystemPrompt` on the current harness). */
    harnessRef: {
        current?: AgentHarness;
    };
    /** borrowed-readonly — the provider-declared sections in the epoch shape (the candidate's declared-sections TYPE). */
    epochDeclaredSections: EpochDeclaredSections;
    /** borrowed-readonly — the ONE carrier-face expression both delegation mounts consume (the observation seat). */
    carrierReadFace: () => ContainmentFace | undefined;
    /** borrowed-readonly — the same carrier expression on the WRITE seat. */
    carrierWriteFace: () => ContainmentFace | undefined;
    /** borrowed-readonly — the normalized deny additions (the observation seat copies them). */
    readDenyAdditionsNormalized: ReadonlyArray<{
        pattern: string;
        caseSensitive: boolean;
    }>;
    /** borrowed-mutable — the holder of the built Prepared. Writer: the DRIVER fills `current` right after `buildPrepared()`;
     *  the candidate's `apply` then writes `current.epochDeclaredSections` and `current.promptOverheadTokens` at a boundary. */
    preparedHolder: {
        current?: Prepared;
    };
}
export interface PrepareTurnWiringResult {
    /** owned — the two-phase cache-break detector (`Prepared.cacheBreakDetector`), or undefined when the knob is off. */
    cacheBreakDetector: CacheBreakDetector | undefined;
    /** borrowed-mutable — the prefix fingerprint (`Prepared.cacheFingerprint`; the same object `fpRef.current` holds), or
     *  undefined. Writers after this phase: the candidate's `apply` (systemPrompt), the disclosure rebuild seam (tools). */
    cacheFingerprint: {
        systemPrompt: string;
        tools: ToolFingerprintInput[];
    } | undefined;
    /** owned — the fixed prompt-overhead term in the compaction trigger's coordinate (`Prepared.promptOverheadTokens`). */
    promptOverheadTokens: number;
    /** owned — the fenced working-file reader, or undefined without hands (`Prepared.readTaskFile`). */
    readTaskFile: Prepared["readTaskFile"];
    /** owned — the kept-tail path normalizer, or undefined without hands. */
    normalizeAttachmentPath: Prepared["normalizeAttachmentPath"];
    /** owned — the Read tool's dedup-stub predicate, or undefined without hands. */
    isDedupStubResult: Prepared["isDedupStubResult"];
    /** owned — the most-recently-read files projection, or undefined without read state. */
    recentlyReadFiles: Prepared["recentlyReadFiles"];
    /** owned — the landed-compaction read-state hook, or undefined without read state. */
    onCompactionApplied: Prepared["onCompactionApplied"];
    /** owned — the boundary-time changed-files scan, or undefined without read state. */
    detectExternalChanges: Prepared["detectExternalChanges"];
    /** owned — the run's ONE synthetic-Read deny judge over every layer that can refuse a model's `Read` (the
     *  changed-files door reads it; a face that delivers a file the model did not ask for reads the same one). */
    syntheticReadVerdict: SyntheticReadJudge;
    /** owned — the post-compact background-task listing (`Prepared.listBackgroundTasks`). */
    listBackgroundTasks: Prepared["listBackgroundTasks"];
    /** owned — the compaction-boundary center adoption candidate, or undefined (no source, or no adoption). */
    centerCompactionCandidate: Prepared["centerCompactionCandidate"];
    /** owned — the effective read face observed for the result seats (`Prepared.effectiveReadFace`), or undefined. */
    effectiveReadFaceObserved: ContainmentFace | undefined;
    /** owned — the same observation on the WRITE seat (`Prepared.effectiveWriteFace`), or undefined. */
    effectiveWriteFaceObserved: ContainmentFace | undefined;
    /** owned — the effective read-deny patterns observed (fresh copies), or undefined when none. */
    effectiveReadDenyObserved: Array<{
        pattern: string;
        caseSensitive: boolean;
    }> | undefined;
}
/** The M22 phase body — prepareTask's turn-wiring stretch, verbatim (see the module header). */
export declare function prepareTurnWiring(input: PrepareTurnWiringInput): PrepareTurnWiringResult;