@anvia/core 1.2.1 → 1.2.2

package/dist/tool/index.js

@@ -1,45 +1,45 @@
 import "../chunk-JMJFK3A4.js";
 import {
   createThinkTool
-} from "../chunk-6N4ENZO4.js";
+} from "../chunk-VU6YTPPH.js";
 import {
   createMiddleware
 } from "../chunk-4AW2633B.js";
 import {
   createQuestionTool,
   isQuestionTool
-} from "../chunk-IV6YQTY2.js";
+} from "../chunk-ICDPUAKN.js";
 import {
   createToolIndex,
   embedTools,
   isToolIndex
-} from "../chunk-G336L2IE.js";
-import "../chunk-72LBHKYP.js";
+} from "../chunk-VCMBQTR4.js";
+import "../chunk-5REZFNZ3.js";
 import "../chunk-ESOFEAYK.js";
 import "../chunk-HAAGSIZH.js";
 import "../chunk-5WLIHNNJ.js";
-import "../chunk-QHGYCYV6.js";
+import "../chunk-5KS4SG2U.js";
+import "../chunk-KO5NMTAM.js";
+import "../chunk-TFIOU6UR.js";
+import "../chunk-GPVXCY5I.js";
 import "../chunk-ERN7P6Q4.js";
+import "../chunk-DU4WA6LQ.js";
 import "../chunk-7F53DOML.js";
 import "../chunk-HHMLE3TZ.js";
-import "../chunk-DU4WA6LQ.js";
 import "../chunk-4FIVU53H.js";
-import "../chunk-KO5NMTAM.js";
-import "../chunk-TFIOU6UR.js";
-import "../chunk-GPVXCY5I.js";
 import "../chunk-5V533R7F.js";
 import {
   createTool
-} from "../chunk-XV3DH5GC.js";
+} from "../chunk-WUZG6B3Q.js";
 import "../chunk-YZVFIW5D.js";
-import "../chunk-MHOJJYDK.js";
+import "../chunk-647TQE3E.js";
 import {
   ToolOutput,
   ToolResultSerializationError,
   normalizeToolResultOutput,
   parseToolArgs,
   toolResultContentToText
-} from "../chunk-47NTHIVB.js";
+} from "../chunk-SCFWN3T2.js";
 import {
   ToolCallError,
   ToolJsonError,

package/dist/tool/question-tool.js

@@ -1,11 +1,11 @@
 import {
   createQuestionTool,
   isQuestionTool
-} from "../chunk-IV6YQTY2.js";
-import "../chunk-XV3DH5GC.js";
+} from "../chunk-ICDPUAKN.js";
+import "../chunk-WUZG6B3Q.js";
 import "../chunk-YZVFIW5D.js";
-import "../chunk-MHOJJYDK.js";
-import "../chunk-47NTHIVB.js";
+import "../chunk-647TQE3E.js";
+import "../chunk-SCFWN3T2.js";
 import "../chunk-J6S6MT7O.js";
 import "../chunk-BONQTXRQ.js";
 import "../chunk-4C7AXYOM.js";

package/dist/tool/think-tool.js

@@ -1,10 +1,10 @@
 import {
   createThinkTool
-} from "../chunk-6N4ENZO4.js";
-import "../chunk-XV3DH5GC.js";
+} from "../chunk-VU6YTPPH.js";
+import "../chunk-WUZG6B3Q.js";
 import "../chunk-YZVFIW5D.js";
-import "../chunk-MHOJJYDK.js";
-import "../chunk-47NTHIVB.js";
+import "../chunk-647TQE3E.js";
+import "../chunk-SCFWN3T2.js";
 import "../chunk-J6S6MT7O.js";
 import "../chunk-BONQTXRQ.js";
 import "../chunk-4C7AXYOM.js";

package/dist/tool/tool.js

