@voltro/ai 0.85.0 → 0.87.0

package/dist/events.js

@@ -1,2 +1,81 @@
-import { a as e, i as t, n, o as r, r as i, s as a, t as o } from "./agentEvent-Bl4egdM5.js";
-export { o as AgentErrorCode, n as AgentEvent, t as RealtimeClientEvent, e as RealtimeServerEvent, i as SeqEvent, r as TranscriptionStreamError, a as TranscriptionStreamEvent };
+import { TranscriptionStreamError as e, TranscriptionStreamEvent as t } from "./transcriptionEvent.js";
+import { RealtimeClientEvent as n, RealtimeServerEvent as r } from "./realtimeEvent.js";
+import { Schema as i } from "effect";
+//#region src/agentEvent.ts
+var a = i.Literals([
+	"provider",
+	"tool",
+	"timeout",
+	"cancelled",
+	"decode",
+	"internal"
+]), o = i.Struct({
+	inputTokens: i.optional(i.Number),
+	outputTokens: i.optional(i.Number),
+	totalTokens: i.optional(i.Number)
+}), s = i.Union([
+	i.Struct({
+		_tag: i.Literal("token"),
+		text: i.String
+	}),
+	i.Struct({
+		_tag: i.Literal("reasoning"),
+		text: i.String
+	}),
+	i.Struct({
+		_tag: i.Literal("toolCall"),
+		id: i.String,
+		name: i.String,
+		input: i.Unknown,
+		execution: i.optional(i.Literal("client"))
+	}),
+	i.Struct({
+		_tag: i.Literal("toolResult"),
+		id: i.String,
+		name: i.String,
+		output: i.optional(i.Unknown),
+		error: i.optional(i.String)
+	}),
+	i.Struct({
+		_tag: i.Literal("source"),
+		sourceType: i.Literals(["url", "document"]),
+		id: i.String,
+		url: i.optional(i.String),
+		title: i.optional(i.String),
+		mediaType: i.optional(i.String),
+		filename: i.optional(i.String),
+		providerMetadata: i.optional(i.Unknown)
+	}),
+	i.Struct({
+		_tag: i.Literal("file"),
+		mediaType: i.String,
+		data: i.String,
+		providerMetadata: i.optional(i.Unknown)
+	}),
+	i.Struct({
+		_tag: i.Literal("stepMetadata"),
+		step: i.Int.pipe(i.check(i.isGreaterThanOrEqualTo(0))),
+		providerMetadata: i.Unknown
+	}),
+	i.Struct({
+		_tag: i.Literal("message"),
+		role: i.String,
+		content: i.String
+	}),
+	i.Struct({
+		_tag: i.Literal("error"),
+		code: a,
+		message: i.String,
+		retryable: i.Boolean
+	}),
+	i.Struct({
+		_tag: i.Literal("done"),
+		finishReason: i.String,
+		usage: o
+	})
+]), c = i.Struct({
+	seq: i.Number,
+	event: s
+});
+//#endregion
+export { a as AgentErrorCode, s as AgentEvent, n as RealtimeClientEvent, r as RealtimeServerEvent, c as SeqEvent, e as TranscriptionStreamError, t as TranscriptionStreamEvent };

package/dist/executableModalities.js

@@ -0,0 +1,13 @@
+//#region src/executableModalities.ts
+var e = {
+	language: "generateText / generateObject / streamText",
+	embedding: "embed / embedMany",
+	image: "generateImage",
+	video: "generateVideo",
+	speech: "generateSpeech",
+	reranking: "rerank",
+	transcription: "transcribe",
+	realtime: "defineRealtimeSession / resolveRealtimeModel"
+}, t = () => new Set(Object.keys(e)), n = (e) => t().has(e.modality);
+//#endregion
+export { e as MODALITY_PRIMITIVE, n as canExecute, t as executableModalities };

package/dist/gateway.js

