@statelyai/agent 1.1.6 → 2.0.0-alpha.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Stately Software, Inc.
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/adapter.cjs

@@ -0,0 +1,15 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_events = require("./events-CRQj3VtP.cjs");
+exports.bindRequestExecutor = require_events.bindRequestExecutor;
+exports.buildEnvelopeSchema = require_events.buildEnvelopeSchema;
+exports.getAgentOutputMode = require_events.getAgentOutputMode;
+exports.getJsonSchema = require_events.getJsonSchema;
+exports.getJsonSchemaSync = require_events.getJsonSchemaSync;
+exports.getMachineStructuralHash = require_events.getMachineStructuralHash;
+exports.isStandardSchema = require_events.isStandardSchema;
+exports.isStructuredOutputSchema = require_events.isStructuredOutputSchema;
+exports.matchesEventPattern = require_events.matchesEventPattern;
+exports.parseModelRef = require_events.parseModelRef;
+exports.parseOutput = require_events.parseOutput;
+exports.parseStructuredEnvelope = require_events.parseStructuredEnvelope;
+exports.validateSchemaSync = require_events.validateSchemaSync;

package/dist/adapter.d.cts

@@ -0,0 +1,4 @@
+import { C as StandardSchemaV1 } from "./types-C9QiMjre.cjs";
+import { D as parseOutput, E as parseModelRef, J as matchesEventPattern, O as parseStructuredEnvelope, S as buildEnvelopeSchema, T as isStructuredOutputSchema, a as AgentRequestExecutorInfo, h as TextLogic, i as AgentRequestExecutor, l as AgentTextRequest, m as StructuredOutputEnvelope, o as AgentRequestExecutorResult, r as AgentOutputMode, w as getAgentOutputMode, x as bindRequestExecutor } from "./text-logic-Ckhr2kKC.cjs";
+import { a as getMachineStructuralHash, f as validateSchemaSync, i as getJsonSchemaSync, r as getJsonSchema, s as isStandardSchema } from "./utils-BYqT_Dyv.cjs";
+export { type AgentOutputMode, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentTextRequest, type StandardSchemaV1, type StructuredOutputEnvelope, type TextLogic, bindRequestExecutor, buildEnvelopeSchema, getAgentOutputMode, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, isStandardSchema, isStructuredOutputSchema, matchesEventPattern, parseModelRef, parseOutput, parseStructuredEnvelope, validateSchemaSync };

package/dist/adapter.d.mts

@@ -0,0 +1,4 @@
+import { C as StandardSchemaV1 } from "./types-qm00QF91.mjs";
+import { D as parseOutput, E as parseModelRef, J as matchesEventPattern, O as parseStructuredEnvelope, S as buildEnvelopeSchema, T as isStructuredOutputSchema, a as AgentRequestExecutorInfo, h as TextLogic, i as AgentRequestExecutor, l as AgentTextRequest, m as StructuredOutputEnvelope, o as AgentRequestExecutorResult, r as AgentOutputMode, w as getAgentOutputMode, x as bindRequestExecutor } from "./text-logic-CaKqgX4Y.mjs";
+import { a as getMachineStructuralHash, f as validateSchemaSync, i as getJsonSchemaSync, r as getJsonSchema, s as isStandardSchema } from "./utils-Do5wIJrh.mjs";
+export { type AgentOutputMode, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentTextRequest, type StandardSchemaV1, type StructuredOutputEnvelope, type TextLogic, bindRequestExecutor, buildEnvelopeSchema, getAgentOutputMode, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, isStandardSchema, isStructuredOutputSchema, matchesEventPattern, parseModelRef, parseOutput, parseStructuredEnvelope, validateSchemaSync };

package/dist/adapter.mjs

@@ -0,0 +1,2 @@
+import { F as getMachineStructuralHash, H as validateSchemaSync, L as isStandardSchema, N as getJsonSchema, P as getJsonSchemaSync, b as parseOutput, d as buildEnvelopeSchema, g as isStructuredOutputSchema, h as getAgentOutputMode, r as matchesEventPattern, u as bindRequestExecutor, x as parseStructuredEnvelope, y as parseModelRef } from "./events-JiVPYrct.mjs";
+export { bindRequestExecutor, buildEnvelopeSchema, getAgentOutputMode, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, isStandardSchema, isStructuredOutputSchema, matchesEventPattern, parseModelRef, parseOutput, parseStructuredEnvelope, validateSchemaSync };

