@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/types.d.ts

@@ -1,22 +1,35 @@
-import type { CacheMode, CacheTtl, CompactionMeter, CompactionOutcome, CompactionTiming, ContinueStopKind, FieldMeta, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveStartSensitivity, MediaInputKind, ProfileType, ProfileTypeProtocol, Protocol, Provider, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolLoadTier, TurnStage, TurnStopKind } from './schema.js';
+import type { ProviderCheckpoint, ProviderContinuationPolicy } from './checkpoint.js';
+import type { JsonObject } from './json.js';
+import type { CacheMode, CacheTtl, CompactionMeter, CompactionOutcome, CompactionTiming, ContextSender, ContinueStopKind, FieldMeta, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveStartSensitivity, MediaInputKind, ProfileType, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolLoadTier, TurnStage, TurnStopKind } from './schema.js';
 import type { StageHandler } from './stages.js';
 import type { GateDecision } from './tools/gate-answer.js';
-import type { BuiltinWire, HostProfileToolsSpec, InvokeToolRequest, InvokeToolResume, LiveProfileToolsSpec, ModelToolResult, ProfileToolsSpec, RegisteredTool, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolPolicy, TurnToolSnapshot, WireFunctionTool } from './tools/types.js';
-import type { CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, ProviderEvent, ProviderEvidence, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
-export type { CacheMode, CacheTtl, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvokeToolRequest, InvokeToolResume, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ProfileToolsSpec, ProfileType, ProfileTypeProtocol, Protocol, Provider, ProviderEvent, ProviderEvidence, RegisteredTool, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
+import type { PageToolExecution, ToolExecutionCoordinator } from './tools/operation.js';
+import type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, HostProfileToolsSpec, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, LiveProfileToolsSpec, ModelToolResult, PageAnswer, ProfileToolsSpec, RegisteredTool, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolPolicy, TurnToolSnapshot, WireFunctionTool } from './tools/types.js';
+import type { AttemptReason, CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, ModelEvent, ProviderEvidence, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
+export type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, AttemptReason, CacheMode, CacheTtl, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ModelEvent, ProfileToolsSpec, ProfileType, ProviderEvidence, RegisteredTool, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
+/** A host-chosen key naming one model binding in a profile's `models`. */
 export type ModelId = string;
+/** The id of a provider-side tool such as web search. */
 export type BuiltinToolId = string;
+/** The id a profile lists in `tools.allow` and the model calls a tool by. */
 export type ToolId = string;
+/** The id of a registered structured-output schema. */
 export type StructuredSchemaId = string;
+/** A structured-output schema resolved to its JSON Schema. */
 export interface ResolvedStructured {
     id: StructuredSchemaId;
     jsonSchema: Record<string, unknown>;
 }
+/** A provider-side tool the turn uses, with the args the request addressed to it. */
 export interface ProviderBuiltin {
     id: BuiltinToolId;
-    wire: BuiltinWire;
+    args?: JsonObject;
 }
+/** Args a request hands to built-in tools, each checked by the schema its adapter declares. */
+export type BuiltInArgs = Record<BuiltinToolId, JsonObject>;
+/** The id a profile is registered and run under. */
 export type ProfileId = string;
+/** The roles a history message can carry. */
 export type ChatRole = 'system' | 'user' | 'assistant';
 /** Host strings (presets own the vocabularies); an unpinned value is the provider default. */
 export interface ProfileImageSpec {
@@ -32,52 +45,10 @@ export interface ProfileImageSpec {
     /** Also request interleaved text with the images (Google: text + image `response_format`). */
     includeText?: boolean;
 }
-export interface ModelBinding {
-    protocol: Protocol;
-    provider: Provider;
-    apiId: string;
-    /** Alias → thinking level. One entry = fixed; two+ may be selectable at turn time. */
-    efforts?: Record<string, ThinkingLevel>;
-    /** Effort alias when the turn omits `effort`. Defaults to the only key when there is one. */
-    defaultEffort?: string;
-    /** Turn may pass `{ effort: "<alias>" }`. Requires two or more `efforts` keys. */
-    allowEffortSelect?: boolean;
-    /** Emit thinking summaries on the stream. Omit → provider default. */
-    summaries?: boolean;
-    /** Cap on output tokens. Omit → provider default. */
-    maxOutputTokens?: number;
-    /** Sampling temperature. Omit → provider default. */
-    temperature?: number;
-    builtInTools?: BuiltinToolId[];
-    /** Overrides `profile.key` for this model. */
-    key?: KeySlot;
-    /** Overrides `profile.fallbackKey` for this model. */
-    fallbackKey?: KeySlot;
-    compaction?: CompactionSpec;
-    /**
-     * OpenRouter prompt-cache policy. Omit → no opt-in `cache_control`.
-     * `defineProfile` accepts only when `provider` is `openrouter` (protocol `openAi`).
-     */
-    cache?: CacheSpec;
-    /** Gemini Interactions: whether the provider stores the interaction. Omit → provider default. */
-    store?: boolean;
-    /**
-     * Gemini Interactions: `true` chains each step and turn on Google's stored
-     * interaction (`previous_interaction_id`), so Google builds the context;
-     * `false` sends the history the host passes, plus this turn's steps, on every
-     * call — across turns the host builds that history. Required on every
-     * `geminiInteractions` binding; `true` needs `store` left on.
-     */
-    persistViaInteractionId?: boolean;
-    /**
-     * Local server that hosts the model (e.g. `ollama`, `vllm`, `llama.cpp`).
-     * Traces report it as `gen_ai.provider.name`; omit → the attribute is absent.
-     * `defineProfile` accepts only when `provider` is `local`.
-     */
-    server?: string;
-}
+import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
+export type { DecisionModelBinding, ModelBinding };
 /**
- * OpenRouter prompt-cache policy (`models.*.cache`).
+ * OpenRouter prompt-cache policy (`models.*.options.cache`).
  *
  * - `automatic` — top-level `cache_control`; breakpoint advances with the conversation.
  * - `system` — explicit breakpoint on the system instruction only.
@@ -87,6 +58,7 @@ export interface CacheSpec {
     /** Ephemeral TTL. Omit → provider default (typically 5m on Anthropic). */
     ttl?: CacheTtl;
 }
+/** What a compaction trigger sees when it decides whether to compact. */
 export interface CompactionTriggerContext {
     tokens: number;
     maxTokens: number;
@@ -95,6 +67,7 @@ export interface CompactionTriggerContext {
     /** Media parts not counted in `tokens` — no verified rule for this model. */
     unknownMedia: number;
 }
+/** When history compacts and how: the meter, the token budget, and the compactor. */
 export interface CompactionSpec {
     /**
      * Token budget compared by the trigger (`compactAt * maxTokens`).
@@ -142,15 +115,18 @@ export interface CompactHistoryRequest {
     conversationId?: string;
     metadata?: Record<string, unknown>;
 }
+/** A structured-output schema given inline. */
 export interface StructuredSpec {
     jsonSchema: Record<string, unknown>;
 }
+/** Caps on the files a turn may attach. */
 export interface MediaLimits {
     maxFiles: number;
     maxBytes: number;
     maxTurnBytes: number;
     limitsByMime?: Record<string, number>;
 }
+/** The input kinds a profile accepts, with their limits. */
 export interface MimeInputs extends Partial<MediaLimits> {
     text?: boolean;
     attachments?: {
@@ -160,16 +136,19 @@ export interface MimeInputs extends Partial<MediaLimits> {
         accept: string[];
     };
 }
-export type AttachmentValidationCode = 'mime_not_allowed' | 'too_many_files' | 'file_too_large' | 'turn_too_large' | 'attachments_not_accepted' | 'voice_not_accepted' | 'limits_unconfigured';
+/** Why an attachment was refused. */
+export type AttachmentValidationCode = 'mime_not_allowed' | 'too_many_files' | 'too_many_of_kind' | 'file_too_large' | 'turn_too_large' | 'attachments_not_accepted' | 'voice_not_accepted' | 'limits_unconfigured';
 /**
  * Structured parameters for rendering one validation issue. Validation emits
- * codes + params only; the wording is the lexicon's `attachments.*` lines.
+ * codes + params only; the wording is the labels' `attachments.*` lines.
  */
 export interface AttachmentValidationParams {
     maxFiles?: number;
     maxBytes?: number;
     maxTurnBytes?: number;
     mimeType?: string;
+    /** The kind of media a count is of, such as `PDF` or `image`. */
+    kind?: string;
     channel?: 'attachment' | 'voice';
 }
 /** One reason a turn's files were refused; `fileName` names the file when the problem is one file's. */
@@ -178,18 +157,45 @@ export interface AttachmentValidationIssue {
     params?: AttachmentValidationParams;
     fileName?: string;
 }
+/** Picks the structured-output schema by the value of a turn slot, with a fallback. */
 export interface StructuredBySlot {
     by: string;
     map: Record<string, string>;
     fallback: string;
 }
+/** What a host validator returns for a candidate output. */
 export interface ValidationResult {
     isValid: boolean;
     error?: string;
     finding?: string;
     data?: Record<string, unknown>;
 }
+/** A host function that checks one structured-output field. */
 export type ProfileValidator = (candidate: unknown, slots?: Record<string, string>) => ValidationResult | Promise<ValidationResult>;
+/** A tool call the turn completed, as an item check reads it. */
+export interface TurnToolResult {
+    tool: string;
+    /** The output the call settled with, after any `post_tool` `mutate`. */
+    output: unknown;
+}
+/** What an item check reads of the turn whose reply it is checking. */
+export interface ItemCheckTurn {
+    slots?: Record<string, string>;
+    /** Every tool call the turn completed, in order, across its attempts. */
+    toolResults: readonly TurnToolResult[];
+}
+/** A host function that checks one item of a list against what the turn's tools returned. */
+export type ProfileItemCheck = (item: unknown, turn: ItemCheckTurn) => ValidationResult | Promise<ValidationResult>;
+/**
+ * A host check on each item of one list in a structured reply. A refused item
+ * never fails the reply: `drop` removes it, and `fix` first asks the model to
+ * rewrite the refused items alone, then removes any that are refused again.
+ */
+export interface ProfileItemRule {
+    check: ProfileItemCheck;
+    onFail: 'drop' | 'fix';
+}
+/** Host validators a profile runs on its structured output. */
 export interface ProfileValidationSpec {
     /**
      * Host domain validators keyed by dotted paths into structured output
@@ -197,14 +203,23 @@ export interface ProfileValidationSpec {
      * these run only for required paths and for optional paths that are present.
      */
     fields?: Record<string, ProfileValidator>;
+    /** Host checks on list items, keyed by the dotted path of a list in the structured output. */
+    items?: Record<string, ProfileItemRule>;
     maxRetries?: number;
 }
 /** `voice` is the TTS voice id, not ingress audio (`inputs.voice`). */
 export interface ProfileSpeechSpec {
     voice?: string;
-    /** `mp3` requires `protocol: 'openAi'` speech; rejected on Interactions. */
+    /** How the script is delivered, in plain words: pace, mood, accent. Never read aloud. */
+    style?: string;
+    /** The speaking rate; 1 is the voice's own pace. */
+    speed?: number;
+    /** A provider that cannot make the format refuses the turn. */
     format?: SpeechAudioFormat;
 }
+/** What one speech turn sets for itself; each field given replaces the profile's `speech` field of that name. */
+export type TurnSpeech = Pick<ProfileSpeechSpec, 'voice' | 'style' | 'speed'>;
+/** Voice activity detection settings for a live session. */
 export interface LiveVadSpec {
     activityHandling?: LiveActivityHandling;
     startSensitivity?: LiveStartSensitivity;
@@ -227,6 +242,7 @@ export interface LiveContextCompressionSpec {
     /** Drops the oldest turns; the system instruction stays. Gemini's only mechanism. */
     slidingWindow: LiveSlidingWindowSpec;
 }
+/** Sliding-window context compression for a live session. */
 export interface LiveSlidingWindowSpec {
     /**
      * Tokens to keep after compressing. A whole number above 0, below
@@ -234,6 +250,7 @@ export interface LiveSlidingWindowSpec {
      */
     targetTokens?: number;
 }
+/** Which sides of a live session are transcribed. */
 export interface LiveTranscriptionSpec {
     input?: boolean;
     output?: boolean;
@@ -251,40 +268,52 @@ export interface LiveIngressSpec {
     /** Typed text via `sendText`. Omit → disabled (opt-in). */
     text?: boolean;
 }
+/** The prompt a resumed call opens with, and how long away earns it. */
+export interface LiveResumedSpec {
+    prompt: string;
+    /** The shortest time away, in milliseconds, the agent remarks on. Omit → `DEFAULT_RESUMED_AFTER_MS`. */
+    afterMs?: number;
+}
+/** The settings only a live profile has: ingress, voice, detection, windowing, transcription, and resumption. */
 export interface ProfileLiveSpec {
     ingress?: LiveIngressSpec;
     voice?: string;
     vad?: LiveVadSpec;
     sessionResumption?: boolean;
+    /** A prompt the session sends itself when a call opens new, so the agent speaks first. Omit → the agent waits. */
+    greeting?: string;
+    /** What the agent is prompted with when a call resumes after the caller was away. Omit → a resumed call is silent. */
+    resumed?: LiveResumedSpec;
     /** Context window compression. Omit → none: the provider ends the session at its limit. */
     contextCompression?: LiveContextCompressionSpec;
     transcription?: LiveTranscriptionSpec;
 }
+/** How a profile's reply streams. */
 export interface ProfileStreamingSpec {
     mode?: StreamMode;
     /** When false, filter `thought` events from the turn stream. */
     streamThoughts?: boolean;
 }
 export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
-import type { LexiconOverrides } from '../guardrails/lexicon.js';
+import type { LabelOverrides } from '../guardrails/labels.js';
 import type { ResolveHost } from '../guardrails/network.js';
 import type { DecisionGuardrailsSpec, HostGuardrailsSpec, ProfileGuardrailsSpec } from '../guardrails/types.js';
 import type { ProfileObservabilitySpec } from '../observability/types.js';
 import type { ToolCredentialSource } from './auth/credential-source.js';
 import type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, TurnContinueFrom } from './stop.js';
+/** The model fields every model-running profile shares. */
 export interface ProfileModelFields {
+    providerContinuation?: ProviderContinuationPolicy;
     /** Host-named models. Each key is a selectable model id when `allowModelSelect` is set. */
     models: Record<ModelId, ModelBinding>;
     /** The model a turn runs when it names none; registration fills it with the only key when there is one. */
     defaultModel: ModelId;
-    /** Turn may pass `{ model: "<id>" }`. Requires two or more `models` keys. */
+    /** Turn may pass `{ model: "<id>" }`; a name that is not a key of `models` is refused. */
     allowModelSelect?: boolean;
-    /** Tool-loop ceiling. Omit or `<= 0` = unbounded; `1` = one-shot; `> 1` = hard cap. */
+    /** Tool-loop ceiling. Omit = `DEFAULT_MAX_STEPS`; `1` = one-shot; `> 1` = hard cap. */
     maxSteps?: number;
-    key?: KeySlot;
-    /** Retried once when `key` is refused for quota. Off unless set. */
-    fallbackKey?: KeySlot;
 }
+/** What a profile accepts as input. */
 export interface ProfileInputsSpec {
     text?: boolean;
     attachments?: {
@@ -298,7 +327,18 @@ export interface ProfileInputsSpec {
     maxTurnBytes?: number;
     limitsByMime?: Record<string, number>;
     slots?: Record<string, string[]>;
+    context?: ProfileContextSpec;
+}
+/** What a live profile declares beside its ingress channels. */
+export type LiveInputsSpec = Pick<ProfileInputsSpec, 'slots' | 'context'>;
+/** Who may send a turn its context, and how much. */
+export interface ProfileContextSpec {
+    from: ContextSender[];
+    maxChars: number;
 }
+/** The context each sender gives a turn: any JSON, or text. */
+export type TurnContext = Partial<Record<ContextSender, unknown>>;
+/** What a profile returns: its structured schema, validation, and streaming. */
 export interface ProfileOutputsSpec {
     structured?: StructuredSchemaId | StructuredBySlot | null;
     validation?: ProfileValidationSpec;
@@ -308,6 +348,7 @@ export interface ProfileOutputsSpec {
 export interface PrivateSystemPart {
     private: string;
 }
+/** One part of a system prompt: plain text or a part kept out of traces. */
 export type SystemPart = string | PrivateSystemPart;
 /**
  * A system prompt: a string, or parts sent concatenated as written. A string,
@@ -320,36 +361,32 @@ export interface SystemPiece {
     text: string;
     private: boolean;
 }
+/** A profile's handle and system prompt. */
 export interface ProfileIdentity {
     handle: string;
     system?: SystemPrompt;
     systemByRole?: Record<string, SystemPrompt>;
 }
+/** The fields every profile type shares. */
 export interface ProfileCommon {
+    providerContinuation?: ProviderContinuationPolicy;
     id: ProfileId;
     identity: ProfileIdentity;
     models: Record<ModelId, ModelBinding>;
     defaultModel: ModelId;
     allowModelSelect?: boolean;
     maxSteps?: number;
-    key?: KeySlot;
-    /** Retried once when `key` is refused for quota. Off unless set. */
-    fallbackKey?: KeySlot;
     outputs?: ProfileOutputsSpec;
     guardrails?: ProfileGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    /** This profile's wording: replaces any lexicon default, and any `overrideLexicon` entry, for this profile. */
-    lexicon?: LexiconOverrides;
+    /** This profile's wording: replaces any label default, and any `overrideLabels` entry, for this profile. */
+    labels?: LabelOverrides;
 }
+/** Any JSON value; the state a decision reads. */
 export type DecisionJson = null | string | number | boolean | DecisionJson[] | {
     [key: string]: DecisionJson;
 };
-/** A decision model binding follows the same protocol/provider/apiId spine as turn models. */
-export interface DecisionModelBinding extends Pick<ModelBinding, 'apiId' | 'key'> {
-    protocol: 'decision';
-    provider: 'typesafe' | 'openrouter';
-    timeoutMs?: number;
-}
+/** What a decision profile accepts: JSON state up to a byte cap. */
 export interface DecisionInputsSpec {
     state: 'json';
     maxStateBytes?: number;
@@ -367,40 +404,64 @@ export interface DecisionProfile {
     identity: Pick<ProfileIdentity, 'handle'>;
     /** Exactly one model: a decision profile runs one model and never selects. */
     models: Record<ModelId, DecisionModelBinding>;
-    key?: KeySlot;
     inputs: DecisionInputsSpec;
     decision: {
         contract: DecisionContractId;
     };
     guardrails?: DecisionGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    /** This profile's wording: replaces any lexicon default, and any `overrideLexicon` entry, for this profile. */
-    lexicon?: LexiconOverrides;
+    /** This profile's wording: replaces any label default, and any `overrideLabels` entry, for this profile. */
+    labels?: LabelOverrides;
 }
 /** Text or nested text instruction entries. Non-text leaves are rejected locally. */
 export type DecisionEntry = string | DecisionEntry[] | {
     [key: string]: DecisionEntry;
 };
+/** A question answered by picking one of the named criteria. */
 export interface DecisionChoiceQuestion {
     type: 'choice';
     instructions: DecisionEntry;
     criteria: Record<string, DecisionEntry>;
 }
+/** A question answered with a single number, optionally with named criteria. */
 export interface DecisionNoulQuestion {
     type: 'noul';
     instructions: DecisionEntry;
     criteria?: Record<string, DecisionEntry>;
 }
+/** A question answered by scoring against an ordered list of criteria. */
 export interface DecisionScoreQuestion {
     type: 'score';
     instructions: DecisionEntry;
     criteria: readonly DecisionEntry[];
 }
-export type DecisionQuestion = DecisionChoiceQuestion | DecisionNoulQuestion | DecisionScoreQuestion;
+/** A question answered with the one box that holds what the instructions name, in an image. */
+export interface DecisionBoxQuestion {
+    type: 'box';
+    instructions: DecisionEntry;
+    /**
+     * The image the box is in: a reference in `assets`, such as `<ghs02>`, or the state field that
+     * holds one, such as `photo.front`. Unset, the model reads the image from the instructions.
+     */
+    image?: string;
+}
+/** One question a decision answers. */
+export type DecisionQuestion = DecisionChoiceQuestion | DecisionNoulQuestion | DecisionScoreQuestion | DecisionBoxQuestion;
+/** An image a decision reads: PNG or JPEG bytes as base64, with no `data:` prefix. */
+export interface DecisionAsset {
+    mimeType: 'image/png' | 'image/jpeg';
+    data: string;
+}
+/** A request to `runDecision`: the profile, the state to judge, and the questions to answer. */
 export interface DecisionRequest {
     profile: ProfileId;
     state: Exclude<DecisionJson, null>;
     questions: Record<string, DecisionQuestion>;
+    /**
+     * Images by reference. Write a reference as a string where its image belongs, in `state`, in a
+     * question's instructions, or in its criteria; the provider puts the image there.
+     */
+    assets?: Record<string, DecisionAsset>;
     signal?: AbortSignal;
     /** Host-owned metadata preserved on the decision's trace record; the kernel does not interpret it. */
     metadata?: Record<string, unknown>;
@@ -411,6 +472,7 @@ export interface DecisionRequest {
      */
     traceparent?: string;
 }
+/** The model's answer to one decision question. */
 export type DecisionAnswer = {
     type: 'choice';
     choice: string;
@@ -425,17 +487,99 @@ export type DecisionAnswer = {
     confidence: number;
     legend: Record<string, string>;
     probabilities: Record<string, number>;
+}
+/** Edges are fractions of the image, from its top-left corner. */
+ | {
+    type: 'box';
+    box: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    confidence: number;
 };
+/** What `runDecision` returns: the model and an answer for each question. */
 export interface DecisionResult {
     model: string;
     answers: Record<string, DecisionAnswer>;
-    /** Provider-reported tokens and cost, or a provider adapter's known model tariff. */
+    /** Provider-reported tokens and cost; a cost worked out from the provider's prices is `estimated`. */
     usage?: {
         inputTokens: number;
         outputTokens: number;
         costUsd?: number;
+        estimated?: true;
     };
 }
+/** One provider-neutral input part for an embedding request. */
+export type EmbeddingPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'media';
+    mimeType: string;
+    data: string;
+} | {
+    type: 'media-ref';
+    mimeType: string;
+    uri: string;
+};
+/** One embedding input. Media-only inputs remain valid for native local models. */
+export type EmbeddingInput = string | {
+    parts: readonly EmbeddingPart[];
+};
+/** A profile's accepted embedding input kinds and limits. */
+export interface EmbeddingInputsSpec {
+    text?: boolean;
+    attachments?: {
+        accept: string[];
+    };
+    maxFiles?: number;
+    maxBytes?: number;
+    maxTurnBytes?: number;
+    limitsByMime?: Record<string, number>;
+}
+/** A profile that returns vectors instead of a model turn. */
+export interface EmbeddingProfile extends Omit<ProfileCommon, 'identity' | 'outputs' | 'maxSteps'> {
+    type: 'embedding';
+    identity: Pick<ProfileIdentity, 'handle'>;
+    inputs: EmbeddingInputsSpec;
+}
+/**
+ * What the inputs are for in a search: `query` for what someone asks,
+ * `document` for what is searched. A model that embeds the two the same way
+ * ignores it.
+ */
+export type EmbeddingTask = 'query' | 'document';
+/** A request to `runEmbedding`. */
+export interface EmbeddingRequest {
+    profile: ProfileId;
+    model?: ModelId;
+    input: EmbeddingInput | readonly EmbeddingInput[];
+    task?: EmbeddingTask;
+    signal?: AbortSignal;
+    metadata?: Record<string, unknown>;
+    traceparent?: string;
+}
+/** One vector returned for one ordered embedding input. */
+export interface EmbeddingVector {
+    index: number;
+    values: readonly number[];
+    dimensions: number;
+}
+/** Provider usage for an embedding call. */
+export interface EmbeddingUsage {
+    inputTokens?: number;
+    costUsd?: number;
+    estimated?: true;
+}
+/** The normalized result of `runEmbedding`. */
+export interface EmbeddingResult {
+    model: string;
+    embeddings: readonly EmbeddingVector[];
+    usage?: EmbeddingUsage;
+}
+/** A profile that runs text turns. */
 export interface TextProfile extends ProfileCommon {
     type: 'text';
     tools: ProfileToolsSpec;
@@ -448,6 +592,7 @@ export interface TextProfile extends ProfileCommon {
  * `maxFiles` caps them.
  */
 export type ImageInputsSpec = Omit<ProfileInputsSpec, 'voice'>;
+/** A profile that generates images. */
 export interface ImageProfile extends ProfileCommon {
     type: 'image';
     image: ProfileImageSpec;
@@ -456,35 +601,28 @@ export interface ImageProfile extends ProfileCommon {
     turnBehaviour?: MediaTurnBehaviourSpec;
 }
 /**
- * Speech guardrails: no canary. A speech turn has no system channel to bind a
- * token into (Gemini TTS rejects developer instructions) and yields audio, not
- * text a canary scan could read.
+ * Unary TTS — text-in locked by type; no tools / inputs block. The input text is the transcript;
+ * there is no system prompt, so no canary is planted and nothing of the profile's own can leak.
  */
-export type SpeechGuardrailsSpec = Omit<ProfileGuardrailsSpec, 'canary'> & {
-    canary?: false;
-};
-/** Unary TTS — text-in locked by type; no tools / inputs block. The input text is the transcript; there is no system prompt. */
-export interface SpeechProfile extends Omit<ProfileCommon, 'identity' | 'guardrails'> {
+export interface SpeechProfile extends Omit<ProfileCommon, 'identity'> {
     type: 'speech';
     identity: Pick<ProfileIdentity, 'handle'>;
-    /** Registration always stores `canary: false`. */
-    guardrails: SpeechGuardrailsSpec & {
-        canary: false;
-    };
     speech: ProfileSpeechSpec;
     turnBehaviour?: MediaTurnBehaviourSpec;
 }
+/** A profile that holds a live audio session. */
 export interface LiveProfile extends Omit<ProfileCommon, 'outputs'> {
     type: 'live';
     live: ProfileLiveSpec;
+    inputs?: LiveInputsSpec;
     tools: LiveProfileToolsSpec;
     /** Stage inject gate only; live resumption is `live.sessionResumption`. */
     turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
 }
 /**
  * Host-driven tool execution; never runs a model. `invokeTool` runs any tool in
- * `tools.allow` with no visibility, loading tiers or path gating. `guardrails` holds only
- * the guards that fire on `invokeTool`: quota, canary and egress guard a model turn, so
+ * `tools.allow` with no visibility, loading tiers, or path gating. `guardrails` holds only
+ * the guards that fire on `invokeTool`: quota, canary, and egress guard a model turn, so
  * `defineProfile` refuses them rather than accept inert config.
  */
 export interface HostProfile {
@@ -493,12 +631,14 @@ export interface HostProfile {
     tools: HostProfileToolsSpec;
     guardrails?: HostGuardrailsSpec;
     observability?: ProfileObservabilitySpec;
-    /** This profile's wording: replaces any lexicon default, and any `overrideLexicon` entry, for this profile. */
-    lexicon?: LexiconOverrides;
+    /** This profile's wording: replaces any label default, and any `overrideLabels` entry, for this profile. */
+    labels?: LabelOverrides;
 }
-export type Profile = TextProfile | ImageProfile | SpeechProfile | LiveProfile | DecisionProfile | HostProfile;
+/** The contract that defines an agent’s capabilities and the rules for its interactions. Its type determines which settings it accepts. */
+export type Profile = TextProfile | ImageProfile | SpeechProfile | LiveProfile | DecisionProfile | EmbeddingProfile | HostProfile;
 /** Profiles that run a model turn — every type except `host` and `decision` (which runs through `runDecision`). */
-export type ModelProfile = Exclude<Profile, HostProfile | DecisionProfile>;
+export type ModelProfile = Exclude<Profile, HostProfile | DecisionProfile | EmbeddingProfile>;
+/** The image a profile asks the model to return. */
 export interface ImageResponseFormat {
     type: 'image';
     mimeType?: string;
@@ -512,6 +652,7 @@ export interface ImageResponseFormat {
     outputCompression?: number;
     includeText: boolean;
 }
+/** A file sent inline with a turn. */
 export interface TurnBlob {
     mimeType: string;
     data: string;
@@ -528,15 +669,19 @@ export interface TurnMediaRef {
     /** The file's name, used only to tell the user which file was refused; never sent to the model. */
     name?: string;
 }
+/** A rejected output and the guidance to retry it with. */
 export interface TurnRepairRequest {
     previousOutput: string;
     rejection: string;
     guidance?: string;
 }
+/** What the user sent for a turn: text, slots, attachments, voice, and history. */
 export interface TurnInput {
     text?: string;
     role?: string;
     slots?: Record<string, string>;
+    /** What the page or the host wants the model to know, by sender; the profile's `inputs.context` allows it. */
+    context?: TurnContext;
     attachments?: Array<TurnBlob | TurnMediaRef>;
     voice?: TurnBlob[];
     history?: TurnHistoryMessage[];
@@ -552,8 +697,8 @@ export interface TurnInput {
      * Ignored when `meter` is `'history'`.
      */
     inputTokens?: number;
-    sessionResumptionHandle?: string;
 }
+/** A turn request whose `input` is always present. */
 export type NormalizedTurnRequest = TurnRequest & {
     input: TurnInput;
 };
@@ -569,7 +714,11 @@ export interface TurnTraceLink {
     /** How the earlier turn stopped, when the host knows. */
     stop?: TurnStopKind;
 }
+/** A request to `runTurn`: the profile, the input, and the host's hooks and keys. */
 export interface TurnRequest {
+    execution?: ToolExecutionCoordinator;
+    pageExecution?: PageToolExecution;
+    providerState?: ProviderCheckpoint;
     profile: ProfileId;
     projectId?: string;
     /**
@@ -577,25 +726,19 @@ export interface TurnRequest {
      * Not the same as `projectId` or Gemini `previousInteractionId`.
      */
     sessionId?: string;
-    /** Google Interactions server-side conversation state. Omit for stateless/manual history. */
-    previousInteractionId?: string;
-    /**
-     * Location bias for Interactions `google_maps` builtin.
-     * Wired as `tools: [{ type: "google_maps", latitude, longitude }]`.
-     * Ignored when `googleMaps` is not enabled for the selected model.
-     */
-    googleMapsLocation?: {
-        latitude: number;
-        longitude: number;
-    };
-    /** Optional Interactions storage override. Omit to let the selected model binding decide. */
-    store?: boolean;
     /** Selected model id when `profile.allowModelSelect` is true. */
     model?: ModelId;
     /** Selected effort alias when the binding has `allowEffortSelect`. */
     effort?: string;
+    /**
+     * Args for built-in tools on the chosen model's `builtInTools`, by tool id.
+     * Each is parsed by the schema the provider's adapter declares for that tool.
+     */
+    builtInArgs?: BuiltInArgs;
     /** Host-provided dynamic system prompt combined with profile persona */
     system?: SystemPrompt;
+    /** This turn's voice, style, and speed, over `profile.speech`. Speech profiles only. */
+    speech?: TurnSpeech;
     sessionPermissions?: string[];
     /** Host channel/path for catalog `paths` filtering. */
     path?: string;
@@ -634,9 +777,6 @@ export interface TurnRequest {
      */
     continuation?: number;
     input?: TurnInput;
-    /** Runs a `timing: 'before'` compactor the turn's provider cannot. */
-    compactionProvider?: ModelProvider;
-    sessionResumptionHandle?: string;
     /** Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs one. */
     credentials?: ToolCredentialSource;
     /**
@@ -646,7 +786,14 @@ export interface TurnRequest {
     resolveHost?: ResolveHost;
     /** Text `runTurn` emits stages and applies the returned affordances. */
     onStage?: StageHandler;
+    /**
+     * Runs before each agent tool call in this turn, and in the turns those
+     * calls run. Shape the called agent's request (history, model, provider) or
+     * refuse the call. Omit it: the agent runs on what the model sent.
+     */
+    onAgentCall?: AgentCallHook;
 }
+/** A profile projected for a client, with its secrets and server-only fields removed. */
 export interface ProjectedProfile extends ProfileModelFields {
     id: string;
     type: ModelProfile['type'];
@@ -661,11 +808,10 @@ export interface ProjectedProfile extends ProfileModelFields {
     speech?: ProfileSpeechSpec | null;
     live?: ProfileLiveSpec | null;
 }
+/** The generation settings a provider call is made with. */
 export interface ProviderGenerationConfig {
     model: ModelId;
     apiId: string;
-    previousInteractionId?: string;
-    store?: boolean;
     /**
      * Upstream stream vs batch, derived from `outputs.streaming.mode`.
      * `true` = SSE (THEOREM default when mode is omitted); `false` = buffered.
@@ -676,35 +822,22 @@ export interface ProviderGenerationConfig {
     maxOutputTokens?: number;
     temperature?: number;
     builtins: BuiltinToolId[];
-    googleMapsLocation?: {
-        latitude: number;
-        longitude: number;
-    };
-    /** OpenRouter only. */
-    cache?: CacheSpec;
     /** Forwarded as OpenRouter `session_id`. */
     sessionId?: string;
 }
-export type ProviderTransport = 'interactions' | 'geminiLive' | 'openAiCompat';
+/** The transport a provider adapter speaks. */
+export type ProviderTransport = 'turn' | 'live';
+/** A generation config after the profile and request are resolved, with its transport. */
 export interface ResolvedGeneration extends ProviderGenerationConfig {
+    /** The request's `builtInArgs`, parsed. */
+    builtInArgs?: BuiltInArgs;
+    execution?: ToolExecutionCoordinator;
+    pageExecution?: PageToolExecution;
     transport: ProviderTransport;
-    /**
-     * Whether the turn's steps chain on the stored interaction: a tool result or
-     * stage inject rides `continuation` after `previousInteractionId`. Only an
-     * Interactions binding chains, and never one with `persistViaInteractionId:
-     * false` — its steps each send the host's history plus the turn's steps so far.
-     */
-    chains: boolean;
     tools: TurnToolSnapshot;
     sessionPermissions?: string[];
     history?: TurnHistoryMessage[];
-    /**
-     * Interactions-only: messages sent after `previousInteractionId` (tool
-     * results, stage injects) instead of history + user parts. The model reads
-     * the stored interaction plus these.
-     */
-    continuation?: TurnHistoryMessage[];
-    /** Tool-loop ceiling. `undefined` or `<= 0` = unbounded. */
+    /** Tool-loop ceiling: the profile's `maxSteps`, or `DEFAULT_MAX_STEPS`. */
     maxSteps?: number;
     structured: ResolvedStructured | null;
     image: ImageResponseFormat | null;
@@ -712,64 +845,62 @@ export interface ResolvedGeneration extends ProviderGenerationConfig {
     live?: ProfileLiveSpec;
     input: InteractionPart[];
     /**
-     * Vault key slot; every model but a local one without a key names one. Never sent on the wire.
+     * The canary bound into the system prompt; empty with the canary off. A turn
+     * binds the profile's (`profileCanary`), the same for the same prompt; a
+     * Live session binds this one, minted for it.
      */
-    keySlot?: KeySlot;
-    /** The slot a quota refusal on `keySlot` retries on once, when the profile names one. */
-    fallbackKeySlot?: KeySlot;
     canary: string;
-    sessionResumptionHandle?: string;
     /** Snapshotted synchronously before any async work; the runner binds the canary on top. */
     resolvedSystem: readonly SystemPiece[];
     /** `TurnRequest.host`, carried to tool contexts only. Never sent to providers or traces. */
     host?: unknown;
 }
-/**
- * `previousInteractionId`, `store`, `stream`, `summaries` and `continuation` are
- * Google Interactions-only and absent otherwise. `keySlot` is required for every
- * provider but local; it is never sent on the wire.
- */
-export interface ProviderCompleteRequest extends Omit<ProviderGenerationConfig, 'summaries' | 'builtins'> {
-    /** The turn's builtins with their wire names; adapters read no registry. */
+/** One model call as the engine asks it: the resolved generation, the conversation, and the tools. */
+export interface ModelRequest extends Omit<ProviderGenerationConfig, 'summaries' | 'builtins'> {
+    /** The turn's builtins with the args addressed to each. */
     builtins: ProviderBuiltin[];
     summaries?: SummaryMode;
+    providerState?: ProviderCheckpoint;
     system: string;
     input: InteractionPart[];
     history?: TurnHistoryMessage[];
-    /** Sent after `previousInteractionId` instead of history + user parts; mapped like history. */
-    continuation?: TurnHistoryMessage[];
     wireTools?: WireFunctionTool[];
     structured: ResolvedStructured | null;
     image: ImageResponseFormat | null;
     speech?: ProfileSpeechSpec;
     live?: ProfileLiveSpec;
-    sessionResumptionHandle?: string;
-    keySlot?: KeySlot;
-    /** The slot a quota refusal on `keySlot` retries on once. Never sent on the wire. */
-    fallbackKeySlot?: KeySlot;
     /** Scrubbed SSE / HTTP rows for traces. */
     tapUpstream?: (row: Record<string, unknown>) => void;
-    /** Host abort signal — adapters should pass this into fetch / SDK calls. */
+    /** Host abort signal. */
     signal?: AbortSignal;
 }
-export interface ModelProvider {
-    complete: (req: ProviderCompleteRequest) => AsyncIterable<ProviderEvent>;
+/** One model call, streamed as the model's events. */
+export interface TurnModel {
+    complete: (req: ModelRequest) => AsyncIterable<ModelEvent>;
 }
 /**
  * Host request to open a long-lived live session (`runSession`).
  * Profile must be `type: 'live'`.
  */
 export interface SessionRequest {
+    providerState?: ProviderCheckpoint;
     profile: ProfileId;
     /** Host-built system prompt merged with profile identity.system. */
     system?: SystemPrompt;
     /** Override `profile.live.voice` for this session. */
     voice?: string;
+    /** As `TurnRequest.builtInArgs`. */
+    builtInArgs?: BuiltInArgs;
     path?: string;
     sessionPermissions?: string[];
     history?: TurnHistoryMessage[];
-    sessionResumptionHandle?: string;
-    /** Optional realtime parts sent immediately after setup. */
+    /** The value chosen for each of the profile's `inputs.slots`. */
+    slots?: Record<string, string>;
+    /** What the page and the host tell the agent as the call opens; `sendContext` replaces it later. */
+    context?: TurnContext;
+    /** How long the caller was away before this resume, in milliseconds. The session keeps no clock across calls. */
+    awayMs?: number;
+    /** Optional realtime parts sent immediately after setup. A call that sends them gets no `live.greeting`. */
     input?: InteractionPart[];
     /**
      * Registry-resolved tool snapshot from the process that owns the tool registry
@@ -793,6 +924,12 @@ export interface SessionRequest {
     links?: TurnTraceLink[];
     /** Immutable for the session; there is no `setOnStage`. */
     onStage?: StageHandler;
+    /**
+     * As `TurnRequest.onAgentCall`, for the agent tools this session's calls run.
+     * Omit it: each agent runs on what the model sent, with the session's own
+     * provider options.
+     */
+    onAgentCall?: AgentCallHook;
     /**
      * Default credentials for `executeTool` (per-call args override). Without one, the
      * session keeps keys typed at its sign-in gates in memory.
@@ -813,6 +950,7 @@ export interface SessionRequest {
  */
 export type LiveExecuteToolArgs = {
     callId: string;
+    operationId?: string;
     decision?: GateDecision;
     input?: unknown;
     /**
@@ -823,6 +961,8 @@ export type LiveExecuteToolArgs = {
     secret?: string;
     credentials?: ToolCredentialSource;
     host?: unknown;
+    /** The page's answer, for a call to a tool with `answeredBy: 'page'`. */
+    page?: PageAnswer;
 };
 /**
  * Settle a call the model made in this session whose body ran in the process
@@ -833,6 +973,7 @@ export type LiveAnswerToolCallArgs = {
     callId: string;
     events: readonly TurnEvent[];
 };
+/** What running a tool call during a live session returns. */
 export type LiveExecuteToolResult = {
     outputRaw?: unknown;
     outputModel?: ModelToolResult;
@@ -841,7 +982,7 @@ export type LiveExecuteToolResult = {
     gated?: ToolGate;
 };
 /**
- * Open Gemini Live session returned by `runSession`. It streams events until
+ * Open live session returned by `runSession`. It streams events until
  * `close()` and exposes realtime media ingress and staged tool execution.
  */
 export interface LiveSession {
@@ -860,11 +1001,11 @@ export interface LiveSession {
     }): Promise<void>;
     sendText(text: string): Promise<void>;
     /**
-     * Text the model reads as background, not as the caller speaking: it opens no
-     * turn and draws no reply. Same `ingress.text` gate and inbound guardrails as
-     * `sendText`; the model sees it from its next turn on.
+     * What the page or the host tells the model to know, by sender: it opens no turn and
+     * draws no reply. Checked against `inputs.context` and read at the `context` boundary;
+     * the model sees it from its next turn on.
      */
-    sendContext(text: string): Promise<void>;
+    sendContext(context: TurnContext): Promise<void>;
     /**
      * Run a call the model made through the registry, with stages; its events
      * join `events()`. A gate returns `gated` and answers the model nothing yet;