@@ -0,0 +1,58 @@
+import { capabilitiesOf as e, contextWindowOf as t, dataPolicyOf as n, knowledgeCutoffOf as r, maxOutputTokensOf as i, modalitiesOf as a, modalityOf as o, releasedAtOf as s } from "./gatewayCatalog.js";
+import { createGateway as c, gateway as l } from "@ai-sdk/gateway";
+//#region src/gateway.ts
+var u = (e) => {
+	if (e === void 0) return;
+	let t = Number(e);
+	return Number.isFinite(t) ? t * 1e6 : void 0;
+}, d = (e) => {
+	let t = u(e.pricing?.input), n = u(e.pricing?.output), r = u(e.pricing?.cachedInputTokens ?? void 0);
+	return {
+		id: e.id,
+		name: e.name,
+		...e.description == null ? {} : { description: e.description },
+		modality: o({ model_type: e.modelType }),
+		...t !== void 0 && n !== void 0 ? { pricing: {
+			inputPer1M: t,
+			outputPer1M: n,
+			...r === void 0 ? {} : { cachedInputPer1M: r }
+		} } : {}
+	};
+}, f = async (e = {}) => {
+	let t = (await (e.gatewayProvider ?? (e.apiKey !== void 0 || e.baseURL !== void 0 ? c({
+		...e.apiKey === void 0 ? {} : { apiKey: e.apiKey },
+		...e.baseURL === void 0 ? {} : { baseURL: e.baseURL }
+	}) : l)).getAvailableModels()).models.map(d);
+	return e.modality === void 0 ? t : t.filter((t) => t.modality === e.modality);
+}, p = "https://ai-gateway.vercel.sh/v1", m = async (e = {}) => {
+	let t = (e.baseURL ?? p).replace(/\/+$/, ""), n = e.apiKey ?? process.env.AI_GATEWAY_API_KEY, r = await (e.fetchImpl ?? fetch)(`${t}/models`, { headers: {
+		accept: "application/json",
+		...n === void 0 ? {} : { authorization: `Bearer ${n}` }
+	} });
+	if (!r.ok) throw Error(`gateway catalog: GET ${t}/models answered ${r.status}. Set AI_GATEWAY_API_KEY, or pass \`apiKey\`.`);
+	let i = await r.json(), a = (Array.isArray(i.data) ? i.data : Array.isArray(i.models) ? i.models : []).map(h);
+	return e.modality === void 0 ? a : a.filter((t) => t.modality === e.modality);
+}, h = (c) => {
+	let l = c.pricing ?? {}, d = u(l.input), f = u(l.output), p = u(l.cachedInputTokens), m = t(c), h = i(c), g = s(c), _ = r(c);
+	return {
+		id: String(c.id ?? ""),
+		name: String(c.name ?? c.id ?? ""),
+		...typeof c.description == "string" && c.description !== "" ? { description: c.description } : {},
+		modality: o(c),
+		...d !== void 0 && f !== void 0 ? { pricing: {
+			inputPer1M: d,
+			outputPer1M: f,
+			...p === void 0 ? {} : { cachedInputPer1M: p }
+		} } : {},
+		capabilities: e(c),
+		modalities: a(c),
+		...m === void 0 ? {} : { contextWindow: m },
+		...h === void 0 ? {} : { maxOutputTokens: h },
+		...g === void 0 ? {} : { releasedAt: g },
+		..._ === void 0 ? {} : { knowledgeCutoff: _ },
+		dataPolicy: n(c),
+		raw: c
+	};
+};
+//#endregion
+export { h as fromRaw, f as getAvailableModels, m as readGatewayCatalog, d as toModelInfo };

package/dist/gatewayCatalog.js

