@sema-agent/core 7.5.0 → 7.5.2

package/dist/core/runner/prepare-tool-disclosure-mount.d.ts

@@ -0,0 +1,111 @@
+/**
+ * design/390 §1.2 M14 — 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
+ * (design/238 R-1).
+ *
+ * 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";
+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 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: 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: 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;
+    };
+}
+/** 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>;

package/dist/core/runner/prepare-tool-disclosure-mount.js

@@ -0,0 +1,219 @@
+import { readCompactionActiveTools } from "../../internal/harness.js";
+import { toolsToFingerprintInputs } from "../cache-break-detector.js";
+import { deliverEngineNotice } from "../types.js";
+import { TOOL_SEARCH_NAME, buildDeferredRegistry, extractDiscoveredToolNames, createPlaceholderTool, createToolSearchTool, staticSchemaRenderable } from "./tool-disclosure.js";
+let announcedMaterializeEnvBySink = new WeakMap();
+const announcedMaterializeEnvConsole = new Set();
+function materializeEnvLedger(onNotice) {
+    if (typeof onNotice !== "function")
+        return announcedMaterializeEnvConsole;
+    let lines = announcedMaterializeEnvBySink.get(onNotice);
+    if (lines === undefined) {
+        lines = new Set();
+        announcedMaterializeEnvBySink.set(onNotice, lines);
+    }
+    return lines;
+}
+export function __resetMaterializeEnvAnnouncements() {
+    announcedMaterializeEnvBySink = new WeakMap();
+    announcedMaterializeEnvConsole.clear();
+}
+function emitMaterializeEnvNotice(onNotice, message, detail) {
+    const ledger = materializeEnvLedger(onNotice);
+    if (ledger.has(message))
+        return;
+    ledger.add(message);
+    deliverEngineNotice(onNotice, { code: "config.materialize_env_discarded", message, detail });
+}
+export async function prepareToolDisclosureMount(input) {
+    const { spec, deps, session, resume, deferred, tools, onceLedger, mcp, promptManifest, offloadReachableToolsRef, contentOriginWrapRef, rebuildHarnessToolsRef, harnessRef } = input;
+    const activeTools = new Set();
+    const fpRef = {};
+    const turnSnapshotRef = {};
+    let harnessTools = tools;
+    const failedMcpServers = onceLedger.mcpFailuresToAnnounce(mcp.statuses);
+    let toolsDeltaRef;
+    let toolMaterializeStatic = false;
+    let deferDirectCall = false;
+    const staticFaceForRef = {};
+    if (deferred.size > 0 || failedMcpServers.length > 0) {
+        toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
+    }
+    const listingRideRef = {};
+    {
+        const raw = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+        if (raw !== undefined && raw !== "swap" && raw !== "static" && deferred.size === 0) {
+            const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(raw)} is not "swap" or "static" — inert on this task (no deferred tools), but a deferring task WITHOUT an explicit spec strategy will refuse to prepare under it (an explicit legal spec outranks and discards it, loudly). Fix or unset the flag.`;
+            emitMaterializeEnvNotice(deps.onNotice, line, { raw });
+        }
+    }
+    if (deferred.size > 0) {
+        if (deferred.has(TOOL_SEARCH_NAME) || tools.some((t) => t.name === TOOL_SEARCH_NAME)) {
+            const e = new Error(`Tool name "${TOOL_SEARCH_NAME}" is reserved when deferred tools are present.`);
+            e.code = "config.reserved_tool_name";
+            throw e;
+        }
+        const registry = buildDeferredRegistry(deferred, tools);
+        const rawEnvStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+        const envStrategyInvalid = rawEnvStrategy !== undefined && rawEnvStrategy !== "swap" && rawEnvStrategy !== "static";
+        if (envStrategyInvalid && spec.toolMaterializeStrategy === undefined) {
+            const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(rawEnvStrategy)}).`);
+            e.code = "config.tool_materialize_invalid";
+            throw e;
+        }
+        if (envStrategyInvalid) {
+            const line = `SEMA_TOOL_MATERIALIZE_STRATEGY=${JSON.stringify(rawEnvStrategy)} was ignored — not "swap" or "static", and the task spec pins toolMaterializeStrategy=${JSON.stringify(spec.toolMaterializeStrategy)} which outranks it. Fix or unset the env flag.`;
+            emitMaterializeEnvNotice(deps.onNotice, line, { raw: rawEnvStrategy, specStrategy: spec.toolMaterializeStrategy });
+        }
+        const envStrategy = envStrategyInvalid ? undefined : rawEnvStrategy;
+        const requestedStrategy = spec.toolMaterializeStrategy ?? envStrategy ?? "swap";
+        const laneDegrade = requestedStrategy === "static" && spec.deferSelfResolve === false;
+        const materializeStatic = requestedStrategy === "static" && !laneDegrade;
+        toolMaterializeStatic = materializeStatic;
+        deferDirectCall = spec.deferSelfResolve !== false;
+        promptManifest.toolDisclosure = {
+            deferredTools: deferred.size,
+            strategy: materializeStatic ? "static" : "swap",
+            source: laneDegrade ? "degraded_no_direct_lane" : spec.toolMaterializeStrategy !== undefined ? "spec" : envStrategy !== undefined ? "env" : "default",
+        };
+        const everExempt = new Set();
+        const staticFaceFor = (name) => {
+            if (!materializeStatic)
+                return false;
+            if (everExempt.has(name))
+                return false;
+            if (staticSchemaRenderable(tools.find((t) => t.name === name)?.parameters))
+                return true;
+            everExempt.add(name);
+            return false;
+        };
+        staticFaceForRef.current = staticFaceFor;
+        let activationChain = Promise.resolve();
+        const serializeActivation = (section) => {
+            const p = activationChain.then(section);
+            activationChain = p.then(() => undefined, () => undefined);
+            return p;
+        };
+        const directCallFor = (name) => {
+            if (spec.deferSelfResolve === false)
+                return undefined;
+            const executionMode = tools.find((t) => t.name === name)?.executionMode;
+            return {
+                resolveReal: () => {
+                    const real = tools.find((t) => t.name === name);
+                    if (real === undefined)
+                        return undefined;
+                    return {
+                        parameters: real.parameters,
+                        invoke: (toolCallId, params, signal, onUpdate) => real.execute(toolCallId, params, signal, onUpdate),
+                    };
+                },
+                ...(executionMode !== undefined ? { executionMode } : {}),
+                staticFace: () => staticFaceFor(name),
+                activate: async () => serializeActivation(async () => {
+                    if (activeTools.has(name))
+                        return undefined;
+                    activeTools.add(name);
+                    try {
+                        await rematerialize(activeTools);
+                    }
+                    catch (e) {
+                        activeTools.delete(name);
+                        throw e;
+                    }
+                    return listingRideRef.current?.([name]);
+                }),
+            };
+        };
+        const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i, directCallFor(i.name))]));
+        const { messages } = await session.buildContext();
+        for (const n of extractDiscoveredToolNames(messages, registry)) {
+            if (deferred.has(n))
+                activeTools.add(n);
+        }
+        for (const entry of await session.getBranch()) {
+            if (entry.type !== "compaction" || entry.fromHook === true)
+                continue;
+            for (const n of readCompactionActiveTools(entry.details)) {
+                if (deferred.has(n))
+                    activeTools.add(n);
+            }
+        }
+        if (resume) {
+            for (const n of resume.seed.activeTools)
+                if (deferred.has(n))
+                    activeTools.add(n);
+        }
+        const callableToolNames = () => {
+            const s = new Set(tools.map((t) => t.name));
+            for (const n of deferred)
+                if (!activeTools.has(n))
+                    s.delete(n);
+            s.add(TOOL_SEARCH_NAME);
+            return s;
+        };
+        offloadReachableToolsRef.current = callableToolNames;
+        let toolSearch;
+        const buildToolList = (active) => {
+            const list = tools.map((t) => (deferred.has(t.name) && (staticFaceFor(t.name) || !active.has(t.name)) ? placeholders.get(t.name) : t));
+            list.push(toolSearch);
+            return list;
+        };
+        const announcedTools = new Set(activeTools);
+        const withdrawnTools = new Set();
+        const deltaRef = toolsDeltaRef;
+        const rematerialize = async (active) => {
+            contentOriginWrapRef.current?.();
+            const list = buildToolList(active);
+            await harnessRef.current.setTools(list, list.map((t) => t.name));
+            if (fpRef.current)
+                fpRef.current.tools = toolsToFingerprintInputs(list);
+            turnSnapshotRef.current?.refreshTools(toolsToFingerprintInputs(list));
+            const live = new Set(list.map((t) => t.name));
+            for (const n of [...announcedTools]) {
+                if (!live.has(n)) {
+                    announcedTools.delete(n);
+                    withdrawnTools.add(n);
+                    deltaRef.pendingRemoved.push(n);
+                }
+            }
+            for (const n of active) {
+                if (!live.has(n))
+                    continue;
+                if (!announcedTools.has(n)) {
+                    announcedTools.add(n);
+                    if (withdrawnTools.delete(n))
+                        deltaRef.pendingReadded.push(n);
+                    else
+                        deltaRef.pending.push(n);
+                }
+            }
+        };
+        rebuildHarnessToolsRef.current = () => rematerialize(activeTools);
+        toolSearch = createToolSearchTool({
+            registry,
+            active: activeTools,
+            rematerialize,
+            listingRide: (newly) => listingRideRef.current?.(newly),
+            mountedNames: callableToolNames,
+            directCallEnabled: spec.deferSelfResolve !== false,
+            isMounted: (name) => tools.some((t) => t.name === name),
+            ...(materializeStatic
+                ? { staticSchemaFor: (name) => (staticFaceFor(name) ? tools.find((t) => t.name === name)?.parameters : undefined) }
+                : {}),
+            serializeActivation,
+        });
+        harnessTools = buildToolList(activeTools);
+    }
+    else {
+        rebuildHarnessToolsRef.current = async () => {
+            contentOriginWrapRef.current?.();
+            const list = [...tools];
+            await harnessRef.current.setTools(list, list.map((t) => t.name));
+            if (fpRef.current)
+                fpRef.current.tools = toolsToFingerprintInputs(list);
+            turnSnapshotRef.current?.refreshTools(toolsToFingerprintInputs(list));
+        };
+    }
+    return { activeTools, fpRef, turnSnapshotRef, harnessTools, toolsDeltaRef, toolMaterializeStatic, deferDirectCall, staticFaceForRef, listingRideRef };
+}

package/dist/core/runner/prepare-turn-wiring.d.ts

@@ -0,0 +1,154 @@
+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 { RunnerDeps, TaskSpec } from "../types.js";
+import type { CwdRef } from "../../tools/fs/fs-shared.js";
+import { type ReadFace } from "../../tools/fs/index.js";
+import type { ReadDenyMatcher } from "../../tools/fs/read-deny.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: ReadDenyMatcher | undefined;
+    /** borrowed-readonly — the resolved read face, or undefined (the fence's ninth argument). */
+    resolvedReadFace: ReadFace | 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 (the changed-files deny door's authority). */
+    denyNarrowingPolicy: ToolPolicy | undefined;
+    /** 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: () => ReadFace | 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 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: ReadFace | 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;