@theoremjs/agents 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,599 @@
+import { z } from 'zod';
+import { type ErrorCopies, type GuardrailEvent } from '../guardrails/event-schemas.js';
+import type { ErrorKind } from '../guardrails/theorem-error.js';
+import { AWAITING_USER_INPUT_STATUS, type CompactionMeter, type CompactionOutcome, type MediaInputKind, type Provider, type StageApplyWarningCode, type ToolAuthType, type ToolPermission, type TurnStage, type TurnStopKind } from './schema.js';
+export type { ErrorCopies, ErrorKind, GuardrailEvent };
+export interface InteractionTextPart {
+    type: 'text';
+    text: string;
+}
+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;
+}
+export type InteractionPart = InteractionTextPart | InteractionMediaPart | InteractionMediaRefPart;
+export interface TurnHistoryMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string;
+    parts?: InteractionPart[];
+    tool_calls?: {
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+        /** The call's `ToolCallRequest.thoughtSignature`, replayed with it. */
+        thoughtSignature?: string;
+    }[];
+    tool_call_id?: string;
+    name?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare const turnHistoryMessageSchema: z.ZodType<TurnHistoryMessage>;
+/** Why a turn or live utterance ended. */
+export interface TurnStop {
+    kind: TurnStopKind;
+    native?: string;
+}
+declare const TURN_TOKEN_SIDES: readonly ["input", "output"];
+export type TurnTokenSide = (typeof TURN_TOKEN_SIDES)[number];
+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];
+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 {
+    provider: Provider;
+    /** 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;
+}
+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 (Gemini `goAway`). */
+    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';
+};
+export type SessionEventKind = SessionEvent['kind'];
+export type SessionEventOf<K extends SessionEventKind> = Extract<SessionEvent, {
+    kind: K;
+}>;
+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` and `summary` are trimmed and never blank. */
+export interface ToolGateBase {
+    tool: string;
+    permission?: ToolPermission;
+    summary?: string;
+}
+/**
+ * Confirm-to-run / permission / sign-in gate: the tool's body did not run.
+ * A sign-in gate (`auth`) carries the challenge that says where.
+ */
+export type ToolGate = (ToolGateBase & {
+    kind: 'confirmation' | 'permission';
+}) | (ToolGateBase & {
+    kind: 'auth';
+    authChallenge: ToolAuthChallenge;
+});
+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[];
+});
+export declare const awaitingUserInputSchema: z.ZodType<AwaitingUserInput>;
+export interface WireFunctionTool {
+    type: 'function';
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+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[];
+}
+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;
+}
+/**
+ * The model's call, as the provider emitted it (no phase). It is the first
+ * event of every call and the one owner of its arguments; phase events join
+ * it by `callId`.
+ */
+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>;
+    /**
+     * Google's opaque signature for the thought that led to this call, when the
+     * provider sent one. Only the first call of a step carries it: the model
+     * thinks once before all of that step's calls. Replaying a call without it
+     * fails on Google (probe 25/09/2026).
+     */
+    thoughtSignature?: string;
+    /**
+     * 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;
+}
+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.
+ * - `complete` — `output`; `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.
+ * - `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.
+ * - `cancel` — cancelled in flight (e.g. live barge-in).
+ */
+export type ToolPhaseEvent = ToolPhaseBase & ({
+    phase: 'running';
+    edited?: ToolCallEdit;
+    activity?: string;
+} | {
+    phase: 'progress';
+    data: unknown;
+} | {
+    phase: 'trace';
+    step: ToolTraceStep;
+} | {
+    phase: 'artifact';
+    artifact: unknown;
+} | {
+    phase: 'warning';
+    warning: ToolWarning;
+} | {
+    phase: 'complete';
+    output: unknown;
+    awaiting?: boolean;
+    readBack?: string;
+    parts?: InteractionPart[];
+    activityPast?: string;
+} | {
+    phase: 'gate';
+    gate: ToolGate;
+    readBack?: string;
+} | {
+    phase: 'error';
+    failure: ToolFailure;
+    readBack?: string;
+} | {
+    phase: 'cancel';
+});
+export type ToolCallPhase = ToolPhaseEvent['phase'];
+export type ToolCallEvent = ToolCallRequest | ToolPhaseEvent;
+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 {
+    /** 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. */
+export type TurnEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thought';
+    text: string;
+}
+/** The profile's structured-output schema validates `structured`. */
+ | {
+    type: 'structured';
+    structured: unknown;
+} | {
+    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;
+    }[];
+} | {
+    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 lexicon 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;
+};
+export type TurnEventType = TurnEvent['type'];
+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 {
+    stop: TurnStop;
+    interactionId?: string;
+    /** A user utterance interrupted the live response (barge-in). */
+    interrupted?: boolean;
+}
+/**
+ * What a provider yields: the host events, its call's `done`, and the
+ * response's identity (`response`, recorded on the call's trace), which hosts
+ * never receive.
+ */
+export type ProviderEvent = Exclude<TurnEvent, {
+    type: 'done';
+}> | ({
+    type: 'done';
+} & CallDone) | {
+    type: 'response';
+    response: TurnResponse;
+};
+/** 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'>;
+export declare function turnDoneOf(done: DoneFields): TurnEventOf<'done'> | undefined;
+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>>;
+};