@@ -0,0 +1,47 @@
+//#region src/gatewayCatalog.ts
+var e = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string") : [], t = (e) => typeof e == "number" && Number.isFinite(e) ? e : void 0, n = (e) => e === "all" || e === "some" ? e : "none", r = (e) => {
+	let n = t(e);
+	if (n === void 0) return;
+	let r = /* @__PURE__ */ new Date(n * 1e3);
+	return Number.isNaN(r.getTime()) ? void 0 : r.toISOString();
+}, i = (t) => {
+	let n = new Set(e(t.tags)), r = new Set(e(t.supported_parameters)), i = t.modalities ?? {}, a = new Set(e(i.input)), o = new Set(e(i.output));
+	return {
+		vision: n.has("vision") || a.has("image"),
+		reasoning: n.has("reasoning") || r.has("reasoning"),
+		toolUse: n.has("tool-use") || r.has("tools"),
+		structuredOutput: n.has("structured-output") || r.has("response_format"),
+		webSearch: n.has("web-search") || r.has("web_search_options"),
+		caching: n.has("caching") || r.has("prompt_cache_key"),
+		imageOut: o.has("image"),
+		audioOut: o.has("audio"),
+		videoOut: o.has("video"),
+		audioIn: a.has("audio"),
+		videoIn: a.has("video"),
+		fileInput: a.has("file") || a.has("pdf")
+	};
+}, a = (t) => {
+	let n = t.modalities ?? {};
+	return {
+		input: e(n.input),
+		output: e(n.output)
+	};
+}, o = (e) => ({
+	zeroRetention: n(e.zdr),
+	noTraining: n(e.no_training)
+}), s = (e) => t(e.context_window), c = (e) => t(e.max_tokens), l = (e) => r(e.released), u = (e) => typeof e.knowledge == "string" && e.knowledge !== "" ? e.knowledge : void 0, d = (e) => {
+	let t = e.model_type;
+	return typeof t == "string" && [
+		"language",
+		"embedding",
+		"image",
+		"video",
+		"realtime",
+		"reranking",
+		"speech",
+		"transcription",
+		"evaluation"
+	].includes(t) ? t : "unknown";
+};
+//#endregion
+export { i as capabilitiesOf, s as contextWindowOf, o as dataPolicyOf, u as knowledgeCutoffOf, c as maxOutputTokensOf, a as modalitiesOf, d as modalityOf, l as releasedAtOf };

package/dist/gatewayMedia.js

@@ -0,0 +1,88 @@
+import { createGateway as e } from "@ai-sdk/gateway";
+//#region src/gatewayMedia.ts
+var t = (e, t) => {
+	let n = Object.fromEntries(Object.entries(t).filter(([, e]) => e !== void 0));
+	return {
+		...e,
+		fetch: async (t, r) => {
+			let i = e.fetch ?? globalThis.fetch;
+			if (Object.keys(n).length === 0) return i(t, r);
+			if (r?.method !== "POST" || typeof r.body != "string") throw Error("Gateway media: expected a JSON POST to preserve the requested parameters");
+			let a;
+			try {
+				a = JSON.parse(r.body);
+			} catch {
+				throw Error("Gateway media: expected a JSON object to preserve the requested parameters");
+			}
+			if (typeof a != "object" || !a || Array.isArray(a)) throw Error("Gateway media: expected a JSON object to preserve the requested parameters");
+			return i(t, {
+				...r,
+				body: JSON.stringify({
+					...a,
+					...n
+				})
+			});
+		}
+	};
+}, n = (e, t) => {
+	let n = Reflect.get(e, t, e);
+	return typeof n == "function" && t !== "constructor" ? n.bind(e) : n;
+}, r = (r, i) => {
+	let a = e(r).image(i), o = (n) => e(t(r, {
+		seed: n.seed,
+		size: n.size,
+		aspectRatio: n.aspectRatio
+	})).image(i).doGenerate(n);
+	return new Proxy(a, { get: (e, t) => t === "doGenerate" ? o : n(e, t) });
+}, i = (r, i) => {
+	let a = e(r).video(i), o = a.doGenerate === void 0 ? void 0 : (n) => {
+		let a = e(t(r, {
+			seed: n.seed,
+			duration: n.duration,
+			fps: n.fps,
+			aspectRatio: n.aspectRatio,
+			resolution: n.resolution
+		})).video(i);
+		if (!a.doGenerate) throw Error("Gateway video does not implement doGenerate");
+		return a.doGenerate(n);
+	}, s = a.doStart === void 0 ? void 0 : (n) => {
+		let a = e(t(r, {
+			seed: n.seed,
+			duration: n.duration,
+			fps: n.fps,
+			aspectRatio: n.aspectRatio,
+			resolution: n.resolution
+		})).video(i);
+		if (!a.doStart) throw Error("Gateway video does not implement doStart");
+		return a.doStart(n);
+	};
+	return new Proxy(a, { get: (e, t) => t === "doGenerate" ? o : t === "doStart" ? s : n(e, t) });
+}, a = 134217728, o = (e, t = process.env) => {
+	if (e !== void 0) return e;
+	let n = Number(t.VOLTRO_AI_MEDIA_MAX_RESPONSE_BYTES);
+	return Number.isFinite(n) && n > 0 ? Math.floor(n) : a;
+}, s = (e) => `gateway media response exceeded maxResponseBytes (${e}); it was not read further. Raise \`maxResponseBytes\` on the gateway provider config, or VOLTRO_AI_MEDIA_MAX_RESPONSE_BYTES.`, c = (e) => Response.json({ error: {
+	message: s(e),
+	type: "response_too_large"
+} }, { status: 413 }), l = async (e, t) => {
+	let n = Number(e.headers.get("content-length"));
+	if (Number.isFinite(n) && n > t) return e.body?.cancel(), c(t);
+	if (e.body === null) return e;
+	let r = e.body.getReader(), i = [], a = 0;
+	for (;;) {
+		let { done: e, value: n } = await r.read();
+		if (e) break;
+		if (a += n.byteLength, a > t) return r.cancel(), c(t);
+		i.push(new Uint8Array(n));
+	}
+	return new Response(new Blob(i), {
+		status: e.status,
+		statusText: e.statusText,
+		headers: e.headers
+	});
+}, u = (e, t) => ({
+	...e,
+	fetch: async (n, r) => l(await (e.fetch ?? globalThis.fetch)(n, r), t)
+});
+//#endregion
+export { a as DEFAULT_MEDIA_MAX_RESPONSE_BYTES, u as boundedGatewaySettings, r as gatewayImageModel, i as gatewayVideoModel, o as mediaResponseBudget, s as mediaResponseTooLargeMessage };

