@statelyai/agent 1.1.5 → 2.0.0-alpha.5

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/ai-sdk.cjs

@@ -0,0 +1,249 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_decision = require("./decision-pC-bY2DE.cjs");
+let ai = require("ai");
+//#region src/ai-sdk/index.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 internally by {@link toAiSdkCallSettings}; exported for callers
+* building AI SDK calls by hand outside `createAiSdkExecutors`.
+*/
+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_decision.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);
+}
+function maxStepsSetting(request) {
+	return typeof request.metadata?.maxSteps === "number" ? { stopWhen: (0, ai.stepCountIs)(request.metadata.maxSteps) } : {};
+}
+const unknownSchema = { "~standard": {
+	version: 1,
+	vendor: "statelyai-agent",
+	validate: (value) => ({ value }),
+	jsonSchema: { input: () => ({}) }
+} };
+/**
+* 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;
+}
+/**
+* AI SDK request-mapping settings shared by `generateText`/`streamText`.
+* `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
+* are structurally compatible by design (§1 of docs/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_decision.getAgentOutputMode(request.outputSchema) === "structured";
+}
+/**
+* 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_decision.buildEnvelopeSchema(request.outputSchema, { reasoning: request.reasoning });
+			const result = await (0, ai.generateText)({
+				...common,
+				output: ai.Output.object({ schema: envelope })
+			});
+			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
+	};
+}
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+* toolChoice: 'required'" recipe from docs/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
+exports.createAiSdkExecutors = createAiSdkExecutors;
+exports.defineModels = defineModels;
+exports.isStructuredOutputRequest = isStructuredOutputRequest;
+exports.toAiSdkCallSettings = toAiSdkCallSettings;
+exports.toAiSdkEventTools = toAiSdkEventTools;
+exports.toAiSdkToolChoice = toAiSdkToolChoice;
+exports.toAiSdkTools = toAiSdkTools;
+exports.toDecisionMessages = toDecisionMessages;

package/dist/ai-sdk.d.cts

@@ -0,0 +1,168 @@
+import { c as AgentTools, f as ChosenEvent } from "./types-BHjeDdch.cjs";
+import { B as AgentEventDescriptor, D as AgentDecisionExecutor, i as AgentRequestExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-1ZQkO3zr.cjs";
+import { FinishReason, LanguageModel, LanguageModelUsage, ModelMessage, Tool, ToolSet, TypedToolCall, TypedToolResult } from "ai";
+
+//#region src/ai-sdk/index.d.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 internally by {@link toAiSdkCallSettings}; exported for callers
+ * building AI SDK calls by hand outside `createAiSdkExecutors`.
+ */
+declare function toAiSdkTools(tools: AgentTools): {
+  [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+};
+/** 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;
+};
+/**
+ * AI SDK request-mapping settings shared by `generateText`/`streamText`.
+ * `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
+ * are structurally compatible by design (§1 of docs/p0-design.md) — the cast
+ * below is a typed identity mapping, not a semantic conversion.
+ */
+declare function toAiSdkCallSettings(request: AgentTextRequest & {
+  tools?: AgentTools;
+}): {
+  temperature: number | undefined;
+  maxOutputTokens: number | undefined;
+  topP: number | undefined;
+  topK: number | undefined;
+  seed: number | undefined;
+  stopSequences: string[] | undefined;
+  tools: {
+    [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+  } | undefined;
+  toolChoice: "auto" | "none" | "required" | {
+    type: "tool";
+    toolName: string;
+  } | undefined;
+  messages: ModelMessage[];
+  system: string | undefined;
+} | {
+  temperature: number | undefined;
+  maxOutputTokens: number | undefined;
+  topP: number | undefined;
+  topK: number | undefined;
+  seed: number | undefined;
+  stopSequences: string[] | undefined;
+  tools: {
+    [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+  } | undefined;
+  toolChoice: "auto" | "none" | "required" | {
+    type: "tool";
+    toolName: string;
+  } | undefined;
+  prompt: string;
+  system: string | undefined;
+};
+/** 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. */
+declare function toAiSdkToolChoice(toolChoice: AgentTextRequest["toolChoice"]): "auto" | "none" | "required" | {
+  type: "tool";
+  toolName: string;
+} | undefined;
+/** `true` when the request should use AI SDK structured `Output.object`. */
+declare function isStructuredOutputRequest(request: Pick<AgentTextRequest, "outputSchema">): boolean;
+/**
+ * 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> {
+  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;
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+ * toolChoice: 'required'" recipe from docs/p0-design.md §2.6. */
+declare function toAiSdkEventTools(events: AgentEventDescriptor[]): {
+  [k: string]: Tool<unknown, never>;
+};
+/**
+ * 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.
+ */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ModelMessage[] | undefined;
+//#endregion
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };

package/dist/ai-sdk.d.mts

@@ -0,0 +1,168 @@
+import { c as AgentTools, f as ChosenEvent } from "./types-Cq1YlAQ6.mjs";
+import { B as AgentEventDescriptor, D as AgentDecisionExecutor, i as AgentRequestExecutor, k as AgentDecisionRequest, l as AgentTextRequest, s as AgentRequestExecutors } from "./text-logic-2EMJIS-n.mjs";
+import { FinishReason, LanguageModel, LanguageModelUsage, ModelMessage, Tool, ToolSet, TypedToolCall, TypedToolResult } from "ai";
+
+//#region src/ai-sdk/index.d.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 internally by {@link toAiSdkCallSettings}; exported for callers
+ * building AI SDK calls by hand outside `createAiSdkExecutors`.
+ */
+declare function toAiSdkTools(tools: AgentTools): {
+  [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+};
+/** 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;
+};
+/**
+ * AI SDK request-mapping settings shared by `generateText`/`streamText`.
+ * `AgentTextRequest.messages` (`AgentMessage[]`) and AI SDK's `ModelMessage[]`
+ * are structurally compatible by design (§1 of docs/p0-design.md) — the cast
+ * below is a typed identity mapping, not a semantic conversion.
+ */
+declare function toAiSdkCallSettings(request: AgentTextRequest & {
+  tools?: AgentTools;
+}): {
+  temperature: number | undefined;
+  maxOutputTokens: number | undefined;
+  topP: number | undefined;
+  topK: number | undefined;
+  seed: number | undefined;
+  stopSequences: string[] | undefined;
+  tools: {
+    [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+  } | undefined;
+  toolChoice: "auto" | "none" | "required" | {
+    type: "tool";
+    toolName: string;
+  } | undefined;
+  messages: ModelMessage[];
+  system: string | undefined;
+} | {
+  temperature: number | undefined;
+  maxOutputTokens: number | undefined;
+  topP: number | undefined;
+  topK: number | undefined;
+  seed: number | undefined;
+  stopSequences: string[] | undefined;
+  tools: {
+    [k: string]: Tool<unknown, unknown> | Tool<unknown, never>;
+  } | undefined;
+  toolChoice: "auto" | "none" | "required" | {
+    type: "tool";
+    toolName: string;
+  } | undefined;
+  prompt: string;
+  system: string | undefined;
+};
+/** 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. */
+declare function toAiSdkToolChoice(toolChoice: AgentTextRequest["toolChoice"]): "auto" | "none" | "required" | {
+  type: "tool";
+  toolName: string;
+} | undefined;
+/** `true` when the request should use AI SDK structured `Output.object`. */
+declare function isStructuredOutputRequest(request: Pick<AgentTextRequest, "outputSchema">): boolean;
+/**
+ * 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> {
+  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;
+/** One AI SDK `tool()` per candidate event — the "tool-per-event +
+ * toolChoice: 'required'" recipe from docs/p0-design.md §2.6. */
+declare function toAiSdkEventTools(events: AgentEventDescriptor[]): {
+  [k: string]: Tool<unknown, never>;
+};
+/**
+ * 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.
+ */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ModelMessage[] | undefined;
+//#endregion
+export { AiSdkDecideResult, AiSdkExecutors, AiSdkGenerateResult, AiSdkModelMap, AiSdkStreamResult, CreateAiSdkExecutorsOptions, createAiSdkExecutors, defineModels, isStructuredOutputRequest, toAiSdkCallSettings, toAiSdkEventTools, toAiSdkToolChoice, toAiSdkTools, toDecisionMessages };