@@ -4,7 +4,7 @@ import {
   normalizeToolResultOutput,
   parseToolArgs,
   toolResultContentToText
-} from "../chunk-47NTHIVB.js";
+} from "../chunk-SCFWN3T2.js";
 import "../chunk-BONQTXRQ.js";
 import "../chunk-4C7AXYOM.js";
 export {

package/dist/{tool-DQMZpZSS.d.ts → tool-D_jV3cRZ.d.ts}

@@ -1,33 +1,53 @@
-import { J as JsonObject, B as ToolDefinition, t as JsonValue, H as ToolResultOutput, G as ToolResultContentPart } from './types-CiHjqE6J.js';
+import { J as JsonObject, B as ToolDefinition, t as JsonValue, H as ToolResultOutput, G as ToolResultContentPart } from './types-DYqZKDA8.js';
 
+/** Identifies the agent run that requested a tool approval. */
 type ToolApprovalRunContext = {
     agentId: string;
     runId: string;
     sessionId?: string;
     metadata?: JsonObject;
 };
+/** Details of the pending tool call being evaluated for approval. */
 type ToolApprovalContext<Args = unknown> = {
     toolName: string;
     args: Args;
+    /** The serialized argument string passed to hooks and approval checks. */
     rawArgs: string;
     toolCallId: string;
     callId?: string;
     internalCallId: string;
     run: ToolApprovalRunContext;
 };
+/** An approval demand, with an optional human-readable reason. */
 type ToolApprovalRequirement = {
     reason?: string | undefined;
 };
+/**
+ * Whether a tool call needs human approval before execution:
+ *
+ * - `boolean`: a static requirement
+ * - `ToolApprovalRequirement`: a requirement with a reason
+ * - a function: evaluated per call, receiving the parsed args and call context
+ */
 type ToolRequiresApproval<Args = unknown> = boolean | ToolApprovalRequirement | ((args: Args, context: ToolApprovalContext<Args>) => boolean | ToolApprovalRequirement | Promise<boolean | ToolApprovalRequirement>);
+/** A child-agent event forwarded through a tool into the parent run's stream. */
 type ToolCallStreamEvent = {
     agentId: string;
     agentName?: string | undefined;
     event: unknown;
 };
+/** Execution context handed to a tool when the run invokes it. */
 type ToolCallContext = {
+    /** Emits a child-agent event into the parent run's stream. */
     emitStreamEvent?(event: ToolCallStreamEvent): void | Promise<void>;
+    /** Aborted when the run is cancelled or the stream consumer leaves. */
     abortSignal?: AbortSignal | undefined;
 };
+/**
+ * A model-callable tool. `definition` builds the model-facing JSON description,
+ * `call` executes it, and the optional `parseInput` converts raw model-supplied
+ * JSON arguments into the typed `Args` before `call` runs.
+ */
 interface Tool<Args = unknown, Output = unknown> {
     readonly name: string;
     readonly requiresApproval?: ToolRequiresApproval<Args>;
@@ -35,24 +55,41 @@ interface Tool<Args = unknown, Output = unknown> {
     call(args: Args, context?: ToolCallContext): Output | Promise<Output>;
     parseInput?(args: JsonValue): Args;
 }
+/** A tool with its argument and output types erased, e.g. as stored in an agent's catalog. */
 type AnyTool = Omit<Tool<unknown, unknown>, "requiresApproval"> & {
     readonly requiresApproval?: unknown;
 };
 declare const richToolOutput: unique symbol;
+/**
+ * A tool result carrying mixed content parts (text, files), created with
+ * {@link ToolOutput.content}. The brand symbol keeps plain objects from
+ * impersonating rich outputs.
+ */
 type RichToolOutput = Readonly<{
     [richToolOutput]: true;
     content: readonly ToolResultContentPart[];
 }>;
+/** Normalized tool result as stored in tool messages. */
 type NormalizedToolOutput = ToolResultOutput;
+/** Thrown when a tool returns a value that cannot be represented as a tool result. */
 declare class ToolResultSerializationError extends TypeError {
     readonly output: unknown;
     constructor(output: unknown);
 }
+/** Helpers for building tool results. */
 declare const ToolOutput: {
+    /** Wraps content parts so a tool can return text and files together. */
     content(content: readonly ToolResultContentPart[]): RichToolOutput;
 };
+/**
+ * Coerces a tool's return value into a normalized result: strings become text,
+ * rich outputs are validated, and strict JSON values become JSON results.
+ * Anything else throws {@link ToolResultSerializationError}.
+ */
 declare function normalizeToolResultOutput(output: unknown): NormalizedToolOutput;
+/** Renders tool result content as text; file parts become `[file:<mediaType>]` placeholders. */
 declare function toolResultContentToText(content: readonly ToolResultContentPart[]): string;
+/** Parses and JSON-validates the raw argument string supplied by the model. */
 declare function parseToolArgs(args: string): JsonValue;
 
 export { type AnyTool as A, type NormalizedToolOutput as N, type RichToolOutput as R, type Tool as T, type ToolApprovalContext as a, type ToolApprovalRequirement as b, type ToolCallContext as c, type ToolCallStreamEvent as d, type ToolRequiresApproval as e, type ToolApprovalRunContext as f, ToolOutput as g, ToolResultSerializationError as h, normalizeToolResultOutput as n, parseToolArgs as p, toolResultContentToText as t };

package/dist/transcription/index.d.ts

@@ -1,7 +1,7 @@
 import { M as ModelCallOptions } from '../model-call-options-CZkSw_xN.js';
 import { b as RetrySetting } from '../retry-CjvSlKGW.js';
 export { R as RetryContext, a as RetryOptions } from '../retry-CjvSlKGW.js';
-import { J as JsonObject } from '../types-CiHjqE6J.js';
+import { J as JsonObject } from '../types-DYqZKDA8.js';
 
 type TranscriptionRequest = {
     data: Uint8Array;

package/dist/{types-DfRPfehE.d.ts → types-0t3BczrD.d.ts}

@@ -1,5 +1,5 @@
-import { J as JsonObject } from './types-CiHjqE6J.js';
-import { A as AnyTool } from './tool-DQMZpZSS.js';
+import { J as JsonObject } from './types-DYqZKDA8.js';
+import { A as AnyTool } from './tool-D_jV3cRZ.js';
 
 type McpServerInfo = {
     readonly name: string;

package/dist/{types-CODGMHnp.d.ts → types-ChyQISt-.d.ts}

@@ -1,5 +1,5 @@
 import { b as RetrySetting } from './retry-CjvSlKGW.js';
-import { J as JsonObject } from './types-CiHjqE6J.js';
+import { J as JsonObject } from './types-DYqZKDA8.js';
 import { b as VectorMetadataValue, V as VectorMetadata, a as EmbeddedDocument, S as SparseVector, E as EmbeddingModel, c as SparseEmbeddingModel } from './types-Cr4uiYo5.js';
 
 type VectorFilter = {

package/dist/{types-Bqw0AuFl.d.ts → types-CqiX-4_C.d.ts}

@@ -1,4 +1,4 @@
-import { M as Message, J as JsonObject, U as Usage } from './types-CiHjqE6J.js';
+import { M as Message, J as JsonObject, U as Usage } from './types-DYqZKDA8.js';
 
 type MaybePromise<T> = T | Promise<T>;
 type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : T extends object ? {

package/dist/{types-C1xYKXF2.d.ts → types-Cu2tEf3V.d.ts}

@@ -1,4 +1,4 @@
-import { A as AnyTool } from './tool-DQMZpZSS.js';
+import { A as AnyTool } from './tool-D_jV3cRZ.js';
 
 type Skill = {
     readonly name: string;

package/dist/{types-CiHjqE6J.d.ts → types-DYqZKDA8.d.ts}

@@ -1,21 +1,33 @@
 import { M as ModelCallOptions } from './model-call-options-CZkSw_xN.js';
 
 type JsonPrimitive = string | number | boolean | null;
+/** Any JSON-compatible value: primitives, objects, or readonly arrays of JSON values. */
 type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
 type JsonObject = {
     [key: string]: JsonValue;
 };
+/** A retrievable text document passed to a completion as grounding context. */
 type Document = {
     id: string;
     text: string;
+    /** String metadata rendered as a `<metadata ... />` header above the text when documents are serialized into prompts. */
     additionalProps?: Record<string, string>;
 };
+/**
+ * A text segment, optionally carrying a provider reasoning signature.
+ */
 type TextPart = Readonly<{
     type: "text";
     text: string;
+    /** Provider signature preserved so reasoning can be replayed on later turns. */
     signature?: string;
 }>;
+/** Image input fidelity hint forwarded to providers that support it. */
 type ImageDetail = "auto" | "low" | "high";
+/**
+ * File payload for image/file parts: a remote URL, base64 data, or literal text
+ * interpreted as a document.
+ */
 type FileData = Readonly<{
     type: "url";
     url: string;
@@ -26,6 +38,7 @@ type FileData = Readonly<{
     type: "text";
     text: string;
 }>;
+/** Image input with an optional media type override and detail hint. */
 type ImagePart = Readonly<{
     type: "image";
     image: Exclude<FileData, Readonly<{
@@ -35,18 +48,27 @@ type ImagePart = Readonly<{
     mediaType?: string;
     detail?: ImageDetail;
 }>;
+/** Document/file input part; non-text data is rejected by models without `documentInput`. */
 type FilePart = Readonly<{
     type: "file";
     data: FileData;
     mediaType: string;
     filename?: string;
 }>;
+/** Model reasoning content, replayable across turns to preserve thinking state. */
 type ReasoningPart = Readonly<{
     type: "reasoning";
     text: string;
     id?: string;
     details?: readonly ReasoningDetail[];
 }>;
+/**
+ * Reasoning detail variants:
+ *
+ * - `text` / `summary`: displayable reasoning text
+ * - `encrypted` / `redacted`: opaque payloads that can only be echoed back to
+ *   the provider; their content is not readable by the application
+ */
 type ReasoningDetail = Readonly<{
     type: "text";
     text: string;
@@ -62,6 +84,7 @@ type ReasoningDetail = Readonly<{
     data: string;
 }>;
 type ReasoningContentType = ReasoningDetail["type"];
+/** A tool call requested by the model; `signature` preserves provider replay state. */
 type ToolCallPart = Readonly<{
     type: "tool-call";
     toolCallId: string;
@@ -70,7 +93,17 @@ type ToolCallPart = Readonly<{
     input: JsonValue;
     signature?: string;
 }>;
+/** The content variants allowed inside a tool result payload. */
 type ToolResultContentPart = TextPart | FilePart;
+/**
+ * Outcome of one tool execution, as recorded in tool messages:
+ *
+ * - `text` / `json`: successful result as plain text or JSON
+ * - `content`: successful result as mixed content parts
+ * - `execution-denied`: the call was blocked (e.g. by a required approval)
+ * - `error-text` / `error-json`: failure surfaced to the model so the run can
+ *   continue instead of aborting
+ */
 type ToolResultOutput = Readonly<{
     type: "text";
     value: string;
@@ -90,6 +123,7 @@ type ToolResultOutput = Readonly<{
     type: "error-json";
     value: JsonValue;
 }>;
+/** Tool result reported back to the model, matched to its call via `toolCallId`. */
 type ToolResultPart = Readonly<{
     type: "tool-result";
     toolCallId: string;
@@ -97,6 +131,7 @@ type ToolResultPart = Readonly<{
     toolName: string;
     output: ToolResultOutput;
 }>;
+/** Human decision on a tool call that required approval before execution. */
 type ToolApprovalResponsePart = Readonly<{
     type: "tool-approval-response";
     interactionId: string;
@@ -106,10 +141,12 @@ type ToolApprovalResponsePart = Readonly<{
     approved: boolean;
     reason?: string;
 }>;
+/** Answer to one question asked by a tool suspended on a human interaction. */
 type ToolQuestionAnswer = Readonly<{
     questionId: string;
     value: string;
 }>;
+/** Answers to tool questions, delivered back through the suspended run. */
 type ToolQuestionResponsePart = Readonly<{
     type: "tool-question-response";
     interactionId: string;
@@ -118,8 +155,11 @@ type ToolQuestionResponsePart = Readonly<{
     toolName: string;
     answers: readonly ToolQuestionAnswer[];
 }>;
+/** A tool or human-interaction response delivered inside a `role: "tool"` message. */
 type ToolInteractionResponsePart = ToolApprovalResponsePart | ToolQuestionResponsePart;
+/** Content parts allowed in user messages. */
 type UserContentPart = TextPart | ImagePart | FilePart;
+/** Content parts allowed in assistant messages, including replayed reasoning and tool calls. */
 type AssistantContentPart = TextPart | ImagePart | FilePart | ReasoningPart | ToolCallPart;
 type SystemMessage<Metadata extends JsonObject = JsonObject> = Readonly<{
     role: "system";
@@ -142,12 +182,25 @@ type ToolMessage<Metadata extends JsonObject = JsonObject> = Readonly<{
     content: readonly (ToolResultPart | ToolInteractionResponsePart)[];
     metadata?: Metadata;
 }>;
+/**
+ * A conversation message from the system, user, assistant, or tool role.
+ *
+ * Framework-generated metadata (provider, model, usage of the generation that
+ * produced an assistant message) is stored under the `anvia` key of `metadata`;
+ * read it back with {@link getAssistantGenerationMetadata}.
+ */
 type Message<Metadata extends JsonObject = JsonObject> = SystemMessage<Metadata> | UserMessage<Metadata> | AssistantMessage<Metadata> | ToolMessage<Metadata>;
+/** Joins the human-readable text of a reasoning part or its details. */
 declare function reasoningDisplayText(reasoning: ReasoningPart | readonly ReasoningDetail[]): string;
+/**
+ * How the model may call tools: freely, mandatorily, never, or a named function.
+ * Requires the model's `toolChoice` capability.
+ */
 type ToolChoice = "auto" | "required" | "none" | {
     type: "function";
     name: string;
 };
+/** JSON Schema-shaped tool description sent to the model (a local tool's public face). */
 type ToolDefinition = {
     name: string;
     description: string;
@@ -166,7 +219,9 @@ type ProviderTool = {
     configuration?: JsonObject;
 };
 type CompletionTool = ToolDefinition | ProviderTool;
+/** Narrows an unknown value to a well-formed {@link ProviderTool}. */
 declare function isProviderTool(value: unknown): value is ProviderTool;
+/** A grounding source (e.g. web result) returned by the provider, with optional text offsets. */
 type CompletionSource = {
     type: "url";
     url: string;
@@ -175,6 +230,7 @@ type CompletionSource = {
     startIndex?: number;
     endIndex?: number;
 };
+/** A tool call executed on the provider side, surfaced for observability. */
 type ProviderToolCall = {
     id: string;
     name: string;
@@ -188,15 +244,18 @@ type ProviderToolCall = {
  * only aggregate key and should equal the sum of the other buckets.
  */
 type UsageDetails = Record<string, number>;
+/** Model context window bounds; unset input/output caps fall back to the window. */
 type ModelContextLimits = {
     contextWindow: number;
     maxInputTokens?: number;
     maxOutputTokens?: number;
 };
+/** Identifies a model together with its context limits. */
 type CompletionModelInfo = {
     modelId: string;
     context: ModelContextLimits;
 };
+/** Snapshot of how much of a model's context window a request consumed. */
 type ContextUsage = {
     model: CompletionModelInfo;
     usedTokens: number;
@@ -204,9 +263,13 @@ type ContextUsage = {
     usedPercent: number;
     remainingPercent: number;
 };
+/** Computes context usage, or undefined when the model or usage data is unusable. */
 declare function calculateContextUsage(usage: Usage, model: CompletionModelInfo | undefined): ContextUsage | undefined;
+/** Attaches context usage to a response when model limits are known. */
 declare function withContextUsage<RawResponse>(response: CompletionResponse<RawResponse>, model: CompletionModelInfo | undefined): CompletionResponse<RawResponse>;
+/** Resolves a model's context limits: explicit override wins over catalog lookup. */
 declare function resolveModelContextLimits(modelId: string, catalog: Readonly<Record<string, ModelContextLimits>>, override?: ModelContextLimits): ModelContextLimits | undefined;
+/** Provider/model/usage metadata embedded in assistant message metadata by the runtime. */
 type AssistantGenerationMetadata = {
     provider: string;
     modelId: string;
@@ -217,6 +280,13 @@ type AssistantGenerationMetadata = {
     sources?: CompletionSource[];
     providerToolCalls?: ProviderToolCall[];
 };
+/**
+ * Token usage for one or more generations.
+ *
+ * `cachedInputTokens` counts input tokens served from the provider's prompt
+ * cache; `cacheCreationInputTokens` counts input tokens billed for writing to
+ * that cache. Both are subsets of `inputTokens`.
+ */
 type Usage = {
     inputTokens: number;
     outputTokens: number;
@@ -225,12 +295,26 @@ type Usage = {
     cacheCreationInputTokens: number;
     details?: UsageDetails;
 };
+/**
+ * Helpers for constructing and combining token usage.
+ */
 declare const Usage: {
+    /** Returns an all-zero usage value. */
     empty(): Usage;
+    /**
+     * Sums two usage values bucket by bucket. `details` are merged only when
+     * both sides carry them; if either side omits them, the result omits them.
+     */
     add(left: Usage, right: Usage): Usage;
+    /** Returns true when every bucket, including `details`, is zero. */
     isEmpty(usage: Usage): boolean;
 };
+/**
+ * Reads the generation metadata the runtime embeds in assistant messages, when
+ * present and structurally valid.
+ */
 declare function getAssistantGenerationMetadata(message: Message): AssistantGenerationMetadata | undefined;
+/** Provider-agnostic completion request assembled by the runtime for adapters. */
 type CompletionRequest = {
     instructions?: string;
     chatHistory: Message[];
@@ -240,25 +324,45 @@ type CompletionRequest = {
     temperature?: number;
     maxTokens?: number;
     toolChoice?: ToolChoice;
+    /** Values for the model's declared completion controls; validated before sending. */
     controls?: Readonly<Record<string, string>>;
+    /** Provider-specific passthrough options; never validated by the core runtime. */
     providerOptions?: JsonObject;
+    /** JSON Schema the output must conform to; requires the `outputSchema` capability. */
     outputSchema?: JsonObject;
 };
+/** Normalized finish reasons:
+ *
+ * - `stop`: the model finished naturally
+ * - `length`: an output token limit was hit
+ * - `content-filter`: output was blocked by a safety filter
+ * - `tool-calls`: the model stopped to request tool calls
+ * - `other`: any provider-specific reason
+ */
 type CompletionFinishReason = "stop" | "length" | "content-filter" | "tool-calls" | "other";
+/** A provider's raw completion response: normalized parts plus usage and metadata. */
 type CompletionResponse<RawResponse = unknown> = {
     choice: AssistantContentPart[];
     usage: Usage;
     finishReason?: CompletionFinishReason;
     providerFinishReason?: string;
     contextUsage?: ContextUsage;
+    /** The provider SDK's original response object, unmodified. */
     rawResponse: RawResponse;
     messageId?: string;
     sources?: CompletionSource[];
     providerToolCalls?: ProviderToolCall[];
 };
+/** Final result of a completion: typed output, plain text, full content, and usage. */
 type CompletionResult<Output = string, RawResponse = unknown> = {
+    /**
+     * The typed output. When an output schema was requested this is the parsed,
+     * validated object; otherwise it is the plain text.
+     */
     output: Output;
+    /** The generated text, joined from the response's text parts. */
     text: string;
+    /** Every content part the model produced, including reasoning and tool calls. */
     content: readonly AssistantContentPart[];
     usage: Usage;
     finishReason?: CompletionFinishReason;
@@ -269,6 +373,7 @@ type CompletionResult<Output = string, RawResponse = unknown> = {
     sources?: readonly CompletionSource[];
     providerToolCalls?: readonly ProviderToolCall[];
 };
+/** Feature flags a model declares; requests are validated against these at runtime. */
 type CompletionModelCapabilities = {
     streaming: boolean;
     tools: boolean;
@@ -279,6 +384,7 @@ type CompletionModelCapabilities = {
     reasoning: boolean;
     providerTools?: boolean;
 };
+/** A selectable model control exposed to applications (e.g. "reasoning effort"). */
 type CompletionModelSelectControl<Option extends string = string> = Readonly<{
     type: "select";
     label: string;
@@ -286,24 +392,50 @@ type CompletionModelSelectControl<Option extends string = string> = Readonly<{
     description?: string | undefined;
     defaultValue?: Option | undefined;
 }>;
+/** Named set of controls a model supports, keyed by control id. */
 type CompletionModelControls = Readonly<Record<string, CompletionModelSelectControl<string>>>;
+/** Marker type for models that accept no completion controls. */
 type NoCompletionModelControls = Readonly<Record<string, never>>;
+/** The option values a model's controls accept, keyed by control id. */
 type CompletionControlValues<Controls extends CompletionModelControls> = Readonly<Partial<{
     [Key in keyof Controls]: Controls[Key] extends CompletionModelSelectControl<infer Option> ? Option : never;
 }>>;
+/** Extracts a model's control types, defaulting to the open controls record. */
 type CompletionModelControlsOf<Model> = Model extends CompletionModel<unknown, infer Controls> ? Controls : CompletionModelControls;
+/**
+ * The provider-agnostic model contract every adapter implements: non-streaming
+ * completions plus capability, context, and control metadata.
+ */
 interface CompletionModel<RawResponse = unknown, Controls extends CompletionModelControls = CompletionModelControls> {
     readonly provider: string;
     readonly modelId: string;
     readonly contextLimits?: ModelContextLimits | undefined;
     readonly capabilities: CompletionModelCapabilities;
     readonly controls?: Controls | undefined;
+    /**
+     * Returns a JSON-safe representation of the outgoing request for
+     * observability traces, or undefined to omit the trace payload. Errors
+     * thrown here are swallowed by the runtime and recorded as a trace error.
+     */
     traceRequest?(request: CompletionRequest, options?: {
         stream?: boolean | undefined;
     }): JsonObject | undefined;
     completion(request: CompletionRequest, options?: ModelCallOptions): Promise<CompletionResponse<RawResponse>>;
 }
+/** How a `tool_call_delta` updates arguments: append to, or replace, accumulated JSON. */
 type ToolCallArgumentsMode = "append" | "replace";
+/**
+ * Incremental completion stream content:
+ *
+ * - `text_delta` / `reasoning_delta`: incremental text or reasoning content
+ * - `tool_call_delta`: partial tool call input; argument fragments accumulate
+ *   according to `argumentsMode` (`append` continues the JSON string, `replace`
+ *   restarts it)
+ * - `tool_call`: a complete tool call
+ * - `source`: a grounding source discovered during generation
+ * - `provider_tool_call`: progress on a provider-executed tool
+ * - `message_id`: the id of the message being generated
+ */
 type CompletionStreamPart = {
     type: "text_delta";
     delta: string;
@@ -312,6 +444,7 @@ type CompletionStreamPart = {
     delta: string;
     id?: string;
     contentType?: ReasoningContentType;
+    /** Provider signature preserved for reasoning replay. */
     signature?: string;
 } | {
     type: "tool_call_delta";
@@ -334,6 +467,7 @@ type CompletionStreamPart = {
     type: "message_id";
     id: string;
 };
+/** Raw model stream events: stream parts, the final response, or a terminal error. */
 type CompletionModelStreamEvent<RawResponse = unknown> = CompletionStreamPart | {
     type: "final";
     response: CompletionResponse<RawResponse>;
@@ -342,6 +476,7 @@ type CompletionModelStreamEvent<RawResponse = unknown> = CompletionStreamPart |
     error: unknown;
     usage?: Usage;
 };
+/** High-level stream events: stream parts, the final typed result, or a terminal error. */
 type CompletionStreamEvent<Output = string, RawResponse = unknown> = CompletionStreamPart | {
     type: "final";
     result: CompletionResult<Output, RawResponse>;
@@ -350,16 +485,21 @@ type CompletionStreamEvent<Output = string, RawResponse = unknown> = CompletionS
     error: unknown;
     usage: Usage;
 };
+/** A completion model that can additionally stream events as they are produced. */
 interface StreamingCompletionModel<RawResponse = unknown, Controls extends CompletionModelControls = CompletionModelControls> extends CompletionModel<RawResponse, Controls> {
     streamCompletion(request: CompletionRequest, options?: ModelCallOptions): AsyncIterable<CompletionModelStreamEvent<RawResponse>>;
 }
+/** Thrown when a request uses a capability the target model does not declare. */
 declare class CompletionCapabilityError extends Error {
     constructor(message: string);
 }
+/** Validates a request against a model's declared capabilities; throws {@link CompletionCapabilityError}. */
 declare function assertCompletionRequestSupported(model: CompletionModel, request: CompletionRequest, options?: {
     streaming?: boolean | undefined;
 }): void;
+/** Validates control values against a model's controls; throws {@link CompletionCapabilityError}. */
 declare function assertCompletionControlsSupported(model: CompletionModel, controls: Readonly<Record<string, string | undefined>> | undefined): void;
+/** Joins the text parts of assistant content with newlines. */
 declare function textFromAssistantContent(content: readonly AssistantContentPart[]): string;
 
 export { type CompletionStreamPart as $, type AssistantContentPart as A, type ToolDefinition as B, type CompletionControlValues as C, type Document as D, type ToolMessage as E, type FileData as F, type ToolResultContentPart as G, type ToolResultOutput as H, type ImageDetail as I, type JsonObject as J, type ToolResultPart as K, type UserContentPart as L, type Message as M, type NoCompletionModelControls as N, type UserMessage as O, type ProviderTool as P, calculateContextUsage as Q, type ReasoningContentType as R, type SystemMessage as S, type TextPart as T, Usage as U, getAssistantGenerationMetadata as V, isProviderTool as W, resolveModelContextLimits as X, withContextUsage as Y, CompletionCapabilityError as Z, type CompletionModelCapabilities as _, type AssistantGenerationMetadata as a, type StreamingCompletionModel as a0, type ToolApprovalResponsePart as a1, type ToolCallArgumentsMode as a2, type ToolInteractionResponsePart as a3, type ToolQuestionAnswer as a4, type ToolQuestionResponsePart as a5, type UsageDetails as a6, assertCompletionControlsSupported as a7, assertCompletionRequestSupported as a8, reasoningDisplayText as a9, textFromAssistantContent as aa, type AssistantMessage as b, type CompletionFinishReason as c, type CompletionModel as d, type CompletionModelControls as e, type CompletionModelControlsOf as f, type CompletionModelInfo as g, type CompletionModelSelectControl as h, type CompletionModelStreamEvent as i, type CompletionRequest as j, type CompletionResponse as k, type CompletionResult as l, type CompletionSource as m, type CompletionStreamEvent as n, type CompletionTool as o, type ContextUsage as p, type FilePart as q, type ImagePart as r, type JsonPrimitive as s, type JsonValue as t, type ModelContextLimits as u, type ProviderToolCall as v, type ReasoningDetail as w, type ReasoningPart as x, type ToolCallPart as y, type ToolChoice as z };