@voltro/ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1996 @@
+import { ActionProcedureDescriptor } from '@voltro/protocol';
+import { ColumnDefinition } from '@voltro/database';
+import { Context } from 'effect';
+import { DataStore } from '@voltro/database';
+import { defaultSettingsMiddleware } from 'ai';
+import { Effect } from 'effect';
+import { EmbeddingModelV4 } from '@ai-sdk/provider';
+import { Experimental_VideoModelV4 } from '@ai-sdk/provider';
+import { extractReasoningMiddleware } from 'ai';
+import { GatewayLanguageModelEntry } from '@ai-sdk/gateway';
+import { ImageModelV4 } from '@ai-sdk/provider';
+import { LanguageModelMiddleware } from 'ai';
+import { LanguageModelV4 } from '@ai-sdk/provider';
+import { ModelMessage } from 'ai';
+import { QueryDescriptor } from '@voltro/database';
+import { QueryProcedureDescriptor } from '@voltro/protocol';
+import { Runtime } from 'effect';
+import { Schema } from 'effect';
+import { simulateStreamingMiddleware } from 'ai';
+import { SpeechModelV4 } from '@ai-sdk/provider';
+import { Stream } from 'effect';
+import { Table } from '@voltro/database';
+import { ToolSet } from 'ai';
+
+/** Count of in-flight streams (diagnostics / leak detection). */
+export declare const activeStreamCount: () => number;
+
+declare const AGENT_DESCRIPTOR_BRAND: "@voltro/ai/AgentDescriptor";
+
+declare const AGENT_DESCRIPTOR_SYMBOL: unique symbol;
+
+/** Per-turn message table — the `source` of the reactive `<name>.messages`
+ *  query, and what `runAssistant` delta-patches as it streams. */
+export declare const AGENT_MESSAGES_TABLE = "agent_messages";
+
+/** Thread metadata table (one row per conversation). */
+export declare const AGENT_THREADS_TABLE = "agent_threads";
+
+/** Stamp an agent-initiated call's actor with `via: 'agent'` so audit + trace
+ *  + provenance (08) can distinguish "user X" from "user X via agent". The
+ *  actor id stays the calling subject's — the agent never escalates identity. */
+export declare const agentActor: (subjectId: string | null) => {
+    readonly id: string | null;
+    readonly via: "agent";
+};
+
+export declare interface AgentDescriptor<S extends Schema.Schema.Any = DefaultAgentInputSchema> {
+    readonly [AGENT_DESCRIPTOR_SYMBOL]: true;
+    readonly _brand: typeof AGENT_DESCRIPTOR_BRAND;
+    /** Wire id → rpc tags `<name>.send` / `<name>.messages`. */
+    readonly name: string;
+    /** Input schema (default `{ prompt: string }`). The send route's wire input
+     *  extends this with `{ threadId, order }`. */
+    readonly input?: S;
+}
+
+/** Error taxonomy. `retryable` on the event drives client/agent retry. */
+export declare const AgentErrorCode: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+
+export declare type AgentErrorCode = typeof AgentErrorCode.Type;
+
+export declare const AgentEvent: Schema.Union<[Schema.Struct<{
+    _tag: Schema.Literal<["token"]>;
+    text: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["reasoning"]>;
+    text: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["toolCall"]>;
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    input: typeof Schema.Unknown;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["toolResult"]>;
+    id: typeof Schema.String;
+    name: typeof Schema.String;
+    output: Schema.optional<typeof Schema.Unknown>;
+    error: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["source"]>;
+    sourceType: Schema.Literal<["url", "document"]>;
+    id: typeof Schema.String;
+    url: Schema.optional<typeof Schema.String>;
+    title: Schema.optional<typeof Schema.String>;
+    mediaType: Schema.optional<typeof Schema.String>;
+    filename: Schema.optional<typeof Schema.String>;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["file"]>;
+    mediaType: typeof Schema.String;
+    data: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["message"]>;
+    role: typeof Schema.String;
+    content: typeof Schema.String;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["error"]>;
+    code: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+    message: typeof Schema.String;
+    retryable: typeof Schema.Boolean;
+}>, Schema.Struct<{
+    _tag: Schema.Literal<["done"]>;
+    finishReason: typeof Schema.String;
+    usage: Schema.Struct<{
+        inputTokens: Schema.optional<typeof Schema.Number>;
+        outputTokens: Schema.optional<typeof Schema.Number>;
+        totalTokens: Schema.optional<typeof Schema.Number>;
+    }>;
+}>]>;
+
+export declare type AgentEvent = typeof AgentEvent.Type;
+
+export declare interface AgentExecutor<S extends Schema.Schema.Any = DefaultAgentInputSchema> {
+    readonly [EXECUTOR_SYMBOL]: true;
+    readonly _brand: typeof EXECUTOR_BRAND;
+    readonly descriptor: AgentDescriptor<S>;
+    readonly config: AgentExecutorConfig<AgentInput<S>>;
+}
+
+export declare interface AgentExecutorConfig<Input = {
+    readonly prompt: string;
+}> {
+    /** Static prompt, or a function of the decoded input. */
+    readonly system?: SystemPrompt<Input>;
+    /** Tools the model may call. Same shape `runAssistant` takes. */
+    readonly tools?: Record<string, AnyTool>;
+    /** Per-agent provider override, INCLUDING its own key:
+     *  `{ name, model, apiKey? }`. Each field falls back to env when omitted —
+     *  `AI_PROVIDER` / `AI_MODEL` and the provider's standard key var
+     *  (`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `AI_GATEWAY_API_KEY`). The key
+     *  stays server-side (this file never reaches the browser).
+     *
+     *  May ALSO be a function of the decoded input — for a UI model picker,
+     *  cost/size routing, plan-tier models, etc. (mirrors `system`). Return
+     *  `undefined` to fall back to env for that call. Runs server-side.
+     *
+     *  SECURITY: the input is client-controlled. NEVER feed it straight into the
+     *  config (`(i) => ({ model: i.model })`) — a caller could pick an
+     *  expensive/arbitrary model. Constrain the picker with a `Schema.Literal`
+     *  in the descriptor input + map to server-owned configs; read keys from
+     *  `process.env`, never from the input:
+     *  ```ts
+     *  // descriptor: input: Schema.Struct({ prompt: Schema.String, tier: Schema.Literal('fast','smart') })
+     *  model: (input) => input.tier === 'smart'
+     *    ? { name: 'openai', model: 'gpt-5.5' }
+     *    : { name: 'openai', model: 'gpt-4o-mini' },
+     *  ``` */
+    readonly model?: ProviderConfig | ((input: Input) => ProviderConfig | undefined);
+    /** Max LLM↔tool round-trips before the loop stops. */
+    readonly maxSteps?: number;
+    /** Provider-specific options forwarded to the SDK — most importantly REASONING
+     *  EFFORT. A routing/help agent on a reasoning model (`gpt-5.x`) should pin it
+     *  low so a one-line answer doesn't cost the default high-effort 10s+:
+     *    providerOptions: { openai: { reasoningEffort: 'low' } }
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+/** The decoded input an agent's executor sees, derived from its schema. */
+export declare type AgentInput<S extends Schema.Schema.Any> = Schema.Schema.Type<S>;
+
+/** The agent's input schema (default `{ prompt: string }`). */
+export declare const agentInputSchema: (desc: AnyAgentDescriptor) => Schema.Schema.Any;
+
+export declare interface AgentMessage {
+    readonly id: string;
+    readonly threadId: string;
+    readonly tenantId: string | null;
+    readonly role: AgentMessageRole;
+    readonly content: string;
+    readonly streaming: boolean;
+    readonly order: number;
+    readonly stepOrder: number;
+    readonly parts: ReadonlyArray<MessagePart>;
+    readonly createdAt: Date;
+}
+
+export declare type AgentMessageRole = 'user' | 'assistant' | 'system' | 'tool';
+
+export declare const agentMessageSchema: Schema.Struct<{
+    id: typeof Schema.String;
+    threadId: typeof Schema.String;
+    role: typeof Schema.String;
+    content: typeof Schema.String;
+    streaming: typeof Schema.Boolean;
+    order: typeof Schema.Number;
+    stepOrder: typeof Schema.Number;
+    parts: Schema.Array$<Schema.TypeLiteral<{
+        type: typeof Schema.String;
+    }, readonly [{
+        readonly key: typeof Schema.String;
+        readonly value: typeof Schema.Unknown;
+    }]>>;
+}>;
+
+export declare const agentMessagesTable: Table<typeof AGENT_MESSAGES_TABLE, Record<string, ColumnDefinition<unknown>>, false>;
+
+/**
+ * The two browser-safe route descriptors synthesized for an agent. The SAME
+ * source the runtime synthesis (`agentSynthesis.ts`) and codegen both consume,
+ * so "what the server serves" and "what the client is typed for" can't drift.
+ */
+export declare const agentRouteDescriptors: (desc: AnyAgentDescriptor) => {
+    send: ActionProcedureDescriptor<`${string}.send`, Schema.Schema.Any, Schema.Struct<{
+        text: typeof Schema.String;
+    }>, typeof Schema.Never>;
+    messages: QueryProcedureDescriptor<`${string}.messages`, Schema.Struct<{
+        threadId: typeof Schema.String;
+    }>, Schema.Array$<Schema.Struct<{
+        id: typeof Schema.String;
+        threadId: typeof Schema.String;
+        role: typeof Schema.String;
+        content: typeof Schema.String;
+        streaming: typeof Schema.Boolean;
+        order: typeof Schema.Number;
+        stepOrder: typeof Schema.Number;
+        parts: Schema.Array$<Schema.TypeLiteral<{
+            type: typeof Schema.String;
+        }, readonly [{
+            readonly key: typeof Schema.String;
+            readonly value: typeof Schema.Unknown;
+        }]>>;
+    }>>, typeof Schema.Never>;
+};
+
+export declare interface AgentThread {
+    readonly id: string;
+    readonly tenantId: string | null;
+    readonly title: string | null;
+    readonly createdAt: Date;
+    readonly updatedAt: Date;
+}
+
+export declare const agentThreadsTable: Table<typeof AGENT_THREADS_TABLE, Record<string, ColumnDefinition<unknown>>, false>;
+
+export declare const AI_BUDGET_TABLE = "_voltro_ai_budget";
+
+export declare const AI_USAGE_TABLE = "_voltro_ai_usage";
+
+/** Thrown when an AI call would push a tenant over its USD budget. */
+export declare class AiBudgetExceeded extends AiBudgetExceeded_base {
+}
+
+declare const AiBudgetExceeded_base: Schema.TaggedErrorClass<AiBudgetExceeded, "AiBudgetExceeded", {
+    readonly _tag: Schema.tag<"AiBudgetExceeded">;
+} & {
+    tenantId: Schema.NullOr<typeof Schema.String>;
+    limitUsd: typeof Schema.Number;
+    spentUsd: typeof Schema.Number;
+    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 const aiBudgetTable: Table<typeof AI_BUDGET_TABLE, Record<string, ColumnDefinition<unknown>>, false>;
+
+/** Attributes stamped on the span + used as metric labels. Derived from the
+ *  resolved provider config; carries NO prompt/response content or secrets. */
+export declare interface AiCallAttributes {
+    readonly provider: string;
+    readonly model: string;
+    /** 'generateText' | 'generateObject' | 'generateObjectWithTools' | 'streamText' | custom. */
+    readonly operation: string;
+}
+
+/** Derive span/metric attributes from a resolved provider config + operation. */
+export declare const aiCallAttributes: (config: ProviderConfig, operation: string) => AiCallAttributes;
+
+/** 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 {
+    readonly phase: 'generate' | 'stream';
+    readonly model: string;
+    readonly usage?: unknown;
+}
+
+/**
+ * Typed AI failure. `reason: 'generation'` — the provider call failed
+ * (network / API / quota). `reason: 'decode'` — the model returned output
+ * that didn't satisfy the requested schema. Handlers can
+ * `Effect.catchTag('AiError', …)` and, for 'generation', retry.
+ */
+export declare class AiError extends AiError_base {
+}
+
+declare const AiError_base: Schema.TaggedErrorClass<AiError, "AiError", {
+    readonly _tag: Schema.tag<"AiError">;
+} & {
+    reason: Schema.Literal<["generation", "decode"]>;
+    message: typeof Schema.String;
+}>;
+
+/** Provider-specific knobs forwarded verbatim to the Vercel AI SDK's
+ *  `providerOptions` on generateText / streamText / generateObject. The outer
+ *  key is the provider id, the inner record its options. The headline use is
+ *  REASONING EFFORT on reasoning models — `gpt-5.x` defaults to a high effort
+ *  that costs many seconds per call even for a one-line answer, so a routing/
+ *  help agent should pin it low:
+ *
+ *    providerOptions: { openai: { reasoningEffort: 'low' } }   // or 'minimal'
+ *    providerOptions: { anthropic: { thinking: { type: 'disabled' } } }
+ *
+ *  Shape matches the SDK's `ProviderOptions` (Record<provider, Record<key,
+ *  JSONValue>>). The value is the standard JSON value (mutable object + array,
+ *  so it stays assignable to the SDK's `SharedV2ProviderOptions` under
+ *  `exactOptionalPropertyTypes`) — NOT `unknown`, which the SDK rejects. */
+declare type AiJsonValue = null | boolean | number | string | {
+    [key: string]: AiJsonValue;
+} | AiJsonValue[];
+
+/** A language-model middleware (the AI SDK's `LanguageModelMiddleware`): may
+ *  implement any of `transformParams` / `wrapGenerate` / `wrapStream`. */
+export declare type AiMiddleware = LanguageModelMiddleware;
+
+export declare type AiProviderOptions = Record<string, Record<string, AiJsonValue>>;
+
+export declare class AiService extends AiService_base {
+}
+
+declare const AiService_base: Context.TagClass<AiService, "@voltro/AiService", AiServiceImpl>;
+
+export declare interface AiServiceImpl {
+    readonly generateText: (options: GenerateTextOptions) => Effect.Effect<GenerateTextResult, AiError>;
+    readonly generateObject: <A, I>(options: GenerateObjectOptions<A, I>) => Effect.Effect<GenerateObjectResult<A>, AiError>;
+}
+
+/**
+ * Sum recorded spend (USD) — optionally scoped to a tenant and/or a
+ * `since` window. Reads the ledger table; pair with a reactive query
+ * (`source: '_voltro_ai_usage'`) for a live spend meter.
+ */
+export declare const aiSpendUsd: (store: DataStore, opts?: {
+    readonly tenantId?: string | null;
+    readonly since?: Date;
+}) => Effect.Effect<number>;
+
+/** Token tally as returned by `generateText` / `generateObject` / `streamText`. */
+export declare interface AiUsage {
+    readonly inputTokens: number | undefined;
+    readonly outputTokens: number | undefined;
+    readonly totalTokens?: number | undefined;
+}
+
+export declare interface AiUsageRecordInput {
+    readonly tenantId?: string | null;
+    readonly provider: ProviderName | string;
+    readonly model: string;
+    readonly operation: string;
+    readonly agent?: string | null;
+    readonly usage: AiUsage;
+    /** Override the price table (negotiated/volume pricing or unknown model). */
+    readonly price?: ModelPrice;
+    /** The ACTUAL per-call cost reported by the provider/gateway (USD). When set,
+     *  it's persisted verbatim (costSource='gateway') — the fix for gateway-routed
+     *  models the static table prices at zero. Extract it from the AI-SDK result's
+     *  `providerMetadata.gateway.cost` (see `gatewayCostUsd`). */
+    readonly actualCostUsd?: number;
+    /** Override the timestamp (tests; default `new Date()`). */
+    readonly calledAt?: Date;
+}
+
+/**
+ * One row per priced AI call. Registered into the auto-migrate set
+ * alongside the agent tables when an app ships any `*.agent.tsx`; a
+ * non-agent app that wants plain-call cost tracking imports
+ * `aiUsageTable` into its `database/index.ts` barrel. `.reactive()` so
+ * a live spend meter can subscribe to it.
+ */
+export declare const aiUsageTable: Table<typeof AI_USAGE_TABLE, Record<string, ColumnDefinition<unknown>>, true>;
+
+export declare type AnthropicModel = 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-haiku-4-5-20251001' | (string & {});
+
+/** A descriptor of any input shape — for the type-erased runtime helpers. */
+export declare type AnyAgentDescriptor = AgentDescriptor<Schema.Schema.Any>;
+
+/** An executor of any input shape — for the type-erased runtime helpers. */
+export declare type AnyAgentExecutor = AgentExecutor<Schema.Schema.Any>;
+
+/** A heterogeneous tool — the shape `buildSdkTools` / `runAssistant` consume.
+ *  `defineTool` keeps full input typing on its `execute`/`handler` body, then
+ *  erases to this shape so a `Record<string, AnyTool>` accepts tools of
+ *  differing input/output types (Effect's `Schema` encoded type is invariant,
+ *  so a heterogeneous collection can't preserve per-tool generics). */
+export declare interface AnyTool {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema.Schema.Any;
+    readonly output?: Schema.Schema.Any;
+    readonly execute?: (input: never) => Effect.Effect<unknown, never, unknown>;
+    readonly handler?: ToolHandler<never, unknown>;
+    readonly timeoutMs?: number;
+}
+
+/** Append a message + bump the thread's `updatedAt` (best-effort). */
+export declare const appendMessage: (store: DataStore, input: {
+    readonly threadId: string;
+    readonly role: AgentMessageRole;
+    readonly content: string;
+    readonly tenantId?: string | null;
+    readonly order?: number;
+    readonly stepOrder?: number;
+    readonly parts?: ReadonlyArray<MessagePart>;
+    readonly streaming?: boolean;
+}) => Effect.Effect<AgentMessage>;
+
+/**
+ * Insert the assistant row that the run will stream into. Starts empty +
+ * `streaming:true` so the reactive feed renders it as the live bubble. Returns
+ * the new row id (the store generates it).
+ */
+export declare const appendStreamingMessage: (store: DataStore, input: {
+    readonly threadId: string;
+    readonly tenantId?: string | null;
+    readonly order: number;
+}) => Effect.Effect<string>;
+
+/**
+ * Wrap `model` with the global stack plus any per-call `middleware`, in that
+ * order (global first). Returns `model` untouched when there's nothing to
+ * apply — no wrapper, no behavior change. Used by `resolveModel`.
+ */
+export declare const applyMiddleware: (model: LanguageModelV4, middleware?: AiMiddleware | ReadonlyArray<AiMiddleware>) => LanguageModelV4;
+
+/** The descriptor fields tool synthesis reads. */
+export declare interface AppToolDescriptor {
+    readonly kind: 'query' | 'mutation' | 'action' | string;
+    readonly name: string;
+    readonly input: Schema.Schema.Any;
+    readonly output?: Schema.Schema.Any;
+    readonly exposeAsTool?: ExposeAsToolLike;
+}
+
+/** A descriptor paired with its ctx-bound executor (the real handler). */
+export declare interface AppToolEntry {
+    readonly descriptor: AppToolDescriptor;
+    readonly invoke: (input: unknown) => Promise<unknown> | unknown;
+}
+
+export declare interface AppToolPolicy {
+    /** Allowlist — tags (with `*` glob) or a RegExp. Omitted = all exposed. */
+    readonly allow?: ReadonlyArray<string> | RegExp;
+    /** Denylist — wins over allow. For destructive/high-blast tags. */
+    readonly deny?: ReadonlyArray<string> | RegExp;
+    /** Default confirm posture for writes when the descriptor doesn't say.
+     *  Default true (writes confirm). */
+    readonly requireConfirmForWrites?: boolean;
+    /** Include WRITE tools (mutation/action) in the executable toolset.
+     *  Default false — writes are opt-in + confirm (the safety default). Reads
+     *  are always included. */
+    readonly includeWrites?: boolean;
+}
+
+/**
+ * The EXECUTABLE toolset for the agent loop. Read tools are always included;
+ * WRITE tools only when `policy.includeWrites` is true (writes are opt-in —
+ * the safety default). Each tool's handler runs the descriptor's bound
+ * `invoke` (the real handler under the caller's subject). Confirm is enforced
+ * by the agent loop / UI using `synthesizeToolSpecs` — the pure executable
+ * tool can't gate a human prompt.
+ */
+export declare const appTools: (entries: ReadonlyArray<AppToolEntry>, policy?: AppToolPolicy) => ReadonlyArray<AnyTool>;
+
+/** Render the capability map into a system prompt that enumerates EXACTLY the
+ *  tables + columns the model may use — the soft in-grammar steer that pairs
+ *  with the hard validator. */
+export declare const buildCopilotSystemPrompt: (schema: CopilotSchema) => string;
+
+/** Adapt our tools to the AI SDK's ToolSet (keyed by tool name). When a
+ *  `ctx` is supplied it is threaded into `*.tool.tsx` executor bodies; inline
+ *  `execute` tools ignore it. */
+export declare const buildSdkTools: (tools: Record<string, AnyTool>, ctx?: ToolContext) => ToolSet;
+
+/**
+ * Cancel an in-flight stream by id. Aborts its controller (the SDK call stops +
+ * the stream emits a terminal `cancelled` error). Returns `true` if a live
+ * stream was found and aborted, `false` if the id is unknown (already finished
+ * or never started) — so a double-click "Stop" is a harmless no-op.
+ */
+export declare const cancelStream: (streamId: string) => boolean;
+
+/** Clear the global middleware stack. */
+export declare const clearAiMiddleware: () => void;
+
+export declare interface ConsumeOptions {
+    /** Replay events with `seq` strictly greater than this (default 0 = from the
+     *  start). A reconnecting client passes the last `seq` it rendered. */
+    readonly fromSeq?: number;
+    /** Tail poll interval in ms while the producer is still running (default 50). */
+    readonly pollMs?: number;
+    /** End the consumer if no new event arrives for this long AND the producer
+     *  hasn't finished — a safety valve against a crashed producer that never
+     *  marked done. Default: undefined (wait indefinitely). */
+    readonly idleTimeoutMs?: number;
+}
+
+/**
+ * Consume a resumable stream: replay persisted events past `fromSeq`, then tail
+ * live ones until the producer marks it done. This is what a streaming rpc
+ * returns to each client — a fresh subscription (or a reconnect) just calls it
+ * again with the right `fromSeq`.
+ */
+export declare const consumeResumableStream: (streamId: string, store: ResumableStreamStore, opts?: ConsumeOptions) => Stream.Stream<SeqEvent>;
+
+/** Hard cap on rows — a copilot query never returns an unbounded set. */
+export declare const COPILOT_MAX_LIMIT = 200;
+
+export declare interface CopilotFilter {
+    readonly column: string;
+    readonly op: CopilotOp;
+    readonly value: unknown;
+}
+
+export declare type CopilotOp = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'in';
+
+/** The model's proposed query — a constrained shape, never free SQL. */
+export declare interface CopilotProposal {
+    readonly table: string;
+    /** Projection; omit/empty = all columns. */
+    readonly columns?: ReadonlyArray<string>;
+    readonly filters?: ReadonlyArray<CopilotFilter>;
+    readonly orderBy?: {
+        readonly column: string;
+        readonly direction?: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+    /** Optional aggregate (validated; the descriptor build for aggregates is a
+     *  refinement — see `aggregate` on the result). */
+    readonly aggregate?: {
+        readonly fn: 'count' | 'sum' | 'avg' | 'min' | 'max';
+        readonly column?: string;
+    };
+}
+
+/** The effect/Schema the model's structured output is constrained to (pass as
+ *  `generateObject({ schema: CopilotProposalSchema })`). Mirrors
+ *  {@link CopilotProposal}. */
+export declare const CopilotProposalSchema: Schema.Struct<{
+    table: typeof Schema.String;
+    columns: Schema.optional<Schema.Array$<typeof Schema.String>>;
+    filters: Schema.optional<Schema.Array$<Schema.Struct<{
+        column: typeof Schema.String;
+        op: Schema.Literal<["eq", "neq", "gt", "gte", "lt", "lte", "contains", "in"]>;
+        value: typeof Schema.Unknown;
+    }>>>;
+    orderBy: Schema.optional<Schema.Struct<{
+        column: typeof Schema.String;
+        direction: Schema.optional<Schema.Literal<["asc", "desc"]>>;
+    }>>;
+    limit: Schema.optional<typeof Schema.Number>;
+    aggregate: Schema.optional<Schema.Struct<{
+        fn: Schema.Literal<["count", "sum", "avg", "min", "max"]>;
+        column: Schema.optional<typeof Schema.String>;
+    }>>;
+}>;
+
+/** Why a proposal was refused. Typed so a copilot tool/action can surface it on
+ *  its `error:` channel and the client can show "I can't answer that". */
+export declare class CopilotRejected extends CopilotRejected_base {
+}
+
+declare const CopilotRejected_base: Schema.TaggedErrorClass<CopilotRejected, "CopilotRejected", {
+    readonly _tag: Schema.tag<"CopilotRejected">;
+} & {
+    reason: Schema.Literal<["unknown-table", "unknown-column", "bad-op", "bad-aggregate", "empty"]>;
+    detail: typeof Schema.String;
+}>;
+
+export declare interface CopilotSchema {
+    readonly tables: ReadonlyArray<CopilotSchemaTable>;
+}
+
+/** The manifest slice the validator needs (mirrors the capability map's
+ *  `tables`). Decoupled — pass the live manifest's tables. */
+export declare interface CopilotSchemaColumn {
+    readonly name: string;
+    readonly type?: string;
+}
+
+export declare interface CopilotSchemaTable {
+    readonly name: string;
+    readonly columns: ReadonlyArray<CopilotSchemaColumn>;
+}
+
+export declare type CopilotValidation = {
+    readonly ok: true;
+    readonly descriptor: QueryDescriptor;
+    readonly table: string;
+    readonly aggregate?: CopilotProposal['aggregate'];
+} | {
+    readonly ok: false;
+    readonly rejection: CopilotRejected;
+};
+
+/** Cosine similarity between two vectors (re-export of the AI SDK helper).
+ *  Useful for app-side reranking / thresholding without a DB round-trip. */
+export declare const cosineSimilarity: (a: ReadonlyArray<number>, b: ReadonlyArray<number>) => number;
+
+export declare interface CostBreakdown {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly inputCostUsd: number;
+    readonly outputCostUsd: number;
+    readonly totalCostUsd: number;
+    /** Where `totalCostUsd` came from: `gateway` = the provider/gateway reported
+     *  the ACTUAL per-call cost (authoritative); `estimated` = derived from the
+     *  static price table (or zero for an unknown model). Analytics can flag
+     *  estimated rows + a model that priced at zero. */
+    readonly costSource: 'gateway' | 'estimated';
+}
+
+/** Open a new thread (the store generates the id). */
+export declare const createThread: (store: DataStore, input?: {
+    readonly tenantId?: string | null;
+    readonly title?: string | null;
+}) => Effect.Effect<AgentThread>;
+
+export declare interface DataCopilotDeps {
+    /** Turn the NL question (+ the grammar system prompt) into a structured
+     *  proposal. Wire to `@voltro/ai`'s `generateObject` with
+     *  `CopilotProposalSchema`; injected so the orchestrator is unit-testable
+     *  without a live model. */
+    readonly propose: (args: {
+        readonly system: string;
+        readonly prompt: string;
+    }) => Promise<CopilotProposal>;
+}
+
+/**
+ * Durable, multi-node resumable-stream store backed by the framework's own
+ * `DataStore` — works on every dialect the framework supports. The producer
+ * election uses `insertIgnore` (INSERT … ON CONFLICT DO NOTHING) on the UNIQUE
+ * `streamId`, comparing the returned row's id to ours: we inserted ⇒ we won.
+ * That is the same at-most-once arbiter `_voltro_idempotency` uses.
+ *
+ * The two tables (`streamEventsTable`, `streamStateTable`) register into the
+ * app's migration set like the agent/usage tables — add them to the database
+ * barrel (or they ride along with a `*.agent.tsx` app). Run `gcResumableStreams`
+ * periodically to drop finished streams past a retention window.
+ */
+export declare const dataStoreResumableStreamStore: (store: DataStore) => ResumableStreamStore;
+
+declare const DEFAULT_INPUT: Schema.Struct<{
+    prompt: typeof Schema.String;
+}>;
+
+/** Default input schema type when `input` is omitted (`{ prompt: string }`). */
+export declare type DefaultAgentInputSchema = typeof DEFAULT_INPUT;
+
+/**
+ * Default service implementation backed by `providerFromEnv`. Apps that
+ * want runtime provider switching wire their own AiServiceImpl into a
+ * Layer and provide it instead.
+ */
+export declare const defaultAiService: AiServiceImpl;
+
+export { defaultSettingsMiddleware }
+
+/**
+ * Declare an agent's browser-safe wire contract: its `name` and `input`
+ * schema. The decoded input type is inferred from the schema (like
+ * `defineQuery`). Behaviour (system prompt, tools, model + key, maxSteps) lives
+ * in the paired `*.agent.server.tsx` via `defineAgentExecutor`.
+ *
+ * ```ts
+ * // support.agent.tsx (browser-safe descriptor)
+ * export const support = defineAgent({
+ *   name: 'support',
+ *   input: Schema.Struct({ prompt: Schema.String, locale: Schema.optional(Schema.String) }),
+ * })
+ * ```
+ */
+export declare const defineAgent: <S extends Schema.Schema.Any = DefaultAgentInputSchema>(config: {
+    readonly name: string;
+    readonly input?: S;
+}) => AgentDescriptor<S>;
+
+/**
+ * Bind a server executor to its descriptor. Default-export the result from
+ * `<name>.agent.server.tsx`:
+ *
+ * ```ts
+ * import { defineAgentExecutor } from '@voltro/ai'
+ * import { support } from './support.agent'
+ * import { searchDocs } from '../tools/searchDocs.tool'
+ *
+ * export default defineAgentExecutor(support, {
+ *   system: (input) => `…locale=${input.locale}`,
+ *   tools: { searchDocs },
+ *   model: { name: 'openai', model: 'gpt-5.5', apiKey: process.env.SUPPORT_OPENAI_KEY },
+ *   maxSteps: 6,
+ * })
+ * ```
+ */
+export declare const defineAgentExecutor: <S extends Schema.Schema.Any = DefaultAgentInputSchema>(descriptor: AgentDescriptor<S>, config: AgentExecutorConfig<AgentInput<S>>) => AgentExecutor<S>;
+
+export declare const defineTool: <A, I, O>(def: {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema.Schema<A, I>;
+    readonly output?: Schema.Schema.Any;
+    readonly execute?: (input: A) => Effect.Effect<O, never, unknown>;
+    readonly handler?: ToolHandler<A, O>;
+    readonly timeoutMs?: number;
+}) => AnyTool;
+
+/**
+ * Embed a single string to a vector. Returns the embedding through Effect's
+ * success channel; provider failures surface as a typed
+ * `AiError({ reason: 'generation' })`. Defaults to the env-configured
+ * provider (mock unless `AI_EMBED_PROVIDER` is set).
+ *
+ * ```ts
+ * const vec = yield* embed('how do I deploy?')
+ * ```
+ */
+export declare const embed: (text: string, config?: EmbeddingProviderConfig) => Effect.Effect<ReadonlyArray<number>, AiError>;
+
+export declare interface EmbeddingProviderConfig {
+    readonly name: EmbeddingProviderName;
+    /** Model id. For 'openai': e.g. 'text-embedding-3-small'. Ignored by the
+     *  mock provider (which derives its output from `mockDim`). */
+    readonly model: string;
+    /** Mock-only: the deterministic output-vector length. Default 8. */
+    readonly mockDim?: number;
+}
+
+/**
+ * Read the embedding-provider config from env:
+ *   AI_EMBED_PROVIDER=mock|openai|voyage|cohere   (default: mock)
+ *   AI_EMBED_MODEL=<model-id>                      (default per provider)
+ *   AI_EMBED_MOCK_DIM=<n>                          (mock-only, default 8)
+ */
+export declare const embeddingProviderFromEnv: (env?: Record<string, string | undefined>) => EmbeddingProviderConfig;
+
+export declare type EmbeddingProviderName = 'mock' | 'openai' | 'voyage' | 'cohere';
+
+/**
+ * Embed many strings in one batched call. Order-preserving: result[i] is the
+ * embedding of texts[i]. Cheaper than N `embed()` calls — the SDK batches up
+ * to the provider's per-call limit.
+ */
+export declare const embedMany: (texts: ReadonlyArray<string>, config?: EmbeddingProviderConfig) => Effect.Effect<ReadonlyArray<ReadonlyArray<number>>, AiError>;
+
+/**
+ * Derive a USD cost from a token `usage` tally + a model price. An
+ * unknown model (or the `mock` provider) resolves to zero cost rather
+ * than throwing, so cost accounting never breaks a call.
+ */
+export declare const estimateCostUsd: (usage: AiUsage, opts: {
+    readonly model: string;
+    readonly price?: ModelPrice;
+    readonly actualCostUsd?: number;
+}) => CostBreakdown;
+
+declare const EXECUTOR_BRAND: "@voltro/ai/AgentExecutor";
+
+declare const EXECUTOR_SYMBOL: unique symbol;
+
+/** The `exposeAsTool` annotation shape (mirrors @voltro/protocol's, structural
+ *  so @voltro/ai needs no protocol dep). `true` alone can't expose — a tool
+ *  needs a description, so only the object form (with `description`) exposes. */
+export declare type ExposeAsToolLike = boolean | {
+    readonly description: string;
+    readonly confirm?: boolean;
+    readonly maxPerRun?: number;
+};
+
+export { extractReasoningMiddleware }
+
+/**
+ * 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.
+ */
+export declare const gatewayCostUsd: (providerMetadata: unknown) => number | undefined;
+
+/** Creator namespaces the Vercel AI Gateway routes to. Open union — the named
+ *  arms are autocomplete, any other creator string still works. */
+export declare type GatewayCreator = 'openai' | 'anthropic' | 'google' | (string & {});
+
+/** The gateway addresses models as `creator/model` ids. The template-literal
+ *  type enforces that shape at COMPILE time — what `providerFromEnv` otherwise
+ *  only catches as a runtime throw (`{ name: 'gateway', model: 'gpt-5.5' }` is
+ *  now a type error, not a boot crash). */
+export declare type GatewayModel = `${GatewayCreator}/${string}`;
+
+export declare interface GatewayModelInfo {
+    /** `creator/model` id used to address the model (e.g. `openai/gpt-5.5`). */
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly modality: ModelModality;
+    /** Pricing normalised to USD per 1,000,000 tokens (matches `cost.ModelPrice`). */
+    readonly pricing?: {
+        readonly inputPer1M: number;
+        readonly outputPer1M: number;
+        readonly cachedInputPer1M?: number;
+    };
+}
+
+/**
+ * Drop finished resumable streams whose state row predates `olderThan` —
+ * deletes the state row + all its event rows. Run it on a schedule (a cron /
+ * sweep) so the log doesn't grow without bound. Returns the count of streams
+ * collected. Only DONE streams are eligible (an in-flight one is never GC'd).
+ */
+export declare const gcResumableStreams: (store: DataStore, opts: {
+    readonly olderThan: Date;
+}) => Effect.Effect<number>;
+
+export declare interface GeneratedAudio {
+    readonly data: Uint8Array | string;
+    readonly mediaType: string;
+}
+
+/** One generated image. `data` is the raw bytes (the SDK also exposes base64;
+ *  the union keeps a base64 string valid for callers that pass one through). */
+export declare interface GeneratedImage {
+    readonly data: Uint8Array | string;
+    readonly mediaType: string;
+}
+
+/** The produced video. Providers return EITHER a `url` (the common case — video
+ *  files are large) OR inline `data` bytes; exactly one is populated. */
+export declare interface GeneratedVideo {
+    readonly data?: Uint8Array;
+    readonly url?: string;
+    readonly mediaType: string;
+}
+
+/**
+ * Generate one or more images from a text prompt. Returns the decoded image
+ * bytes + media type, a usage tally, and provider metadata. Provider failures
+ * surface as `AiError({ reason: 'generation' })`.
+ */
+export declare const generateImage: (options: GenerateImageOptions) => Effect.Effect<GenerateImageResult, AiError>;
+
+export declare interface GenerateImageOptions {
+    /** What to draw. */
+    readonly prompt: string;
+    /** Override the provider/model for a single call (defaults to `providerFromEnv()`).
+     *  `anthropic` has no image model; use `openai` or `gateway`. */
+    readonly provider?: ProviderConfig;
+    /** Number of images to generate. Default 1 (provider-dependent). */
+    readonly n?: number;
+    /** Exact pixel size, `{width}x{height}` (mutually exclusive with `aspectRatio`
+     *  per provider). */
+    readonly size?: `${number}x${number}`;
+    /** Aspect ratio, `{width}:{height}`. */
+    readonly aspectRatio?: `${number}:${number}`;
+    /** Provider-specific options forwarded to the SDK. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface GenerateImageResult {
+    readonly images: ReadonlyArray<GeneratedImage>;
+    readonly usage?: MediaUsage;
+    /** Raw provider/gateway metadata — feed to `gatewayCostUsd(...)` for the
+     *  gateway's real per-call cost (see {@link GenerateTextResult.providerMetadata}). */
+    readonly providerMetadata?: unknown;
+}
+
+export declare const generateObject: <A, I>(options: GenerateObjectOptions<A, I>) => Effect.Effect<GenerateObjectResult<A>, AiError>;
+
+export declare interface GenerateObjectOptions<A, I> {
+    /** Effect Schema the model output must satisfy. Converted to JSON
+     *  Schema for the SDK, then decoded back through this schema so the
+     *  result carries branded types + refinements (not just JSON shape). */
+    readonly schema: Schema.Schema<A, I>;
+    readonly prompt: string;
+    readonly system?: string;
+    readonly provider?: ProviderConfig;
+    /** Ordered provider/model fallback chain — see {@link ProviderFallbacks}. A
+     *  `decode` failure does NOT fall through (another provider won't fix a schema
+     *  mismatch); only a `generation` failure does. */
+    readonly fallbacks?: ProviderFallbacks;
+    readonly maxTokens?: number;
+    /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface GenerateObjectResult<A> {
+    readonly object: A;
+    readonly usage: {
+        readonly inputTokens: number | undefined;
+        readonly outputTokens: number | undefined;
+        readonly totalTokens: number | undefined;
+    };
+    /** Raw provider/gateway metadata (see {@link GenerateTextResult.providerMetadata}):
+     *  feed to `gatewayCostUsd` for the gateway's real per-call cost. */
+    readonly providerMetadata?: unknown;
+}
+
+/**
+ * Run an adaptive tool-calling loop AND constrain the final answer to an
+ * Effect Schema — the batch-agent analogue of `generateObject` that also gets
+ * tool access (the Convex agents' "call Jira tools on demand, then emit the
+ * structured summary" pattern).
+ *
+ * Mechanism: the AI SDK's `generateText` drives the LLM↔tool loop
+ * (`stopWhen: stepCountIs(maxSteps)`); `experimental_output: Output.object`
+ * makes the terminal step emit a JSON object constrained to the schema's
+ * JSON Schema. The SDK's parsed `experimental_output` is then re-decoded
+ * through the SAME Effect Schema, so brands/refinements hold and malformed
+ * output surfaces as `AiError({ reason: 'decode' })`.
+ *
+ * Tool bodies inherit the caller's services: the ambient Effect runtime is
+ * captured (`Effect.runtime`) and threaded into the tool context, so a tool
+ * may `yield* JiraService` and reach the layer provided at the
+ * action/workflow boundary.
+ */
+export declare const generateObjectWithTools: <A, I>(options: GenerateObjectWithToolsOptions<A, I>) => Effect.Effect<GenerateObjectResult<A>, AiError>;
+
+export declare interface GenerateObjectWithToolsOptions<A, I> {
+    /** Effect Schema the FINAL object must satisfy. The model runs the tool
+     *  loop, then emits one object matching this schema; it is decoded back
+     *  through the schema so refinements/brands hold. */
+    readonly schema: Schema.Schema<A, I>;
+    readonly prompt: string;
+    readonly system?: string;
+    readonly provider?: ProviderConfig;
+    /** Ordered provider/model fallback chain — see {@link ProviderFallbacks}. */
+    readonly fallbacks?: ProviderFallbacks;
+    readonly maxTokens?: number;
+    /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+    /** Tools the model may call while reasoning toward the final object. The
+     *  SDK drives the call→execute→feed-back loop up to `maxSteps`. Tool bodies
+     *  reach the caller's services through the ambient runtime (see below). */
+    readonly tools: Record<string, AnyTool>;
+    /** Max LLM↔tool round-trips before the model must produce the object.
+     *  Default 8. */
+    readonly maxSteps?: number;
+    /** Request context threaded into `*.tool.tsx` executor bodies. The caller's
+     *  ambient Effect runtime is captured automatically and merged in, so tool
+     *  bodies may `yield*` services (`JiraService`, the store layer, …). */
+    readonly toolContext?: ToolContext;
+}
+
+/**
+ * Synthesize speech audio from text. Returns the audio bytes + media type and
+ * provider metadata; provider failures surface as `AiError`.
+ */
+export declare const generateSpeech: (options: GenerateSpeechOptions) => Effect.Effect<GenerateSpeechResult, AiError>;
+
+export declare interface GenerateSpeechOptions {
+    /** Text to speak. */
+    readonly text: string;
+    /** Override the provider/model (defaults to `providerFromEnv()`). `anthropic`
+     *  has no speech model; use `openai` or `gateway`. */
+    readonly provider?: ProviderConfig;
+    /** Provider voice id. */
+    readonly voice?: string;
+    /** Desired audio container, e.g. `'mp3'` / `'wav'`. */
+    readonly outputFormat?: 'mp3' | 'wav' | (string & {});
+    /** Free-text delivery instructions, e.g. "speak slowly". */
+    readonly instructions?: string;
+    /** Speaking rate multiplier. */
+    readonly speed?: number;
+    /** ISO 639-1 language code (or `'auto'`). */
+    readonly language?: string;
+    /** Provider-specific options forwarded to the SDK. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface GenerateSpeechResult {
+    readonly audio: GeneratedAudio;
+    /** The speech model spec reports no usage; present for surface parity. */
+    readonly usage?: MediaUsage;
+    readonly providerMetadata?: unknown;
+}
+
+/**
+ * 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.
+ */
+export declare const generateText: (options: GenerateTextOptions) => Effect.Effect<GenerateTextResult, AiError>;
+
+export declare interface GenerateTextOptions {
+    /** The user prompt. The SDK auto-wraps it as the single user message. */
+    readonly prompt: string;
+    /** Optional system message. Steers the model independently of the prompt. */
+    readonly system?: string;
+    /** Override the provider/model for a single call. */
+    readonly provider?: ProviderConfig;
+    /** Ordered provider/model fallback chain — see {@link ProviderFallbacks}. */
+    readonly fallbacks?: ProviderFallbacks;
+    /** Soft ceiling on output tokens. Provider-dependent. */
+    readonly maxTokens?: number;
+    /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface GenerateTextResult {
+    readonly text: string;
+    readonly usage: {
+        readonly inputTokens: number | undefined;
+        readonly outputTokens: number | undefined;
+        readonly totalTokens: number | undefined;
+    };
+    /** Raw provider/gateway metadata from the SDK result. The Vercel AI Gateway
+     *  reports the ACTUAL per-call cost here (`gateway.cost`); pass this to
+     *  `gatewayCostUsd(...)` → `recordAiUsage({ actualCostUsd })` to record the
+     *  real charge for a gateway-routed model the static price table can't price.
+     *  `undefined` for direct providers / the mock. */
+    readonly providerMetadata?: unknown;
+}
+
+/**
+ * Generate a video from a text prompt (optionally conditioned on reference
+ * images/videos). Returns the URL the provider yields OR inline bytes, plus
+ * provider metadata; provider failures surface as `AiError`.
+ *
+ * Unlike image/speech, this calls the resolved `VideoModelV4` DIRECTLY rather
+ * than the SDK's `experimental_generateVideo`. That helper force-DOWNLOADS a
+ * URL-typed video into bytes (a potentially multi-GB fetch), discarding the
+ * URL; calling the model spec directly lets us return whichever form the
+ * provider produced (`{ url }` or `{ data }`), matching {@link GeneratedVideo}.
+ * No SDK-less gateway fallback is needed — the installed `ai` ships a video
+ * primitive and the gateway provider exposes a native `.video()` model.
+ */
+export declare const generateVideo: (options: GenerateVideoOptions) => Effect.Effect<GenerateVideoResult, AiError>;
+
+export declare interface GenerateVideoInputs {
+    /** Reference / starting-frame image URL (image-to-video). */
+    readonly image?: string;
+    /** Reference image/video URLs (reference-to-video). */
+    readonly references?: ReadonlyArray<string>;
+}
+
+export declare interface GenerateVideoOptions {
+    /** What to animate. */
+    readonly prompt: string;
+    /** 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;
+    /** Provider-specific options forwarded to the model. */
+    readonly providerOptions?: AiProviderOptions;
+}
+
+export declare interface GenerateVideoParams {
+    readonly aspectRatio?: `${number}:${number}`;
+    readonly durationSeconds?: number;
+    readonly resolution?: `${number}x${number}`;
+    readonly fps?: number;
+    readonly seed?: number;
+}
+
+export declare interface GenerateVideoResult {
+    readonly video: GeneratedVideo;
+    /** The video model spec reports no usage; present for surface parity. */
+    readonly usage?: MediaUsage;
+    readonly providerMetadata?: unknown;
+}
+
+/** The currently-installed global middleware stack. */
+export declare const getAiMiddleware: () => ReadonlyArray<AiMiddleware>;
+
+/**
+ * Fetch the live model catalog from the Vercel AI Gateway. Uses the default
+ * `gateway` (reads `AI_GATEWAY_API_KEY`) unless an explicit `apiKey`/`baseURL`
+ * is given. Optionally filter by modality (the picker usually wants `language`).
+ * `gatewayProvider` is injectable for tests.
+ */
+export declare const getAvailableModels: (opts?: {
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+    readonly modality?: ModelModality;
+    readonly gatewayProvider?: {
+        getAvailableModels: () => Promise<{
+            models: GatewayLanguageModelEntry[];
+        }>;
+    };
+}) => Promise<ReadonlyArray<GatewayModelInfo>>;
+
+/** Load a thread's messages in chronological order (for reload / resume). */
+export declare const getMessages: (store: DataStore, threadId: string) => Effect.Effect<ReadonlyArray<AgentMessage>>;
+
+/** The currently-installed override (or null). */
+export declare const getProviderOverride: () => ProviderConfig | null;
+
+export declare const getThread: (store: DataStore, threadId: string) => Effect.Effect<AgentThread | null>;
+
+/** FNV-1a-seeded deterministic float vector in [-1, 1], length `dim`. */
+export declare const hashToVector: (text: string, dim: number) => number[];
+
+/**
+ * Convert a persisted thread (`agent_messages` rows) into the model-message
+ * list that gives an assistant turn its CONVERSATION MEMORY. Without this the
+ * model only ever sees the latest prompt + system — it can't remember earlier
+ * turns. Keeps user/assistant text turns (skips the live streaming row, empty
+ * rows, and system/tool rows — `system` is passed separately), ordered by the
+ * thread's monotonic `order`/`stepOrder`.
+ */
+export declare const historyToModelMessages: (history: ReadonlyArray<AgentMessage>) => ModelMessage[];
+
+/** Discovery predicate for `*.agent.tsx` exports. */
+export declare const isAgentDescriptor: (x: unknown) => x is AnyAgentDescriptor;
+
+/** Discovery predicate for `*.agent.server.tsx` default exports. */
+export declare const isAgentExecutor: (x: unknown) => x is AnyAgentExecutor;
+
+/** Whether a stream with this id is currently registered (in flight). */
+export declare const isStreamActive: (streamId: string) => boolean;
+
+/** Is `x` a `defineTool(...)` result? */
+export declare const isTool: (x: unknown) => x is AnyTool;
+
+/** The synthesized `<name>.messages` body — load the thread's messages. */
+export declare const loadAgentMessages: (store: DataStore, threadId: string) => Effect.Effect<ReadonlyArray<AgentMessage>>;
+
+/**
+ * A middleware that logs every generate/stream call's model (and token usage
+ * for generate). Dependency-free demonstration of the seam and a useful dev
+ * default. Pass `log` to route into `@voltro/logger` or a metrics sink instead
+ * of `console`.
+ *
+ * ```ts
+ * setAiMiddleware(loggingMiddleware())
+ * ```
+ */
+export declare const loggingMiddleware: (opts?: {
+    readonly log?: (event: AiCallLog) => void;
+}) => AiMiddleware;
+
+/** Token tally, mirroring `GenerateTextResult['usage']`. Only `generateImage`
+ *  reports one (the speech + video model specs carry no usage), which is why
+ *  it's optional on every media result. */
+export declare interface MediaUsage {
+    readonly inputTokens: number | undefined;
+    readonly outputTokens: number | undefined;
+    readonly totalTokens: number | undefined;
+}
+
+/**
+ * Single-process resumable-stream store. Holds each stream's log in memory —
+ * perfect for dev, tests, and single-node self-host. A multi-node deployment
+ * needs `dataStoreResumableStreamStore` (or a Redis backend) so every node
+ * shares the log and the producer election.
+ */
+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;
+} | {
+    readonly type: 'tool';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    /** 'input-available' once the model emitted args; 'output-available' once the tool ran. */
+    readonly state: 'input-available' | 'output-available' | 'output-error';
+    readonly input?: unknown;
+    readonly output?: unknown;
+    readonly errorText?: string;
+}
+/** The model's reasoning ("thinking"), separate from the answer text — a UI
+*  renders it in a collapsible pane. Accumulated like `text`. */
+| {
+    readonly type: 'reasoning';
+    readonly text: string;
+}
+/** 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;
+}
+/** 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;
+};
+
+/** A scripted inline file the mock model emits on a turn (usually an image).
+ *  `data` is base64 (a short ascii string works for assertions). */
+export declare interface MockFile {
+    readonly mediaType: string;
+    readonly data: string;
+}
+
+/** A consumable sequence of model turns, plus a recorder for asserting on
+ *  what the model was asked. Each `doGenerate`/`doStream` advances the
+ *  cursor by one turn; running past the end repeats the last turn's text
+ *  (or empties) so a loop that over-steps doesn't hang. */
+export declare class MockScript {
+    private readonly turns;
+    private cursor;
+    readonly calls: Array<{
+        readonly prompt: unknown;
+        readonly tools: ReadonlyArray<string>;
+    }>;
+    constructor(turns: ReadonlyArray<MockTurn>);
+    record(prompt: unknown, tools: ReadonlyArray<string>): void;
+    next(): MockTurn;
+    reset(): void;
+}
+
+/** A scripted citation the mock model emits on a turn (RAG grounding). */
+export declare interface MockSource {
+    readonly sourceType?: 'url' | 'document';
+    readonly id?: string;
+    readonly url?: string;
+    readonly title?: string;
+    readonly mediaType?: string;
+    readonly filename?: string;
+}
+
+/** A scripted tool call the mock model emits on a turn. */
+export declare interface MockToolCall {
+    readonly name: string;
+    readonly input: unknown;
+}
+
+/** One model turn. A turn can carry text (streamed word-by-word), scripted
+ *  tool calls (which trigger the SDK's tool loop), cited sources, inline files,
+ *  or an error. A turn with tool calls + no text drives one LLM↔tool
+ *  round-trip. */
+export declare interface MockTurn {
+    readonly text?: string;
+    /** Reasoning ("thinking") the mock streams before the answer text. */
+    readonly reasoning?: string;
+    readonly toolCalls?: ReadonlyArray<MockToolCall>;
+    readonly sources?: ReadonlyArray<MockSource>;
+    readonly files?: ReadonlyArray<MockFile>;
+    readonly error?: {
+        readonly message: string;
+    };
+}
+
+/**
+ * Built-in published list prices (USD per 1M tokens) for the major providers.
+ *
+ * ⚠️ POINT-IN-TIME DEFAULTS — these are public LIST prices as of **January
+ * 2026** and WILL drift as providers re-price. They are a sane default for the
+ * budget guard + cost dashboard, NOT a contract. Override them without editing
+ * the framework three ways:
+ *   - per call:    `estimateCostUsd(usage, { model, price })` / `recordAiUsage({ price })`
+ *   - app-wide:    `setModelPricing({ 'my-model': { inputPer1M, outputPer1M } })`
+ *                  (merged OVER these defaults — a user entry wins)
+ *   - authoritative: for a GATEWAY-routed model, pass the gateway's REPORTED
+ *                  per-call cost via `actualCostUsd: gatewayCostUsd(meta)`
+ *                  (`costSource: 'gateway'`), which beats any static rate here.
+ *
+ * The `mock` provider + any model absent from the merged map price at zero
+ * (never throws — cost accounting must not break a call).
+ *
+ * Covers the framework's first-class DIRECT providers — `anthropic` (`claude-*`)
+ * and `openai` (`gpt-*`) — plus the common GATEWAY creators reachable by their
+ * bare model id (`google` Gemini, and the same OpenAI/Anthropic ids the gateway
+ * routes with a `creator/` prefix, matched below by their bare id after the `/`).
+ */
+export declare const MODEL_PRICING_DEFAULTS: Record<string, ModelPrice>;
+
+export declare type ModelModality = 'language' | 'embedding' | 'image' | 'video' | 'realtime' | 'reranking' | 'speech' | 'transcription' | 'unknown';
+
+export declare interface ModelPrice {
+    /** USD per 1,000,000 input (prompt) tokens. */
+    readonly inputPer1M: number;
+    /** USD per 1,000,000 output (completion) tokens. */
+    readonly outputPer1M: number;
+}
+
+/** The current merged price map (defaults + installed overrides). Overrides win. */
+export declare const modelPricing: () => Record<string, ModelPrice>;
+
+/**
+ * Wrap a `streamText` `Stream<AgentEvent>` with the same `voltro.ai.call` span +
+ * metrics. The stream never fails — usage arrives on the terminal `done` event,
+ * error status on a terminal `error` event — so the metrics are recorded from a
+ * `Stream.tap` on the terminal event, and the whole stream is spanned via
+ * `Stream.withSpan`. A `cancelled` error counts as an error (non-`ok`) call.
+ */
+export declare const observeStream: (attributes: AiCallAttributes, stream: Stream.Stream<AgentEvent>) => Stream.Stream<AgentEvent>;
+
+export declare type OpenAIModel = 'gpt-5.5' | 'gpt-4o' | 'gpt-4o-mini' | (string & {});
+
+/** Does this tag pass the allow/deny policy? deny wins; allow (when set) gates. */
+export declare const passesPolicy: (tag: string, policy: AppToolPolicy) => boolean;
+
+/**
+ * Patch the streaming row's `parts` (the live snapshot). Call-site throttles
+ * this to ~100ms so the subscription doesn't fan out one update per token.
+ * Mirrors `content` to the concatenated text so the durable row stays readable
+ * even if a consumer ignores `parts`.
+ */
+export declare const patchStreamingMessage: (store: DataStore, id: string, parts: ReadonlyArray<MessagePart>) => Effect.Effect<void>;
+
+/**
+ * The effective {@link ModelPrice} for a model id, or `undefined` if unknown.
+ * Looks up the merged map (overrides over defaults); a gateway `creator/model`
+ * id also matches on its bare `model` segment, so `openai/gpt-4o` prices like
+ * `gpt-4o` when the caller didn't pass a `price` / `actualCostUsd`.
+ */
+export declare const priceForModel: (model: string) => ModelPrice | undefined;
+
+/**
+ * A resolved provider choice — a DISCRIMINATED UNION on `name`. Each provider
+ * only carries the fields that apply to it: the mock-only `mockText` / `script`
+ * cannot appear on a real provider, and a real provider always carries a
+ * `model` typed to that provider's ids. `apiKey` / `baseURL` switch
+ * `resolveModel` to a per-config provider instance (per-agent key / BYOK);
+ * omit them to fall back to the provider's standard env var (OPENAI_API_KEY /
+ * ANTHROPIC_API_KEY / AI_GATEWAY_API_KEY).
+ */
+export declare type ProviderConfig = {
+    readonly name: 'mock';
+    /** Optional for mock — defaults to `'mock'`. */
+    readonly model?: string;
+    /** The exact text the mock returns (instead of echoing the prompt).
+     *  Lets tests/demos drive `generateObject` with canned JSON. */
+    readonly mockText?: string;
+    /** A multi-turn script. Takes precedence over `mockText` — each
+     *  `doGenerate`/`doStream` consumes the next turn, so the SDK's tool
+     *  loop runs deterministically. */
+    readonly script?: MockScript;
+    /** Provider metadata the mock attaches to its `doGenerate` result — lets a
+     *  test exercise the gateway-cost path (`gatewayCostUsd`) deterministically
+     *  by faking `{ gateway: { cost } }`. Also surfaced by the mock speech +
+     *  video media models. */
+    readonly providerMetadata?: AiProviderOptions;
+    /** Canned output for the media models (`resolveImageModel` /
+     *  `resolveSpeechModel` / `resolveVideoModel`). Every field is optional and
+     *  falls back to a deterministic default, so `useMockAi` yields valid media
+     *  without configuration; set a field to assert on exact bytes / URL. */
+    readonly mockMedia?: {
+        /** base64 image payload `generateImage` decodes to bytes (default: a
+         *  1×1 PNG header, so media-type detection resolves to `image/png`). */
+        readonly imageBase64?: string;
+        /** base64 audio payload `generateSpeech` decodes to bytes. */
+        readonly audioBase64?: string;
+        /** URL the mock video model yields (the default branch — most video
+         *  providers return a URL rather than inline bytes). */
+        readonly videoUrl?: string;
+        /** base64 the mock video model yields INSTEAD of a URL — exercises the
+         *  bytes branch of `generateVideo`. Takes precedence over `videoUrl`. */
+        readonly videoBase64?: string;
+    };
+} | {
+    readonly name: 'anthropic';
+    readonly model: AnthropicModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+} | {
+    readonly name: 'openai';
+    readonly model: OpenAIModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+} | {
+    readonly name: 'gateway';
+    /** A `creator/model` id, e.g. 'openai/gpt-5.5'. */
+    readonly model: GatewayModel;
+    readonly apiKey?: string;
+    readonly baseURL?: string;
+};
+
+/**
+ * An ordered provider/model fallback chain. When a call FAILS on the primary
+ * provider (`provider ?? providerFromEnv()`) — after that provider's OWN
+ * SDK-level retries — the call re-runs against `fallbacks[0]`, then
+ * `fallbacks[1]`, … until one succeeds. Exhausting every option surfaces the
+ * LAST provider's typed error (an `AiError({ reason: 'generation' })`). Only a
+ * `generation` failure (the provider call itself) falls through — a `decode`
+ * failure (the model answered but the output didn't satisfy the schema) is a
+ * prompt/schema problem another provider won't fix, so it surfaces immediately.
+ * An empty / absent chain leaves behavior unchanged.
+ */
+export declare type ProviderFallbacks = ReadonlyArray<ProviderConfig>;
+
+/**
+ * Read the provider config. The process-global override (set by `useMockAi`)
+ * wins over env. Otherwise honours:
+ *   AI_PROVIDER=mock|anthropic|openai|gateway   (default: mock)
+ *   AI_MODEL=<model-id>   (default per provider: 'claude-opus-4-8' for
+ *                          anthropic, 'gpt-5.5' for openai, 'mock' for mock;
+ *                          REQUIRED for gateway — a `creator/model` id)
+ *
+ * Provider keys are read by the underlying AI SDK packages from their standard
+ * env vars: ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY.
+ */
+export declare const providerFromEnv: (env?: Record<string, string | undefined>) => ProviderConfig;
+
+export declare type ProviderName = 'mock' | 'anthropic' | 'openai' | 'gateway';
+
+/**
+ * Price a usage tally and write a ledger row. Returns the computed
+ * `CostBreakdown` so the caller can surface the cost without a re-query.
+ */
+export declare const recordAiUsage: (store: DataStore, record: AiUsageRecordInput) => Effect.Effect<CostBreakdown>;
+
+/**
+ * Redis-backed resumable-stream store — the production "resumable via
+ * Redis-Replay" path. The append-only log is a Redis LIST per `streamId`
+ * (`RPUSH` to append, `LRANGE afterSeq -1` to read the tail past a cursor — the
+ * list index lines up with the 1-based `seq` because exactly ONE producer
+ * appends, elected by `claimProducer` = `SET … NX`). Multi-node correct + the
+ * fastest backend; TTL (default 1h) evicts finished/abandoned streams without a
+ * sweep. A drop-in for `dataStoreResumableStreamStore` against the same
+ * `ResumableStreamStore` interface.
+ */
+export declare const redisResumableStreamStore: (redis: ResumableRedis, opts?: {
+    readonly keyPrefix?: string;
+    readonly ttlSeconds?: number;
+}) => ResumableStreamStore;
+
+/**
+ * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
+ * this when given a `streamId`; it threads the returned controller's `signal`
+ * into the SDK call. Re-registering an id that is still in flight returns the
+ * SAME controller (so a pre-registered-then-aborted id is honoured) — keep
+ * `streamId` unique per logical stream.
+ */
+export declare const registerStream: (streamId: string) => AbortController;
+
+/**
+ * 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.
+ */
+export declare const requireAiBudget: (store: DataStore, opts: {
+    readonly tenantId?: string | null;
+    readonly limitUsd: number;
+    readonly addUsd?: number;
+    readonly since?: Date;
+}) => Effect.Effect<void, AiBudgetExceeded>;
+
+/**
+ * Rerank `documents` by relevance to `query`, highest score first. Returns
+ * each surviving document with its relevance score; truncated to `topN`
+ * when set.
+ *
+ * ```ts
+ * const top = yield* rerank({ query: 'deploy', documents: rows, getText: (r) => r.body, topN: 5 })
+ * ```
+ */
+export declare const rerank: <T>(options: RerankOptions<T>) => Effect.Effect<ReadonlyArray<RerankResult<T>>, AiError>;
+
+export declare interface RerankOptions<T> {
+    readonly query: string;
+    readonly documents: ReadonlyArray<T>;
+    /** Extract the text to score from each document. Default: identity for
+     *  `string[]`; required for non-string document shapes. */
+    readonly getText?: (doc: T) => string;
+    /** Rerank model id. e.g. 'rerank-english-v3.0' (cohere) / 'rerank-2' (voyage). */
+    readonly model?: string;
+    /** Provider. Default 'mock' (lexical overlap; deterministic). */
+    readonly provider?: 'mock' | 'cohere' | 'voyage';
+    /** Return only the top-N after reranking. Default: all. */
+    readonly topN?: number;
+}
+
+export declare interface RerankResult<T> {
+    readonly document: T;
+    readonly score: number;
+}
+
+/** Resolve the provider config for a given decoded input. Supports a static
+ *  config OR a `(input) => ProviderConfig | undefined` selector (model picker /
+ *  cost routing). `undefined` → fall back to env (`providerFromEnv`). */
+export declare const resolveAgentModel: (exec: AnyAgentExecutor, input: unknown) => ProviderConfig | undefined;
+
+/**
+ * Resolve an {@link EmbeddingProviderConfig} to an AI-SDK
+ * `EmbeddingModelV4`. The mock provider is synchronous; real providers are
+ * resolved lazily (server-only dynamic import) so the provider package is
+ * never bundled for the browser and is an optional, user-installed
+ * dependency. A missing package surfaces a clear, actionable error.
+ */
+export declare const resolveEmbeddingModel: (config: EmbeddingProviderConfig) => Promise<EmbeddingModelV4>;
+
+export declare const resolveImageModel: (config: ProviderConfig) => ImageModelV4;
+
+export declare const resolveModel: (config: ProviderConfig, middleware?: AiMiddleware | ReadonlyArray<AiMiddleware>) => LanguageModelV4;
+
+export declare const resolveSpeechModel: (config: ProviderConfig) => SpeechModelV4;
+
+/** Resolve the system prompt for a given decoded input. */
+export declare const resolveSystem: (exec: AnyAgentExecutor, input: unknown) => string | undefined;
+
+/**
+ * Wire a `*.tool.tsx` module's DEFAULT-EXPORT handler onto its `defineTool`
+ * export(s). The documented tool shape is a named descriptor with NO body plus
+ * a separate `export default (input, ctx) => …` handler:
+ *
+ *   export const searchDocs = defineTool({ name, description, input })
+ *   export default async ({ query }, ctx) => ctx.store.select('docs')…
+ *
+ * Nothing else connects the two halves — an agent's `tools: { searchDocs }`
+ * imports the BODY-LESS descriptor, so without this pass every such tool fails
+ * at call time ("neither execute nor handler"). This attaches the default
+ * export as the descriptor's `handler` (mutated in place — the agent imports
+ * the SAME module instance, so its tool reference is fixed too). No-op when the
+ * tool already has an inline `execute`/`handler`, or the module has no default
+ * function. Returns the number of tools wired. Idempotent.
+ */
+export declare const resolveToolModuleHandlers: (mod: Record<string, unknown>) => number;
+
+export declare const resolveVideoModel: (config: ProviderConfig) => Experimental_VideoModelV4;
+
+/**
+ * The minimal Redis surface a resumable-stream store needs — a per-event LIST
+ * (`RPUSH`/`LRANGE`) plus two flag keys (claim + done). Adapt your client
+ * (ioredis / node-redis / a `@voltro/cache` RESP handle) to these five methods;
+ * `@voltro/ai` takes NO Redis dependency, so the client is always injected.
+ * `ttlSeconds`, when passed, should map to `SET … EX` / `EXPIRE` so finished
+ * (or abandoned) streams self-evict — there is no GC sweep for the Redis path.
+ */
+export declare interface ResumableRedis {
+    /** `SET key value NX [EX ttl]` — return true iff the key did NOT exist (we set it). */
+    readonly setNx: (key: string, value: string, ttlSeconds?: number) => Promise<boolean>;
+    /** `RPUSH key value`. */
+    readonly rpush: (key: string, value: string) => Promise<void>;
+    /** `LRANGE key start stop` (0-based, inclusive; negative = from the end, -1 = last). */
+    readonly lrange: (key: string, start: number, stop: number) => Promise<ReadonlyArray<string>>;
+    /** `SET key value [EX ttl]`. */
+    readonly set: (key: string, value: string, ttlSeconds?: number) => Promise<void>;
+    /** `EXISTS key` → boolean. */
+    readonly exists: (key: string) => Promise<boolean>;
+    /** `EXPIRE key seconds` — refresh a key's TTL. Optional (no-op if absent). */
+    readonly expire?: (key: string, seconds: number) => Promise<void>;
+}
+
+/**
+ * The one call a streaming rpc makes per subscription. Elects a producer for
+ * `streamId` (forking it as a daemon so it survives THIS consumer's lifetime),
+ * then returns a consumer stream that replays past `fromSeq` and tails to the
+ * end. First connection produces + consumes; a reconnect (producer already
+ * elected) just consumes from its cursor.
+ */
+export declare const resumableStream: (opts: ResumableStreamOptions) => Stream.Stream<SeqEvent>;
+
+export declare interface ResumableStreamOptions {
+    readonly streamId: string;
+    readonly store: ResumableStreamStore;
+    /** The underlying event source — typically `() => streamText({...})`. Run at
+     *  most once per `streamId` (by the elected producer). */
+    readonly source: () => Stream.Stream<AgentEvent>;
+    /** Replay events past this `seq` before tailing (a reconnect cursor). */
+    readonly fromSeq?: number;
+    readonly pollMs?: number;
+    readonly idleTimeoutMs?: number;
+}
+
+/**
+ * The persistence port a resumable stream drives. Append-only log + a
+ * done-flag + a one-winner producer election, all keyed by `streamId`.
+ * Implement it against any ordered store (a Redis list, a log table, …);
+ * two implementations ship below.
+ */
+export declare interface ResumableStreamStore {
+    /**
+     * Atomically elect the producer for `streamId`. Returns `true` for the ONE
+     * caller that should run the model, `false` for everyone else (they consume).
+     * Must be race-free across processes — the durable backend uses an
+     * insert-if-not-exists, exactly like `_voltro_idempotency`'s claim.
+     */
+    readonly claimProducer: (streamId: string) => Effect.Effect<boolean>;
+    /** Append one event at its `seq`. Producer-only. */
+    readonly append: (streamId: string, ev: SeqEvent) => Effect.Effect<void>;
+    /** Persisted events with `seq > afterSeq`, ascending. */
+    readonly read: (streamId: string, afterSeq: number) => Effect.Effect<ReadonlyArray<SeqEvent>>;
+    /** Mark the stream complete — the producer reached a terminal event. */
+    readonly markDone: (streamId: string) => Effect.Effect<void>;
+    /** Whether the producer has finished (all events are persisted). */
+    readonly isDone: (streamId: string) => Effect.Effect<boolean>;
+}
+
+/** Convenience: resume a `streamText` run by `streamId`. The producer runs
+ *  `streamText(options)`; reconnect by passing `fromSeq`. */
+export declare const resumableStreamText: (args: {
+    readonly streamId: string;
+    readonly store: ResumableStreamStore;
+    readonly options: StreamTextOptions;
+    readonly fromSeq?: number;
+    readonly pollMs?: number;
+    readonly idleTimeoutMs?: number;
+}) => Stream.Stream<SeqEvent>;
+
+/**
+ * The synthesized `<name>.send` body. Appends the user turn at `order`, then
+ * drives a streaming assistant turn at `order + 1` via `runAssistant` (which
+ * owns the loop + delta-persistence). Returns the assembled assistant text.
+ */
+export declare const runAgentTurn: (exec: AnyAgentExecutor, store: DataStore, args: {
+    readonly threadId: string;
+    readonly input: unknown;
+    readonly tenantId?: string | null;
+    readonly order: number;
+    readonly toolContext?: ToolContext;
+    readonly throttleMs?: number;
+    readonly promptOf?: (input: unknown) => string;
+}) => Effect.Effect<string, Error>;
+
+/**
+ * Drive a streaming assistant turn end-to-end against the persisted row.
+ *
+ * Inserts the streaming row, consumes `streamText`, accumulates token deltas
+ * into a single text part, records each tool call + result as a tool part,
+ * throttle-patches the row as deltas arrive, and flips `streaming:false` on the
+ * terminal `done`/`error` event. Returns the final assembled text.
+ */
+export declare const runAssistant: (store: DataStore, input: RunAssistantInput) => Effect.Effect<string, Error>;
+
+export declare interface RunAssistantInput {
+    readonly threadId: string;
+    readonly tenantId?: string | null;
+    readonly prompt: string;
+    /** Full prior conversation for multi-turn memory. When present it is sent to
+     *  the model INSTEAD of `prompt` (must already end with the latest user
+     *  turn). The synthesized agent send builds this from the thread history. */
+    readonly messages?: ReadonlyArray<ModelMessage>;
+    readonly system?: string;
+    readonly tools?: Record<string, AnyTool>;
+    /** Provider override; defaults to `providerFromEnv()`. */
+    readonly provider?: ProviderConfig;
+    /** Max LLM↔tool round-trips before the loop stops. Forwarded to streamText. */
+    readonly maxSteps?: number;
+    /** Request context threaded into `*.tool.tsx` executor bodies. */
+    readonly toolContext?: ToolContext;
+    /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+    /** The order the streaming assistant row was inserted at. */
+    readonly order: number;
+    /** Throttle window for the live `parts` patch. Default 100ms. */
+    readonly throttleMs?: number;
+}
+
+/**
+ * End-to-end copilot step: build the grammar prompt, ask the model for a
+ * constrained proposal, then VALIDATE it against the schema. Returns a
+ * validated read-only descriptor or a typed {@link CopilotRejected}. Run the
+ * descriptor AS the subject for tenant/scope isolation.
+ *
+ * Real wiring of `propose`:
+ * ```ts
+ * propose: ({ system, prompt }) =>
+ *   Effect.runPromise(
+ *     generateObject({ system, prompt, schema: CopilotProposalSchema })
+ *       .pipe(Effect.map((r) => r.object)),
+ *   )
+ * ```
+ */
+export declare const runDataCopilot: (question: string, schema: CopilotSchema, deps: DataCopilotDeps) => Promise<CopilotValidation>;
+
+/**
+ * One persisted event of a RESUMABLE stream: an `AgentEvent` plus its monotonic
+ * 1-based position. `seq` is the resume cursor — a client that has rendered up
+ * to `seq=N` reconnects with `fromSeq: N` and gets `N+1…` replayed, then live.
+ *
+ * This is the WIRE element for a resumable `defineStream` (`element: SeqEvent`).
+ * It lives here — next to `AgentEvent`, with ZERO server imports — so a
+ * browser-loaded stream descriptor can reference the Schema without dragging
+ * the server-only resumable-stream store graph (`@voltro/database`) into the
+ * client bundle.
+ */
+export declare const SeqEvent: Schema.Struct<{
+    seq: typeof Schema.Number;
+    event: Schema.Union<[Schema.Struct<{
+        _tag: Schema.Literal<["token"]>;
+        text: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["reasoning"]>;
+        text: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["toolCall"]>;
+        id: typeof Schema.String;
+        name: typeof Schema.String;
+        input: typeof Schema.Unknown;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["toolResult"]>;
+        id: typeof Schema.String;
+        name: typeof Schema.String;
+        output: Schema.optional<typeof Schema.Unknown>;
+        error: Schema.optional<typeof Schema.String>;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["source"]>;
+        sourceType: Schema.Literal<["url", "document"]>;
+        id: typeof Schema.String;
+        url: Schema.optional<typeof Schema.String>;
+        title: Schema.optional<typeof Schema.String>;
+        mediaType: Schema.optional<typeof Schema.String>;
+        filename: Schema.optional<typeof Schema.String>;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["file"]>;
+        mediaType: typeof Schema.String;
+        data: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["message"]>;
+        role: typeof Schema.String;
+        content: typeof Schema.String;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["error"]>;
+        code: Schema.Literal<["provider", "tool", "timeout", "cancelled", "decode", "internal"]>;
+        message: typeof Schema.String;
+        retryable: typeof Schema.Boolean;
+    }>, Schema.Struct<{
+        _tag: Schema.Literal<["done"]>;
+        finishReason: typeof Schema.String;
+        usage: Schema.Struct<{
+            inputTokens: Schema.optional<typeof Schema.Number>;
+            outputTokens: Schema.optional<typeof Schema.Number>;
+            totalTokens: Schema.optional<typeof Schema.Number>;
+        }>;
+    }>]>;
+}>;
+
+export declare type SeqEvent = typeof SeqEvent.Type;
+
+/**
+ * Install the global middleware stack — every subsequent `resolveModel` wraps
+ * its model with it. Returns the PREVIOUS stack so a caller (a test, a scoped
+ * boot) can restore it. Call with no args to clear.
+ */
+export declare const setAiMiddleware: (...middleware: ReadonlyArray<AiMiddleware>) => ReadonlyArray<AiMiddleware>;
+
+/**
+ * Install app-wide model-price overrides, merged OVER the built-in
+ * point-in-time defaults (a user entry for a model id wins). Wire the ai
+ * config's `pricing` map through this at boot to encode current/negotiated
+ * rates without editing the framework. Returns the previous overrides so a
+ * test can restore them. Pass `{}` to clear.
+ */
+export declare const setModelPricing: (pricing: Record<string, ModelPrice>) => Record<string, ModelPrice>;
+
+/** Install a provider override that every `providerFromEnv()` call honours
+ *  regardless of env. `useMockAi` uses this; returns the previous override
+ *  so it can be restored. */
+export declare const setProviderOverride: (config: ProviderConfig | null) => ProviderConfig | null;
+
+export { simulateStreamingMiddleware }
+
+/**
+ * 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).
+ */
+export declare const startResumableProducer: (streamId: string, store: ResumableStreamStore, source: () => Stream.Stream<AgentEvent>) => Effect.Effect<void>;
+
+export declare const STREAM_EVENTS_TABLE = "_voltro_stream_events";
+
+export declare const STREAM_STATE_TABLE = "_voltro_stream_state";
+
+/** The append-only event log. UNIQUE (streamId, seq) defends against a stray
+ *  double-producer writing duplicate positions. */
+export declare const streamEventsTable: Table<typeof STREAM_EVENTS_TABLE, Record<string, ColumnDefinition<unknown>>, false>;
+
+export declare interface StreamRetryOptions {
+    /** Total attempts, including the first (default 3 → 1 try + 2 retries). */
+    readonly maxAttempts?: number;
+    /** Base backoff between attempts in ms (default 250); grows exponentially. */
+    readonly backoffMs?: number;
+    /** Cap on a single backoff in ms (default 5000). */
+    readonly maxBackoffMs?: number;
+}
+
+/** The per-stream state + producer-election row. UNIQUE `streamId` is the
+ *  atomic claim arbiter (insert-if-not-exists). */
+export declare const streamStateTable: Table<typeof STREAM_STATE_TABLE, Record<string, ColumnDefinition<unknown>>, false>;
+
+export declare const streamText: (options: StreamTextOptions) => Stream.Stream<AgentEvent>;
+
+export declare interface StreamTextOptions {
+    /** The latest user turn, sent as a single user message. Ignored when
+     *  `messages` is supplied (then the full conversation is sent instead). */
+    readonly prompt: string;
+    /** Full prior conversation (multi-turn memory). When present it is sent to
+     *  the model INSTEAD of `prompt` — it should already include the latest user
+     *  turn as its last entry. The agent send path builds this from the thread. */
+    readonly messages?: ReadonlyArray<ModelMessage>;
+    readonly system?: string;
+    readonly provider?: ProviderConfig;
+    /** Ordered provider/model fallback chain. When a stream ERRORS with a
+     *  retryable `provider` error BEFORE any content has streamed, the run
+     *  re-attempts against the next config in this list (then the next, …). Once
+     *  any content event (token / tool / …) has flowed the answer is committed and
+     *  a later error surfaces as-is — re-running elsewhere would duplicate tokens.
+     *  A `cancelled` error (deliberate abort) never falls through. Applies via
+     *  `streamTextWithFallback` / `streamTextWithRetry`; a plain `streamText` uses
+     *  only the primary provider. */
+    readonly fallbacks?: ReadonlyArray<ProviderConfig>;
+    readonly maxTokens?: 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. */
+    readonly maxSteps?: number;
+    /** Request context threaded into `*.tool.tsx` executor bodies. */
+    readonly toolContext?: ToolContext;
+    /** Provider-specific options forwarded to the SDK (e.g. reasoning effort).
+     *  See `AiProviderOptions`. */
+    readonly providerOptions?: AiProviderOptions;
+    /** Cancel-by-streamId (#12). When set, the run registers an `AbortController`
+     *  addressable by `cancelStream(streamId)` — a "Stop" button calls that out of
+     *  band to abort the run. The id is dropped from the registry when the stream
+     *  ends. Keep it unique per logical stream. */
+    readonly streamId?: string;
+    /** An external abort signal (composed with `streamId`'s controller, if any).
+     *  Aborting it ends the run with a terminal `cancelled` error. */
+    readonly signal?: AbortSignal;
+    /** SDK-level transient retry (#12). Forwarded as the AI SDK's `maxRetries` —
+     *  retries the provider HTTP call on a transient failure BEFORE any bytes
+     *  stream, so it never duplicates emitted tokens. For re-attempting a whole
+     *  stream that errored before producing content, use `streamTextWithRetry`. */
+    readonly maxRetries?: number;
+}
+
+/**
+ * `streamText` with an ordered provider/model FALLBACK chain (F10). When a run
+ * ERRORS with a retryable `provider` error BEFORE any content has streamed, it
+ * re-attempts against the next config in `options.fallbacks` (then the next, …).
+ * The moment any content event (token / reasoning / tool / source / file) flows,
+ * the answer is committed and a later error surfaces as-is — re-running against
+ * another provider would duplicate tokens. A `cancelled` error (deliberate
+ * abort) is never a fallback trigger. Exhausting every option surfaces the LAST
+ * provider's terminal error.
+ *
+ * This complements `streamTextWithRetry` (which re-attempts the SAME provider on
+ * a transient blip): each fallback config gets its own SDK-level `maxRetries`
+ * BEFORE the chain moves on. Compose both by passing `fallbacks` AND wrapping in
+ * `streamTextWithRetry` per config — or just use `streamTextWithRetry`, which
+ * runs the fallback chain internally. With no `fallbacks` this is a single
+ * `streamText`.
+ */
+export declare const streamTextWithFallback: (options: StreamTextOptions) => Stream.Stream<AgentEvent>;
+
+/**
+ * `streamText` with automatic re-attempts on a transient failure — but ONLY
+ * while nothing has streamed yet. The moment any content event (token /
+ * reasoning / tool / source / file) flows, the answer is committed and a later
+ * error is surfaced as-is (re-running would duplicate tokens). A `cancelled`
+ * error (deliberate abort) is never retryable, so a Stop is honoured.
+ *
+ * This complements `streamText({ maxRetries })` (the SDK's HTTP-level retry,
+ * which handles a transient failure BEFORE the first byte): use `maxRetries`
+ * for connection blips, this wrapper to recover from an immediate provider
+ * error event (e.g. a 503 surfaced as the first stream chunk). Backoff is
+ * exponential between attempts.
+ *
+ * FALLBACK-AWARE (F10): when `options.fallbacks` is set, each provider in the
+ * chain (primary first) gets its OWN `maxAttempts` retries; when a provider
+ * exhausts its retries WITHOUT streaming content, the chain moves to the next
+ * provider before finally surfacing the last provider's terminal error. So this
+ * one wrapper gives you "retry each provider N times, then fall to the next".
+ */
+export declare const streamTextWithRetry: (options: StreamTextOptions, retry?: StreamRetryOptions) => Stream.Stream<AgentEvent>;
+
+/** A synthesized tool's metadata (the discovery/inventory view). */
+export declare interface SynthesizedTool {
+    readonly name: string;
+    readonly kind: string;
+    readonly description: string;
+    /** mutation/action → true. Drives the confirm default + the writes gate. */
+    readonly write: boolean;
+    /** Require human confirmation before this call executes. */
+    readonly confirm: boolean;
+    readonly maxPerRun?: number;
+}
+
+/**
+ * The discovery/inventory view: every descriptor that is exposable AND passes
+ * the policy, as `SynthesizedTool` metadata (no executable body). Use for the
+ * capability surface / a confirm-UI. Sorted by name.
+ */
+export declare const synthesizeToolSpecs: (entries: ReadonlyArray<AppToolEntry>, policy?: AppToolPolicy) => ReadonlyArray<SynthesizedTool>;
+
+/** A `system` prompt: a static string OR a per-request function of the
+ *  decoded input (templates locale / plan / persona into the prompt). */
+export declare type SystemPrompt<Input> = string | ((input: Input) => string);
+
+/** Project a raw gateway entry → our clean, UI-friendly + cost-aligned shape. */
+export declare const toModelInfo: (e: GatewayLanguageModelEntry) => GatewayModelInfo;
+
+/** The slice of the request context a `*.tool.tsx` handler receives. Kept
+ *  structurally typed here (rather than importing `AppContext` from
+ *  `@voltro/runtime`) so `@voltro/ai` carries no runtime dependency — the
+ *  CLI discovery path passes the real `AppContext`, which is a superset.
+ *
+ *  `runtime` is the caller's ambient Effect `Runtime`. When present, tool
+ *  bodies are run through it (`Runtime.runPromise(runtime)(eff)`) instead of
+ *  bare `Effect.runPromise`, so a body may `yield*` any service the caller's
+ *  runtime carries — `JiraService`, the data store layer, `HttpClient`, … —
+ *  rather than being limited to `R = never`. The agent loop
+ *  (`streamText`/`runAssistant`) captures `yield* Effect.runtime()` and threads
+ *  it here; without a runtime, behaviour is unchanged. */
+export declare interface ToolContext {
+    readonly store: unknown;
+    readonly request?: {
+        readonly subject?: unknown;
+    };
+    readonly runtime?: Runtime.Runtime<unknown>;
+}
+
+export declare interface ToolDef<A, I, O> {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Schema.Schema<A, I>;
+    /** Optional result schema. When set, `buildSdkTools` decodes the body's
+     *  output through it before handing the value back to the model. */
+    readonly output?: Schema.Schema.Any;
+    /** Inline body: returns an Effect. May declare service deps on the R
+     *  channel — they are provided by the caller's runtime
+     *  (`ctx.runtime`) at execution time. */
+    readonly execute?: (input: A) => Effect.Effect<O, never, unknown>;
+    /** File-convention body: receives `ctx`, returns Effect or Promise. */
+    readonly handler?: ToolHandler<A, O>;
+    /** Per-call deadline; the tool fails with a timeout error past it. */
+    readonly timeoutMs?: number;
+}
+
+/** A context-receiving tool body — the `*.tool.tsx` default-export form.
+ *  May return an Effect (with service deps the caller's runtime provides) or
+ *  a Promise; `buildSdkTools` normalises both. */
+export declare type ToolHandler<A, O> = (input: A, ctx: ToolContext) => Effect.Effect<O, never, unknown> | Promise<O>;
+
+/**
+ * Drop a stream's controller. `streamText` calls this in its finaliser when the
+ * stream ends — success, error, cancel, or consumer interrupt. Idempotent.
+ */
+export declare const unregisterStream: (streamId: string) => void;
+
+/**
+ * Validate a proposal against the schema and (on success) build a read-only
+ * `QueryDescriptor`. EVERY table/column the proposal names must exist in the
+ * manifest — otherwise a typed `CopilotRejected`. The descriptor is always a
+ * SELECT (read-only); run it as the subject for tenant/scope isolation.
+ */
+export declare const validateCopilotProposal: (proposal: CopilotProposal, schema: CopilotSchema) => CopilotValidation;
+
+/**
+ * Wrap an `Effect`-returning generate call with a `voltro.ai.call` span +
+ * per-call metrics (count, error count, duration histogram, token + cost
+ * counters), labelled by provider/model/operation. A typed failure increments
+ * the error counter + marks the span; success records the usage tally the
+ * result exposes via `usageOf`. Pure metric updates + one span — no content or
+ * secret ever touches a label.
+ */
+export declare const withAiCallSpan: <A, E, R>(attributes: AiCallAttributes, usageOf: (a: A) => {
+    readonly inputTokens?: number | undefined;
+    readonly outputTokens?: number | undefined;
+}, effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+
+export { }