@voltro/ai 0.70.0 → 0.71.0

package/dist/index.d.ts

@@ -6,12 +6,14 @@ import { defaultSettingsMiddleware } from 'ai';
 import { Effect } from 'effect';
 import { EmbeddingModelV4 } from '@ai-sdk/provider';
 import { Experimental_VideoModelV4 } from '@ai-sdk/provider';
+import { Experimental_VideoModelV4File } from '@ai-sdk/provider';
 import { extractReasoningMiddleware } from 'ai';
 import { GatewayLanguageModelEntry } from '@ai-sdk/gateway';
 import { Guards } from '@voltro/protocol';
 import { ImageModelV4 } from '@ai-sdk/provider';
 import { LanguageModelMiddleware } from 'ai';
 import { LanguageModelV4 } from '@ai-sdk/provider';
+import { LanguageModelV4Source } from '@ai-sdk/provider';
 import { ModelMessage } from 'ai';
 import { QueryDescriptor } from '@voltro/database';
 import { QueryProcedureDescriptor } from '@voltro/protocol';
@@ -113,10 +115,18 @@ export declare const AgentEvent: Schema.Union<[Schema.Struct<{
     title: Schema.optional<typeof Schema.String>;
     mediaType: Schema.optional<typeof Schema.String>;
     filename: Schema.optional<typeof Schema.String>;
+    /** Provider-owned citation attribution; not normalized or interpreted. */
+    providerMetadata: Schema.optional<typeof Schema.Unknown>;
 }>, Schema.Struct<{
     _tag: Schema.Literal<["file"]>;
     mediaType: typeof Schema.String;
     data: typeof Schema.String;
+    /** Metadata for this file, not the whole model step. */
+    providerMetadata: Schema.optional<typeof Schema.Unknown>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["stepMetadata"]>;
+    step: Schema.filter<typeof Schema.Int>;
+    providerMetadata: typeof Schema.Unknown;
 }>, Schema.Struct<{
     _tag: Schema.Literal<["message"]>;
     role: typeof Schema.String;
@@ -283,13 +293,15 @@ declare const AgentThreadAccessDenied_base: Schema.TaggedErrorClass<AgentThreadA
 
 export declare const agentThreadsTable: Table<typeof AGENT_THREADS_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
 
+export declare const AI_BUDGET_RESERVATIONS_TABLE = "_voltro_ai_budget_reservations";
+
 export declare const AI_BUDGET_TABLE = "_voltro_ai_budget";
 
 export declare const AI_INFERENCES_TABLE = "_voltro_ai_inferences";
 
 export declare const AI_USAGE_TABLE = "_voltro_ai_usage";
 
-/** Thrown when an AI call would push a tenant over its USD budget. */
+/** A refused reservation, not evidence of a provider charge. */
 export declare class AiBudgetExceeded extends AiBudgetExceeded_base {
 }
 
@@ -302,21 +314,17 @@ declare const AiBudgetExceeded_base: Schema.TaggedErrorClass<AiBudgetExceeded, "
     attemptedUsd: typeof Schema.Number;
 }>;
 
-/**
- * ONE reservation-counter row per `(tenantId, window)` budget bucket. It is the
- * arbiter for the per-tenant USD cap: {@link requireAiBudget} RESERVES headroom
- * on this row ATOMICALLY (a compare-and-set loop over the UNIQUE `bucket`
- * below) BEFORE the provider call, so concurrent calls — same replica or
- * across replicas — cannot overshoot the cap. This replaces the old
- * check-then-act SUM over the ledger, which N concurrent callers could all read
- * under-cap and all pass.
- *
- * `bucket` is a stable string key derived from the tenant + the budget window
- * (see `budgetBucketKey`), so a rolling `since` window rotates to a fresh
- * counter. `.maxLength(191)` keeps the UNIQUE a plain cross-dialect BTREE.
- * The counter is a RESERVATION ledger separate from the descriptive
- * `_voltro_ai_usage` spend ledger; it too is bounded by the retention sweep.
- */
+export declare interface AiBudgetReservation {
+    readonly reservationId: string;
+    readonly tenantId: string | null;
+    readonly amountMicroUsd: string;
+    readonly status: 'reserved' | 'replayed';
+}
+
+/** Receipt and release tombstone. A receipt and its counter change commit together. */
+export declare const aiBudgetReservationsTable: Table<typeof AI_BUDGET_RESERVATIONS_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
+
+/** Exact micro-USD counter, shared by a tenant's window. */
 export declare const aiBudgetTable: Table<typeof AI_BUDGET_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
 
 /** Attributes stamped on the span + used as metric labels. Derived from the
@@ -331,6 +339,29 @@ export declare interface AiCallAttributes {
 /** Derive span/metric attributes from a resolved provider config + operation. */
 export declare const aiCallAttributes: (config: ProviderConfig, operation: string) => AiCallAttributes;
 
+export declare type AiCallEvidence = typeof AiCallEvidenceSchema.Type;
+
+/** Allowlisted consumption evidence, never a provider response or SDK error.
+ * Completeness describes the three token counters, not billing completeness. */
+export declare const AiCallEvidenceSchema: Schema.Struct<{
+    provider: typeof Schema.String;
+    model: typeof Schema.String;
+    usage: Schema.Struct<{
+        inputTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+        outputTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+        totalTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+        completeness: Schema.Literal<["complete", "partial", "unknown"]>;
+    }>;
+    cost: Schema.Union<[Schema.Struct<{
+        status: Schema.Literal<["actual"]>;
+        source: Schema.Literal<["gateway"]>;
+        usd: Schema.filter<Schema.filter<typeof Schema.Number>>;
+    }>, Schema.Struct<{
+        status: Schema.Literal<["unknown"]>;
+        source: Schema.Literal<["unreported"]>;
+    }>]>;
+}>;
+
 /** One logged AI call. `usage` is the SDK's token-usage object (present for
  *  generate; a stream logs the call at start, before usage is known). */
 export declare interface AiCallLog {
@@ -353,6 +384,24 @@ declare const AiError_base: Schema.TaggedErrorClass<AiError, "AiError", {
 } & {
     reason: Schema.Literal<["generation", "decode"]>;
     message: typeof Schema.String;
+    evidence: Schema.optional<Schema.Struct<{
+        provider: typeof Schema.String;
+        model: typeof Schema.String;
+        usage: Schema.Struct<{
+            inputTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+            outputTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+            totalTokens: Schema.optional<Schema.filter<Schema.filter<Schema.filter<typeof Schema.Number>>>>;
+            completeness: Schema.Literal<["complete", "partial", "unknown"]>;
+        }>;
+        cost: Schema.Union<[Schema.Struct<{
+            status: Schema.Literal<["actual"]>;
+            source: Schema.Literal<["gateway"]>;
+            usd: Schema.filter<Schema.filter<typeof Schema.Number>>;
+        }>, Schema.Struct<{
+            status: Schema.Literal<["unknown"]>;
+            source: Schema.Literal<["unreported"]>;
+        }>]>;
+    }>>;
 }>;
 
 /**
@@ -1052,6 +1101,13 @@ export declare interface EmbeddingProviderConfig {
     readonly model: string;
     /** Mock-only: the deterministic output-vector length. Default 8. */
     readonly mockDim?: number;
+    /** Native SDK options, e.g. `{ openai: { dimensions: 512 } }` or
+     * `{ voyage: { inputType: 'query', outputDimension: 512 } }`.
+     * Model support is provider-specific; these are passed to every SDK batch. */
+    readonly providerOptions?: AiProviderOptions;
+    /** Validate the returned vector length. This does not configure the model:
+     * request its dimension through providerOptions (or mockDim for mock). */
+    readonly expectedDimensions?: number;
 }
 
 /**
@@ -1245,8 +1301,9 @@ export declare const fromRaw: (raw: RawGatewayModel) => GatewayModelInfo;
  * Pull the ACTUAL per-call cost (USD) out of an AI-SDK result's provider
  * metadata, when the Vercel AI Gateway reported it. The gateway attaches
  * `providerMetadata.gateway.cost` (a USD number or numeric string) to
- * generate/stream results; returns `undefined` when absent (direct providers,
- * the mock) so the caller falls back to the price table.
+ * generate/stream results; returns `undefined` when absent or invalid so the
+ * caller falls back to the price table. Empty, negative and non-finite values
+ * are not evidence of a charge. An explicit zero remains authoritative.
  */
 export declare const gatewayCostUsd: (providerMetadata: unknown) => number | undefined;
 
@@ -1337,6 +1394,15 @@ export declare interface GeneratedAudio {
 export declare interface GeneratedImage {
     readonly data: Uint8Array | string;
     readonly mediaType: string;
+    /** Metadata belonging to this image, not the entire generation. */
+    readonly providerMetadata?: unknown;
+}
+
+/** Preserve provider-call boundaries: grounding for one batch is not another's. */
+export declare interface GeneratedImageCall {
+    readonly images: ReadonlyArray<GeneratedImage>;
+    readonly usage?: MediaUsage;
+    readonly providerMetadata?: unknown;
 }
 
 /** The produced video. Providers return EITHER a `url` (the common case — video
@@ -1357,6 +1423,14 @@ export declare const generateImage: (options: GenerateImageOptions) => Effect.Ef
 export declare interface GenerateImageOptions {
     /** What to draw. */
     readonly prompt: string;
+    /** Image-editing references and optional mask: URLs, data URLs, base64 or bytes. */
+    readonly inputs?: {
+        readonly images: ReadonlyArray<string | Uint8Array>;
+        readonly mask?: string | Uint8Array;
+    };
+    readonly seed?: number;
+    /** Interrupt the call and signal provider I/O. Fiber interruption does the same. */
+    readonly abortSignal?: AbortSignal;
     /** Override the provider/model for a single call (defaults to `providerFromEnv()`).
      *  `anthropic` has no image model; use `openai` or `gateway`. */
     readonly provider?: ProviderConfig;
@@ -1373,6 +1447,8 @@ export declare interface GenerateImageOptions {
 
 export declare interface GenerateImageResult {
     readonly images: ReadonlyArray<GeneratedImage>;
+    /** Original per-call metadata, including grounding. No response headers or bodies. */
+    readonly calls: ReadonlyArray<GeneratedImageCall>;
     readonly usage?: MediaUsage;
     /** Raw provider/gateway metadata — feed to `gatewayCostUsd(...)` for the
      *  gateway's real per-call cost (see {@link GenerateTextResult.providerMetadata}). */
@@ -1382,8 +1458,7 @@ export declare interface GenerateImageResult {
 export declare const generateObject: <A, I>(options: GenerateObjectOptions<A, I>) => Effect.Effect<GenerateObjectResult<A>, AiError>;
 
 /**
- * Structured output against an already-rendered JSON Schema, WITHOUT the decode
- * step.
+ * Structured output validated against its already-rendered JSON Schema.
  *
  * Extracted from `generateObject` rather than written beside it: an offloaded
  * inference is performed by a dispatcher that has the stored JSON Schema and no
@@ -1402,6 +1477,7 @@ export declare interface GenerateObjectJsonOptions {
     readonly provider?: ProviderConfig;
     readonly fallbacks?: ProviderFallbacks;
     readonly maxTokens?: number;
+    readonly temperature?: number;
     readonly providerOptions?: AiProviderOptions;
 }
 
@@ -1418,6 +1494,7 @@ export declare interface GenerateObjectOptions<A, I> {
      *  mismatch); only a `generation` failure does. */
     readonly fallbacks?: ProviderFallbacks;
     readonly maxTokens?: number;
+    readonly temperature?: number;
     /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
      *  See `AiProviderOptions`. */
     readonly providerOptions?: AiProviderOptions;
@@ -1425,6 +1502,8 @@ export declare interface GenerateObjectOptions<A, I> {
 
 export declare interface GenerateObjectResult<A> {
     readonly object: A;
+    /** Allowlisted usage/cost evidence from the provider that actually answered. */
+    readonly evidence: AiCallEvidence;
     readonly usage: {
         readonly inputTokens: number | undefined;
         readonly outputTokens: number | undefined;
@@ -1466,6 +1545,7 @@ export declare interface GenerateObjectWithToolsOptions<A, I> {
     /** Ordered provider/model fallback chain — see {@link ProviderFallbacks}. */
     readonly fallbacks?: ProviderFallbacks;
     readonly maxTokens?: number;
+    readonly temperature?: number;
     /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
      *  See `AiProviderOptions`. */
     readonly providerOptions?: AiProviderOptions;
@@ -1487,6 +1567,8 @@ export declare const generateSpeech: (options: GenerateSpeechOptions) => Effect.
 export declare interface GenerateSpeechOptions {
     /** Text to speak. */
     readonly text: string;
+    /** Interrupt native or registered providers and signal their I/O. */
+    readonly abortSignal?: AbortSignal;
     /** Override the provider/model (defaults to `providerFromEnv()`). `anthropic`
      *  has no speech model; use `openai` or `gateway`. */
     readonly provider?: ProviderConfig | RegisteredSpeechConfig;
@@ -1525,10 +1607,7 @@ export declare interface GenerateSpeechResult {
 }
 
 /**
- * Generate text from a single-turn prompt. Returns the model's response
- * plus a usage tally; provider-specific extras (tool calls, finish reason)
- * are dropped — a richer surface will follow when the framework grows
- * dedicated *.agent.tsx primitives that need them.
+ * Generate text from a prompt or conversation. Returns text, sources and usage.
  */
 export declare const generateText: (options: GenerateTextOptions) => Effect.Effect<GenerateTextResult, AiError>;
 
@@ -1542,7 +1621,9 @@ export declare interface GenerateTextOptions {
     /** Request context threaded into the tool executors. */
     readonly toolContext?: ToolContext;
     /** The user prompt. The SDK auto-wraps it as the single user message. */
-    readonly prompt: string;
+    readonly prompt?: string;
+    /** Complete conversation, including the latest user message. Supply instead of prompt. */
+    readonly messages?: ReadonlyArray<ModelMessage>;
     /** Optional system message. Steers the model independently of the prompt. */
     readonly system?: string;
     /** Override the provider/model for a single call. */
@@ -1551,6 +1632,8 @@ export declare interface GenerateTextOptions {
     readonly fallbacks?: ProviderFallbacks;
     /** Soft ceiling on output tokens. Provider-dependent. */
     readonly maxTokens?: number;
+    /** Model sampling temperature; explicit zero is preserved. Provider support varies. */
+    readonly temperature?: number;
     /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
      *  See `AiProviderOptions`. */
     readonly providerOptions?: AiProviderOptions;
@@ -1558,6 +1641,7 @@ export declare interface GenerateTextOptions {
 
 export declare interface GenerateTextResult {
     readonly text: string;
+    readonly sources: ReadonlyArray<LanguageModelV4Source>;
     readonly usage: {
         readonly inputTokens: number | undefined;
         readonly outputTokens: number | undefined;
@@ -1586,22 +1670,33 @@ export declare interface GenerateTextResult {
  */
 export declare const generateVideo: (options: GenerateVideoOptions) => Effect.Effect<GenerateVideoResult, AiError>;
 
+/** A URL shorthand or an explicitly typed file/URL for provider routing. */
+export declare type GenerateVideoInput = string | Experimental_VideoModelV4File;
+
 export declare interface GenerateVideoInputs {
     /** Reference / starting-frame image URL (image-to-video). */
-    readonly image?: string;
+    readonly image?: GenerateVideoInput;
     /** Reference image/video URLs (reference-to-video). */
-    readonly references?: ReadonlyArray<string>;
+    readonly references?: ReadonlyArray<GenerateVideoInput>;
+    readonly frameImages?: ReadonlyArray<{
+        readonly frameType: 'first_frame' | 'last_frame';
+        readonly image: GenerateVideoInput;
+    }>;
 }
 
 export declare interface GenerateVideoOptions {
     /** What to animate. */
     readonly prompt: string;
+    /** Interrupt the call and signal provider I/O. Fiber interruption does the same. */
+    readonly abortSignal?: AbortSignal;
     /** Override the provider/model (defaults to `providerFromEnv()`). Only the
      *  Vercel AI Gateway (`gateway`) ships a video model among the wired
      *  providers; `openai` / `anthropic` raise an `AiError`. */
     readonly provider?: ProviderConfig;
     readonly params?: GenerateVideoParams;
     readonly inputs?: GenerateVideoInputs;
+    /** Maximum decoded inline video bytes. Default 64 MiB; URL results are not downloaded. */
+    readonly maxInlineBytes?: number;
     /** Provider-specific options forwarded to the model. */
     readonly providerOptions?: AiProviderOptions;
 }
@@ -1612,6 +1707,7 @@ export declare interface GenerateVideoParams {
     readonly resolution?: `${number}x${number}`;
     readonly fps?: number;
     readonly seed?: number;
+    readonly generateAudio?: boolean;
 }
 
 export declare interface GenerateVideoResult {
@@ -2017,6 +2113,10 @@ export declare interface McpToolInfo {
     readonly name: string;
     readonly description: string;
     readonly inputSchema: Record<string, unknown>;
+    /** Advertised execution contract. This client does not negotiate MCP tasks. */
+    readonly execution?: {
+        readonly taskSupport: 'forbidden' | 'optional' | 'required';
+    };
     /**
      * The server's own hints about the tool. ADVISORY ONLY — see
      * `mcpTools.ts`; the server is the untrusted party, so its claim that a tool
@@ -2128,11 +2228,6 @@ export declare interface MediaUsage {
  */
 export declare const memoryResumableStreamStore: () => ResumableStreamStore;
 
-/**
- * One structured part of an assistant message. Either streamed assistant text
- * or a record of a tool call + its result. Stored in `agent_messages.parts`
- * and rendered by the frontend (`toUIMessages`).
- */
 export declare type MessagePart = {
     readonly type: 'text';
     readonly text: string;
@@ -2155,22 +2250,12 @@ export declare type MessagePart = {
 /** A cited source (RAG / web-search grounding). `url` variant carries `url`;
 *  `document` variant carries `mediaType`/`filename`. Rendered as a citation
 *  chip / footnote. */
-| {
-    readonly type: 'source';
-    readonly sourceType: 'url' | 'document';
-    readonly id: string;
-    readonly url?: string;
-    readonly title?: string;
-    readonly mediaType?: string;
-    readonly filename?: string;
-}
+| StoredEventPart<'source'>
 /** An inline file the model produced (usually an image): IANA `mediaType` +
 *  base64 `data`. A UI renders `image/*` inline. */
-| {
-    readonly type: 'file';
-    readonly mediaType: string;
-    readonly data: string;
-};
+| StoredEventPart<'file'>
+/** Provider-owned attribution for each model step, not answer text. */
+| StoredEventPart<'stepMetadata'>;
 
 /**
  * A tally in a unit that is not tokens.
@@ -2799,6 +2884,13 @@ export declare interface RegisterSpeechProviderOptions {
  */
 export declare const registerStream: (streamId: string) => AbortController;
 
+/** Release the STORED amount once. Supply the owning tenant, never an amount.
+ * A missing/expired receipt cannot be reconstructed and returns not-found. */
+export declare const releaseAiBudget: (store: DataStore, opts: {
+    readonly reservationId: string;
+    readonly tenantId: string | null;
+}) => Effect.Effect<"released" | "already-released" | "not-found">;
+
 export declare const releasedAtOf: (raw: RawGatewayModel) => string | undefined;
 
 /** What `.render(vars)` produces — a stamp plus the text to send. */
@@ -2816,36 +2908,17 @@ export declare interface RenderedPrompt extends PromptStamp {
 /** Whether `name` is a registration standing in front of a built-in. */
 export declare const replacesBuiltinSpeechProvider: (name: string) => boolean;
 
-/**
- * Gate an AI call against a per-tenant USD budget with an ATOMIC reservation —
- * the cap precedent is billing's `requireEntitlement` / storage's
- * `consumeUsage`. Fails with `AiBudgetExceeded` (typed, client-marshalable)
- * when `reserved + addUsd` would exceed `limitUsd`. Call it BEFORE the provider
- * call, estimating `addUsd` from the prompt; record the actual cost with
- * `recordAiUsage` after (for the spend dashboard).
- *
- * Cross-replica-safe WITHOUT a `SELECT … FOR UPDATE` (the DataStore contract
- * exposes no row lock): a bounded compare-and-set loop over the single
- * `_voltro_ai_budget` counter row for the bucket. Read the counter, decide,
- * then EITHER conditionally `updateMany` the row only if the reservation we
- * read still holds (`affected === 1` ⇒ we won) OR `insertIgnore` the first row
- * (ON CONFLICT over the UNIQUE `bucket`). A lost CAS / ignored insert means a
- * concurrent reservation moved the counter → retry. So N concurrent calls
- * reserve exactly the budgeted amount — no overshoot — where the old
- * check-then-act SUM admitted all of them.
- *
- * NB the reservation is optimistic: it does NOT auto-release if the provider
- * call later fails (like billing's consume). For a rolling budget that's the
- * correct conservative bound; a rare failed-call over-reservation ages out with
- * the window. Pass `addUsd: 0` to check-only (no reservation) — useful for a UI
- * pre-flight where you don't want to consume headroom.
- */
+/** Reserve before provider I/O. Reuse reservationId only for the same logical
+ * spend, tenant, amount and window. Zero is check-only and returns null.
+ * Call outside another transaction; the receipt and counter need one commit.
+ * A provider failure does not automatically release possibly billed spend. */
 export declare const requireAiBudget: (store: DataStore, opts: {
     readonly tenantId?: string | null;
     readonly limitUsd: number;
     readonly addUsd?: number;
     readonly since?: Date;
-}) => Effect.Effect<void, AiBudgetExceeded>;
+    readonly reservationId?: string;
+}) => Effect.Effect<AiBudgetReservation | null, AiBudgetExceeded>;
 
 /**
  * Rerank `documents` by relevance to `query`, highest score first. Returns
@@ -3302,10 +3375,18 @@ export declare const SeqEvent: Schema.Struct<{
         title: Schema.optional<typeof Schema.String>;
         mediaType: Schema.optional<typeof Schema.String>;
         filename: Schema.optional<typeof Schema.String>;
+        /** Provider-owned citation attribution; not normalized or interpreted. */
+        providerMetadata: Schema.optional<typeof Schema.Unknown>;
     }>, Schema.Struct<{
         _tag: Schema.Literal<["file"]>;
         mediaType: typeof Schema.String;
         data: typeof Schema.String;
+        /** Metadata for this file, not the whole model step. */
+        providerMetadata: Schema.optional<typeof Schema.Unknown>;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["stepMetadata"]>;
+        step: Schema.filter<typeof Schema.Int>;
+        providerMetadata: typeof Schema.Unknown;
     }>, Schema.Struct<{
         _tag: Schema.Literal<["message"]>;
         role: typeof Schema.String;
@@ -3365,6 +3446,8 @@ export declare const speechProvider: (name: string) => SpeechProvider | undefine
  *  minus the parts the framework resolves. */
 export declare interface SpeechSynthesisRequest {
     readonly text: string;
+    /** Aborted on external cancellation or Effect interruption; pass to provider I/O. */
+    readonly abortSignal?: AbortSignal;
     readonly model?: string;
     readonly voice?: string;
     readonly outputFormat?: string;
@@ -3376,9 +3459,10 @@ export declare interface SpeechSynthesisRequest {
 
 /**
  * Run the underlying stream ONCE and persist every event. Assigns a monotonic
- * `seq`, appends each event, and marks the stream done at the end — even if a
- * store append throws, so consumers never tail forever. Intended to run
- * detached (see `resumableStream`, which forks it as a daemon).
+ * `seq` and persists a terminal event BEFORE marking done. Defects, a throwing
+ * source factory, missing terminals and producer interruption become sanitized
+ * error events. If persistence itself fails, the Effect fails; it must not
+ * advertise a completed log. A process kill cannot run this finalization.
  */
 export declare const startResumableProducer: (streamId: string, store: ResumableStreamStore, source: () => Stream.Stream<AgentEvent>) => Effect.Effect<void>;
 
@@ -3407,6 +3491,17 @@ export declare interface StdioMcpTransportOptions {
     readonly bounds?: Partial<McpBounds>;
 }
 
+/**
+ * One structured part of an assistant message. Either streamed assistant text
+ * or a record of a tool call + its result. Stored in `agent_messages.parts`
+ * and rendered by the frontend (`toUIMessages`).
+ */
+declare type StoredEventPart<Tag extends AgentEvent['_tag']> = Omit<Extract<AgentEvent, {
+    _tag: Tag;
+}>, '_tag'> & {
+    readonly type: Tag;
+};
+
 export declare const STREAM_EVENTS_TABLE = "_voltro_stream_events";
 
 export declare const STREAM_STATE_TABLE = "_voltro_stream_state";
@@ -3461,6 +3556,7 @@ export declare interface StreamTextOptions {
      *  only the primary provider. */
     readonly fallbacks?: ReadonlyArray<ProviderConfig>;
     readonly maxTokens?: number;
+    readonly temperature?: number;
     /** Tools the model may call. The SDK dispatches them + loops. */
     readonly tools?: Record<string, AnyTool>;
     /** Max LLM↔tool round-trips before the loop stops. Default 8. */
@@ -3587,6 +3683,10 @@ export declare interface ToolContext {
         readonly subject?: unknown;
     };
     readonly runtime?: Runtime.Runtime<unknown>;
+    /** SDK tool-call identity for this execution, not a durable application idempotency key. */
+    readonly invocationId?: string;
+    /** The SDK's cancellation signal; Promise handlers must pass it to their I/O. */
+    readonly abortSignal?: AbortSignal;
 }
 
 export declare interface ToolDef<A, I, O> {