@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -1,12 +1,16 @@
+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 { 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';
+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;
@@ -18,7 +22,31 @@ export interface InteractionMediaRefPart {
     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;
@@ -30,21 +58,40 @@ export interface TurnHistoryMessage {
             name: string;
             arguments: string;
         };
-        /** The call's `ToolCallRequest.thoughtSignature`, replayed with it. */
-        thoughtSignature?: 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;
@@ -118,6 +165,7 @@ export interface TurnResponse {
 }
 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;
@@ -133,7 +181,8 @@ export interface GroundingEvent {
     searchHtml?: string;
 }
 export interface EvidenceBase {
-    provider: Provider;
+    /** The registered provider's id. */
+    provider: string;
     /** The provider's own payload, for the builder: `forClient` strips it unless `includeEvidenceRaw`. */
     raw?: Record<string, unknown>;
     /**
@@ -143,6 +192,7 @@ export interface EvidenceBase {
      */
     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`. */
@@ -173,7 +223,7 @@ export type ProviderEvidence = (EvidenceBase & {
 });
 /** A session the provider ended after warning it would. */
 export interface SessionEnded {
-    /** The provider warned first (Gemini `goAway`). */
+    /** The provider warned first. */
     cause: 'go_away';
     code: number;
     /** Milliseconds from the last warning to the close; compare with `timeLeftMs`. */
@@ -204,10 +254,13 @@ export type SessionEvent = {
 } | {
     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;
@@ -232,22 +285,30 @@ export interface ToolAuthChallenge {
     resource?: string;
     requiredScopes?: string[];
 }
-/** Fields every gate carries. `tool` and `summary` are trimmed and never blank. */
+/**
+ * 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 gate: the tool's body did not run.
- * A sign-in gate (`auth`) carries the challenge that says where.
+ * 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';
+    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;
@@ -276,13 +337,18 @@ export type AwaitingUserInput = {
     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). */
@@ -295,16 +361,21 @@ export interface TurnToolSnapshot {
     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>;
 /**
- * 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`.
+ * 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;
@@ -314,18 +385,23 @@ export interface ToolCallRequest extends ToolEventBase {
      */
     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).
+     * 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.
      */
-    thoughtSignature?: string;
+    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). */
@@ -341,24 +417,38 @@ export interface ToolCallEdit {
  *
  * - `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);
+ * - `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.
- * - `gate` — confirmation, permission or sign-in held the call; the body did not run.
+ *   `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.
+ *   `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;
@@ -375,6 +465,8 @@ export type ToolPhaseEvent = ToolPhaseBase & ({
     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;
@@ -383,11 +475,19 @@ export type ToolPhaseEvent = ToolPhaseBase & ({
     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'];
-export type ToolCallEvent = ToolCallRequest | ToolPhaseEvent;
+/** 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;
@@ -447,6 +547,7 @@ export interface CompactionEvent extends Omit<CompactionResult, 'toCompact'> {
 /** 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`. */
@@ -471,18 +572,70 @@ export type DoneEvent = DoneBase & ({
     };
     tools?: undefined;
 });
-/** Every event a host receives from `runTurn`, `invokeTool` or a live session. */
+/** 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: {
@@ -537,6 +690,17 @@ export type TurnEvent = {
     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;
@@ -549,12 +713,14 @@ export type TurnEvent = {
     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. */
+    /** 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;
 }>;
@@ -563,24 +729,27 @@ export type TurnEventOf<K extends TurnEventType> = Extract<TurnEvent, {
  * 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 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.
+ * 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 ProviderEvent = Exclude<TurnEvent, {
+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;
@@ -591,9 +760,17 @@ export type DoneFields = DoneBase & {
  * (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[];