@statelyai/agent 2.0.0-alpha.28 → 2.0.0-alpha.30

package/dist/tanstack-ai.mjs

@@ -0,0 +1,618 @@
+import { L as parseProviderOutput, R as providerOutputSchema, X as getJsonSchemaSync, Y as getJsonSchema, ct as AgentTruncatedError, j as getAgentOutputMode, tt as isStandardSchema, w as AGENT_USAGE_TOKEN_FIELDS } from "./event-log-DJCMHek_.mjs";
+import { c as renderDecisionAttempts } from "./decision-BHkvuImD.mjs";
+import { t as resolveModelSource } from "./model-source-BaHwJ1wK.mjs";
+import { chat, maxIterations } from "@tanstack/ai";
+//#region src/tanstack-ai/index.ts
+/**
+* The TanStack AI adapter: builds the `{ generateText, streamText, decide }`
+* executor set consumed by `createAgentRuntime`/`executeAgentRequest`, mapped
+* onto TanStack AI's `chat()` activity and any text adapter
+* (`openaiText(...)`, `anthropicText(...)`, `geminiText(...)`, …).
+*
+* `@tanstack/ai` is an OPTIONAL peer dependency, imported only here. No
+* provider package (`@tanstack/ai-openai`, …) is a dependency: the host passes
+* its own text adapters. Compare `@statelyai/agent/ai-sdk`, the same contract
+* over the Vercel AI SDK.
+*/
+/** Thrown for a message part TanStack AI's model messages cannot carry —
+* dropping it would silently change what the model sees. */
+function unsupportedPart(role, type) {
+	throw new Error(`createTanStackAiExecutors: a ${role} message part of type '${type}' has no TanStack AI equivalent. Send text, image, tool-call, or tool-result parts, or convert it before the request.`);
+}
+/** A `DataContent`/`URL` image as a TanStack AI content source: an http(s)
+* string or `URL` is a `url` source; a `data:` URL, a bare base64 string, and
+* raw bytes are a base64 `data` source. */
+function toImagePart(image, mediaType) {
+	const mimeType = mediaType ?? "image/jpeg";
+	if (image instanceof URL || typeof image === "string" && /^https?:/.test(image)) return {
+		type: "image",
+		source: {
+			type: "url",
+			value: String(image)
+		}
+	};
+	if (typeof image === "string") {
+		const dataUrl = /^data:([^;,]+)?(?:;base64)?,(.*)$/.exec(image);
+		return {
+			type: "image",
+			source: {
+				type: "data",
+				value: dataUrl ? dataUrl[2] : image,
+				mimeType: dataUrl?.[1] ?? mimeType
+			}
+		};
+	}
+	const bytes = image instanceof Uint8Array ? image : new Uint8Array(image);
+	const encode = globalThis.btoa;
+	if (!encode) throw new Error("createTanStackAiExecutors: binary image parts need a global `btoa` to base64-encode. Pass the image as a URL or a base64 string instead.");
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return {
+		type: "image",
+		source: {
+			type: "data",
+			value: encode(binary),
+			mimeType
+		}
+	};
+}
+/** One tool message per `ToolResultPart` — the tool role is one message per result. */
+function toToolMessage(part) {
+	return {
+		role: "tool",
+		toolCallId: part.toolCallId,
+		content: part.output.type === "text" || part.output.type === "error-text" ? part.output.value : JSON.stringify(part.output.value)
+	};
+}
+/**
+* Maps `AgentTextRequest.messages`/`system`/`prompt` onto `chat()`'s
+* `systemPrompts` and `messages`. TanStack AI's model messages have no
+* `system` role — a provider adapter may forward one as a user turn — so every
+* system message, and the request's `system`, becomes a system prompt.
+*/
+function toTanStackAiMessages(request) {
+	const systemPrompts = request.system ? [request.system] : [];
+	if (!request.messages) return {
+		systemPrompts,
+		messages: [{
+			role: "user",
+			content: request.prompt ?? ""
+		}]
+	};
+	return {
+		systemPrompts,
+		messages: request.messages.flatMap((message) => {
+			switch (message.role) {
+				case "system":
+					systemPrompts.push(message.content);
+					return [];
+				case "user":
+					if (typeof message.content === "string") return [{
+						role: "user",
+						content: message.content
+					}];
+					return [{
+						role: "user",
+						content: message.content.map((part) => {
+							switch (part.type) {
+								case "text": return {
+									type: "text",
+									content: part.text
+								};
+								case "image": return toImagePart(part.image, part.mediaType);
+								default: return unsupportedPart("user", part.type);
+							}
+						})
+					}];
+				case "assistant": {
+					if (typeof message.content === "string") return [{
+						role: "assistant",
+						content: message.content
+					}];
+					let text = "";
+					const toolCalls = [];
+					const trailing = [];
+					for (const part of message.content) switch (part.type) {
+						case "text":
+							text += part.text;
+							break;
+						case "tool-call":
+							toolCalls.push({
+								id: part.toolCallId,
+								type: "function",
+								function: {
+									name: part.toolName,
+									arguments: JSON.stringify(part.input ?? {})
+								}
+							});
+							break;
+						case "tool-result":
+							trailing.push(toToolMessage(part));
+							break;
+						default: unsupportedPart("assistant", part.type);
+					}
+					return [{
+						role: "assistant",
+						content: text || null,
+						...toolCalls.length > 0 ? { toolCalls } : {}
+					}, ...trailing];
+				}
+				case "tool": return message.content.map(toToolMessage);
+			}
+		})
+	};
+}
+/** A tool `description` may be a string or, for an AI SDK v7 tool, a function
+* of the call's context. TanStack AI tools carry the static form. */
+function staticDescription(descriptor) {
+	if (typeof descriptor === "function") return "";
+	return typeof descriptor.description === "string" ? descriptor.description : "";
+}
+/**
+* One TanStack AI tool per `AgentTools` entry. A tool with an `execute` (or a
+* bare function) is a server tool `chat()` runs in its loop; a tool without one
+* is a client tool, so the run stops at its call and hands the call back.
+* Input schemas travel as JSON Schema.
+*/
+function toTanStackAiTools(tools) {
+	return Object.entries(tools).flatMap(([name, descriptor]) => {
+		if (!descriptor) return [];
+		const inputSchema = typeof descriptor === "function" ? void 0 : descriptor.inputSchema;
+		const execute = typeof descriptor === "function" ? descriptor : descriptor.execute;
+		return [{
+			name,
+			description: staticDescription(descriptor),
+			inputSchema: (isStandardSchema(inputSchema) ? getJsonSchemaSync(inputSchema) : void 0) ?? { type: "object" },
+			...typeof execute === "function" ? { execute: (input) => execute(input) } : {}
+		}];
+	});
+}
+/** One client tool per candidate decision event: no `execute`, so the run
+* stops at the model's first call — the "tool-per-event" recipe. */
+function toTanStackAiEventTools(events) {
+	return events.map((event) => ({
+		name: event.toolName,
+		description: `Choose the '${event.type}' move.`,
+		inputSchema: getJsonSchemaSync(event.inputSchema) ?? { type: "object" }
+	}));
+}
+/** Drops keys whose value is `undefined`, so a spread cannot erase what it lands on. */
+function defined(settings) {
+	return Object.fromEntries(Object.entries(settings).filter(([, value]) => value !== void 0));
+}
+/**
+* Maps the request's portable generation settings and tool choice onto the
+* `modelOptions` of the adapter's provider. TanStack AI has no portable
+* sampling or tool-choice options — each provider adapter names its own — so
+* the mapping is per provider (`adapter.name`):
+*
+* - `openai` (Responses API): `temperature`, `top_p`, `max_output_tokens`,
+*   `tool_choice`. The API has no `top_k`, `seed`, or `stop`; those are dropped.
+* - `anthropic`: `temperature`, `top_p`, `top_k`, `max_tokens`,
+*   `stop_sequences`, `tool_choice`. `seed` is dropped.
+* - `gemini`: `temperature`, `topP`, `topK`, `maxOutputTokens`, `seed`,
+*   `stopSequences`, `toolConfig.functionCallingConfig`.
+*
+* Any other provider gets none of them: map them yourself through the
+* `settings` option, which receives the request.
+*/
+function toTanStackAiModelOptions(adapter, request) {
+	const { toolChoice } = request;
+	switch (adapter.name) {
+		case "openai": return defined({
+			temperature: request.temperature,
+			top_p: request.topP,
+			max_output_tokens: request.maxOutputTokens,
+			tool_choice: typeof toolChoice === "object" ? {
+				type: "function",
+				name: toolChoice.name
+			} : toolChoice
+		});
+		case "anthropic": return defined({
+			temperature: request.temperature,
+			top_p: request.topP,
+			top_k: request.topK,
+			max_tokens: request.maxOutputTokens,
+			stop_sequences: request.stopSequences,
+			tool_choice: typeof toolChoice === "object" ? {
+				type: "tool",
+				name: toolChoice.name
+			} : toolChoice === "required" ? { type: "any" } : toolChoice === void 0 ? void 0 : { type: toolChoice }
+		});
+		case "gemini": return defined({
+			temperature: request.temperature,
+			topP: request.topP,
+			topK: request.topK,
+			maxOutputTokens: request.maxOutputTokens,
+			seed: request.seed,
+			stopSequences: request.stopSequences,
+			toolConfig: toolChoice === void 0 ? void 0 : { functionCallingConfig: typeof toolChoice === "object" ? {
+				mode: "ANY",
+				allowedFunctionNames: [toolChoice.name]
+			} : { mode: toolChoice === "required" ? "ANY" : toolChoice.toUpperCase() } }
+		});
+		default: return {};
+	}
+}
+/**
+* Messages for a decision request, with prior failed `attempts` rendered as
+* appended user messages so retries converge. Mirrors the AI SDK adapter's
+* `toDecisionMessages`.
+*/
+function toDecisionMessages(request) {
+	const mapped = toTanStackAiMessages(request);
+	for (const attempt of renderDecisionAttempts(request)) mapped.messages.push({
+		role: "user",
+		content: attempt.content
+	});
+	return mapped;
+}
+/**
+* Folds TanStack AI's `TokenUsage` onto the flat {@link AgentCallUsage} field
+* names core aggregates. A field the provider omitted stays omitted, so it
+* never contributes a `0` to a run's partial sums.
+*/
+function toAgentCallUsage(usage) {
+	if (!usage) return;
+	const reasoningTokens = usage.completionTokensDetails?.reasoningTokens;
+	const cachedInputTokens = usage.promptTokensDetails?.cachedTokens;
+	return defined({
+		inputTokens: usage.promptTokens,
+		outputTokens: usage.completionTokens,
+		totalTokens: usage.totalTokens,
+		reasoningTokens,
+		cachedInputTokens
+	});
+}
+/** Adds two model turns' usage together, field by field. A field neither
+* reported stays absent. */
+function addUsage(total, next) {
+	if (!total || !next) return total ?? next;
+	const sum = {};
+	for (const field of AGENT_USAGE_TOKEN_FIELDS) if (total[field] !== void 0 || next[field] !== void 0) sum[field] = (total[field] ?? 0) + (next[field] ?? 0);
+	return sum;
+}
+/**
+* Maps a TanStack AI finish reason onto the portable {@link AgentFinishReason}.
+* Anything unrecognized, including a missing reason, lands on `'other'`.
+*/
+function toAgentFinishReason(finishReason) {
+	switch (finishReason) {
+		case "stop": return "stop";
+		case "length": return "length";
+		case "tool_calls": return "tool-calls";
+		case "content_filter": return "content-filter";
+		default: return "other";
+	}
+}
+function toToolResultOutput(content) {
+	if (typeof content !== "string") return {
+		type: "json",
+		value: content
+	};
+	try {
+		return {
+			type: "json",
+			value: JSON.parse(content)
+		};
+	} catch {
+		return {
+			type: "text",
+			value: content
+		};
+	}
+}
+/** A `RUN_ERROR` chunk as the `Error` it reports, `code` included. */
+var TanStackAiRunError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.name = "TanStackAiRunError";
+		this.code = code;
+	}
+};
+/**
+* Reads a `chat()` stream to the end. Text arrives as `TEXT_MESSAGE_CONTENT`
+* deltas; every model turn ends in its own `RUN_FINISHED`, so a tool loop's
+* usage is summed and the last finish reason wins. A provider failure arrives
+* as a `RUN_ERROR` chunk rather than a throw, and is thrown here.
+*/
+async function readRun(stream, onDelta) {
+	const summary = {
+		text: "",
+		structured: void 0,
+		usage: void 0,
+		finishReason: "other",
+		toolCalls: [],
+		messages: [],
+		chunks: []
+	};
+	const args = /* @__PURE__ */ new Map();
+	let assistant;
+	let results;
+	const flushAssistant = () => {
+		if (assistant?.length) summary.messages.push({
+			role: "assistant",
+			content: assistant
+		});
+		assistant = void 0;
+	};
+	const flushResults = () => {
+		if (results?.length) summary.messages.push({
+			role: "tool",
+			content: results
+		});
+		results = void 0;
+	};
+	const assistantParts = () => {
+		flushResults();
+		return assistant ??= [];
+	};
+	for await (const chunk of stream) {
+		summary.chunks.push(chunk);
+		switch (chunk.type) {
+			case "TEXT_MESSAGE_CONTENT": {
+				summary.text += chunk.delta;
+				onDelta?.(chunk.delta);
+				const parts = assistantParts();
+				const last = parts.at(-1);
+				if (last?.type === "text") last.text += chunk.delta;
+				else parts.push({
+					type: "text",
+					text: chunk.delta
+				});
+				break;
+			}
+			case "TOOL_CALL_START": {
+				const part = {
+					type: "tool-call",
+					toolCallId: chunk.toolCallId,
+					toolName: chunk.toolCallName,
+					input: {}
+				};
+				assistantParts().push(part);
+				args.set(chunk.toolCallId, {
+					part,
+					json: ""
+				});
+				break;
+			}
+			case "TOOL_CALL_ARGS": {
+				const call = args.get(chunk.toolCallId);
+				if (call) call.json += chunk.delta;
+				break;
+			}
+			case "TOOL_CALL_RESULT":
+				flushAssistant();
+				(results ??= []).push({
+					type: "tool-result",
+					toolCallId: chunk.toolCallId,
+					toolName: args.get(chunk.toolCallId)?.part.toolName ?? "",
+					output: toToolResultOutput(chunk.content)
+				});
+				break;
+			case "CUSTOM":
+				if (chunk.name === "structured-output.complete") summary.structured = chunk.value?.object;
+				break;
+			case "RUN_FINISHED":
+				summary.finishReason = toAgentFinishReason(chunk.finishReason ?? (chunk.metadata?.tanstack)?.finishReason);
+				if (chunk.usage && !Array.isArray(chunk.usage)) summary.usage = addUsage(summary.usage, toAgentCallUsage(chunk.usage));
+				break;
+			case "RUN_ERROR": throw new TanStackAiRunError(chunk.message, chunk.code ?? chunk.error?.code);
+		}
+	}
+	for (const { part, json } of args.values()) part.input = json ? JSON.parse(json) : {};
+	flushAssistant();
+	flushResults();
+	summary.toolCalls = [...args.values()].map(({ part }) => ({
+		toolCallId: part.toolCallId,
+		toolName: part.toolName,
+		input: part.input
+	}));
+	return summary;
+}
+function isAdapterWithSettings(entry) {
+	return "adapter" in entry && !("kind" in entry);
+}
+/** The text adapter inside a map entry, whichever form it takes. */
+function toTextAdapter(entry) {
+	return isAdapterWithSettings(entry) ? entry.adapter : entry;
+}
+function truncated(request, info, partialOutput, cause) {
+	return new AgentTruncatedError(`createTanStackAiExecutors: request '${request.name ?? "(unnamed)"}' hit the output token limit — its structured output never completed. Raise \`maxOutputTokens\`, shorten the input, or ask for a smaller output schema.`, {
+		requestName: request.name ?? "(unnamed)",
+		...info?.requestId !== void 0 ? { requestId: info.requestId } : {},
+		...partialOutput !== void 0 ? { partialOutput } : {},
+		...cause !== void 0 ? { cause } : {}
+	});
+}
+function isTruncationError(error) {
+	const { code, message } = error ?? {};
+	return code === "max_tokens" || code === "incomplete" || message === "max_output_tokens";
+}
+function usageField(usage) {
+	return usage ? { usage } : {};
+}
+/**
+* Runs one `chat()` call to the end. `chat()` takes an `AbortController`, not
+* a signal, so the runtime's signal is bridged to one — and unhooked once the
+* run settles, so a long-lived signal does not collect a listener per request.
+* An aborted `chat()` stream just ends, so the abort is surfaced as the throw
+* it is.
+*/
+async function runChat(options, signal, onDelta) {
+	const controller = new AbortController();
+	const abort = () => controller.abort(signal?.reason);
+	if (signal?.aborted) abort();
+	else signal?.addEventListener("abort", abort, { once: true });
+	let run;
+	try {
+		run = await readRun(chat({
+			...options,
+			abortController: controller
+		}), onDelta);
+	} finally {
+		signal?.removeEventListener("abort", abort);
+	}
+	if (signal?.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("createTanStackAiExecutors: the request was aborted.");
+	return run;
+}
+/**
+* A request's tool choice belongs to its first model turn. `chat()` reuses
+* `modelOptions` for every turn of its tool loop, so a forced choice left in
+* place would force another tool call after each result, and the request could
+* never answer. From the second turn on, the choice's keys go back to what the
+* host set, or away.
+*/
+function toolChoiceOnFirstTurn(keys, later) {
+	return {
+		name: "statelyai:tool-choice-first-turn",
+		onConfig: (ctx, config) => {
+			if (ctx.iteration === 0) return;
+			const modelOptions = { ...config.modelOptions };
+			for (const key of keys) if (key in later) modelOptions[key] = later[key];
+			else delete modelOptions[key];
+			return { modelOptions };
+		}
+	};
+}
+function createTanStackAiExecutors(source) {
+	const options = resolveModelSource("createTanStackAiExecutors", source);
+	const resolve = (request, portable) => {
+		let adapter;
+		let entrySettings;
+		if (options.resolveModel) adapter = options.resolveModel(request.model);
+		else {
+			const entry = options.models?.[request.model];
+			if (!options.models) throw new Error(`createTanStackAiExecutors: no model resolver configured for '${request.model}'.`);
+			if (!entry) throw new Error(`createTanStackAiExecutors: unknown model '${request.model}'.`);
+			adapter = toTextAdapter(entry);
+			entrySettings = isAdapterWithSettings(entry) ? entry.settings : void 0;
+		}
+		const host = (typeof options.settings === "function" ? options.settings(request) : options.settings) ?? {};
+		const merged = {
+			...host,
+			...entrySettings
+		};
+		const base = {
+			...host.modelOptions,
+			...entrySettings?.modelOptions
+		};
+		const generation = toTanStackAiModelOptions(adapter, {
+			...portable,
+			toolChoice: void 0
+		});
+		const firstTurn = toTanStackAiModelOptions(adapter, portable);
+		const choiceKeys = Object.keys(firstTurn).filter((key) => !(key in generation));
+		return {
+			adapter,
+			settings: {
+				...merged,
+				modelOptions: {
+					...base,
+					...firstTurn
+				},
+				...choiceKeys.length > 0 ? { middleware: [...merged.middleware ?? [], toolChoiceOnFirstTurn(choiceKeys, {
+					...base,
+					...generation
+				})] } : {}
+			}
+		};
+	};
+	const loopBound = (request) => maxIterations(typeof request.maxSteps === "number" && Number.isFinite(request.maxSteps) ? Math.max(1, Math.floor(request.maxSteps)) : 1);
+	const generateText = async (request, info) => {
+		const { adapter, settings } = resolve(request, request);
+		const tools = toTanStackAiTools(request.tools);
+		const structured = getAgentOutputMode(request.outputSchema) === "structured";
+		const outputSchema = structured ? await getJsonSchema(providerOutputSchema(request.outputSchema, { reasoning: request.includeReasoning })) : void 0;
+		let run;
+		try {
+			run = await runChat({
+				...settings,
+				adapter,
+				...toTanStackAiMessages(request),
+				...tools.length > 0 ? { tools } : {},
+				...outputSchema ? {
+					outputSchema,
+					stream: true
+				} : {},
+				agentLoopStrategy: loopBound(request)
+			}, info?.signal);
+		} catch (error) {
+			throw structured && isTruncationError(error) ? truncated(request, info, void 0, error) : error;
+		}
+		if (outputSchema) {
+			if (run.finishReason === "length") throw truncated(request, info, run.structured ?? run.text);
+			const parsed = parseProviderOutput(request, run.structured !== void 0 ? run.structured : JSON.parse(run.text));
+			return {
+				result: parsed.result,
+				...typeof parsed.reasoning === "string" ? { reasoning: parsed.reasoning } : {},
+				...usageField(run.usage),
+				finishReason: run.finishReason,
+				toolCalls: run.toolCalls,
+				messages: run.messages,
+				raw: run.chunks
+			};
+		}
+		return {
+			result: run.text,
+			...usageField(run.usage),
+			finishReason: run.finishReason,
+			toolCalls: run.toolCalls,
+			messages: run.messages,
+			raw: run.chunks
+		};
+	};
+	const streamText = async (request, info) => {
+		if (getAgentOutputMode(request.outputSchema) === "structured") throw new Error("createTanStackAiExecutors: streamText streams text — a request declaring a structured output schema must be routed to generateText.");
+		const { adapter, settings } = resolve(request, request);
+		const tools = toTanStackAiTools(request.tools ?? {});
+		const run = await runChat({
+			...settings,
+			adapter,
+			...toTanStackAiMessages(request),
+			...tools.length > 0 ? { tools } : {},
+			agentLoopStrategy: loopBound(request)
+		}, info?.signal, (delta) => info?.onChunk?.(delta));
+		return {
+			result: run.text,
+			...usageField(run.usage),
+			finishReason: run.finishReason,
+			messages: run.messages,
+			raw: run.chunks
+		};
+	};
+	const decide = async (request, info) => {
+		const { adapter, settings } = resolve(request, {
+			...request,
+			toolChoice: "required"
+		});
+		const run = await runChat({
+			...settings,
+			adapter,
+			...toDecisionMessages(request),
+			tools: toTanStackAiEventTools(request.events),
+			agentLoopStrategy: maxIterations(1)
+		}, info?.signal);
+		const toolCall = run.toolCalls[0];
+		if (!toolCall) throw new Error("createTanStackAiExecutors: decide — model did not call an event tool.");
+		const chosenEvent = request.events.find((event) => event.toolName === toolCall.toolName);
+		if (!chosenEvent) throw new Error(`createTanStackAiExecutors: decide — model called unknown tool '${toolCall.toolName}'.`);
+		return {
+			event: {
+				...toolCall.input && typeof toolCall.input === "object" ? toolCall.input : {},
+				type: chosenEvent.type
+			},
+			...usageField(run.usage),
+			finishReason: run.finishReason,
+			raw: run.chunks
+		};
+	};
+	return {
+		generateText,
+		streamText,
+		decide
+	};
+}
+//#endregion
+export { createTanStackAiExecutors, toAgentCallUsage, toAgentFinishReason, toDecisionMessages, toTanStackAiEventTools, toTanStackAiMessages, toTanStackAiModelOptions, toTanStackAiTools, toTextAdapter };