package/dist/ai-sdk.cjs

@@ -0,0 +1,306 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_events = require("./events-CRQj3VtP.cjs");
+const require_decision = require("./decision-D8wJrM8W.cjs");
+let ai = require("ai");
+//#region src/ai-sdk/mappers.ts
+/**
+* Maps an {@link AgentTools} map onto AI SDK `tool()` definitions. A tool that
+* already carries its own Standard Schema `inputSchema` — an AI SDK
+* `tool({...})`, or any equivalent descriptor — is passed through **unchanged**,
+* so the SDK applies its own validation, calls `execute(input, options)`, and
+* every extra property (`providerOptions`, `toModelOutput`, …) survives. A bare
+* `AgentToolExecute` function becomes a tool with an unconstrained input schema;
+* a minimal descriptor with no readable schema is converted with a permissive
+* fallback. Used by {@link toAiSdkCallSettings}.
+*/
+function toAiSdkTools(tools) {
+	const entries = [];
+	for (const [name, descriptor] of Object.entries(tools)) {
+		if (!descriptor) continue;
+		if (typeof descriptor === "function") {
+			entries.push([name, (0, ai.tool)({
+				inputSchema: unknownSchema,
+				execute: (input) => descriptor(input)
+			})]);
+			continue;
+		}
+		if (require_events.isStandardSchema(descriptor.inputSchema)) {
+			entries.push([name, descriptor]);
+			continue;
+		}
+		const inputSchema = descriptor.inputSchema ?? descriptor.schemas?.input;
+		const toolOptions = {
+			description: descriptor.description,
+			inputSchema: inputSchema ? inputSchema : unknownSchema
+		};
+		if (descriptor.execute) {
+			entries.push([name, (0, ai.tool)({
+				...toolOptions,
+				execute: (input) => descriptor.execute?.(input)
+			})]);
+			continue;
+		}
+		entries.push([name, (0, ai.tool)(toolOptions)]);
+	}
+	return Object.fromEntries(entries);
+}
+const unknownSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate: (value) => ({ value }),
+	jsonSchema: { input: () => ({}) }
+} };
+/**
+* AI SDK request-mapping settings shared by `generateText`/`streamText`.
+* `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
+* are structurally compatible by design (§1 of .scratch/p0-design.md) — the cast
+* below is a typed identity mapping, not a semantic conversion.
+*/
+function toAiSdkCallSettings(request) {
+	const messages = request.messages;
+	return {
+		system: request.system,
+		...messages ? { messages } : { prompt: request.prompt ?? "" },
+		temperature: request.temperature,
+		maxOutputTokens: request.maxOutputTokens,
+		topP: request.topP,
+		topK: request.topK,
+		seed: request.seed,
+		stopSequences: request.stopSequences,
+		tools: request.tools ? toAiSdkTools(request.tools) : void 0,
+		toolChoice: toAiSdkToolChoice(request.toolChoice)
+	};
+}
+/** Maps an {@link AgentToolChoice} to AI SDK's tool-choice shape — `{ type: 'tool'; name }` becomes `{ type: 'tool'; toolName }`; `'auto'`/`'none'`/`'required'`/`undefined` pass through unchanged. */
+function toAiSdkToolChoice(toolChoice) {
+	return typeof toolChoice === "object" ? {
+		type: "tool",
+		toolName: toolChoice.name
+	} : toolChoice;
+}
+/** `true` when the request should use AI SDK structured `Output.object`. */
+function isStructuredOutputRequest(request) {
+	return require_events.getAgentOutputMode(request.outputSchema) === "structured";
+}
+/**
+* Extracts the first complete top-level JSON value from `text`, or returns
+* `undefined` when there is nothing to repair (no complete value, or the value
+* already spans the whole text). Models occasionally emit two structured-output
+* envelopes back to back (`{"result":{…}}{"result":{…}}`), which fails JSON
+* parsing wholesale; the balanced scan below recovers the first value and
+* drops the rest.
+*/
+function extractFirstJsonValue(text) {
+	const start = text.search(/[{[]/);
+	if (start === -1) return;
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i];
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") inString = true;
+		else if (char === "{" || char === "[") depth++;
+		else if (char === "}" || char === "]") {
+			depth--;
+			if (depth === 0) {
+				const value = text.slice(start, i + 1);
+				return value === text.trim() ? void 0 : value;
+			}
+		}
+	}
+}
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+* toolChoice: 'required'" recipe from .scratch/p0-design.md §2.6. */
+function toAiSdkEventTools(events) {
+	return Object.fromEntries(events.map((event) => [event.toolName, (0, ai.tool)({
+		description: `Choose the '${event.type}' move.`,
+		inputSchema: event.inputSchema ? event.inputSchema : unknownSchema
+	})]));
+}
+/**
+* Messages for a decision request, with prior failed `attempts` (§2.6)
+* rendered as appended user messages (via core's {@link renderDecisionAttempts})
+* so retries converge. Core never rewrites prompts — this is adapter business.
+*/
+function toDecisionMessages(request) {
+	if (!request.messages && request.attempts.length === 0) return;
+	const messages = [...request.messages ?? (request.prompt !== void 0 ? [{
+		role: "user",
+		content: request.prompt
+	}] : [])];
+	for (const attempt of require_decision.renderDecisionAttempts(request)) messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return messages;
+}
+//#endregion
+//#region src/ai-sdk/index.ts
+function maxStepsSetting(request) {
+	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: (0, ai.stepCountIs)(request.metadata.maxSteps) } : {};
+}
+/**
+* Identity helper for a `models` map whose value is exported. Returns the map
+* unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
+* portable, nameable type — so an exported `const models = defineModels({...})`
+* needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
+* TS2742 ("inferred type cannot be named without a reference to …"). The exact
+* ref keys survive, so `createAiSdkExecutors({ models })` and
+* `setupAgent({ models })` still infer/autocomplete them.
+*
+* @example
+* ```ts
+* export const models = defineModels({
+*   quick: openai('gpt-5.4-mini'),
+*   deep: openai('gpt-5.4'),
+* });
+* // typeof models === AiSdkModelMap<'quick' | 'deep'>
+* ```
+*/
+function defineModels(models) {
+	return models;
+}
+function resolveAiSdkModel(options, modelRef) {
+	if (options.resolveModel) return options.resolveModel(modelRef);
+	const models = options.models;
+	if (!models) throw new Error(`createAiSdkExecutors: no model resolver configured for '${modelRef}'.`);
+	const model = models[modelRef];
+	if (!model) throw new Error(`createAiSdkExecutors: unknown model '${modelRef}'.`);
+	return model;
+}
+function withJsonRepair(output) {
+	return {
+		...output,
+		parseCompleteOutput: async (options, context) => {
+			try {
+				return await output.parseCompleteOutput(options, context);
+			} catch (error) {
+				const repaired = extractFirstJsonValue(options.text);
+				if (repaired === void 0) throw error;
+				return await output.parseCompleteOutput({
+					...options,
+					text: repaired
+				}, context);
+			}
+		}
+	};
+}
+/**
+* The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
+* decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
+* must not become a dependency of core `src/` files — this subpath is the one
+* place it's imported, and callers must supply their own model resolver so no
+* concrete provider package (e.g. `@ai-sdk/openai`) becomes a dependency here
+* either.
+*
+* @example
+* ```ts
+* const executors = createAiSdkExecutors({ models: { quick: openai('gpt-5.4-mini') } });
+* const result = await runAgent(machine, { input, executors });
+* ```
+*/
+function createAiSdkExecutors(options) {
+	const generateText = async (request, info) => {
+		const common = {
+			model: resolveAiSdkModel(options, request.model),
+			abortSignal: info?.signal,
+			...toAiSdkCallSettings(request),
+			...maxStepsSetting(request)
+		};
+		if (isStructuredOutputRequest(request)) {
+			const envelope = require_events.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
+			const structuredOutput = withJsonRepair(ai.Output.object({ schema: envelope }));
+			const canRetry = !request.tools || Object.keys(request.tools).length === 0;
+			let result;
+			try {
+				result = await (0, ai.generateText)({
+					...common,
+					output: structuredOutput
+				});
+			} catch (error) {
+				if (!canRetry || !ai.NoObjectGeneratedError.isInstance(error) || info?.signal?.aborted) throw error;
+				result = await (0, ai.generateText)({
+					...common,
+					output: structuredOutput
+				});
+			}
+			const { result: output, reasoning } = result.output;
+			return {
+				output,
+				...reasoning !== void 0 ? { reasoning } : {},
+				usage: result.usage,
+				finishReason: result.finishReason,
+				toolCalls: result.toolCalls,
+				toolResults: result.toolResults
+			};
+		}
+		const result = await (0, ai.generateText)(common);
+		return {
+			output: result.text,
+			usage: result.usage,
+			finishReason: result.finishReason,
+			toolCalls: result.toolCalls,
+			toolResults: result.toolResults
+		};
+	};
+	const streamText = async (request, info) => {
+		const result = (0, ai.streamText)({
+			model: resolveAiSdkModel(options, request.model),
+			abortSignal: info?.signal,
+			...toAiSdkCallSettings(request),
+			...maxStepsSetting(request)
+		});
+		for await (const chunk of result.textStream) info?.onChunk?.(chunk);
+		return {
+			output: await result.text,
+			usage: await result.usage,
+			finishReason: await result.finishReason
+		};
+	};
+	const decide = async (request) => {
+		const model = resolveAiSdkModel(options, request.model);
+		const tools = toAiSdkEventTools(request.events);
+		const messages = toDecisionMessages(request);
+		const result = await (0, ai.generateText)({
+			model,
+			abortSignal: request.signal,
+			system: request.system,
+			...messages ? { messages } : { prompt: request.prompt ?? "" },
+			tools,
+			toolChoice: "required",
+			stopWhen: (0, ai.stepCountIs)(1),
+			temperature: request.temperature,
+			maxOutputTokens: request.maxOutputTokens,
+			topP: request.topP,
+			topK: request.topK,
+			seed: request.seed,
+			stopSequences: request.stopSequences
+		});
+		const toolCall = result.toolCalls[0];
+		if (!toolCall) throw new Error("createAiSdkExecutors: decide — model did not call an event tool.");
+		const chosenEvent = request.events.find((event) => event.toolName === toolCall.toolName);
+		if (!chosenEvent) throw new Error(`createAiSdkExecutors: decide — model called unknown tool '${toolCall.toolName}'.`);
+		return {
+			event: {
+				...toolCall.input && typeof toolCall.input === "object" ? toolCall.input : {},
+				type: chosenEvent.type
+			},
+			usage: result.usage,
+			finishReason: result.finishReason
+		};
+	};
+	return {
+		generateText,
+		streamText,
+		decide
+	};
+}
+//#endregion
+exports.createAiSdkExecutors = createAiSdkExecutors;
+exports.defineModels = defineModels;

