@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/engine.d.ts

@@ -0,0 +1,1298 @@
+import { type CredentialRef, type RuntimeConfig, type PermissionUpdate, type RuleSource, DEFAULT_CONTEXT_WINDOW_TOKENS, type InitPluginInfo, type SDKAssistantMessageError, type WireStreamEvent, type ModelFamilyListing, type ActiveSlotSet, type BrandProfile, type SettingSource } from "@yanlinglabs/winter-agent-sdk";
+import type { ContinuityEndpoint, MessageOrigin, ProviderNativeState, SystemPromptBlock, ToolChangeSet, TurnRequest } from "@yanlinglabs/winter-provider-runtime";
+export type { MessageOrigin, ProviderNativeState };
+import { type ProviderStateRecord, type ProviderStateRecordInput } from "./store/provider-state.js";
+import { type SlotProviderResolution } from "./provider/slots.js";
+import type { FrameSource, FrameSink } from "./protocol/channel.js";
+import type { McpServerStateSource } from "./mcp/state.js";
+import type { McpControlSeam } from "./mcp/control-seam.js";
+import type { SkillListing, SystemPromptAssembler } from "./context/seam.js";
+import type { CompactBoundaryRecord, CompactBoundaryWriteResult, CompactionController } from "./compaction/seam.js";
+import { type StructuredOutputSeam } from "./structured/seam.js";
+import { type FileCheckpointSink } from "./checkpoint/seam.js";
+import { type CommandResolver } from "./commands/seam.js";
+import { type McpServerSource } from "./mcp/lifecycle.js";
+import { type ChildHandle } from "./subagents/child-handle.js";
+import { type SourcedRuleEntry } from "./permissions/ruleset.js";
+import { type AutoAuditRecorder, type ClassifierInterface } from "./permissions/auto/engine.js";
+import { type AutoCounterStore } from "./permissions/auto/caches.js";
+import { type SourcedHookEntry } from "./hooks/registry.js";
+import { type AttachmentPayload } from "./context/attachments.js";
+import { type SessionRequestLayout, type ToolChangeRendering } from "./context/request-layout.js";
+import { type HookAuditRecord } from "./hooks/runner.js";
+import { type DurableApprovalStore } from "./permissions/approvals.js";
+import "./tools/descriptors/index.ts";
+import "./tools/impl/index.ts";
+import { type ResolvedReviewer } from "./tools/impl/advisor.js";
+import type { AuxiliaryModelResolution } from "./provider/session-provider.js";
+import type { ToolSecretResolver } from "./provider/tool-secret.js";
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: "tool_reference";
+    tool_names: string[];
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean;
+    interrupted?: boolean;
+    error?: boolean;
+    denied?: boolean;
+    deferred?: boolean;
+    loadFirst?: boolean;
+    loadedTools?: string[];
+    loadedToolDefinitions?: LoadedToolDefinition[];
+} | {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+} | {
+    type: "redacted_thinking";
+    data: string;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+};
+/** WS-23 (midconv, review I-2): one loaded tool's definition as it stood at load time (see `tool_result.loadedToolDefinitions`). */
+export interface LoadedToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /** The MCP server group (`mcp__<server>`) of an MCP tool whose name carries that prefix. */
+    namespace?: string;
+}
+export interface ProviderMessage {
+    /**
+     * `system` (WS-23) exists ONLY on an outbound request, never in this engine's own history: an
+     * effort-only marker (`outputConfig`) or, later, a mid-conversation system reminder, each inserted by
+     * the request layout for a model whose catalog row documents the shape. See `ProviderMessageLike`.
+     */
+    role: "user" | "assistant" | "tool" | "system";
+    content: string | ContentBlock[];
+    /** WS-23: a `system` marker's per-message effort change. Never set on another role. */
+    outputConfig?: {
+        effort: string;
+    };
+    /**
+     * WS-23 (midconv): a `system` message's mid-conversation tool changes, built by the request layout from
+     * the tool epoch's `tool_changes` entries (context/tool-epoch.ts) -- never in the history itself. See
+     * provider-runtime's `ProviderMessageLike.toolChanges`.
+     */
+    toolChanges?: ToolChangeSet;
+    /**
+     * WS-23 (claude's own transcript fields, `effort`/`perTurnEffort` on an assistant entry): the
+     * TOP-LEVEL effort the request that produced this assistant message sent, and the level actually IN
+     * FORCE for its turn. They differ only on a model with per-message effort, where the top-level value
+     * stays frozen and a change rides a `system` marker. Set on assistant messages only, and only when
+     * the session has a named effort at all -- so a session with none stays byte-identical. The markers
+     * of every later request are DERIVED from these two fields (`withEffortMarkers`), live and resumed
+     * alike, which is what keeps the cached prefix byte-stable across turns.
+     */
+    effort?: string;
+    perTurnEffort?: string;
+    uuid?: string;
+    /** Which provider/model produced this message. The input to R6-9's continuation-domain check on resume, fallback and handoff. */
+    origin?: MessageOrigin;
+    /**
+     * OPAQUE, adapter-owned continuation state. Its ONLY sink is the provider-state sidecar (R6-7).
+     * Never logged, never model-readable, never in a frame or an error message -- `items` is
+     * `unknown[]` precisely so nothing is tempted to inspect it.
+     */
+    nativeState?: ProviderNativeState;
+    /**
+     * A Winter-authored annotation shown to the model -- a handoff note, or a foreign model's reasoning
+     * summary carried across a family boundary. Carried PLAINLY, never dressed as signed thinking
+     * (R6-8): `door` says which channel Lane C's renderer places it on, and neither door produces a
+     * `thinking` block with a fabricated signature.
+     */
+    decoration?: {
+        text: string;
+        door: "tag" | "thinking-channel";
+    };
+    /**
+     * 0.0.16 request layout (P16-5/P16-6): a PERSISTED ATTACHMENT -- claude's `type: "attachment"`
+     * transcript entry. The message is a `user`-role entry in the engine's history whose `content` is
+     * the attachment's rendered, `<system-reminder>`-wrapped text; `attachment` is the payload the
+     * transcript stores and the history folds read back (context/attachments.ts). It is placed right
+     * after the user prompt or tool results that triggered it, persisted through
+     * `SessionPersistence.recordAttachmentEntry`, and survives resume.
+     */
+    meta?: {
+        attachment: AttachmentPayload;
+    };
+    /**
+     * 0.0.16 request layout: the per-request userContext message (claude's `mbt`) at INDEX 0 of the
+     * live request. Never in the engine's history and never persisted; it only appears on an outbound
+     * request whose first history message it could not be merged into (context/request-layout.ts).
+     */
+    isMeta?: true;
+}
+export declare function providerMessageContentToText(content: string | ContentBlock[]): string;
+/**
+ * WS-23: the session's system-prompt cache lifetime -- `RuntimeConfig.promptCacheTtl`, defaulted HERE
+ * and nowhere else. `"5m"` is the vendor's own default and what claude 2.1.282 uses with an API key;
+ * `"1h"` is the host's choice for sessions with long idle gaps (it is written at twice the input
+ * price). Only `"1h"` reaches a request, so a default session's requests are byte-identical to before.
+ */
+export declare function promptCacheTtlFor(config: {
+    promptCacheTtl?: "5m" | "1h";
+}): "5m" | "1h";
+/**
+ * WS-23: the cache-routing key for one conversation -- the session id, and for a subagent the session
+ * id plus its agent id (a child's prefix is its own, so sharing the parent's key would only mix two
+ * prefixes under one routing group). Opaque ids only: nothing about the user or the content.
+ */
+export declare function promptCacheKeyFor(config: {
+    sessionId: string;
+    agentId?: string;
+}): string;
+/** WS-23: a named effort tier -- the string half of `TurnRequest["effort"]`. */
+declare const NAMED_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+export declare function isNamedEffort(value: unknown): value is (typeof NAMED_EFFORTS)[number];
+/**
+ * WS-23: the catalog facts about a model's WIRE that the engine's request layout keys on. Each is a
+ * catalog-evidence flag the production wiring reads off the model's row (`describeCatalogModel`);
+ * absent means "today's layout", which is every scripted double and every row without the evidence.
+ */
+export interface ModelWireFeatures {
+    /** `reasoning.perMessageEffort`: an effort change rides a `system` marker while the top-level value stays frozen. */
+    perMessageEffort?: true;
+    /** `deferredToolLoading`: every deferred tool is declared up front with `defer_loading: true`, and ToolSearch surfaces one by reference. */
+    deferredToolLoading?: true;
+    /** `midConversationSystem`: a reminder whose renderer opted in rides as a `role: "system"` message after the user turn it follows. */
+    midConversationSystem?: true;
+    /**
+     * WS-23 (midconv): how a change to the tool list reaches this model without editing `tools` (the tool
+     * epoch, context/tool-epoch.ts): `"inline"` -- Anthropic by value and by reference
+     * (`inlineToolDefinitions`); `"reference"` -- Anthropic by reference only (`midConversationToolChanges`).
+     */
+    toolChanges?: "inline" | "reference";
+    /** WS-23 (midconv): OpenAI's client-executed `tool_search` stands in for Winter's ToolSearch (`clientToolSearch`). */
+    clientToolSearch?: true;
+    /** WS-23 (midconv): OpenAI's `additional_tools` input item adds or redefines a tool mid-conversation (`additionalToolsItem`). */
+    additionalToolsItem?: true;
+    /** WS-23 (midconv): OpenAI's `tool_choice: allowed_tools` restricts the callable set without editing `tools` (`allowedToolsChoice`). */
+    allowedToolsChoice?: true;
+}
+/** What `EngineOptions.describeModel` knows about a model: its display name, its verified effort vocabulary, and its wire features. */
+export interface ModelDescription {
+    displayName?: string;
+    /** The row's own `reasoning.efforts`, verbatim -- `set_effort` validates a requested level against it. */
+    efforts?: string[];
+    /** The row's own `reasoning.defaultEffort`: the level in force when no effort is named. */
+    defaultEffort?: string;
+    wire?: ModelWireFeatures;
+    /** WS-23 (reasoning-state, decision 5): the row's context window and output ceiling, in tokens -- the switch fit check's budget and the context accountant's limit after a switch. */
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    /** WS-23 (reasoning-state, decision 9): `false` when the row reads no images (its input modalities omit them). Absent: unknown, read as yes. */
+    readsImages?: boolean;
+}
+export interface ProviderRequest {
+    messages: ProviderMessage[];
+    /**
+     * The assembled system prompt for this generation.
+     *
+     * ONE PRODUCER, deliberately. At Task 2 nothing in runEngine sets it -- Task 3 owns prompt
+     * assembly, and a second producer here is exactly the failure mode a new optional field invites
+     * (nothing fails to compile when a producer simply doesn't set it, so the sweep has to be by
+     * MEANING, not by build breakage). A consumer must therefore treat an absent `system` as "this
+     * host supplied no system prompt", never as an error.
+     */
+    system?: string;
+    /**
+     * 0.0.16 request layout (P16-5): `system` as claude's ordered cache blocks -- the static prefix
+     * (`global`), then the session-specific rest with the systemContext lines appended LAST (`org`).
+     * When present, `system` equals the texts joined by a blank line, so a provider that only reads
+     * `system` sees the same prompt.
+     */
+    systemBlocks?: SystemPromptBlock[];
+    /**
+     * The session's ADVERTISED tool set with real JSON Schemas -- what an adapter puts in the request's
+     * own `tools` array. Only tools this session actually advertises reach here, and a DEFERRED tool
+     * appears only once it has been LOADED (WS-09 §8.2's "load != permission"): advertising a schema
+     * for a tool the engine would refuse to dispatch invites the model to call it.
+     */
+    tools?: ProviderToolSpec[];
+    toolChoice?: TurnRequest["toolChoice"];
+    /** WS-23: the system prompt's cache lifetime, sent only when the session asked for `"1h"` (`promptCacheTtlFor`). */
+    cacheTtl?: "1h";
+    /**
+     * WS-23: cache diagnostics -- the previous MAIN-LOOP response's id on the same model, or `null` to
+     * opt in with nothing to compare against (a session's first request, after a compaction rewrote the
+     * history, after a model switch). Main-loop requests only: an auxiliary call in between would make
+     * the next comparison meaningless.
+     */
+    cacheDiagnostics?: {
+        previousMessageId: string | null;
+    };
+    /** WS-23: this conversation's cache-routing key (`promptCacheKeyFor`) -- the session id, plus the agent id for a subagent. */
+    cacheKey?: string;
+    /** WS-23 (midconv): the callable subset of `tools` on this request (OpenAI `allowed_tools`); see `TurnRequest.allowedTools`. */
+    allowedTools?: string[];
+    /** WS-23 (midconv): the conversation carries mid-conversation tool changes -- the opt-in rides every request (`TurnRequest.toolChanges`). */
+    toolChanges?: true;
+    /** WS-23 (midconv): this request re-sends a `pause_turn` response (`TurnRequest.resumesPausedTurn`). */
+    resumesPausedTurn?: true;
+    /** The resolved model for THIS generation. Present once selection is wired; absent means "the provider's own configured default", which is what every pre-P6 double sees. */
+    model?: string;
+    effort?: TurnRequest["effort"];
+    thinking?: TurnRequest["thinking"];
+    /** WS-23: the host's output-token ceiling (`RuntimeConfig.maxOutputTokens`). Absent -> the adapter's own default. */
+    maxOutputTokens?: number;
+    /**
+     * R6-6: TRUE cancellation. Aborted when this turn is interrupted, so an adapter can cancel
+     * pre-header and mid-stream instead of running to completion behind an abandoned await. The same
+     * signal reaches `ToolExecutor` through `ToolExecutionContext.signal`, so an interrupt stops the
+     * generation AND kills the in-flight Bash process group.
+     */
+    signal?: AbortSignal;
+    /**
+     * R6-5: where live observations go. A provider that streams calls these as the stream arrives; the
+     * engine turns them into frames under the gating each frame carries (`stream_event` only under
+     * `includePartialMessages`, `rate_limit_event` only for subscription-shaped quota per R6-B).
+     *
+     * ABSENT for an AUXILIARY generation (R6-G): the compaction summariser, the classifier, the advisor
+     * and `countTokens` never emit `stream_event`s -- capture (F) observed the pinned runtime
+     * suppressing exactly that call's stream events, and a Winter emitter that streamed every provider
+     * call would emit frames the pin does not.
+     */
+    sink?: ProviderStreamSink;
+}
+/** One advertised tool as an adapter serialises it. `inputSchema` is the tool's real JSON Schema, never a placeholder. */
+export interface ProviderToolSpec {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    /**
+     * WS-23: declared up front but WITHHELD from the model until a `tool_reference` surfaces it
+     * (Anthropic's `defer_loading: true`). Set only for a model whose row documents deferred tool
+     * loading (`ModelWireFeatures.deferredToolLoading`), so no other adapter ever receives one.
+     */
+    deferLoading?: true;
+    /** WS-23 (midconv): the MCP server group a deferred tool belongs to, for OpenAI's client tool search (`TurnRequest.tools[].namespace`). */
+    namespace?: string;
+    /** WS-23 (midconv): this is Winter's ToolSearch, rendered as OpenAI's native client `tool_search` (`TurnRequest.tools[].toolSearch`). */
+    toolSearch?: true;
+}
+/** WS-23 (midconv): one request's tool plan -- see the engine's `planToolsForRequest`. */
+export interface ToolPlan {
+    tools: ProviderToolSpec[];
+    allowedTools?: string[];
+    toolChanges?: ToolChangeRendering;
+    /** The vendor's tool-change opt-in rides this request (`ProviderRequest.toolChanges`). */
+    optIn?: true;
+}
+/**
+ * R6-5: the pinned Anthropic-shaped raw stream-event vocabulary every adapter normalises into.
+ *
+ * ALIASED, never re-declared. The declaration home is `packages/sdk/src/protocol/frames.ts`
+ * (`WireStreamEvent`), because the sdk is where a wire shape a host decodes belongs and because a
+ * second structural copy here is exactly the drift R6-D exists to avoid.
+ */
+export type ProviderRawStreamEvent = WireStreamEvent;
+/**
+ * The live observations a streaming provider reports. Every method is fire-and-forget: a sink
+ * implementation that throws must never break a generation, so the engine's own implementation
+ * catches and drops.
+ */
+export interface ProviderStreamSink {
+    onStreamEvent(event: ProviderRawStreamEvent): void;
+    onRetry(info: RetryInfo): void;
+    /**
+     * R6-B: SUBSCRIPTION-QUOTA states ONLY, and the payload's own `kind` says so. An HTTP 429 is NOT
+     * this callback -- capture (G) proved the pinned runtime emits zero `rate_limit_event` frames for a
+     * 429 carrying a full `anthropic-ratelimit-*` header set; the pinned 429 path is `api_retry`.
+     */
+    onRateLimit(info: {
+        kind: "subscription-quota";
+        info: Record<string, unknown>;
+    }): void;
+    /** R6-F: a LOGIN-FLOW progress channel (codex-oauth login/refresh only), never the credential-failure channel. */
+    onAuthStatus(info: {
+        isAuthenticating: boolean;
+        output?: string[];
+        error?: string;
+    }): void;
+    /** R6-8: a FOREIGN model's readable reasoning summary. It rides the sidecar and the Winter-only `system/reasoning_summary` frame -- never `assistant.message.content`. */
+    onReasoningSummary(text: string): void;
+}
+/** The `api_retry` payload minus its frame envelope (`uuid`/`session_id`, which the engine stamps). Mirrors provider-runtime's own `retry` event. */
+export interface RetryInfo {
+    attempt: number;
+    maxRetries: number;
+    retryDelayMs: number;
+    /** ABSENT, never `null`, for a connection error with no HTTP response -- the engine maps absence to the frame's pinned `error_status: null`. */
+    errorStatus?: number;
+    error: SDKAssistantMessageError;
+}
+/** R6-8: what a turn reports about its own reasoning. `blocks` are IN-DIALECT Anthropic-family blocks, complete and in order, carrying their REAL signatures; `summary`/`exposed` are foreign and never enter `assistant.message.content`. */
+export interface ProviderThinkingOutput {
+    summary?: string;
+    exposed?: string;
+    exposedComplete?: boolean;
+    blocks?: ContentBlock[];
+}
+/**
+ * Why the provider stopped. Mirrors provider-runtime's `done` event so the bridge folds one into the
+ * other without a mapping table. WS-23 adds the two that are NOT an end of turn: `pause_turn` (the turn
+ * continues by re-sending) and `model_context_window_exceeded` (reactive compaction, then one retry).
+ */
+export type ProviderStopReason = "end_turn" | "tool_use" | "max_tokens" | "aborted" | "refusal" | "pause_turn" | "model_context_window_exceeded";
+/** WS-23: a refusal's own details (Anthropic's `stop_details`). `explanation` is display prose, never parsed. */
+export interface ProviderStopDetails {
+    category: string | null;
+    explanation: string | null;
+}
+/**
+ * Phase 6 Task 3 (R6-F): the ONE error class the engine recognises as a PROVIDER failure.
+ *
+ * A provider failure that ends a turn does not get its own result subtype. Capture (I) observed the
+ * pinned runtime landing an API failure on `subtype: "success"` with `is_error: true`,
+ * `terminal_reason: "api_error"` and `api_error_status: <status | null>` -- so the engine has to be
+ * able to TELL a provider failure from any other throw, which would otherwise stay
+ * `error_during_execution` exactly as before this phase.
+ *
+ * DECLARED HERE, not in `provider/bridge.ts`, for the same structural reason `ProviderTurn` is
+ * (R6-4): the engine must recognise the type without importing the bridge, and a value import from
+ * engine.ts into bridge.ts and back would be a runtime cycle whose compiled and dev resolutions can
+ * differ. `bridge.ts` re-exports it, so a lane reads it from the module it is working in.
+ *
+ * `status` is ABSENT -- never `null` -- for a connection error with no HTTP response; the frame
+ * producer maps absence to the pinned `api_error_status: null`. (Declared with `declare` and assigned
+ * conditionally because `useDefineForClassFields` would otherwise EMIT an own `status` key holding
+ * `undefined`, making `"status" in err` true for exactly the case the pin distinguishes -- Task 2 hit
+ * this same trap on `ProviderRequestError`.)
+ *
+ * `message` is REDACTED BY CONSTRUCTION at every construction site: no credential material, no
+ * opaque provider state, no raw response body (Global Constraints).
+ */
+export declare class ProviderTurnError extends Error {
+    /** The structural marker the engine matches on, so an error crossing a package boundary is still recognised. */
+    readonly winterProviderFailure: true;
+    readonly status?: number;
+    readonly providerCode: string | undefined;
+    /**
+     * P6 fix wave (Ruling E-3): the normalized error's Winter CODE (`server`/`rate_limit`/`network`/
+     * `timeout`/...) and R6-6's own `retryable` verdict, carried off the adapter's normalized error by
+     * the bridge. `retryable === true` is the fallback trigger: it is exactly the class `withRetry`
+     * retries and has, by the time the engine sees the error, given up on. Absent on an error that
+     * was never normalized (a bare throw with no provider shape).
+     */
+    readonly code: string | undefined;
+    readonly retryable: boolean | undefined;
+    /**
+     * Fix wave round 2 (R-E2, R6-6): had the stream already BEGUN when this failure happened? Set by the
+     * bridge from the fold's own event count. `withRetry`'s first-byte rule ("after `commit()` every
+     * failure is final -- the caller may already have shown text") binds the fallback exactly as it
+     * binds a retry: a committed failure ends the turn on R6-F and never engages a candidate.
+     */
+    readonly committed: boolean | undefined;
+    /**
+     * WS-23: the provider refused the request because the prompt does not fit the model's context
+     * window (Anthropic's 400 "prompt is too long"). The adapter's own verdict, carried by the bridge;
+     * the engine answers it with one reactive compaction and one retry. `undefined` for any other failure.
+     */
+    readonly contextOverflow: true | undefined;
+    constructor(message: string, opts?: {
+        status?: number;
+        providerCode?: string;
+        code?: string;
+        retryable?: boolean;
+        committed?: boolean;
+        contextOverflow?: true;
+        cause?: unknown;
+    });
+}
+/**
+ * True for a provider failure that must land on R6-F's result shape.
+ *
+ * STRUCTURAL for `ProviderTurnError` (the error may have been constructed in another package's copy
+ * of this module), and by NAME for `WinterProviderResolutionError` -- which is Task 2's frozen class
+ * and carries no marker of its own. R6-9 is explicit that "no model + no provider" is surfaced in
+ * R6-F's captured failure shape, so a resolution refusal thrown from `generate()` must not fall
+ * through to `error_during_execution` the way an ordinary bug does. It has no HTTP status, so
+ * `api_error_status` is `null` -- exactly capture (I)'s run (i), where the runtime failed closed
+ * without making a request at all.
+ */
+export declare function isProviderTurnError(err: unknown): err is ProviderTurnError;
+/**
+ * P1 carry: the per-message input byte cap on provider input.
+ *
+ * A DISCLOSED DEFAULT WITH A TYPED ERROR, never a silent truncation -- truncating a message would
+ * hand the model a conversation it never had, and the failure would surface as a confusing answer
+ * rather than as an error. 4 MiB is far above any real message and far below anything that would
+ * stall a serializer.
+ */
+export declare const DEFAULT_MAX_PROVIDER_MESSAGE_BYTES: number;
+/**
+ * Per-generation token accounting (R5-3). `inputTokens`/`outputTokens` are required because a
+ * provider that reports usage at all always knows both; the cache counters are optional because not
+ * every provider family exposes them.
+ *
+ * Review r1 finding 5: ONE convention for every family (provider-runtime's `usage` event):
+ * `inputTokens` is the NON-cached prompt; `cacheReadTokens`/`cacheWriteTokens` are disjoint from it.
+ */
+export interface ProviderUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** WS-23: the 1-hour-lifetime SUBSET of `cacheWriteTokens` (provider-runtime's `usage` event says why). */
+    cacheWrite1hTokens?: number;
+    /** WS-23: the provider's own verdict on where this request's prefix diverged from the previous one. */
+    cacheMiss?: {
+        type: string;
+        missedInputTokens?: number;
+    };
+    /** WS-23: replayed thinking blocks the provider dropped (Anthropic's `input_transformations`). */
+    thinkingBlocksDropped?: number;
+}
+export type ProviderTurn = {
+    kind: "text";
+    text: string;
+    usage?: ProviderUsage;
+    stopReason?: ProviderStopReason;
+    stopDetails?: ProviderStopDetails;
+    thinking?: ProviderThinkingOutput;
+    nativeState?: ProviderNativeState;
+    content?: ContentBlock[];
+    responseId?: string;
+} | {
+    kind: "tool_use";
+    calls: Array<{
+        id: string;
+        name: string;
+        input: unknown;
+    }>;
+    text?: string;
+    usage?: ProviderUsage;
+    stopReason?: ProviderStopReason;
+    stopDetails?: ProviderStopDetails;
+    thinking?: ProviderThinkingOutput;
+    nativeState?: ProviderNativeState;
+    content?: ContentBlock[];
+    responseId?: string;
+};
+export interface Provider {
+    generate(input: ProviderRequest): Promise<ProviderTurn>;
+}
+/** WS-23 (M-7): the tool result a call gets when its turn stopped at the output limit, so the call was never run. */
+export declare const OUTPUT_LIMIT_TRUNCATED_CALL_TEXT = "Error: this tool call was not run. Your response hit the output token limit (max_tokens) before the call's input was complete, so its arguments may be truncated. Issue the call again; if its input is large (a whole file, a long command), split it into smaller calls.";
+/** WS-23: the most times one user envelope re-sends a `pause_turn` response before ending typed. The vendor's own handling guide caps continuations at 5. */
+export declare const MAX_PAUSE_TURN_CONTINUATIONS = 5;
+/**
+ * WS-23 (block order): a turn's assistant content in STREAM ORDER (`ProviderTurn.content`), or
+ * `undefined` when the provider reported none -- the caller then falls back to the per-kind assembly.
+ *
+ * CHECKED, NOT TRUSTED: the tool loop answers `turn.calls`, so a `tool_use` turn's ordered content must
+ * name exactly those calls, in that order. A persisted `tool_use` with no `tool_result` after it (or a
+ * result for a call the content never carried) is a 400 on the very next request, so a list that
+ * disagrees with `calls` is ignored rather than persisted; likewise a `text` turn's content may carry
+ * no call at all.
+ */
+export declare function inStreamOrder(turn: ProviderTurn): ContentBlock[] | undefined;
+/**
+ * WS-23 (reasoning-state): an assistant turn's content as the HOST sees it on the `assistant` frame --
+ * every in-dialect reasoning block keeps its readable text and loses its attestation: `signature` and
+ * `redacted_thinking.data` become `""`. Those bytes exist for one reader, the Anthropic API on the next
+ * request, and they reach it from the provider-state sidecar; a host (the daemon, a phone, a log) has no
+ * use for them and every copy is one more place an opaque token can leak from. The block SHAPES stay,
+ * so a host that renders "thinking…" or "[redacted]" keeps working.
+ */
+export declare function contentForHost(content: ContentBlock[]): ContentBlock[];
+/**
+ * Phase 6 (R6-9), widened by the fix wave: the session's RESOLVED provider identity as the engine
+ * carries it -- the `MessageOrigin` half every `origin` record and `providerAnnotations` read, plus
+ * the catalog/credential half the dialect record stores. One shape for the startup identity
+ * (`EngineOptions.providerIdentity`) and for every identity a switch installs, so a restamp after a
+ * `set_model` or a fallback writes the SAME fields the startup stamp did.
+ */
+export interface EngineProviderIdentity {
+    providerId: string;
+    modelKey: string;
+    family: string;
+    continuationDomain?: string;
+    adapterId?: string;
+    adapterVersion?: string;
+    catalogVersion?: string;
+    authRefKind?: string;
+}
+/**
+ * P6 fix wave (Ruling E-2): what the switch seam answers for a target model it could resolve.
+ *
+ * `provider` is BUILT (a fresh `adapterAsProvider` under Ruling E-1's material rule), `identity` is
+ * what the engine installs as `currentProviderIdentity`, `to` carries the target's continuity facts
+ * for `classifySwitch`, and `from` the source's when the caller named one.
+ */
+export interface ModelSwitchResolution {
+    provider: Provider;
+    identity: EngineProviderIdentity;
+    to: ContinuityEndpoint;
+    from?: ContinuityEndpoint;
+}
+/**
+ * P6 fix wave (Ruling E-4, R6-H): what the wiring answers when it can PRICE a generation. `undefined`
+ * for an unpriced row -- then no cost field is emitted and `maxBudgetUsd` is inert (disclosed).
+ * `costBasis` is always `"list"` here: `estimateCostUsd` reports a price only for `official-doc`
+ * pricing evidence, and an unpriced or inferred row is exactly the `undefined` case.
+ */
+export interface PricedUsage {
+    costUsd: number;
+    costBasis: "list";
+    /** The catalog key the price was looked up under (`ModelUsage.canonicalModel`). */
+    canonicalModel: string;
+    /** The pinned `AccountInfo.apiProvider` family when the provider has one; omitted otherwise. */
+    provider?: string;
+    /** From the descriptor when known, otherwise OMITTED -- never invented (R6-H). */
+    contextWindow?: number;
+    maxOutputTokens?: number;
+}
+/** The seam's typed refusal: R6-K's `provider-mismatch`, `unknown-model`, and every other resolution code -- NEVER a parked switch. */
+export interface ModelSwitchRefusal {
+    refused: true;
+    code: string;
+    message: string;
+}
+/**
+ * P6 fix wave (Ruling E-2): the switch seam, shaped like `resolveChildProvider`. Owned by
+ * `provider/session-provider.ts`: R6-K resolution UNDER THE SESSION PROVIDER (a qualified key naming
+ * another provider is `provider-mismatch`), `buildProvider` under Ruling E-1, and the resolved
+ * identity. The engine calls it FIRST -- before parking anything -- so an unresolvable target is a
+ * control-response refusal, never a model string the wire later chokes on.
+ */
+export type ResolveModelSwitch = (model: string, from?: MessageOrigin) => ModelSwitchResolution | ModelSwitchRefusal;
+/**
+ * The session's running context-window accounting (R5-3), and the input R5-4's compaction trigger
+ * reads: compact when `contextTokens() >= compactionThreshold * limit()`.
+ *
+ * `contextTokens()` is the LAST generation's input + output, not a running total -- an accumulated
+ * sum would grow without bound across a conversation and cross any threshold regardless of how much
+ * context actually survives, which is the opposite of what the trigger means. Cache read/write
+ * counters are informational and deliberately excluded: they describe how the same input was BILLED,
+ * not how much of the window it occupies.
+ *
+ * `limit()` is `contextWindowTokens` -- a DISCLOSED Winter session option, default 200000, until P6's
+ * model catalogue supplies real per-model values. The pin has no per-session equivalent at all (its
+ * nearest relative is the `autoCompactWindow` SETTING, `sdk.d.ts:7599`).
+ */
+export interface ContextAccountant {
+    contextTokens(): number;
+    limit(): number;
+    record(usage: ProviderUsage): void;
+    /**
+     * RULING P5-J (Phase 5 fix wave): the session's CUMULATIVE token spend, monotonically increasing.
+     *
+     * DELIBERATELY NOT `contextTokens()`, and the difference is the whole ruling.
+     * `contextTokens()` is the LAST provider call's context SIZE -- an overwrite, not an accumulation.
+     * It goes DOWN after a compaction and it says nothing about what a session has spent, so a budget
+     * ceiling read off it would be un-reached by a smaller call and un-reached again by a compaction.
+     * `spentTokens()` only ever grows, which is the only shape a ceiling can be built on.
+     *
+     * CHILD USAGE ROLLS UP. A child engine records into its own accountant for its own context
+     * arithmetic AND adds the same usage here, so a workflow's `budget` bounds the work its agents do
+     * rather than only the parent's own turns -- which was the gap that made `budget.spent()` report
+     * an honest but useless 0.
+     */
+    spentTokens(): number;
+    /**
+     * P5-J: fold a DESCENDANT's usage into this accountant's cumulative total WITHOUT touching
+     * `contextTokens()`.
+     *
+     * Two counters, one call, and they must not be conflated: a child's tokens are spend the session
+     * is responsible for, and they are NOT part of the parent's own next request, so adding them to
+     * the context reading would make the parent compact on a window it does not have.
+     */
+    recordDescendantUsage(usage: ProviderUsage): void;
+    /**
+     * WS-23 (reasoning-state, decision 5): the window moves with the model. A switch re-sources the limit
+     * from the TARGET's row -- the auto-compaction threshold used to keep reading the first model's window
+     * for the rest of the session. Optional: an injected accountant without it keeps its own limit.
+     */
+    setLimit?(limit: number): void;
+}
+export { DEFAULT_CONTEXT_WINDOW_TOKENS };
+export interface ContextAccountantOptions {
+    /** Defaults to DEFAULT_CONTEXT_WINDOW_TOKENS. A non-positive value is ignored (the default stands) rather than producing a limit no session could ever sit under. */
+    limit?: number;
+}
+export declare function createContextAccountant(opts?: ContextAccountantOptions): ContextAccountant;
+export interface ToolExecutor {
+    /**
+     * Phase 6 Task 3 (R6-6, P4 carry): `opts.signal` is ABORTED when the turn is interrupted.
+     *
+     * OPTIONAL on both sides, and additive: every pre-existing executor keeps satisfying this
+     * interface unchanged, and an executor that ignores the signal behaves exactly as before. What
+     * changes is that an executor which HONOURS it stops the work rather than merely being abandoned --
+     * "a stopped child starts nothing new AND its in-flight Bash is killed" (R6-6), which was
+     * previously impossible because the interrupt was a raced Promise with no channel into the tool.
+     */
+    execute(call: {
+        id: string;
+        name: string;
+        input: unknown;
+    }, opts?: {
+        signal?: AbortSignal;
+        explicitApproval?: "prompt" | "rule";
+    }): Promise<{
+        output: string;
+        isError?: boolean;
+    }>;
+}
+/**
+ * SDK 0.0.16: one extra attachment producer (`EngineOptions.attachmentProducers`). `messages` is the
+ * engine's live history -- after a compaction, claude's post-boundary slice -- for folds to read.
+ */
+export type AttachmentProducer = (ctx: {
+    phase: "turn-start" | "tool-round" | "compaction";
+    messages: readonly ProviderMessage[];
+    sessionId: string;
+    agentId?: string;
+}) => AttachmentPayload[] | Promise<AttachmentPayload[]>;
+/**
+ * SDK 0.0.16 Lane N: what marks a user entry as one the RUNTIME wrote rather than the human. claude's
+ * own transcript shape: `isMeta: true` plus an `origin` naming why the turn exists (today only
+ * `{kind: "task-notification"}`). Optional on both sides -- a store that ignores it records exactly
+ * what it recorded before.
+ */
+export interface UserEntryMeta {
+    isMeta?: boolean;
+    origin?: {
+        kind: string;
+        [k: string]: unknown;
+    };
+}
+export interface SessionPersistence {
+    /**
+     * WS-23: the durable transcript's absolute path, when the store knows it (store/dialect.ts's
+     * writer does). A command hook's stdin names it as `transcript_path`; absent, that field is `""`.
+     */
+    transcriptPath?: string;
+    recordUserEntry(content: string | ContentBlock[], opts?: UserEntryMeta): void | Promise<void>;
+    /**
+     * SDK 0.0.16 (P16-5/P16-6): one persisted attachment -- claude's `{type: "attachment", attachment}`
+     * transcript entry, chained like any other. Optional: a store without it keeps the attachment in
+     * this run's memory only (a resumed session then re-announces it).
+     */
+    recordAttachmentEntry?(attachment: AttachmentPayload): void | Promise<void>;
+    /**
+     * Phase 6 Task 3 (R6-7): `opts.uuid` PRE-ALLOCATES the entry's own dialect uuid.
+     *
+     * The engine mints the uuid, appends the sidecar `origin` record naming it as `anchorUuid`, and
+     * only THEN calls this -- write-ahead, so a crash can leave a record without an entry (ignorable,
+     * garbage-collectable) but never an entry without a record it needed. Omitted by every pre-P6
+     * caller, in which case the writer mints its own exactly as before.
+     */
+    /**
+     * WS-23: `effort`/`perTurnEffort` are claude's own assistant-entry fields -- the top-level effort
+     * the request sent and the level in force for the turn. Present only when the session has a named
+     * effort; the store writes them as top-level entry fields, and resume carries them back onto the
+     * rebuilt message so the effort markers re-derive at the same positions.
+     */
+    recordAssistantEntry(content: ContentBlock[], opts?: {
+        uuid?: string;
+        effort?: string;
+        perTurnEffort?: string;
+    }): void | Promise<void>;
+    /**
+     * R6-7: one provider-state record. MUST be called BEFORE `recordAssistantEntry` for the same
+     * `anchorUuid` -- that ordering is the whole guarantee, and provider-state.ts's crash-pair fixture
+     * asserts the file order rather than trusting this comment.
+     *
+     * Optional, matching every other method here: a store that predates this field (or a bare test
+     * double) simply never gets asked, and the session keeps an in-memory chain only.
+     */
+    recordProviderState?(record: ProviderStateRecordInput): void | Promise<void>;
+    /** R6-7: the chain, oldest-first, for a resumed session. `undefined`/absent means "no durable chain", which degrades every resumed assistant message to summary-level with a `continuity_warning`. */
+    loadProviderState?(): Promise<ProviderStateRecord[]>;
+    /**
+     * R6-9 / WS-16 §4: the resolved provider identity every subsequent dialect record carries
+     * (`providerId`/`modelKey`/`adapterId`/`adapterVersion`/`catalogVersion`/`authRef`/`classifierPin`).
+     *
+     * A SEAM ADDITION beyond the brief's literal block, and it has to be one: the identity fields are
+     * named as this task's deliverable and `SessionPersistence` is the only channel the engine has to
+     * the store. `authRef` is the credential ref's KIND, never its material (R6-10).
+     */
+    setProviderIdentity?(identity: {
+        providerId: string;
+        modelKey: string;
+        adapterId?: string;
+        adapterVersion?: string;
+        catalogVersion?: string;
+        authRefKind?: string;
+        classifierPin?: string;
+    }): void;
+    /**
+     * Review round 1 (I1): did this session ever RECORD a provider identity?
+     *
+     * `undefined` means "no identity block" -- a pre-P6 transcript, or one written before selection was
+     * wired. That is the ONLY thing distinguishing R6-7's two silent-looking resumes: a session with no
+     * records and no identity has nothing to degrade from, while one with an identity and no records
+     * had its sidecar DELETED and every message is degraded.
+     */
+    loadProviderIdentity?(): Promise<{
+        providerId: string;
+        modelKey: string;
+    } | undefined>;
+    /** R6-C: records a model swap in the dialect record's `providerHistory`, alongside the Winter-only `system/model_switch` frame. */
+    recordProviderSwitch?(entry: {
+        from: string;
+        to: string;
+        reason: "fallback" | "set_model" | "interrupt";
+    }): void;
+    flush?(): void | Promise<void>;
+    recordPermissionUpdate?(update: PermissionUpdate, authority: RuleSource): void | Promise<void>;
+    recordHookAudit?(entry: HookAuditRecord): void | Promise<void>;
+    /**
+     * Phase 5 Task 8 (rider 16): Lane S's `invoked_skills` attachment. Optional, like every other
+     * method here. The engine never calls it -- `skills/runtime.ts`'s `onInvoked` sink does, wired by
+     * `production-wiring.ts` -- but it lives on this interface because it is a DURABLE session record
+     * and this is the one seam the engine's storage-agnostic contract exposes for those.
+     */
+    recordInvokedSkills?(attachment: {
+        type: string;
+        skills: unknown[];
+    }): void | Promise<void>;
+    /**
+     * Phase 5 Task 8 (riders 9/16): one of Lane K's checkpoint records, as a transcript-visible entry.
+     * See `store/dialect.ts`'s `FILE_HISTORY_ENTRY_TYPE_BY_KIND` for what this closes (a transcript
+     * reader can see that a rewind is possible) and what it does not (the `backups/index.jsonl`
+     * sidecar remains the rewind's own read authority).
+     */
+    recordFileHistory?(record: {
+        kind: "snapshot" | "delta";
+        userMessageUuid: string;
+        path: string;
+        pathHash: string;
+        tool: string;
+        at: string;
+        version: number;
+        absent?: boolean;
+        parentRealPath?: string;
+        anchorPath?: string;
+        anchorRealPath?: string;
+    }): void | Promise<void>;
+    recordCompactBoundary?(record: CompactBoundaryRecord): CompactBoundaryWriteResult | void | Promise<CompactBoundaryWriteResult | void>;
+}
+export interface EngineOptions {
+    config: RuntimeConfig;
+    input: FrameSource;
+    output: FrameSink;
+    provider: Provider;
+    tools?: ToolExecutor;
+    unregisteredToolExecutor?: ToolExecutor;
+    store?: SessionPersistence;
+    initialMessages?: ProviderMessage[];
+    approvalStore?: DurableApprovalStore;
+    autoStateStore?: AutoCounterStore;
+    env?: Record<string, string | undefined>;
+    providerSupportsToolSearch?: boolean;
+    deferrableContextShare?: number;
+    mcpServerStateSource?: McpServerStateSource;
+    /**
+     * Fix round 20/21: every MCP server the PARENT run can see (`ParentMcpState.visibleServerNames`,
+     * read at call time), handed to EVERY child engine -- whether or not it owns servers of its own --
+     * so the scope recurses: a grandchild of a subagent that owns a server sees the session's servers
+     * and that subagent's. Read ONLY to scope the advertised partition's MCP tools and ToolSearch's pool
+     * (`computeAdvertisedPartition`); never connected, never reported on `mcp_servers`/`mcp_status`.
+     * Round 20 carried the parent's board only, and only to a child with object-form servers.
+     */
+    inheritedMcpServerNames?: () => readonly string[];
+    mcpControlSeam?: McpControlSeam;
+    contextAccountant?: ContextAccountant;
+    onChildRosterReady?: (getChildren: () => readonly ChildHandle[]) => void;
+    onForegroundChildrenReady?: (getForeground: () => readonly ChildHandle[]) => void;
+    /**
+     * R5-16: prompt assembly (Lane C). Called once per user envelope; its `system` goes on the live
+     * `ProviderRequest`. SDK 0.0.16: its `userContext()` builds the index-0 context message, memoized
+     * per session (context/request-layout.ts). ABSENT => the engine sends `agentSystemPrompt` (or
+     * nothing), no index-0 message, and authors no text of its own -- see context/seam.ts.
+     */
+    systemPromptAssembler?: SystemPromptAssembler;
+    /**
+     * SDK 0.0.16 (P16-5/P16-6): extra PERSISTED-ATTACHMENT producers, run by the attachment scan at the
+     * start of every turn, after every tool round and after a compaction -- after the built-in ones
+     * (agent listing, skill listing, date change). Whatever they return is appended to the history as
+     * attachment messages (context/attachments.ts), persisted, and sent in claude's positions. The
+     * reusable door for other lanes' attachments (task notifications, plan-mode reminders).
+     */
+    attachmentProducers?: readonly AttachmentProducer[];
+    /**
+     * WS-21 §6.3 item 1 (fix round 2): the session's ENABLED plugins that ship a `workflows/`
+     * directory -- threaded into `RegistryToolExecutorDeps.pluginWorkflows` (registry.ts) so the
+     * Workflow tool's `<plugin>:<name>` resolution (`workflows/store.ts`) can find them. A plain
+     * value, not a getter: a session's loaded-plugin set is resolved once per incarnation, like
+     * skills/agents/MCP are.
+     *
+     * Fix round 4 (minors, M-3's last bullet): `workflowsPaths` (a manifest `workflows` override,
+     * `plugins/bundle.ts`'s own citation) is carried alongside `workflowsPath` from here on -- every
+     * hop between `production-wiring.ts`'s own local array and `workflows/store.ts`'s consumption of
+     * it forwards this SAME array reference rather than rebuilding each element, so the value already
+     * survived the trip before this type caught up; widened here so a future hop that DOES rebuild an
+     * element is caught by the type checker instead of silently dropping the field.
+     */
+    pluginWorkflows?: readonly {
+        name: string;
+        workflowsPath?: string;
+        workflowsPaths?: readonly string[];
+    }[];
+    /**
+     * SV-5 fix round 3 (I-4): the session's resolved `settingSources`, threaded to
+     * `RegistryToolExecutorDeps.settingSources` / `ToolExecutionContext.settingSources` so the
+     * Workflow tool's project/user tier resolution is gated on `"project"`/`"user"` membership, not
+     * `trustedWorkspace` alone -- the same fact `production-wiring.ts` already resolves once per
+     * incarnation for skills/agents/rules. Absent means every tier is allowed, matching every
+     * pre-fix-round-3 caller.
+     */
+    settingSources?: readonly SettingSource[];
+    /**
+     * SDK 0.0.16: the model's display name for the `# Environment` section's model line, when the host
+     * knows one (production wiring answers from the catalog). Absent => the bare-id line.
+     */
+    describeModel?: (model: string, providerId?: string) => ModelDescription | undefined;
+    /** SDK 0.0.16: the engine's clock for the `currentDate` entry and the `date_change` fold. Tests only; absent => `new Date()`. */
+    now?: () => Date;
+    /**
+     * R5-3 / P4-J retirement: the child persona a subagent runs with (`AgentDefinition.prompt`
+     * composed over any inherited base). Reaches the assembler as `SystemPromptInput.agentPrompt`, and
+     * IS the system prompt when no assembler is registered. Set by subagents/child-engine.ts; never by
+     * a top-level host.
+     */
+    agentSystemPrompt?: string;
+    /**
+     * Spawn-surface parity (research §A1, `omitClaudeMd`): set by subagents/child-engine.ts from the
+     * child's resolved definition (`RuntimeAgentDefinition.omitProjectContext` -- the `Explore`/`Plan`/
+     * `web-fetch` built-ins). The assembler then drops the discovered instructions files and the git
+     * summary for this run. Never set by a top-level host.
+     */
+    omitProjectContext?: boolean;
+    /**
+     * SDK 0.0.16 (P16-7, R3a §2): a FORK child's exact inherited request layout -- set ONLY by
+     * `subagents/child-engine.ts`'s own fork branch, from `ChildInheritance.requestLayout`, never by a
+     * top-level host. When present, this run's system prompt, tool specs and userContext are sent
+     * EXACTLY as captured (`assemblePrompt`/`ensureSessionContext`/`requestSystem`/`providerToolSpecs`
+     * below all short-circuit to it) -- never re-rendered, however faithfully, because WS-10 §3.5's
+     * "inherits... system prompt... tool pool... verbatim" cannot survive a second independent render
+     * (a different registry snapshot, a different git status, a different local clock all touch the
+     * SAME bytes claude's own fork keeps frozen). `systemPromptAssembler`/`agentSystemPrompt` are never
+     * consulted while this is set -- not even to build the FIRST-turn input, which a fork never needs
+     * one for (its own directive rides `initialMessages`, not `agentSystemPrompt`).
+     */
+    exactRequestLayout?: SessionRequestLayout;
+    /**
+     * R5-14: slash-command resolution (Lane S owns the filesystem half; the engine owns the built-ins
+     * and the ordering between them). Consulted BEFORE the model sees a prompt. ABSENT => only the
+     * built-ins resolve and every other prompt passes through verbatim.
+     */
+    commandResolver?: CommandResolver;
+    /**
+     * R5-4: the compaction vehicle (Lane K). Consulted before every provider call of a turn (the AUTO
+     * trigger) and by `/compact` (the MANUAL one). ABSENT => no auto-compaction happens and `/compact`
+     * says so -- the engine never summarizes on its own.
+     */
+    compactionController?: CompactionController;
+    /**
+     * R5-10: structured output (Lane K). REQUIRED for `config.outputFormat` to do anything -- the
+     * engine registers the host-generated `StructuredOutput` descriptor this seam builds and validates
+     * every call through it. `outputFormat` set with NO seam is reported as a configuration error on
+     * the first turn rather than silently ignored: a session that believes it will get a structured
+     * result and instead gets prose has no way to tell that from a model failure.
+     */
+    structuredOutput?: StructuredOutputSeam;
+    /**
+     * R5-11: file checkpointing (Lane K). Consulted before every Write/Edit/NotebookEdit when
+     * `config.enableFileCheckpointing` is on, and by the `rewind_files` control request. ABSENT with
+     * checkpointing enabled means nothing is backed up and `rewind_files` answers `canRewind: false` --
+     * never a throw, and never a silent "success" that restores nothing.
+     */
+    fileCheckpointSink?: FileCheckpointSink;
+    /**
+     * The resolved winter root for THIS session (`config.winterHome ?? resolveWinterHome(env, brand)`).
+     * Passed rather than re-derived so this file and `store/dialect.ts` can never disagree about where
+     * a session lives -- and because `dialect.ts` imports types from this module, so the reverse import
+     * would be circular. Consumed by the workflow session registration below.
+     */
+    winterHome?: string;
+    /**
+     * Hook entries from SETTINGS FILES and PLUGIN MANIFESTS, already parsed by
+     * `buildHookEntriesFromSettings` (the one parser for that block shape). Concatenated with this
+     * session's own `config.hooks` entries; the WHOLE array feeds both `buildHookRegistry` (which
+     * applies the workspace-trust filter) and `createCommandHookInvoker` (which dispatches
+     * `{type:"command"}` entries BY ID -- so it must be built from the same array, or an id will not
+     * be found).
+     */
+    extraHookEntries?: readonly SourcedHookEntry[];
+    /**
+     * WS-23: set ONLY by `subagents/child-engine.ts` for a child's own engine. A subagent fires
+     * `SubagentStart` where a session fires `SessionStart`, and `SubagentStop` where a session fires
+     * `Stop` -- claude's own split ("Converting Stop hook to SubagentStop"), so a hook can tell a
+     * subagent finishing from the session finishing, and a SubagentStop `block` keeps THE SUBAGENT
+     * going (the child's own turn loop, below) rather than the parent. `agentType` is the resolved
+     * `subagent_type`; `agentTranscriptPath` the child's own transcript (`""` when it has none).
+     */
+    subagentHooks?: {
+        agentType: string;
+        agentTranscriptPath: string;
+    };
+    /**
+     * MCP server sources beyond the host's own `config.mcpServers`: the settings tiers,
+     * the project `mcp.json`, and plugin manifests. Appended AFTER the explicit source, so an explicitly
+     * configured server still wins; `resolveMcpServerSources` owns precedence, duplicate names, the
+     * reserved `winter` name and the project-origin trust gate, exactly as before.
+     *
+     * "PROJECT-ORIGIN", NOT "STDIO" (rd-1, residual round 2). P4's gate was stdio-literal because
+     * process execution was the visible danger; RULING P5-K widened it to every transport, and
+     * `lifecycle.ts`'s own header has said so since. This sentence kept the old name -- a stale
+     * summary of a rule that had moved, which is exactly how a reader concludes an http server from a
+     * clone connects freely.
+     */
+    extraMcpServerSources?: readonly McpServerSource[];
+    /**
+     * `system/init.slash_commands`. Produced by `slashCommandNames(resolver, cwd)`, which ALREADY
+     * includes the engine's own `/compact` -- the engine must not prepend it a second time.
+     */
+    initSlashCommands?: readonly string[];
+    /** `system/init.skills` -- this session's EFFECTIVE set (the `skills` filter applied), not the whole index. */
+    initSkills?: readonly string[];
+    /** `system/init.plugins` -- `pluginInitInfo(bundles)`, with resolved absolute paths. */
+    initPlugins?: readonly InitPluginInfo[];
+    /** `system/init.output_style` -- the CONFIGURED name (`config.outputStyle ?? settings.outputStyle ?? "default"`). */
+    initOutputStyle?: string;
+    /**
+     * The POST-TRUNCATION model-facing skill listing (R5-17). Lane S produces it; Lane C's assembler
+     * places it; neither re-derives the other's caps.
+     *
+     * The engine's own contribution is the one thing neither lane can see: it withholds the listing
+     * whenever `Skill` is NOT in this session's advertised set. Lane C's NEEDS_CONTEXT 3 named that
+     * gap exactly -- a listing tells the model to "call the `Skill` tool", and a session with a
+     * restricted `tools` list would be instructed to call a tool it does not have. `Skill` is in the
+     * pinned default 24 (capture (g)), so the default path is unaffected.
+     *
+     * SDK 0.0.16: rendered as claude's persisted `skill_listing` attachment -- once, then only the
+     * skills not yet sent (session state, seeded on resume, kept across compaction). A GETTER is read
+     * afresh at every attachment scan, which is how a skill added mid-session reaches the model.
+     */
+    skillListing?: SkillListing | (() => SkillListing);
+    /**
+     * Phase 5 fix wave, C1: the settings-file `permissions` block, per tier.
+     *
+     * Before this the engine seeded its rule set from `config.{allowedTools,disallowedTools,permissions}`
+     * ALONE, so the only `project`/`local`/`user`-sourced entry a live session could hold came from a
+     * `canUseTool` answer carrying `addRules`. A `deny` in `~/.winter/settings.json` was silently not a
+     * deny; the whole P5-A/P5-D trust matrix guarded a path a settings file never entered.
+     *
+     * PLAIN DATA, resolved once by `production-wiring.ts` (both entrypoints), so a spawned or compiled
+     * child gets the identical seed. Folded into `initialRules` AFTER the managed baseline denies and
+     * BEFORE the `sdk` entries -- which is the pinned precedence: managed floor, then files
+     * (`perSource`'s own highest-first order), then the host's own `Options`.
+     */
+    settingsRules?: EngineSettingsRuleSeed;
+    /**
+     * Phase 6 Task 3 (P1 carry): the per-message input byte cap on provider input, overridable for
+     * tests and for a host that knows its own provider's real limit.
+     *
+     * An ENGINE OPTION rather than a `RuntimeConfig`/`Options` field, deliberately and disclosed: the
+     * default is a Winter-authored safety bound with no pinned counterpart, and adding an `Options`
+     * field would put an un-pinned knob on the public compatibility surface for a value no host has
+     * asked to tune. Absent -> `DEFAULT_MAX_PROVIDER_MESSAGE_BYTES`.
+     */
+    maxProviderMessageBytes?: number;
+    /**
+     * Phase 6 Task 3 (R6-9): the session's RESOLVED provider identity.
+     *
+     * The one input that makes the write-ahead sidecar path live: with no identity there is nothing to
+     * name in an `origin` record, so `recordAssistant` writes none and the session behaves exactly as
+     * it did before this phase. `provider/selection.ts` produces this and T10's wiring passes it in --
+     * an ENGINE OPTION rather than something the engine resolves itself, for the same reason the
+     * provider is (the engine must stay driveable by a plain double).
+     */
+    providerIdentity?: EngineProviderIdentity;
+    /**
+     * Phase 6 Task 10: the pinned `system/init.apiKeySource` (`sdk.d.ts:4860`, REQUIRED).
+     *
+     * An ENGINE OPTION rather than something derived here, for the same reason `providerIdentity` is:
+     * the mapping from Winter's own `CredentialRef` kinds onto the pin's four-member vocabulary is the
+     * WIRING's decision (`provider/session-provider.ts`'s `apiKeySourceFor`, which documents why every
+     * non-`ANTHROPIC_API_KEY` shape reports `'none'`), and the engine must stay driveable by a plain
+     * double that has no credential model at all.
+     *
+     * Absent -> `"none"`, which is the honest value for a session with no credential ref and is what
+     * every pre-P6 golden's init frame is regenerated against.
+     */
+    apiKeySource?: string;
+    /**
+     * Phase 6 Task 10 (R6-I): the session's model catalogue and account surface, as the control
+     * handlers below answer them.
+     *
+     * BOTH ARE FUNCTIONS, not values, and both come from the WIRING rather than being computed here:
+     * the engine has no registry and no credential model, and giving it one would be a second
+     * resolution path that could disagree with the session's own.
+     *
+     * `supportedModels` answers the pinned payload-free `list_models` control request
+     * (`sdk.d.ts:3855`), whose own JSDoc frames it as "ask the worker" — a table inside the binary, per
+     * capture (J), never a `/v1/models` fetch. Absent -> the handler answers an empty array, which is
+     * the honest answer for a session running a scripted double.
+     */
+    supportedModels?: () => unknown[];
+    /**
+     * WS-13c §7 (P6.6): the session's MODEL FAMILY listing — the active slot set plus every family
+     * behind "more options".
+     *
+     * TAKES THE LIVE MODEL KEY (R-6c-21), for the same reason `activeSlotSet` does: the wiring's own
+     * view of the session's model is the START model, so a listing computed without the key reports
+     * the family a session has already switched away from. Optional, so a producer that ignores it
+     * still satisfies the type.
+     *
+     * A function from the WIRING for the same reason `supportedModels` is: the listing needs the
+     * catalog, the session's effective model AND the credential/enablement view, none of which the
+     * engine has. Absent -> the handler answers `{ active: undefined, families: [] }`, the honest
+     * answer for a session running a scripted double (`active: undefined` means "no effective model
+     * to derive a family from", NOT "no families" — that is the empty array beside it).
+     *
+     * Winter-only and disclosed: `Query.supportedModels()` keeps its pinned `ModelInfo[]` shape
+     * unchanged, and this is a separate surface rather than a widening of it.
+     */
+    listModelFamilies?: (currentModelKey?: string) => ModelFamilyListing;
+    /**
+     * WS-13c §3 (P6.6): the session's ACTIVE SLOT SET, for the model key given.
+     *
+     * TAKES THE MODEL KEY rather than reading one, and that is the whole re-render mechanism (R13c-4).
+     * The wiring's own view of the session's model is the START model (`providerWiring.resolved`);
+     * `installIdentity` updates the ENGINE's `currentModel` and never writes back, so a getter that
+     * closed over the wiring's value would keep advertising the family the session started on after a
+     * `set_model` across families — the exact "false information" D25 forbids. The engine passes
+     * `currentProviderIdentity?.modelKey ?? currentModel` and memoises on `(that key, settingsVersion())`,
+     * so all three re-render points (session start, a `set_model` that lands, a `modelSlots` change)
+     * are one comparison made at the next `providerToolSpecs()` — which happens per turn, and a turn
+     * boundary IS the quiescent boundary R13c-4 names.
+     *
+     * WHAT THIS DOES AND DOES NOT GUARANTEE (R-6c-28). The ENGINE half needs no watcher and no restart:
+     * whenever `settingsVersion()` changes, the next turn re-renders. What no part of this SDK does yet
+     * is RE-RESOLVE the settings cascade mid-session — `production-wiring.ts` resolves once and hands
+     * down a live getter, exactly as R6b-7's `providerSettings` has since WS-13b — so today the version
+     * only moves when a HOST hands down a new resolved view. Until P8's host integration does that, a
+     * `modelSlots` edit to a file is not seen by a running session. Plumbed, not yet reachable.
+     *
+     * ABSENT -> the Agent descriptor keeps its STATIC pinned enum and its description's marker block is
+     * stripped, which is what every scripted double and every pre-P6.6 fixture sees.
+     */
+    activeSlotSet?: (currentModelKey: string | undefined) => ActiveSlotSet;
+    /**
+     * WS-13c §4 (P6.6): the slot -> provider resolver, for the model key given.
+     *
+     * Consulted for a CHILD's requested model (`AgentInput.model`, `AgentDefinition.model`,
+     * `WINTER_SUBAGENT_MODEL`, and the inherited `config.model`). A refusal is THROWN out of
+     * `spawnChild` so `tools/impl/agent.ts` reports it as the tool's own typed error — never a
+     * substitution onto some other model (WS-13 §9).
+     *
+     * ABSENT -> the pre-P6.6 chain, verbatim: the requested string goes on the child unresolved.
+     */
+    resolveSlot?: (requested: string, currentModelKey: string | undefined) => SlotProviderResolution;
+    /**
+     * WS-13c §5 (P6.6): a monotonically increasing number the WIRING bumps whenever the resolved
+     * settings view changes, so a `modelSlots`/`preferredProviders` change re-renders the Agent tool at
+     * the next quiescent boundary. See `activeSlotSet` for what "the resolved view changes" requires
+     * today (a host handing one down) and what it does not (a watcher in this SDK).
+     *
+     * A NUMBER rather than the settings object, deliberately: the memo compares it, and comparing a
+     * settings OBJECT by identity would re-render on every re-resolve that changed nothing while
+     * comparing it by value would mean serialising the whole cascade once per turn.
+     */
+    settingsVersion?: () => number;
+    /**
+     * `account_info` is a WINTER-ONLY control subtype, disclosed.
+     *
+     * The pin carries `AccountInfo` on the `initialize`/`reinitialize` RESPONSE (`sdk.d.ts:3804`), and
+     * derived-shapes-p6 item (d) is explicit that `system/init` must NOT grow an `account` field for
+     * parity. Winter's protocol has no `initialize` control request to hang it on, so the surface it
+     * does expose (`Query.accountInfo()`) needs a subtype of its own rather than a field on a frame the
+     * pin does not put it on.
+     */
+    accountInfo?: () => unknown;
+    /**
+     * Phase 6 Task 10 (R6-14): the session's REAL classifier, or absent for a Manual fallback.
+     *
+     * P2 shipped `createAutoEngine`'s own `alwaysNoVerdictClassifier` default and said the real
+     * model-routed classifier was P6's job. This is that wire. ABSENCE IS MEANINGFUL and is not the
+     * same as a classifier that abstains: R6-14's Manual fallback is a session that was never given a
+     * reviewer it had evidence for, and `selectClassifierRoute` records WHY.
+     */
+    classifier?: ClassifierInterface;
+    /**
+     * P6 fix wave (Ruling E-2): the switch seam -- see `ResolveModelSwitch`. The production wiring
+     * passes it for every catalog-resolved session AND for a session whose model failed to resolve
+     * (the recovery path), and WITHHOLDS it for the reserved `winter-test/<name>` namespace; absent,
+     * `set_model` keeps its pre-fix shape: the requested string is parked verbatim and applied at the
+     * boundary with no identity to rebuild (every pre-P6 fixture, every scripted double).
+     */
+    resolveModelSwitch?: ResolveModelSwitch;
+    /**
+     * P6 fix wave (Ruling E-3): `fallbackModel`'s candidates as CATALOG KEYS, in order, already
+     * domain-checked at init by selection. Engaged through `resolveModelSwitch` when a generation fails
+     * on an R6-6 retryable class after `withRetry` gave up -- see the generation catch.
+     */
+    fallbackModels?: string[];
+    /**
+     * P6 fix wave (Ruling E-4, R6-H): prices ONE generation's usage for the model it ran on. The
+     * wiring implements it over the catalog's `pricing` evidence; absent (a scripted double) or
+     * `undefined` for an unpriced row means no cost is reported and the budget is inert.
+     */
+    priceUsage?: (modelKey: string, usage: ProviderUsage) => PricedUsage | undefined;
+    /**
+     * The catalog facts a `modelUsage` row carries for a generation `priceUsage` could NOT price (a
+     * subscription or pricing-less row): the key, the window, the provider family. Such a generation's
+     * TOKENS still land on `modelUsage` at `costUSD: 0` -- claude folds every API call into it whatever
+     * its price -- while `total_cost_usd` and `maxBudgetUsd` stay governed by priced generations only.
+     * Absent (a scripted double), or `undefined` for a key the catalog cannot resolve: the row carries
+     * the key as its `canonicalModel` and nothing it would have to invent.
+     */
+    usageRowFacts?: (modelKey: string) => UsageRowFacts | undefined;
+    /**
+     * P6 fix wave (Ruling E-5, R6-14): the classifier's own resolved identity, so the session can PIN it
+     * on the first successful classification. Present only when `classifier` is.
+     */
+    classifierIdentity?: {
+        modelKey: string;
+    };
+    /**
+     * P6 fix wave (Ruling E-5): the auto-mode audit recorder. Defaults to the no-op recorder every
+     * session ran with before (audit persistence is WS-15's projector work); a fixture injects one to
+     * observe the pin's `fallback_state` record.
+     */
+    autoAudit?: AutoAuditRecorder;
+    /**
+     * P7a LANE B (D29/D30, WS-06 §4): the ADVISOR's reviewer, for the model key given.
+     *
+     * TAKES THE MODEL KEY for the same reason `activeSlotSet` and `listModelFamilies` do: D30's
+     * default is per FAMILY, the family comes from the session's effective model, and the wiring's own
+     * view of that model is the START snapshot (`installIdentity` updates the ENGINE's, never writes
+     * back). A resolver that closed over the wiring's value would keep reviewing with the family the
+     * session began on after a cross-family `set_model` — the same false-information class D25 forbids
+     * for the Agent tool's enum, with the transcript as the payload.
+     *
+     * TWO CONSUMERS, one authority: the `advisor` tool's executor (which calls it per invocation, so a
+     * hot `settings.advisor.model` edit is seen at the next call) and the `winter.reviewer-model`
+     * capability (WS-06 §4's availability predicate — "a reviewer model is resolvable in the session's
+     * provider catalog", which is this function answering).
+     *
+     * ABSENT -> no reviewer, which is what a scripted double and a session whose own model failed to
+     * resolve both get: the tool is not advertised, and if a host advertised it anyway (by supplying
+     * the capability token) it returns WS-06 §4's ordinary "reviewer unavailable" tool error.
+     */
+    resolveReviewer?: (currentModelKey?: string) => ResolvedReviewer | undefined;
+    /**
+     * A TOOL'S STATED INNER MODEL, by tag (`RuntimeConfig.web.fetch.digestModel` is the first) -- the
+     * wiring's `resolveAuxiliaryModel`, under the cross-provider credential rule. Takes the live model
+     * key for the same reason `resolveReviewer` does: a slot NAME resolves against the family the
+     * session is on NOW, and the wiring's own view of that is the start snapshot.
+     *
+     * NOT consulted for "the session's own model": the engine already holds that provider, live.
+     * ABSENT (a scripted double, a refused session, a child engine) -> a root run treats a stated tag
+     * as unresolvable; a child inherits the root's through the web session registry.
+     */
+    resolveAuxiliaryModel?: (tag: string, opts?: {
+        authRef?: CredentialRef;
+        currentModelKey?: string;
+    }) => AuxiliaryModelResolution;
+    /** The wiring's tool-secret resolver (`provider/tool-secret.ts`), reached by a tool through the web session registry. */
+    resolveToolSecret?: ToolSecretResolver;
+    /**
+     * Called for EVERY generation this run prices -- its own main-loop and inner generations, and
+     * every descendant's it folded in. A CHILD engine is handed its parent's
+     * `ChildEngineRunContext.recordDescendantCost` here, which is what makes a subagent's spend reach
+     * the SESSION's `total_cost_usd`/`modelUsage` and therefore `maxBudgetUsd`. The token roll-up
+     * (`recordDescendantUsage`) cannot do this job: it carries no model key, and a price is per model.
+     */
+    onPricedGeneration?: (entry: PricedGenerationEntry) => void;
+    /**
+     * A SUBAGENT run only: has an ANCESTOR crossed its `maxBudgetUsd`? ORed into this run's own
+     * `budgetExceeded()`. A child's config deliberately carries NO ceiling of its own -- its ledger is
+     * only its own subtree, so the root's number would be compared against the wrong total -- which left
+     * a child's main loop (and any inner-model pass inside it) the one place a session could keep
+     * spending past its limit. Costs fold upward SYNCHRONOUSLY (`onPricedGeneration`), so the owning
+     * run's answer is already true for the whole tree by the time a descendant asks. Each level hands
+     * its OWN `budgetExceeded` down, so the chain reaches the root through any depth.
+     */
+    ancestorBudgetExceeded?: () => boolean;
+}
+/**
+ * One generation, as it travels up the agent tree: the model it ran on, what it used, and -- when
+ * the row is priced -- what that cost. `priced` ABSENT is an unpriced generation (subscription or
+ * pricing-less row): its tokens still land on `modelUsage` at `costUSD: 0`, described by `row`.
+ */
+export interface PricedGenerationEntry {
+    modelKey: string;
+    usage: ProviderUsage;
+    priced?: PricedUsage;
+    /** For an unpriced generation: the row facts `modelUsage` carries (from `EngineOptions.usageRowFacts`). */
+    row?: UsageRowFacts;
+}
+/** What a `modelUsage` row states about a model it could not price. Omitted fields are unknown, never invented. */
+export interface UsageRowFacts {
+    canonicalModel: string;
+    provider?: string;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+}
+/**
+ * The settings seed as the ENGINE consumes it -- named and exported by the residual round (NEW-4)
+ * because a CHILD engine needs the identical value and the chain that carries it
+ * (`production-wiring.ts` -> `register-default-factory.ts` -> `child-engine.ts`) would otherwise
+ * have re-declared this shape three more times. `production-wiring.ts`'s `SettingsRuleSeed` is the
+ * producer's view (mutable arrays plus its own `warnings`); this is the consumer's.
+ */
+export interface EngineSettingsRuleSeed {
+    entries: readonly SourcedRuleEntry[];
+    directories: ReadonlyArray<{
+        path: string;
+        source: RuleSource;
+    }>;
+    defaultMode?: string;
+    disableBypassPermissionsMode?: boolean;
+}
+/**
+ * The turn engine (WS-04 §4.1 state machine: `initializing → idle → turn_active → draining →
+ * closing`). A "turn" is one user envelope through its terminal result; a "tool round" is one
+ * provider tool_use → execute → results-appended → provider-again cycle. Always terminates when
+ * input ends (stdin EOF or an explicit `end_input` control request) — the P0 dangling-loop bug
+ * class is structurally impossible here, though the SHAPE of that guarantee inverted under Ruling
+ * P2-B: `end_input` no longer ends the pump's own read (it only ends `userFrames`, so a runtime-
+ * originated permission RPC arriving after end_input can still be answered) — engine completion now
+ * explicitly cancels the pump instead, once the turn loop has fully drained. See the pump's own
+ * definition further down for the full re-argued termination guarantee.
+ */
+export declare function buildBaselineDenyRules(resolvedWinterHome?: string, brand?: Pick<BrandProfile, "homeDirName">, resolvedStoreHome?: string): SourcedRuleEntry[];
+/**
+ * Fix r2 (N4): the facet's PROCESS-LEVEL registrations, withdrawn from a `finally` that no throw can
+ * skip.
+ *
+ * `runEngine`'s own teardown is a straight-line block near the end of ~2400 lines, and its own
+ * comment says plainly that the `finally` half was never landed ("the residual exposure is: a future
+ * throw from anywhere in those 1800 lines"). That was tolerable while only a session a host had
+ * SUBSCRIBED to held a handle; unconditional self-peer registration made it every session, and a
+ * leaked handle keeps answering `list_reachable` and `deliverToSession` for a session that is gone,
+ * out of a `status()` closure reading dead state.
+ *
+ * This is the cheap half the review asked for rather than the restructure the comment declines: the
+ * body is unchanged and unindented, and only the two registrations that are now universal move into a
+ * disposer list this wrapper drains. Draining is idempotent (`splice`), so the ordinary teardown may
+ * still run them at its own point in the sequence and this is purely the backstop.
+ */
+/**
+ * WS-23: how many times one turn's Stop/SubagentStop hooks may send the model back to work before
+ * the turn ends regardless. Winter's own number (claude has an equivalent cap); the `stop_hook_active`
+ * input flag is the first guard, this is the backstop for a hook that ignores it.
+ */
+export declare const STOP_HOOK_BLOCK_CAP = 8;
+export declare function runEngine(opts: EngineOptions): Promise<number>;