package/dist/index.d.ts

@@ -108,6 +108,8 @@ export declare const AgentEvent: Schema.Union<readonly [Schema.Struct<{
     readonly id: Schema.String;
     readonly name: Schema.String;
     readonly input: Schema.Unknown;
+    /** Present when the caller must execute this pending call. */
+    readonly execution: Schema.optional<Schema.Literal<"client">>;
 }>, Schema.Struct<{
     readonly _tag: Schema.Literal<"toolResult">;
     readonly id: Schema.String;
@@ -621,6 +623,8 @@ export declare interface AnyTool {
     readonly output?: Schema.Top;
     readonly execute?: (input: never) => Effect.Effect<unknown, never, unknown>;
     readonly handler?: ToolHandler<never, unknown>;
+    /** Client tools return a pending call to the caller; never run on the server. */
+    readonly execution?: 'server' | 'client';
     readonly timeoutMs?: number;
 }
 
@@ -1174,6 +1178,8 @@ export declare const defineTool: <A, I, O>(def: {
     readonly output?: Schema.Top;
     readonly execute?: (input: A) => Effect.Effect<O, never, unknown>;
     readonly handler?: ToolHandler<A, O>;
+    /** Client tools return a pending call to the caller; never run on the server. */
+    readonly execution?: "server" | "client";
     readonly timeoutMs?: number;
 }) => AnyTool;
 
@@ -1208,6 +1214,13 @@ export declare const dispatchInferences: (deps: InferenceDispatchDeps, options?:
  */
 export declare const embed: (text: string, config?: EmbeddingProviderConfig) => Effect.Effect<ReadonlyArray<number>, AiError>;
 
+/**
+ * The embedding provider a call without a config resolves to, and whether
+ * anybody chose it (`AI_EMBED_PROVIDER`, declared in `defineEnv` or set).
+ * `chosen: false` is the mock fallback.
+ */
+export declare const embeddingProviderChoice: (env?: Readonly<Record<string, string | undefined>>) => ProviderChoice;
+
 export declare interface EmbeddingProviderConfig {
     readonly name: EmbeddingProviderName;
     /** Model id. For 'openai': e.g. 'text-embedding-3-small'; for 'gateway' a
@@ -1231,13 +1244,24 @@ export declare interface EmbeddingProviderConfig {
 }
 
 /**
- * Read the embedding-provider config from env:
- *   AI_EMBED_PROVIDER=mock|openai|voyage|cohere|gateway   (default: mock)
+ * Read the embedding-provider config from env — a value declared in
+ * `defineEnv` (its `default` included) before the raw variable:
+ *   AI_EMBED_PROVIDER=mock|openai|voyage|cohere|gateway   (default: mock —
+ *                                                  refused in production)
  *   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;
 
+/**
+ * The env var an embedding provider's SDK reads its key from, for the
+ * providers whose SDK this package resolves by default — `openai` through
+ * `@ai-sdk/openai`, `gateway` through `@ai-sdk/gateway`. `undefined` for the
+ * mock, and for the optional `voyage` / `cohere` packages, whose variable the
+ * boot gate cannot vouch for.
+ */
+export declare const embeddingProviderKeyEnvVar: (name: string) => string | undefined;
+
 export declare type EmbeddingProviderName = 'mock' | 'openai' | 'voyage' | 'cohere' | 'gateway';
 
 /**
@@ -2504,6 +2528,7 @@ export declare type MessagePart = {
     readonly type: 'tool';
     readonly toolCallId: string;
     readonly toolName: string;
+    readonly execution?: 'client';
     /** 'input-available' once the model emitted args; 'output-available' once the tool ran. */
     readonly state: 'input-available' | 'output-available' | 'output-error';
     readonly input?: unknown;
@@ -2851,6 +2876,22 @@ export declare interface PromptVersionRow {
 /** Every registered version of one prompt, newest revision first. */
 export declare const promptVersionsFor: (store: DataStore, promptId: string) => Effect.Effect<ReadonlyArray<PromptVersionRow>>;
 
+/** The provider a call without `provider` resolves to, and whether anybody
+ *  chose it — `useMockAi`, `AI_PROVIDER`, or the app's `defineEnv` declaration.
+ *  `chosen: false` is the mock fallback. */
+export declare interface ProviderChoice {
+    readonly name: string;
+    readonly chosen: boolean;
+}
+
+/**
+ * Which provider is in effect. ONE resolution, exported, so the boot gate that
+ * checks the provider's key checks the provider the calls actually use — the
+ * gate read raw `AI_PROVIDER` while an app's declared default was the value it
+ * meant.
+ */
+export declare const providerChoice: (env?: Readonly<Record<string, string | undefined>>) => ProviderChoice;
+
 /**
  * A resolved provider choice — a DISCRIMINATED UNION on `name`. Each provider
  * only carries the fields that apply to it: the mock-only `mockText` / `script`
@@ -2932,6 +2973,19 @@ export declare type ProviderConfig = {
  */
 export declare type ProviderFallbacks = ReadonlyArray<ProviderConfig>;
 
+/**
+ * Read the provider config. The process-global override (set by `useMockAi`)
+ * wins over env. Otherwise honours, a value declared in `defineEnv` (its
+ * `default` included) before the raw variable:
+ *   AI_PROVIDER=mock|anthropic|openai|gateway   (default: mock — refused in
+ *                          a production process, where nobody chose it)
+ *   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;
 
 /**
@@ -3813,6 +3867,8 @@ export declare const SeqEvent: Schema.Struct<{
         readonly id: Schema.String;
         readonly name: Schema.String;
         readonly input: Schema.Unknown;
+        /** Present when the caller must execute this pending call. */
+        readonly execution: Schema.optional<Schema.Literal<"client">>;
     }>, Schema.Struct<{
         readonly _tag: Schema.Literal<"toolResult">;
         readonly id: Schema.String;
@@ -4180,6 +4236,8 @@ export declare interface ToolDef<A, I, O> {
     readonly execute?: (input: A) => Effect.Effect<O, never, unknown>;
     /** File-convention body: receives `ctx`, returns Effect or Promise. */
     readonly handler?: ToolHandler<A, O>;
+    /** Client tools return a pending call to the caller; never run on the server. */
+    readonly execution?: 'server' | 'client';
     /** Per-call deadline; the tool fails with a timeout error past it. */
     readonly timeoutMs?: number;
 }