package/dist/ai-sdk.d.cts

@@ -0,0 +1,96 @@
+import { m as ChosenEvent } from "./types-C9QiMjre.cjs";
+import { i as AgentRequestExecutor, k as AgentDecisionExecutor, s as AgentRequestExecutors } from "./text-logic-Ckhr2kKC.cjs";
+import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
+
+//#region src/ai-sdk/index.d.ts
+/** AI SDK model registry: maps model refs (as used in `setupAgent({ models })`/`AgentTextRequest.model`) to AI SDK `LanguageModel` values. The optional `TKey` parameter pins the ref keys (see {@link defineModels}); it defaults to `string`, so bare `AiSdkModelMap` stays `Record<string, LanguageModel>`. */
+type AiSdkModelMap<TKey extends string = string> = Record<TKey, LanguageModel>;
+/**
+ * Identity helper for a `models` map whose value is exported. Returns the map
+ * unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
+ * portable, nameable type — so an exported `const models = defineModels({...})`
+ * needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
+ * TS2742 ("inferred type cannot be named without a reference to …"). The exact
+ * ref keys survive, so `createAiSdkExecutors({ models })` and
+ * `setupAgent({ models })` still infer/autocomplete them.
+ *
+ * @example
+ * ```ts
+ * export const models = defineModels({
+ *   quick: openai('gpt-5.4-mini'),
+ *   deep: openai('gpt-5.4'),
+ * });
+ * // typeof models === AiSdkModelMap<'quick' | 'deep'>
+ * ```
+ */
+declare function defineModels<T extends Record<string, LanguageModel>>(models: T): AiSdkModelMap<keyof T & string>;
+/**
+ * Options for {@link createAiSdkExecutors}: either a static `models` map
+ * (model refs resolved by lookup), a `resolveModel` function (refs resolved
+ * dynamically, e.g. `"openai/gpt-5.4-mini"` → `openai('gpt-5.4-mini')`), or
+ * both — `resolveModel` takes precedence when both are supplied.
+ */
+type CreateAiSdkExecutorsOptions<TModels extends AiSdkModelMap = AiSdkModelMap> = {
+  models: TModels;
+  resolveModel?: (modelRef: keyof TModels & string) => LanguageModel;
+} | {
+  models?: TModels;
+  resolveModel: (modelRef: string) => LanguageModel;
+};
+/**
+ * Raw result shape from {@link AiSdkExecutors.generateText} — the `{ output }`
+ * envelope (the validated structured object for structured-output requests,
+ * or the accumulated text string otherwise; unwrapped by
+ * `normalizeGeneratorResult`) plus the AI SDK call metadata. Core only reads
+ * `output`; everything else flows verbatim to `runAgent`'s
+ * `onResult(request, { raw })`, so `raw as AiSdkGenerateResult` is the
+ * supported cast for token accounting and tracing.
+ */
+type AiSdkGenerateResult = {
+  output: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `reasoning: true` and the model produced it (see the structured-output
+   * envelope in {@link buildEnvelopeSchema}). Never enters machine context/output. */
+  reasoning?: string;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+  toolCalls: TypedToolCall<ToolSet>[];
+  toolResults: TypedToolResult<ToolSet>[];
+};
+/** Raw result shape from {@link AiSdkExecutors.streamText} — the `{ output }` envelope carrying the fully-accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata for `onResult`. */
+type AiSdkStreamResult = {
+  output: string;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+};
+/** Raw result shape from {@link AiSdkExecutors.decide} — the chosen event plus the AI SDK call metadata, delivered per decision attempt to `onResult`. */
+type AiSdkDecideResult = {
+  event: ChosenEvent;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+};
+/** `createAiSdkExecutors` always populates all three slots (unlike the
+ * general `AgentRequestExecutors`, where `streamText`/`decide` are optional),
+ * and its `generateText`/`streamText` results are concretely typed. */
+interface AiSdkExecutors extends AgentRequestExecutors<AiSdkGenerateResult, AiSdkStreamResult> {
+  generateText: AgentRequestExecutor<AiSdkGenerateResult>;
+  streamText: AgentRequestExecutor<AiSdkStreamResult>;
+  decide: AgentDecisionExecutor;
+}
+/**
+ * The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
+ * decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
+ * must not become a dependency of core `src/` files — this subpath is the one
+ * place it's imported, and callers must supply their own model resolver so no
+ * concrete provider package (e.g. `@ai-sdk/openai`) becomes a dependency here
+ * either.
+ *
+ * @example
+ * ```ts
+ * const executors = createAiSdkExecutors({ models: { quick: openai('gpt-5.4-mini') } });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createAiSdkExecutors<TModels extends AiSdkModelMap>(options: CreateAiSdkExecutorsOptions<TModels>): AiSdkExecutors;
+//#endregion
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels };

package/dist/ai-sdk.d.mts

@@ -0,0 +1,96 @@
+import { m as ChosenEvent } from "./types-qm00QF91.mjs";
+import { i as AgentRequestExecutor, k as AgentDecisionExecutor, s as AgentRequestExecutors } from "./text-logic-CaKqgX4Y.mjs";
+import { FinishReason, LanguageModel, LanguageModelUsage, ToolSet, TypedToolCall, TypedToolResult } from "ai";
+
+//#region src/ai-sdk/index.d.ts
+/** AI SDK model registry: maps model refs (as used in `setupAgent({ models })`/`AgentTextRequest.model`) to AI SDK `LanguageModel` values. The optional `TKey` parameter pins the ref keys (see {@link defineModels}); it defaults to `string`, so bare `AiSdkModelMap` stays `Record<string, LanguageModel>`. */
+type AiSdkModelMap<TKey extends string = string> = Record<TKey, LanguageModel>;
+/**
+ * Identity helper for a `models` map whose value is exported. Returns the map
+ * unchanged, but types it as {@link AiSdkModelMap}`<keyof T & string>` — a
+ * portable, nameable type — so an exported `const models = defineModels({...})`
+ * needs no `Record<'a' | 'b', LanguageModel>` annotation and never triggers
+ * TS2742 ("inferred type cannot be named without a reference to …"). The exact
+ * ref keys survive, so `createAiSdkExecutors({ models })` and
+ * `setupAgent({ models })` still infer/autocomplete them.
+ *
+ * @example
+ * ```ts
+ * export const models = defineModels({
+ *   quick: openai('gpt-5.4-mini'),
+ *   deep: openai('gpt-5.4'),
+ * });
+ * // typeof models === AiSdkModelMap<'quick' | 'deep'>
+ * ```
+ */
+declare function defineModels<T extends Record<string, LanguageModel>>(models: T): AiSdkModelMap<keyof T & string>;
+/**
+ * Options for {@link createAiSdkExecutors}: either a static `models` map
+ * (model refs resolved by lookup), a `resolveModel` function (refs resolved
+ * dynamically, e.g. `"openai/gpt-5.4-mini"` → `openai('gpt-5.4-mini')`), or
+ * both — `resolveModel` takes precedence when both are supplied.
+ */
+type CreateAiSdkExecutorsOptions<TModels extends AiSdkModelMap = AiSdkModelMap> = {
+  models: TModels;
+  resolveModel?: (modelRef: keyof TModels & string) => LanguageModel;
+} | {
+  models?: TModels;
+  resolveModel: (modelRef: string) => LanguageModel;
+};
+/**
+ * Raw result shape from {@link AiSdkExecutors.generateText} — the `{ output }`
+ * envelope (the validated structured object for structured-output requests,
+ * or the accumulated text string otherwise; unwrapped by
+ * `normalizeGeneratorResult`) plus the AI SDK call metadata. Core only reads
+ * `output`; everything else flows verbatim to `runAgent`'s
+ * `onResult(request, { raw })`, so `raw as AiSdkGenerateResult` is the
+ * supported cast for token accounting and tracing.
+ */
+type AiSdkGenerateResult = {
+  output: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `reasoning: true` and the model produced it (see the structured-output
+   * envelope in {@link buildEnvelopeSchema}). Never enters machine context/output. */
+  reasoning?: string;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+  toolCalls: TypedToolCall<ToolSet>[];
+  toolResults: TypedToolResult<ToolSet>[];
+};
+/** Raw result shape from {@link AiSdkExecutors.streamText} — the `{ output }` envelope carrying the fully-accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata for `onResult`. */
+type AiSdkStreamResult = {
+  output: string;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+};
+/** Raw result shape from {@link AiSdkExecutors.decide} — the chosen event plus the AI SDK call metadata, delivered per decision attempt to `onResult`. */
+type AiSdkDecideResult = {
+  event: ChosenEvent;
+  usage: LanguageModelUsage;
+  finishReason: FinishReason;
+};
+/** `createAiSdkExecutors` always populates all three slots (unlike the
+ * general `AgentRequestExecutors`, where `streamText`/`decide` are optional),
+ * and its `generateText`/`streamText` results are concretely typed. */
+interface AiSdkExecutors extends AgentRequestExecutors<AiSdkGenerateResult, AiSdkStreamResult> {
+  generateText: AgentRequestExecutor<AiSdkGenerateResult>;
+  streamText: AgentRequestExecutor<AiSdkStreamResult>;
+  decide: AgentDecisionExecutor;
+}
+/**
+ * The canonical Vercel AI SDK adapter: builds the `{ generateText, streamText,
+ * decide }` executor set consumed by `runAgent`/`executeAgentRequest`. `ai`
+ * must not become a dependency of core `src/` files — this subpath is the one
+ * place it's imported, and callers must supply their own model resolver so no
+ * concrete provider package (e.g. `@ai-sdk/openai`) becomes a dependency here
+ * either.
+ *
+ * @example
+ * ```ts
+ * const executors = createAiSdkExecutors({ models: { quick: openai('gpt-5.4-mini') } });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createAiSdkExecutors<TModels extends AiSdkModelMap>(options: CreateAiSdkExecutorsOptions<TModels>): AiSdkExecutors;
+//#endregion
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels };