@voltro/ai 0.86.0 → 0.88.0

package/dist/agent.js

@@ -1,7 +1,7 @@
 import { AGENT_MESSAGES_TABLE as e } from "./agentConstants.js";
 import { Schema as t } from "effect";
 import { defineAction as n, defineQuery as r } from "@voltro/protocol";
-//#region src/agentDescriptor.ts
+// src/agentDescriptor.ts
 var i = t.Struct({ prompt: t.String }), a = "@voltro/ai/AgentDescriptor", o = class extends t.TaggedError()("AgentThreadAccessDenied", { threadId: t.String }) {
 	get message() {
 		return `agent thread '${this.threadId}' belongs to another subject`;
@@ -60,5 +60,4 @@ var i = t.Struct({ prompt: t.String }), a = "@voltro/ai/AgentDescriptor", o = cl
 		})
 	};
 };
-//#endregion
 export { o as AgentThreadAccessDenied, l as agentInputSchema, d as agentMessageSchema, p as agentRouteDescriptors, s as defineAgent, c as isAgentDescriptor };

package/dist/agentConstants.js

@@ -1,4 +1,3 @@
-//#region src/agentConstants.ts
+// src/agentConstants.ts
 var e = "_voltro_agent_threads", t = "_voltro_agent_messages";
-//#endregion
 export { t as AGENT_MESSAGES_TABLE, e as AGENT_THREADS_TABLE };

package/dist/agentExecutor.js

