@theoremjs/agents 0.0.0-stage → 0.3.1

package/esm/src/kernel/turn-events.d.ts

@@ -0,0 +1,776 @@
+import { type ProviderCheckpoint, type ProviderWarning } from './checkpoint.js';
+import { z } from 'zod';
+import { type ErrorCopies, type GuardrailEvent } from '../guardrails/event-schemas.js';
+import type { ErrorKind } from '../guardrails/theorem-error.js';
+import { type JsonObject, type JsonValue } from './json.js';
+import { AWAITING_USER_INPUT_STATUS, type CompactionMeter, type CompactionOutcome, type MediaInputKind, type StageApplyWarningCode, type ToolAccess, type ToolAuthType, type ToolPermission, type TurnStage, type TurnStopKind } from './schema.js';
+export type { ErrorCopies, ErrorKind, GuardrailEvent };
+/** A text part of a history message. */
+export interface InteractionTextPart {
+    type: 'text';
+    text: string;
+}
+/** A media part of a history message, carried inline as base64. */
+export interface InteractionMediaPart {
+    type: MediaInputKind;
+    mimeType: string;
+    data: string;
+}
+/** The host owns the upload and cleanup; THEOREM only carries the reference. */
+export interface InteractionMediaRefPart {
+    type: MediaInputKind;
+    mimeType: string;
+    uri: string;
+}
+/** A part of a history message: text or media. */
+export type InteractionPart = InteractionTextPart | InteractionMediaPart | InteractionMediaRefPart;
+export declare const interactionPartSchema: z.ZodType<InteractionPart>;
+/** One message of a conversation history the host replays into a turn. */
+/** Where a piece of signed reasoning came from. `protocol` decides where it may go back to. */
+export interface ReasoningOrigin {
+    protocol: string;
+    provider?: string;
+    apiId?: string;
+}
+/**
+ * Signed reasoning a model wrote, kept word for word: Gemini's thought signatures, OpenRouter's
+ * `reasoning_details`. It goes back only to the protocol that wrote it, or one extended from it;
+ * `data` is that protocol's own shape, checked against its `reasoning` schema.
+ */
+export interface ReasoningPart {
+    text?: string;
+    data: JsonValue;
+    origin: ReasoningOrigin;
+}
+export declare const reasoningPartSchema: z.ZodObject<{
+    text: z.ZodOptional<z.ZodString>;
+    data: z.ZodType<JsonValue>;
+    origin: z.ZodType<ReasoningOrigin>;
+}>;
+export interface TurnHistoryMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string;
+    parts?: InteractionPart[];
+    tool_calls?: {
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+    /** On an assistant message: the signed reasoning written with it, to go back with it. */
+    reasoning?: ReasoningPart[];
+    tool_call_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The schema a history message parses against. */
+export declare const turnHistoryMessageSchema: z.ZodType<TurnHistoryMessage>;
+/** Why a turn or live utterance ended. */
+export interface TurnStop {
+    kind: TurnStopKind;
+    native?: string;
+}
+export declare const turnStopSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        length: "length";
+        tool: "tool";
+        cancelled: "cancelled";
+        interrupted: "interrupted";
+        stream_incomplete: "stream_incomplete";
+        provider_error: "provider_error";
+        completed: "completed";
+        gate: "gate";
+        filtered: "filtered";
+        step_limit: "step_limit";
+        generation_complete: "generation_complete";
+    }>;
+    native: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const TURN_TOKEN_SIDES: readonly ["input", "output"];
+/** Which side of a call's tokens, input or output, was estimated rather than reported. */
+export type TurnTokenSide = (typeof TURN_TOKEN_SIDES)[number];
+/** What a turn cost, as the provider reports it. */
+export interface TurnCost {
+    /** What the provider charged, in US dollars. */
+    usd: number;
+    /** What the upstream model vendor charged the provider, when reported (OpenRouter). */
+    upstreamUsd?: number;
+    /**
+     * Set on a sum (`sumTokens`) when some summed calls reported a cost and
+     * others did not: `usd` covers only the calls that did.
+     */
+    partial?: true;
+}
+/** One grounding tool's use in a call (Interactions `grounding_tool_count`). */
+export interface TurnGroundingCount {
+    type: string;
+    count: number;
+    /** Search queries the tool ran. Absent = not reported. */
+    searchQueryCount?: number;
+}
+/**
+ * Token accounting for one model call, one `tokens` event per call; on `done`,
+ * the turn's sum (`sumTokens`).
+ *
+ * Meanings follow the OpenTelemetry GenAI conventions on every provider:
+ * `input` counts everything the model read (cached prompt and provider
+ * tool-use tokens included), `output` everything it wrote (reasoning
+ * included), and `total` is `input + output`.
+ */
+export interface TurnTokens {
+    input: number;
+    output: number;
+    /** Reasoning share of `output`. */
+    thinking?: number;
+    /** Provider tool-use share of `input` (Google code execution / URL context results). */
+    toolUse?: number;
+    /** Share of `input` read from provider cache (cache hit). */
+    cached?: number;
+    /** Share of `input` written into provider cache. */
+    cacheWrite?: number;
+    total: number;
+    cost?: TurnCost;
+    /**
+     * Sides the provider did not report. The runner replaces each with the one
+     * token estimator's count before the event reaches the host. Absent = both
+     * sides provider-reported.
+     */
+    estimated?: TurnTokenSide[];
+    /**
+     * Media parts left out of an estimated side because no verified rule counts
+     * them, per side. Absent when every part was counted.
+     */
+    unknownMedia?: {
+        input?: number;
+        output?: number;
+    };
+    /**
+     * Provider-reported shares of each side by modality (`text`, `image`,
+     * `audio`, …, lower-case). Providers list only some modalities, so the
+     * shares need not add up to the side. Absent = not reported.
+     */
+    byModality?: {
+        input?: Record<string, number>;
+        output?: Record<string, number>;
+    };
+    grounding?: TurnGroundingCount[];
+}
+/** A provider response's identity, as the wire sent it. Live sends neither field. */
+export interface TurnResponse {
+    /** Provider response id (OpenAI-compatible `id`, Interactions `id`). */
+    id?: string;
+    model?: string;
+}
+declare const SOURCE_TYPES: readonly ["web", "maps"];
+export type SourceType = (typeof SOURCE_TYPES)[number];
+/** A source a grounded answer cites. */
+export interface Source {
+    title: string;
+    uri: string;
+    type: SourceType;
+    /** Google Place id when the source is a Maps place / place_citation. */
+    placeId?: string;
+}
+export declare const sourceSchema: z.ZodType<Source>;
+/** Google grounding search metadata. Sources travel as `citation` events. */
+export interface GroundingEvent {
+    metadata?: Record<string, unknown>;
+    chunks?: unknown[];
+    searchHtml?: string;
+}
+export interface EvidenceBase {
+    /** The registered provider's id. */
+    provider: string;
+    /** The provider's own payload, for the builder: `forClient` strips it unless `includeEvidenceRaw`. */
+    raw?: Record<string, unknown>;
+    /**
+     * The provider started this step and never finished it (the stream ended
+     * first). `raw` holds what arrived. A partial tool call is evidence only and
+     * never runs.
+     */
+    partial?: boolean;
+}
+/** What a provider returned beside the answer, such as code it ran or search results it used. */
+export type ProviderEvidence = (EvidenceBase & {
+    kind: 'code_execution_call';
+    /** Generated source from `code_execution_call.arguments.code`. */
+    code: string;
+    /** Language of `code` when the API supplies it (typically `python`). */
+    language?: string;
+    id: string;
+}) | (EvidenceBase & {
+    kind: 'code_execution_result';
+    result?: string;
+    isError?: boolean;
+    /** Links a result to its call (`code_execution_result.call_id`). */
+    callId?: string;
+}) | (EvidenceBase & {
+    kind: 'input_transcription' | 'output_transcription';
+    /** Partial/interim chunk (vs final transcription delta). Text rides on the event. */
+    interim?: boolean;
+}) | (EvidenceBase & {
+    kind: 'voice_activity' | 'url_context';
+}) | (EvidenceBase & {
+    kind: 'session_resumption';
+    /** Whether the handle (on the event) may be used to resume. */
+    resumable: boolean;
+}) | (EvidenceBase & {
+    kind: 'provider_step';
+    /** The provider's own step type, e.g. `google_search_call`. */
+    step: string;
+});
+/** A session the provider ended after warning it would. */
+export interface SessionEnded {
+    /** The provider warned first. */
+    cause: 'go_away';
+    code: number;
+    /** Milliseconds from the last warning to the close; compare with `timeLeftMs`. */
+    closedAfterMs: number;
+    /** What the close code means as a failure, when it is not a normal close (1000). */
+    errorKind?: ErrorKind;
+}
+/**
+ * Live session control signal.
+ *
+ * - `closing_soon` — the provider will end the session; `timeLeftMs` is the
+ *   drain window when it gave one.
+ * - `ended` — the provider ended the session after warning it would; the last
+ *   event of the session, not a failure. `message` is what the user reads
+ *   (the profile's `live.session_ended` wording).
+ * - `turn_complete` — one spoken response ended; the server may still be working.
+ * - `working` — server is reasoning or awaiting async tool results.
+ * - `idle` — server finished all processing; conversational cycle boundary.
+ */
+export type SessionEvent = {
+    kind: 'closing_soon';
+    timeLeftMs?: number;
+} | {
+    kind: 'ended';
+    timeLeftMs?: number;
+    ended: SessionEnded;
+    message: string;
+} | {
+    kind: 'waiting_for_input' | 'turn_complete' | 'working' | 'idle';
+};
+/** The kind of a live session event. */
+export type SessionEventKind = SessionEvent['kind'];
+/** The live session event of kind `K`. */
+export type SessionEventOf<K extends SessionEventKind> = Extract<SessionEvent, {
+    kind: K;
+}>;
+/** Why a tool call failed, for the builder and for the user. */
+export interface ToolFailure {
+    /** What went wrong, for the builder. Stable per failure site. */
+    code: string;
+    /** What kind of failure it is; the user's wording (`error.<kind>`) follows from it. */
+    kind: ErrorKind;
+    /** What the model reads in the tool result. */
+    message: string;
+    /** User-safe wording, added where the event reaches the host. Never sent to the model. */
+    error?: string;
+    details?: unknown;
+}
+export interface ToolAuthChallenge {
+    slot: string;
+    authType: ToolAuthType;
+    /** The service the person signs in to, from the tool's auth config. */
+    service: string;
+    /** Why the tool needs it; never blank. */
+    message: string;
+    authorizationUrl?: string;
+    state?: string;
+    issuer?: string;
+    resource?: string;
+    requiredScopes?: string[];
+}
+/**
+ * Fields every gate carries. `tool`, `summary`, and `request` are trimmed and never blank.
+ * `request` is the tool's `labels.request` filled from the call's input; `access` is the tool's.
+ */
+export interface ToolGateBase {
+    tool: string;
+    permission?: ToolPermission;
+    summary?: string;
+    request?: string;
+    access?: ToolAccess;
+    preparedArguments?: Record<string, unknown>;
+}
+/**
+ * Confirm-to-run / permission / sign-in / page gate: the tool's body did not run.
+ * A sign-in gate (`auth`) carries the challenge that says where. A `page` gate waits for the
+ * page's answer to a tool with `answeredBy: 'page'`; no person decides it.
+ */
+export type ToolGate = (ToolGateBase & {
+    kind: 'confirmation' | 'permission' | 'page';
+}) | (ToolGateBase & {
+    kind: 'auth';
+    authChallenge: ToolAuthChallenge;
+});
+/** The schema a tool gate parses against. */
+export declare const toolGateSchema: z.ZodType<ToolGate>;
+export interface ToolWarning {
+    code: string;
+    message: string;
+    severity?: 'info' | 'warning' | 'error';
+}
+export interface ToolTraceStep {
+    name: string;
+    kind: string;
+    status: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+}
+/**
+ * A tool completed by asking the user something (`docs/contracts/stages.md`).
+ * `prompt` and every option are trimmed and never blank; a `choice` offers at
+ * least one option.
+ */
+export type AwaitingUserInput = {
+    status: typeof AWAITING_USER_INPUT_STATUS;
+    prompt: string;
+} & ({
+    kind: 'confirm' | 'text';
+    options?: string[];
+} | {
+    kind: 'choice';
+    options: string[];
+});
+/** The schema a pause for user input parses against. */
+export declare const awaitingUserInputSchema: z.ZodType<AwaitingUserInput>;
+/** True when a tool output asks the turn to pause for the user. */
+export declare function isAwaitingUserInput(output: unknown): output is AwaitingUserInput;
+/** A function tool as it is sent to the model. */
+export interface WireFunctionTool {
+    type: 'function';
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** The tools a turn was offered: provider builtins, gated ids, and the wire definitions. */
+export interface TurnToolSnapshot {
+    builtins: string[];
+    /** Tool ids eligible this turn (custom: allow + path; builtin: model builtInTools + path). */
+    gated: string[];
+    /** Schemas sent to the provider (respects loadTier + t2Loader promotion). */
+    visible: string[];
+    /** Kernel-executable tools: eligible, visible, and loaded (excludes builtins). */
+    executable: string[];
+    path?: string;
+    sessionPermissions?: string[];
+    wire: WireFunctionTool[];
+}
+/** The schema a tool snapshot parses against. */
+export declare const turnToolSnapshotSchema: z.ZodType<TurnToolSnapshot>;
+export interface ToolEventBase {
+    name: string;
+    /** Call id: the provider's own id when it sent one, else kernel-assigned. */
+    callId: string;
+}
+export interface GateReference {
+    callId: string;
+    operationId: string;
+}
+export declare const gateReferenceSchema: z.ZodType<GateReference>;
+/**
+ * invariant: The provider request owns the arguments. Kernel events add an operation ID.
+ * Interface folds join phases by that ID, or by callId for historical events.
+ */
+export interface ToolCallRequest extends ToolEventBase {
+    phase?: undefined;
+    /**
+     * The arguments the model sent, parsed. `{}` when they did not parse: the
+     * `error` that follows (`malformed_arguments`) carries the raw text.
+     */
+    arguments: Record<string, unknown>;
+    /**
+     * On a step's first call: the signed reasoning the model wrote before the step's calls (a Gemini
+     * thought signature, OpenRouter's `reasoning_details`). It goes back on the assistant message
+     * holding the step's calls, word for word; a host keeping its own history keeps it there.
+     */
+    reasoning?: ReasoningPart[];
+    /**
+     * The model step that made this call: calls sharing it were made together,
+     * in one model response, and replay as one assistant message. Unique within
+     * the turn. Absent on a host's own call (`invokeTool` without a `callId`).
+     */
+    stepId?: string;
+    /**
+     * How many calls the step has, on every call of it: a host that runs a step's
+     * calls as one knows the step is complete once it has seen this many. Set
+     * wherever `stepId` is; absent with it.
+     */
+    stepCallCount?: number;
+}
+export interface ToolPhaseBase extends ToolEventBase {
+    /** When the kernel emitted this phase (epoch ms). */
+    at: number;
+}
+/** The user edited the arguments before approving. */
+export interface ToolCallEdit {
+    from: Record<string, unknown>;
+    to: Record<string, unknown>;
+}
+/**
+ * One phase of the kernel's execution of a call:
+ *
+ * - `running` — the body started; `edited` when the user changed the arguments;
+ *   `activity` is the tool's activity label filled from the call's input.
+ * - `progress` / `trace` / `artifact` / `warning` — streamed while it ran. A `progress` its
+ *   output's check stops is not sent.
+ * - `draft` — the next piece of what the tool is writing, for a preview, each piece read at
+ *   `tool_output_<kind>` first (an agent tool's: its agent's reply). Sent only under
+ *   `outputs.streaming.mode` `sse`. The model never reads it: it reads `complete`'s output.
+ * - `complete` — `output`, as the person is shown it (read at `tool_shown_<kind>`); `awaiting`
+ *   when it asked the user something; `parts` for the media it returned beside its output
+ *   (images, audio);
+ *   `readBack` is the text the model reads back, after guardrails;
+ *   `activityPast` is the tool's past activity label filled from its input and output, or its
+ *   failed label when a `post_tool` handler asked for it (`labelFailed`).
+ * - `gate` — confirmation, permission, or sign-in held the call; the body did not run.
+ *   A sign-in gate's `readBack` is what the model reads while the person signs in.
+ * - `error` — the call failed or was refused (`failure.kind` `declined` · `blocked` · `cancelled` · …);
+ *   `readBack` is the text the model reads back for it, after guardrails;
+ *   `activityPast` is the tool's failed label.
+ * - `cancel` — cancelled in flight (e.g. live barge-in).
+ */
+export type ToolPhaseEvent = ToolPhaseBase & ({
+    phase: 'running';
+    edited?: ToolCallEdit;
+    activity?: string;
+} | {
+    phase: 'dispatch';
+    grantId: string;
+    arguments: Record<string, unknown>;
+} | {
+    phase: 'progress';
+    data: unknown;
+} | {
+    phase: 'draft';
+    text: string;
+} | {
+    phase: 'trace';
+    step: ToolTraceStep;
+} | {
+    phase: 'artifact';
+    artifact: unknown;
+} | {
+    phase: 'warning';
+    warning: ToolWarning;
+} | {
+    phase: 'complete';
+    output: unknown;
+    awaiting?: boolean;
+    readBack?: string;
+    parts?: InteractionPart[];
+    activityPast?: string;
+    /** An agent tool's call: the called agent's own usage, which the caller's `done.tokens` includes. */
+    tokens?: TurnTokens;
+} | {
+    phase: 'gate';
+    gate: ToolGate;
+    readBack?: string;
+} | {
+    phase: 'error';
+    failure: ToolFailure;
+    readBack?: string;
+    activityPast?: string;
+    /** An agent tool's call: the called agent's own usage, as on `complete`. */
+    tokens?: TurnTokens;
+} | {
+    phase: 'cancel';
+});
+export type ToolCallPhase = ToolPhaseEvent['phase'];
+/** A tool call event: the model's request or a phase of running it. */
+export type ToolCallEvent = (ToolCallRequest | ToolPhaseEvent) & {
+    /** Kernel-issued identity. Historical events can predate this field. */
+    operationId?: string;
+};
+/** A note that a stage handler's result was partly or wholly ignored, and why. */
+export interface StageApplyWarning {
+    code: StageApplyWarningCode;
+    message: string;
+    field: string;
+}
+/** Compaction signal on `done` for `timing: 'after'` profiles. */
+export interface CompactionSignal {
+    needed: boolean;
+    meter: CompactionMeter;
+    tokens: number;
+    /** Media parts not counted in `tokens` — no verified rule for this model. */
+    unknownMedia: number;
+    /** Full-prompt input tokens of this turn's last model call, when one completed. */
+    promptTokens?: number;
+    /** True when `promptTokens` is the token estimator's count — the provider reported none. */
+    promptTokensEstimated?: boolean;
+    history: TurnHistoryMessage[];
+}
+/** Why the compactor produced no summary. */
+export interface CompactionFailure {
+    /** How the compactor's turn ended; absent when it threw before it could end. */
+    stop?: TurnStopKind;
+    /** The error it reported, when it reported one. */
+    error?: ErrorKind;
+    /** It completed without a summary. */
+    empty?: true;
+    /** Nothing in `toCompact` was left for it to read, so it did not run. */
+    unreadable?: true;
+}
+/** What one compaction did. The host keeps `history` from now on, whatever the outcome. */
+export interface CompactionResult {
+    outcome: CompactionOutcome;
+    /** The messages the split handed to the compactor. */
+    toCompact: TurnHistoryMessage[];
+    history: TurnHistoryMessage[];
+    /** On `compacted`: the summary that replaced `toCompact`. */
+    summary?: string;
+    /** On `deferred` and `dropped`. */
+    failure?: CompactionFailure;
+    /** Media parts in `toCompact` the compactor's profile does not accept, left out of what it read. */
+    droppedMedia: number;
+    /** The compaction call's own usage. */
+    tokens?: TurnTokens;
+}
+/**
+ * Theorem ran the compactor before the turn. `after` is the host's to run with
+ * `compactHistory`, signalled on `done.compaction`.
+ */
+export interface CompactionEvent extends Omit<CompactionResult, 'toCompact'> {
+    timing: 'before';
+    meter: CompactionMeter;
+    tokensBefore: number;
+    unknownMedia: number;
+    messagesBefore: number;
+    messagesAfter: number;
+}
+/** Stops that end a turn with tools pending; `done.tools` is present exactly on them. */
+export type ToolSnapshotStopKind = Extract<TurnStopKind, 'tool' | 'gate'>;
+export interface DoneBase {
+    providerState?: ProviderCheckpoint;
+    /** The turn's summed usage (`sumTokens` over its `tokens` events). */
+    tokens?: TurnTokens;
+    /** The turn's root span as a W3C `traceparent`, for a later request's `links`. */
+    traceparent?: string;
+    compaction?: CompactionSignal;
+    /** A user utterance interrupted an in-flight live response (barge-in). */
+    interrupted?: boolean;
+    interactionId?: string;
+}
+/**
+ * The turn ended. On stop `tool` or `gate` it carries the turn's tool snapshot
+ * for `invokeTool({ snapshot })`; on every other stop it carries none.
+ */
+export type DoneEvent = DoneBase & ({
+    stop: TurnStop & {
+        kind: ToolSnapshotStopKind;
+    };
+    tools: TurnToolSnapshot;
+} | {
+    stop: TurnStop & {
+        kind: Exclude<TurnStopKind, ToolSnapshotStopKind>;
+    };
+    tools?: undefined;
+});
+/** Every event a host receives from `runTurn`, `invokeTool`, or a live session. */
+/** One item an item rule removed from a structured reply, and why. */
+export interface RemovedItem {
+    /** The dotted path of the list it sat in. */
+    path: string;
+    reason: string;
+    item: unknown;
+}
+/** A field of a structured reply that still failed its checks when the turn ran out of retries. */
+export interface InvalidField {
+    /** The dotted path of the field. */
+    path: string;
+    error: string;
+}
+/** Why a turn threw an attempt's reply away and asked again. */
+export type AttemptReason = 'validation' | 'egress';
+export type TurnEvent = {
+    type: 'provider_warning';
+    warning: ProviderWarning;
+} | {
+    type: 'provider_checkpoint';
+    providerState: ProviderCheckpoint;
+    history?: TurnHistoryMessage[];
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thought';
+    text: string;
+}
+/** Content a protocol emits with no common shape; `kind` is `<protocol>.<kind>`. */
+ | {
+    type: 'custom';
+    kind: string;
+    data: JsonObject;
+}
+/** The profile's structured-output schema validates `structured`. */
+ | {
+    type: 'structured';
+    structured: unknown;
+    /** Items the profile's item rules removed from `structured`, each with why. */
+    removed?: RemovedItem[];
+    /** The fields still invalid when `outputs.validation` ran out of retries; the reply goes out as it is. */
+    failed?: InvalidField[];
+}
+/**
+ * The next piece of a structured reply's JSON as the model writes it, for a preview: read at
+ * `reply` as the reply's text, before the `structured` event that follows is read whole at
+ * `reply_structured`. That event is the reply. Sent only under `outputs.streaming.mode` `sse`; an
+ * `attempt` throws it away with the rest of the reply.
+ */
+ | {
+    type: 'structured_draft';
+    text: string;
+}
+/**
+ * The turn threw the reply so far away and asks again. Text, media, and structured output since
+ * the turn began, or since the last `attempt`, are not the reply; {@linkcode keptReply} drops them.
+ * `attempt` counts the retries: 1 for the first, as the trace's `theorem.attempt.retry` does.
+ */
+ | {
+    type: 'attempt';
+    attempt: number;
+    reason: AttemptReason;
+} | {
+    type: 'media';
+    media: {
+        mimeType: string;
+        data: string;
+    };
+} | {
+    type: 'grounding';
+    grounding: GroundingEvent;
+}
+/** Sources a provider or a tool cited; `callId` names the tool call when a tool did. */
+ | {
+    type: 'citation';
+    sources: Source[];
+    callId?: string;
+} | ({
+    type: 'compaction';
+} & CompactionEvent) | {
+    type: 'evidence';
+    evidence: ProviderEvidence;
+    /** Transcription text. */
+    text?: string;
+    sessionResumptionHandle?: string;
+} | {
+    type: 'tokens';
+    tokens: TurnTokens;
+    interactionId?: string;
+} | {
+    type: 'session';
+    session: SessionEvent;
+    /** Raw close reason of an ended session, for the builder only. */
+    errorInternal?: string;
+}
+/** A guardrail decision — rule identity and offsets, never content. */
+ | {
+    type: 'guardrail';
+    guardrail: GuardrailEvent;
+} | {
+    type: 'stage';
+    stage: TurnStage;
+    callId?: string;
+    toolName?: string;
+    /** `pre_tool` settled without running the body. */
+    callNotStarted?: boolean;
+    /** The tool completed with `awaiting_user_input`. */
+    awaiting?: boolean;
+    gate?: ToolGate;
+    stop?: TurnStop;
+    /** Stage result fields the kernel dropped. */
+    stageWarnings?: StageApplyWarning[];
+    /** The named injects (`StageResult.injectId`) that landed in the conversation at this stage. */
+    injected?: {
+        id: string;
+    }[];
+}
+/**
+ * A tool call the model is still writing: the next piece of its arguments' JSON text, in order,
+ * for a preview. The `tool` call that follows owns the arguments; a draft cut off before it never
+ * runs. Sent only under `outputs.streaming.mode` `sse`.
+ */
+ | {
+    type: 'tool_draft';
+    callId: string;
+    name: string;
+    text: string;
+} | {
+    type: 'tool';
+    tool: ToolCallEvent;
+    /** An untrusted server's own words about this call (a refused token refresh), for the builder only. */
+    errorInternal?: string;
+} | ({
+    type: 'done';
+} & DoneEvent) | {
+    type: 'error';
+    errorKind: ErrorKind;
+    /** Public-safe failure text for hosts to show users: the wording for `errorKind`. */
+    error?: string;
+    /** The labels key and parameters behind `error` when more specific than the kind's. */
+    errorCopy?: ErrorCopies;
+    /** Raw diagnostic detail for traces/logs; never surface to end users (`forClient` strips it). */
+    errorInternal?: string;
+};
+/** The `type` of a turn event. */
+export type TurnEventType = TurnEvent['type'];
+/** The turn event whose `type` is `K`. */
+export type TurnEventOf<K extends TurnEventType> = Extract<TurnEvent, {
+    type: K;
+}>;
+/**
+ * How one model call ended, as a provider reports it. The runner reads it and
+ * reports the turn's own `done`; a live session forwards it (`turnDoneOf`).
+ */
+export interface CallDone {
+    providerState?: ProviderCheckpoint;
+    stop: TurnStop;
+    interactionId?: string;
+    /** A user utterance interrupted the live response (barge-in). */
+    interrupted?: boolean;
+}
+/**
+ * What a model call yields to the engine: the host events, its call's `done`, the response's
+ * identity (`response`, recorded on the call's trace) and the signed reasoning it wrote, which the
+ * engine puts on the step's first call. Hosts never receive the last three as they are.
+ */
+export type ModelEvent = Exclude<TurnEvent, {
+    type: 'done';
+}> | ({
+    type: 'done';
+} & CallDone) | {
+    type: 'response';
+    response: TurnResponse;
+} | ({
+    type: 'reasoning';
+} & ReasoningPart);
+/** A `done` before its stop decides whether it carries the turn's tools. */
+export type DoneFields = DoneBase & {
+    stop: TurnStop;
+};
+/**
+ * The host's `done` for a stop: the one place that decides whether it carries
+ * the turn's tool snapshot (on `tool` and `gate`). Without a snapshot to give
+ * (a live session forwarding a call's `done`), such a stop has no host `done`.
+ */
+export declare function turnDoneOf(done: DoneFields, tools: TurnToolSnapshot): TurnEventOf<'done'>;
+/** Builds the `done` event from a model call's end, with the tools the turn was offered. */
+export declare function turnDoneOf(done: DoneFields): TurnEventOf<'done'> | undefined;
+/** The schema any turn event parses against. */
+export declare const turnEventSchema: z.ZodType<TurnEvent>;
+/** Every `TurnEvent` kind and its schema: a wire parser tells a kind it doesn't know from a malformed one it does. */
+export declare const TURN_EVENT_SCHEMAS: {
+    readonly [K in TurnEventType]: z.ZodType<TurnEventOf<K>>;
+};
+/**
+ * `events` without the replies a retry threw away: each `attempt` drops the text, media and
+ * structured output before it, back to the turn's start or its last `done`. Tool calls, thoughts
+ * and everything else stay, since they happened.
+ */
+export declare function keptReply(events: readonly TurnEvent[]): TurnEvent[];