@@ -1,51 +1,54 @@
-import { AgentThreadAccessDenied as e } from "./agent.js";
-import { appendMessage as t, ensureThreadOwned as n, getMessages as r, getThread as i } from "./threads.js";
-import { historyToModelMessages as a, runAssistant as o } from "./runAndPersist.js";
-import { Effect as s } from "effect";
-//#region src/agentExecutor.ts
-var c = "@voltro/ai/AgentExecutor", l = (e, t) => ({
-	_brand: c,
+import { providerFromEnv as e } from "./provider.js";
+import { AgentThreadAccessDenied as t } from "./agent.js";
+import { appendMessage as n, ensureThreadOwned as r, getMessages as i, getThread as a } from "./threads.js";
+import { historyToModelMessages as o, runAssistant as s } from "./runAndPersist.js";
+import { Effect as c } from "effect";
+// src/agentExecutor.ts
+var l = "@voltro/ai/AgentExecutor", u = (e, t) => ({
+	_brand: l,
 	descriptor: e,
 	config: t
-}), u = (e) => typeof e == "object" && !!e && e._brand === c, d = (e, t) => {
+}), d = (e) => typeof e == "object" && !!e && e._brand === l, f = (e, t) => {
 	let n = e.config.system;
 	if (n !== void 0) return typeof n == "function" ? n(t) : n;
-}, f = (e, t) => {
+}, p = (e, t) => {
 	let n = e.config.model;
 	return typeof n == "function" ? n(t) : n;
-}, p = (e, i, c) => s.gen(function* () {
-	yield* n(i, {
-		threadId: c.threadId,
-		subjectId: c.subjectId ?? null,
-		tenantId: c.tenantId ?? null
+}, m = (t, a, l) => c.gen(function* () {
+	yield* r(a, {
+		threadId: l.threadId,
+		subjectId: l.subjectId ?? null,
+		tenantId: l.tenantId ?? null
 	});
-	let s = c.promptOf ? c.promptOf(c.input) : String(c.input?.prompt ?? ""), l = d(e, c.input), u = f(e, c.input);
-	yield* t(i, {
-		threadId: c.threadId,
+	let u = l.promptOf ? l.promptOf(l.input) : String(l.input?.prompt ?? ""), d = f(t, l.input), m = p(t, l.input) ?? (yield* c.try({
+		try: () => e(),
+		catch: (e) => e instanceof Error ? e : Error(String(e))
+	}));
+	yield* n(a, {
+		threadId: l.threadId,
 		role: "user",
-		content: s,
-		tenantId: c.tenantId ?? null,
-		order: c.order
+		content: u,
+		tenantId: l.tenantId ?? null,
+		order: l.order
 	});
-	let p = yield* r(i, c.threadId), m = a(p);
-	return yield* o(i, {
-		threadId: c.threadId,
-		tenantId: c.tenantId ?? null,
-		prompt: s,
-		...m.length > 0 ? { messages: m } : {},
-		...l === void 0 ? {} : { system: l },
-		...e.config.tools === void 0 ? {} : { tools: e.config.tools },
-		...u === void 0 ? {} : { provider: u },
-		...e.config.maxSteps === void 0 ? {} : { maxSteps: e.config.maxSteps },
-		...e.config.providerOptions === void 0 ? {} : { providerOptions: e.config.providerOptions },
-		...c.toolContext === void 0 ? {} : { toolContext: c.toolContext },
-		order: c.order + 1,
-		...c.throttleMs === void 0 ? {} : { throttleMs: c.throttleMs },
-		agent: e.descriptor.name
+	let h = yield* i(a, l.threadId), g = o(h);
+	return yield* s(a, {
+		threadId: l.threadId,
+		tenantId: l.tenantId ?? null,
+		prompt: u,
+		...g.length > 0 ? { messages: g } : {},
+		...d === void 0 ? {} : { system: d },
+		...t.config.tools === void 0 ? {} : { tools: t.config.tools },
+		provider: m,
+		...t.config.maxSteps === void 0 ? {} : { maxSteps: t.config.maxSteps },
+		...t.config.providerOptions === void 0 ? {} : { providerOptions: t.config.providerOptions },
+		...l.toolContext === void 0 ? {} : { toolContext: l.toolContext },
+		order: l.order + 1,
+		...l.throttleMs === void 0 ? {} : { throttleMs: l.throttleMs },
+		agent: t.descriptor.name
 	});
-}), m = (t, n, a = null) => s.gen(function* () {
-	let o = yield* i(t, n);
-	return o !== null && o.subjectId !== null && o.subjectId !== a ? yield* s.fail(new e({ threadId: n })) : yield* r(t, n);
+}), h = (e, n, r = null) => c.gen(function* () {
+	let o = yield* a(e, n);
+	return o !== null && o.subjectId !== null && o.subjectId !== r ? yield* c.fail(new t({ threadId: n })) : yield* i(e, n);
 });
-//#endregion
-export { l as defineAgentExecutor, u as isAgentExecutor, m as loadAgentMessages, f as resolveAgentModel, d as resolveSystem, p as runAgentTurn };
+export { u as defineAgentExecutor, d as isAgentExecutor, h as loadAgentMessages, p as resolveAgentModel, f as resolveSystem, m as runAgentTurn };

package/dist/aiSettings.js

@@ -0,0 +1,10 @@
+import { readEnvValue as e } from "@voltro/env";
+// src/aiSettings.ts
+var t = (t, n) => {
+	let r = e(t);
+	if (typeof r == "string" && r !== "") return r;
+	if (typeof r == "number" || typeof r == "boolean") return String(r);
+	let i = n[t];
+	return i === void 0 || i === "" ? void 0 : i;
+}, n = (e) => e.NODE_ENV === "production";
+export { t as aiSetting, n as isProductionEnv };

package/dist/api.js

@@ -7,7 +7,7 @@ import { captureStructuredEvidence as c } from "./structuredEvidence.js";
 import { NoObjectGeneratedError as l, Output as u, generateObject as d, generateText as f, jsonSchema as p, stepCountIs as m } from "ai";
 import { Context as h, Effect as g, Schema as _ } from "effect";
 import { jsonSchemaOf as v } from "@voltro/protocol";
-//#region src/api.ts
+// src/api.ts
 var y = class extends _.TaggedError()("AiError", {
 	reason: _.Literals(["generation", "decode"]),
 	message: _.String,
@@ -195,5 +195,4 @@ var y = class extends _.TaggedError()("AiError", {
 	generateText: (e) => C(e),
 	generateObject: (e) => D(e)
 };
-//#endregion
 export { y as AiError, k as AiService, b as aiGenerationError, A as defaultAiService, D as generateObject, E as generateObjectJson, O as generateObjectWithTools, C as generateText, T as outputJsonSchema };

package/dist/appTools.js

@@ -1,5 +1,5 @@
 import { defineTool as e } from "./tools.js";
-//#region src/appTools.ts
+// src/appTools.ts
 var t = /* @__PURE__ */ new Map(), n = (e) => {
 	let n = t.get(e);
 	if (n !== void 0) return n;
@@ -76,5 +76,4 @@ var t = /* @__PURE__ */ new Map(), n = (e) => {
 	...t.descriptor.output === void 0 ? {} : { output: t.descriptor.output },
 	handler: (e) => Promise.resolve(t.invoke(e))
 }));
-//#endregion
 export { s as agentActor, l as appToolDecision, d as appTools, a as passesPolicy, u as synthesizeToolSpecs };

package/dist/budget.js

@@ -1,6 +1,6 @@
 import { Effect as e, Schema as t } from "effect";
 import { and as n, bigint as r, eq as i, generateId as a, id as o, isNull as s, queryFor as c, registerRetention as l, retentionTtlMsFromEnv as u, table as d, text as f, timestamp as p } from "@voltro/database";
-//#region src/budget.ts
+// src/budget.ts
 var m = class extends t.TaggedError()("AiBudgetExceeded", {
 	tenantId: t.NullOr(t.String),
 	limitUsd: t.Number,
@@ -197,5 +197,4 @@ var m = class extends t.TaggedError()("AiBudgetExceeded", {
 		return "released";
 	}));
 });
-//#endregion
 export { v as AI_BUDGET_RESERVATIONS_TABLE, _ as AI_BUDGET_TABLE, m as AiBudgetExceeded, h as AiBudgetInvalidInput, g as AiBudgetReservationConflict, b as aiBudgetReservationsTable, y as aiBudgetTable, A as releaseAiBudget, k as requireAiBudget };

package/dist/callEvidence.js

@@ -1,6 +1,6 @@
 import { gatewayCostUsd as e } from "./cost.js";
 import { Schema as t } from "effect";
-//#region src/callEvidence.ts
+// src/callEvidence.ts
 var n = t.Number.pipe(t.check(t.isInt()), t.check(t.isGreaterThanOrEqualTo(0)), t.check(t.isLessThanOrEqualTo(2 ** 53 - 1))), r = t.Struct({
 	provider: t.String,
 	model: t.String,
@@ -47,5 +47,4 @@ var n = t.Number.pipe(t.check(t.isInt()), t.check(t.isGreaterThanOrEqualTo(0)),
 		}
 	};
 };
-//#endregion
 export { r as AiCallEvidenceSchema, a as normalizeAiCallEvidence };

package/dist/copilot.js

@@ -1,6 +1,6 @@
 import { Schema as e } from "effect";
 import { and as t, contains as n, eq as r, gt as i, gte as a, inSet as o, lt as s, lte as c, neq as l } from "@voltro/database";
-//#region src/copilot.ts
+// src/copilot.ts
 var u = class extends e.TaggedError()("CopilotRejected", {
 	reason: e.Literals([
 		"unknown-table",
@@ -122,5 +122,4 @@ var u = class extends e.TaggedError()("CopilotRejected", {
 		prompt: e
 	}), t);
 };
-//#endregion
 export { d as COPILOT_MAX_LIMIT, _ as CopilotProposalSchema, u as CopilotRejected, v as buildCopilotSystemPrompt, y as runDataCopilot, g as validateCopilotProposal };

package/dist/cost.js

@@ -1,7 +1,7 @@
 import { AI_BUDGET_RESERVATIONS_TABLE as e, AI_BUDGET_TABLE as t, AiBudgetExceeded as n, AiBudgetInvalidInput as r, AiBudgetReservationConflict as i, aiBudgetReservationsTable as a, aiBudgetTable as o, releaseAiBudget as s, requireAiBudget as c } from "./budget.js";
 import { Data as l, Effect as u } from "effect";
 import { and as d, eq as f, generateId as p, gte as m, id as h, integer as g, queryFor as _, registerRetention as v, retentionTtlMsFromEnv as y, table as b, text as x, timestamp as S } from "@voltro/database";
-//#region src/cost.ts
+// src/cost.ts
 var C = {
 	"claude-opus-4-8": {
 		inputPer1M: 15,
@@ -238,5 +238,4 @@ var C = {
 	], r = _(M), i = n.length === 0 ? r : r.where(n.length === 1 ? n[0] : d(...n));
 	return (await e.query(i.descriptor)).reduce((e, t) => e + (Number(t.costMicroUsd) || 0), 0) / 1e6;
 });
-//#endregion
 export { e as AI_BUDGET_RESERVATIONS_TABLE, t as AI_BUDGET_TABLE, j as AI_USAGE_TABLE, n as AiBudgetExceeded, r as AiBudgetInvalidInput, i as AiBudgetReservationConflict, I as AiUsageLedgerError, F as AiUsageReceiptConflict, C as MODEL_PRICING_DEFAULTS, a as aiBudgetReservationsTable, o as aiBudgetTable, V as aiSpendUsd, M as aiUsageTable, A as estimateCostUsd, P as gatewayCostUsd, O as isMeteredUsage, E as modelPricing, k as normaliseUsage, D as priceForModel, R as recordAiUsage, B as recordAiUsageBestEffort, s as releaseAiBudget, c as requireAiBudget, T as setModelPricing };

package/dist/embed.js

@@ -2,7 +2,7 @@ import { aiGenerationError as e } from "./api.js";
 import { embeddingProviderFromEnv as t, resolveEmbeddingModel as n } from "./embeddingProvider.js";
 import { cosineSimilarity as r, embed as i, embedMany as a } from "ai";
 import { Effect as o } from "effect";
-//#region src/embed.ts
+// src/embed.ts
 var s = (r, a) => o.tryPromise({
 	try: async (e) => {
 		let o = a ?? t();
@@ -37,5 +37,4 @@ var s = (r, a) => o.tryPromise({
 	if (t !== void 0 && e.length !== t) throw Error(`embedding ${n}: expected ${t} dimensions, received ${e.length}`);
 	if (e.length === 0 || e.some((e) => !Number.isFinite(e))) throw Error(`embedding ${n}: expected a non-empty vector of finite numbers`);
 }, d = (e, t) => r([...e], [...t]);
-//#endregion
 export { d as cosineSimilarity, s as embed, c as embedMany };

package/dist/embeddingProvider.js

@@ -1,17 +1,18 @@
-import { createGateway as e, gateway as t } from "@ai-sdk/gateway";
-//#region src/embeddingProvider.ts
-var n = (e, t) => ({
+import { aiSetting as e, isProductionEnv as t } from "./aiSettings.js";
+import { createGateway as n, gateway as r } from "@ai-sdk/gateway";
+// src/embeddingProvider.ts
+var i = (e, t) => ({
 	specificationVersion: "v4",
 	provider: "mock",
 	modelId: e,
 	maxEmbeddingsPerCall: 2048,
 	supportsParallelCalls: !0,
 	doEmbed: async ({ values: e }) => ({
-		embeddings: e.map((e) => r(e, t)),
+		embeddings: e.map((e) => a(e, t)),
 		usage: { tokens: e.reduce((e, t) => e + t.length, 0) },
 		warnings: []
 	})
-}), r = (e, t) => {
+}), a = (e, t) => {
 	let n = Array(t);
 	for (let r = 0; r < t; r++) {
 		let t = 2166136261 ^ r * 16777619;
@@ -19,18 +20,18 @@ var n = (e, t) => ({
 		n[r] = (t >>> 0) / 4294967295 * 2 - 1;
 	}
 	return n;
-}, i = async (r) => {
-	switch (r.name) {
-		case "mock": return n(r.model, r.mockDim ?? 8);
-		case "openai": return (await a("@ai-sdk/openai", "openai")).openai.textEmbeddingModel(r.model);
-		case "voyage": return (await a("voyage-ai-provider", "voyage")).voyage.textEmbeddingModel(r.model);
-		case "cohere": return (await a("@ai-sdk/cohere", "cohere")).cohere.textEmbeddingModel(r.model);
-		case "gateway": return (r.apiKey !== void 0 || r.baseURL !== void 0 ? e({
-			...r.apiKey === void 0 ? {} : { apiKey: r.apiKey },
-			...r.baseURL === void 0 ? {} : { baseURL: r.baseURL }
-		}) : t).embeddingModel(r.model);
+}, o = async (e) => {
+	switch (e.name) {
+		case "mock": return i(e.model, e.mockDim ?? 8);
+		case "openai": return (await s("@ai-sdk/openai", "openai")).openai.textEmbeddingModel(e.model);
+		case "voyage": return (await s("voyage-ai-provider", "voyage")).voyage.textEmbeddingModel(e.model);
+		case "cohere": return (await s("@ai-sdk/cohere", "cohere")).cohere.textEmbeddingModel(e.model);
+		case "gateway": return (e.apiKey !== void 0 || e.baseURL !== void 0 ? n({
+			...e.apiKey === void 0 ? {} : { apiKey: e.apiKey },
+			...e.baseURL === void 0 ? {} : { baseURL: e.baseURL }
+		}) : r).embeddingModel(e.model);
 	}
-}, a = async (e, t) => {
+}, s = async (e, t) => {
 	try {
 		return await import(
 			/* @vite-ignore */
@@ -39,13 +40,29 @@ var n = (e, t) => ({
 	} catch {
 		throw Error(`embedding provider '${t}' needs the '${e}' package — install it (pnpm add ${e}) or use AI_EMBED_PROVIDER=mock for tests/demos.`);
 	}
-}, o = (e = process.env) => {
-	let t = (e.AI_EMBED_PROVIDER ?? "mock").toLowerCase(), n = t === "openai" ? "text-embedding-3-small" : t === "voyage" ? "voyage-3" : t === "cohere" ? "embed-english-v3.0" : t === "gateway" ? "openai/text-embedding-3-small" : "mock", r = e.AI_EMBED_MODEL ?? n, i = e.AI_EMBED_MOCK_DIM === void 0 ? void 0 : Number(e.AI_EMBED_MOCK_DIM);
+}, c = (e) => {
+	switch (e.toLowerCase()) {
+		case "openai": return "OPENAI_API_KEY";
+		case "gateway": return "AI_GATEWAY_API_KEY";
+		default: return;
+	}
+}, l = (t = process.env) => {
+	let n = e("AI_EMBED_PROVIDER", t);
+	return n === void 0 ? {
+		name: "mock",
+		chosen: !1
+	} : {
+		name: n.toLowerCase(),
+		chosen: !0
+	};
+}, u = (n = process.env) => {
+	let r = l(n);
+	if (!r.chosen && t(n)) throw Error("No embedding provider is chosen in this production process: AI_EMBED_PROVIDER is unset and this call passes no config, so it would embed with the mock provider, whose vectors carry no meaning. Set AI_EMBED_PROVIDER (openai | voyage | cohere | gateway) for every process that embeds, or declare it in `defineEnv` with a `default`, or pass a config to the call. Set AI_EMBED_PROVIDER=mock to embed with the mock deliberately.");
+	let i = r.name, a = i === "openai" ? "text-embedding-3-small" : i === "voyage" ? "voyage-3" : i === "cohere" ? "embed-english-v3.0" : i === "gateway" ? "openai/text-embedding-3-small" : "mock", o = e("AI_EMBED_MODEL", n) ?? a, s = e("AI_EMBED_MOCK_DIM", n), c = s === void 0 ? void 0 : Number(s);
 	return {
-		name: t,
-		model: r,
-		...i !== void 0 && Number.isFinite(i) ? { mockDim: i } : {}
+		name: i,
+		model: o,
+		...c !== void 0 && Number.isFinite(c) ? { mockDim: c } : {}
 	};
 };
-//#endregion
-export { o as embeddingProviderFromEnv, r as hashToVector, i as resolveEmbeddingModel };
+export { l as embeddingProviderChoice, u as embeddingProviderFromEnv, c as embeddingProviderKeyEnvVar, a as hashToVector, o as resolveEmbeddingModel };

package/dist/eval.js

@@ -1,7 +1,7 @@
 import { providerFromEnv as e } from "./provider.js";
 import { generateObject as t } from "./api.js";
 import { Effect as n, Schema as r } from "effect";
-//#region src/eval.ts
+// src/eval.ts
 var i = (e) => {
 	if (e.name.trim() === "") throw Error("defineEval: name must be non-empty");
 	if (e.cases.length === 0) throw Error(`defineEval "${e.name}": at least one case is required`);
@@ -126,5 +126,4 @@ var i = (e) => {
 	score: 0,
 	reason: `judge failed: ${e.message}`
 }))));
-//#endregion
 export { s as DEFAULT_JUDGE_THRESHOLD, i as defineEval, o as evaluateAssertions, a as isEvalDefinition, f as llmJudge, l as runEval, c as scoreCase };

package/dist/events.js

@@ -1,7 +1,7 @@
 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
+// src/agentEvent.ts
 var a = i.Literals([
 	"provider",
 	"tool",
@@ -77,5 +77,4 @@ var a = i.Literals([
 	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

@@ -1,4 +1,4 @@
-//#region src/executableModalities.ts
+// src/executableModalities.ts
 var e = {
 	language: "generateText / generateObject / streamText",
 	embedding: "embed / embedMany",
@@ -9,5 +9,4 @@ var e = {
 	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

@@ -1,6 +1,6 @@
 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
+// src/gateway.ts
 var u = (e) => {
 	if (e === void 0) return;
 	let t = Number(e);
@@ -54,5 +54,4 @@ var u = (e) => {
 		raw: c
 	};
 };
-//#endregion
 export { h as fromRaw, f as getAvailableModels, m as readGatewayCatalog, d as toModelInfo };

package/dist/gatewayCatalog.js

@@ -1,4 +1,4 @@
-//#region src/gatewayCatalog.ts
+// 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;
@@ -43,5 +43,4 @@ var e = (e) => Array.isArray(e) ? e.filter((e) => typeof e == "string") : [], t
 		"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

@@ -1,5 +1,5 @@
 import { createGateway as e } from "@ai-sdk/gateway";
-//#region src/gatewayMedia.ts
+// src/gatewayMedia.ts
 var t = (e, t) => {
 	let n = Object.fromEntries(Object.entries(t).filter(([, e]) => e !== void 0));
 	return {
@@ -84,5 +84,4 @@ var t = (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

@@ -1214,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
@@ -1237,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';
 
 /**
@@ -2858,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`
@@ -2939,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;
 
 /**