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

package/dist/tanstack-ai.d.cts

@@ -0,0 +1,204 @@
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-DmciuVUQ.cjs";
+import { AnyStateMachine } from "xstate";
+import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
+import { TextActivityOptions } from "@tanstack/ai/adapters";
+//#region src/tanstack-ai/index.d.ts
+/**
+ * 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.
+ */
+export declare function toTanStackAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
+  messages?: AgentMessage[];
+}): {
+  systemPrompts: string[];
+  messages: ModelMessage[];
+};
+/**
+ * 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.
+ */
+export declare function toTanStackAiTools(tools: AgentTools): Tool[];
+/** One client tool per candidate decision event: no `execute`, so the run
+ * stops at the model's first call — the "tool-per-event" recipe. */
+export declare function toTanStackAiEventTools(events: AgentEventDescriptor[]): Tool[];
+/** The generation settings a text and a decision request share. */
+type GenerationSettings = Pick<AgentTextRequest, "temperature" | "maxOutputTokens" | "topP" | "topK" | "seed" | "stopSequences">;
+/**
+ * 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.
+ */
+export declare function toTanStackAiModelOptions(adapter: Pick<AnyTextAdapter, "name">, request: GenerationSettings & {
+  toolChoice?: AgentToolChoice;
+}): Record<string, unknown>;
+/**
+ * Messages for a decision request, with prior failed `attempts` rendered as
+ * appended user messages so retries converge. Mirrors the AI SDK adapter's
+ * `toDecisionMessages`.
+ */
+export declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "system" | "messages" | "prompt" | "events" | "attempts">): {
+  systemPrompts: string[];
+  messages: ModelMessage[];
+};
+/**
+ * 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.
+ */
+export declare function toAgentCallUsage(usage: TokenUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Maps a TanStack AI finish reason onto the portable {@link AgentFinishReason}.
+ * Anything unrecognized, including a missing reason, lands on `'other'`.
+ */
+export declare function toAgentFinishReason(finishReason: string | null | undefined): AgentFinishReason;
+/** A model's tool call, as read off the run's `TOOL_CALL_*` events. */
+export type TanStackAiToolCall = {
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+};
+/**
+ * Per-call `chat()` options a host can apply on top of what the machine asked
+ * for — provider `modelOptions` (reasoning effort, …), `middleware`,
+ * `metadata`, `debug`, and anything else `chat()` accepts. Typed off the
+ * installed `@tanstack/ai`, so it tracks that version.
+ *
+ * The request's own fields are excluded: messages, system prompts, tools,
+ * output schema, streaming, cancellation, and the tool-loop bound belong to the
+ * machine and the adapter.
+ */
+export type TanStackAiCallSettings = Omit<TextActivityOptions<AnyTextAdapter, undefined, boolean>, "adapter" | "messages" | "systemPrompts" | "tools" | "outputSchema" | "stream" | "abortController" | "agentLoopStrategy">;
+/**
+ * One entry in a {@link TanStackAiModelMap}: a bare text adapter, or an adapter
+ * paired with the {@link TanStackAiCallSettings} that ref always runs with — how
+ * a host gives a ref a persona without the machine naming a provider knob.
+ */
+export type TanStackAiModelEntry = AnyTextAdapter | {
+  adapter: AnyTextAdapter;
+  settings?: TanStackAiCallSettings;
+};
+/** Model registry: maps model refs (as used in `setupAgent({ models })`) to
+ * TanStack AI text adapters, or to `{ adapter, settings }` pairs. */
+export type TanStackAiModelMap<TKey extends string = string> = Record<TKey, TanStackAiModelEntry>;
+/**
+ * Options for {@link createTanStackAiExecutors}: a static `models` map, a
+ * `resolveModel` function (refs resolved dynamically), or both —
+ * `resolveModel` takes precedence when both are supplied.
+ *
+ * `settings` carries `chat()` options that are the HOST's business, such as
+ * provider `modelOptions`. Pass an object to apply it to every call, or a
+ * function to vary it per request (`request.name` is the request's registered
+ * key). Precedence is global `settings`, then the model entry's `settings`,
+ * then the request's own generation settings (see
+ * {@link toTanStackAiModelOptions}); `modelOptions` merge key by key.
+ */
+export type CreateTanStackAiExecutorsOptions<TModels extends TanStackAiModelMap = TanStackAiModelMap> = {
+  settings?: TanStackAiCallSettings | ((request: AgentTextRequest | AgentDecisionRequest) => TanStackAiCallSettings | undefined);
+} & ({
+  models: TModels;
+  resolveModel?: (modelRef: keyof TModels & string) => AnyTextAdapter;
+} | {
+  models?: TModels;
+  resolveModel: (modelRef: string) => AnyTextAdapter;
+});
+/**
+ * Raw result shape from {@link TanStackAiExecutors.generateText} — `result`
+ * (the parsed structured object for structured-output requests, or the text
+ * otherwise) plus the run metadata. Core reads `result` and `usage`; everything
+ * else flows verbatim to `onResult(request, { raw })`.
+ */
+export type TanStackAiGenerateResult = {
+  result: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `includeReasoning` and the model produced it. */
+  reasoning?: string;
+  /** Token usage summed over every model turn of the run. */
+  usage?: AgentCallUsage;
+  /** Why the run stopped, normalized to the portable {@link AgentFinishReason}. */
+  finishReason: AgentFinishReason;
+  /** Every tool call the model made during the run. */
+  toolCalls: TanStackAiToolCall[];
+  /** The run's response messages — each turn's assistant text and tool
+   * calls, and the tool results fed back — ready to append to a
+   * conversation. */
+  messages: AgentMessage[];
+  /** Every chunk the run produced, in order. */
+  raw: StreamChunk[];
+};
+/** Raw result shape from {@link TanStackAiExecutors.streamText} — the
+ * accumulated text once the stream finishes (deltas are delivered via
+ * `onChunk`), plus the run's usage and finish reason. */
+export type TanStackAiStreamResult = {
+  result: string;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  /** The run's response messages, as on {@link TanStackAiGenerateResult}. */
+  messages: AgentMessage[];
+  raw: StreamChunk[];
+};
+/** Raw result shape from {@link TanStackAiExecutors.decide} — the chosen event
+ * plus the call metadata, delivered per decision attempt to `onResult`. */
+export type TanStackAiDecideResult = {
+  event: ChosenEvent;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  raw: StreamChunk[];
+};
+/** `createTanStackAiExecutors` always populates all three slots, and its
+ * results are concretely typed. */
+export interface TanStackAiExecutors {
+  generateText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<TanStackAiGenerateResult>;
+  streamText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<TanStackAiStreamResult>;
+  decide: (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => Promise<TanStackAiDecideResult>;
+}
+/** The text adapter inside a map entry, whichever form it takes. */
+export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapter;
+/**
+ * Builds the `{ generateText, streamText, decide }` executor set over TanStack
+ * AI's `chat()`. Compare `createAiSdkExecutors` — same shape, different SDK
+ * underneath.
+ *
+ * - Structured output uses `chat({ outputSchema })` around the
+ *   `{ result, reasoning? }` provider output schema.
+ * - Tools run in `chat()`'s own loop, for `generateText` and `streamText`
+ *   alike, bounded by the request's `maxSteps` (default 1). A tool with no
+ *   `execute` stops the run at its call.
+ * - Decisions offer one tool per candidate event, with no `execute`, so the
+ *   run stops at the model's first call; the tool choice is forced where the
+ *   provider supports it (see {@link toTanStackAiModelOptions}).
+ *
+ * Pass the options object, or pass the machine (or its `setupAgent(...)`
+ * result) to reuse the `models` declared in `setupAgent({ models })`. Anything
+ * else throws here, at construction.
+ *
+ * @example
+ * ```ts
+ * import { openaiText } from '@tanstack/ai-openai';
+ *
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
+ * ```
+ */
+export declare function createTanStackAiExecutors<TModels extends TanStackAiModelMap>(options: CreateTanStackAiExecutorsOptions<TModels>): TanStackAiExecutors;
+export declare function createTanStackAiExecutors(machine: AnyStateMachine): TanStackAiExecutors;
+//#endregion

package/dist/tanstack-ai.d.mts

@@ -0,0 +1,204 @@
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
+import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-BRYOPWvY.mjs";
+import { AnyStateMachine } from "xstate";
+import { AnyTextAdapter, ModelMessage, StreamChunk, TokenUsage, Tool } from "@tanstack/ai";
+import { TextActivityOptions } from "@tanstack/ai/adapters";
+//#region src/tanstack-ai/index.d.ts
+/**
+ * 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.
+ */
+export declare function toTanStackAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
+  messages?: AgentMessage[];
+}): {
+  systemPrompts: string[];
+  messages: ModelMessage[];
+};
+/**
+ * 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.
+ */
+export declare function toTanStackAiTools(tools: AgentTools): Tool[];
+/** One client tool per candidate decision event: no `execute`, so the run
+ * stops at the model's first call — the "tool-per-event" recipe. */
+export declare function toTanStackAiEventTools(events: AgentEventDescriptor[]): Tool[];
+/** The generation settings a text and a decision request share. */
+type GenerationSettings = Pick<AgentTextRequest, "temperature" | "maxOutputTokens" | "topP" | "topK" | "seed" | "stopSequences">;
+/**
+ * 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.
+ */
+export declare function toTanStackAiModelOptions(adapter: Pick<AnyTextAdapter, "name">, request: GenerationSettings & {
+  toolChoice?: AgentToolChoice;
+}): Record<string, unknown>;
+/**
+ * Messages for a decision request, with prior failed `attempts` rendered as
+ * appended user messages so retries converge. Mirrors the AI SDK adapter's
+ * `toDecisionMessages`.
+ */
+export declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "system" | "messages" | "prompt" | "events" | "attempts">): {
+  systemPrompts: string[];
+  messages: ModelMessage[];
+};
+/**
+ * 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.
+ */
+export declare function toAgentCallUsage(usage: TokenUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Maps a TanStack AI finish reason onto the portable {@link AgentFinishReason}.
+ * Anything unrecognized, including a missing reason, lands on `'other'`.
+ */
+export declare function toAgentFinishReason(finishReason: string | null | undefined): AgentFinishReason;
+/** A model's tool call, as read off the run's `TOOL_CALL_*` events. */
+export type TanStackAiToolCall = {
+  toolCallId: string;
+  toolName: string;
+  input: unknown;
+};
+/**
+ * Per-call `chat()` options a host can apply on top of what the machine asked
+ * for — provider `modelOptions` (reasoning effort, …), `middleware`,
+ * `metadata`, `debug`, and anything else `chat()` accepts. Typed off the
+ * installed `@tanstack/ai`, so it tracks that version.
+ *
+ * The request's own fields are excluded: messages, system prompts, tools,
+ * output schema, streaming, cancellation, and the tool-loop bound belong to the
+ * machine and the adapter.
+ */
+export type TanStackAiCallSettings = Omit<TextActivityOptions<AnyTextAdapter, undefined, boolean>, "adapter" | "messages" | "systemPrompts" | "tools" | "outputSchema" | "stream" | "abortController" | "agentLoopStrategy">;
+/**
+ * One entry in a {@link TanStackAiModelMap}: a bare text adapter, or an adapter
+ * paired with the {@link TanStackAiCallSettings} that ref always runs with — how
+ * a host gives a ref a persona without the machine naming a provider knob.
+ */
+export type TanStackAiModelEntry = AnyTextAdapter | {
+  adapter: AnyTextAdapter;
+  settings?: TanStackAiCallSettings;
+};
+/** Model registry: maps model refs (as used in `setupAgent({ models })`) to
+ * TanStack AI text adapters, or to `{ adapter, settings }` pairs. */
+export type TanStackAiModelMap<TKey extends string = string> = Record<TKey, TanStackAiModelEntry>;
+/**
+ * Options for {@link createTanStackAiExecutors}: a static `models` map, a
+ * `resolveModel` function (refs resolved dynamically), or both —
+ * `resolveModel` takes precedence when both are supplied.
+ *
+ * `settings` carries `chat()` options that are the HOST's business, such as
+ * provider `modelOptions`. Pass an object to apply it to every call, or a
+ * function to vary it per request (`request.name` is the request's registered
+ * key). Precedence is global `settings`, then the model entry's `settings`,
+ * then the request's own generation settings (see
+ * {@link toTanStackAiModelOptions}); `modelOptions` merge key by key.
+ */
+export type CreateTanStackAiExecutorsOptions<TModels extends TanStackAiModelMap = TanStackAiModelMap> = {
+  settings?: TanStackAiCallSettings | ((request: AgentTextRequest | AgentDecisionRequest) => TanStackAiCallSettings | undefined);
+} & ({
+  models: TModels;
+  resolveModel?: (modelRef: keyof TModels & string) => AnyTextAdapter;
+} | {
+  models?: TModels;
+  resolveModel: (modelRef: string) => AnyTextAdapter;
+});
+/**
+ * Raw result shape from {@link TanStackAiExecutors.generateText} — `result`
+ * (the parsed structured object for structured-output requests, or the text
+ * otherwise) plus the run metadata. Core reads `result` and `usage`; everything
+ * else flows verbatim to `onResult(request, { raw })`.
+ */
+export type TanStackAiGenerateResult = {
+  result: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `includeReasoning` and the model produced it. */
+  reasoning?: string;
+  /** Token usage summed over every model turn of the run. */
+  usage?: AgentCallUsage;
+  /** Why the run stopped, normalized to the portable {@link AgentFinishReason}. */
+  finishReason: AgentFinishReason;
+  /** Every tool call the model made during the run. */
+  toolCalls: TanStackAiToolCall[];
+  /** The run's response messages — each turn's assistant text and tool
+   * calls, and the tool results fed back — ready to append to a
+   * conversation. */
+  messages: AgentMessage[];
+  /** Every chunk the run produced, in order. */
+  raw: StreamChunk[];
+};
+/** Raw result shape from {@link TanStackAiExecutors.streamText} — the
+ * accumulated text once the stream finishes (deltas are delivered via
+ * `onChunk`), plus the run's usage and finish reason. */
+export type TanStackAiStreamResult = {
+  result: string;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  /** The run's response messages, as on {@link TanStackAiGenerateResult}. */
+  messages: AgentMessage[];
+  raw: StreamChunk[];
+};
+/** Raw result shape from {@link TanStackAiExecutors.decide} — the chosen event
+ * plus the call metadata, delivered per decision attempt to `onResult`. */
+export type TanStackAiDecideResult = {
+  event: ChosenEvent;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  raw: StreamChunk[];
+};
+/** `createTanStackAiExecutors` always populates all three slots, and its
+ * results are concretely typed. */
+export interface TanStackAiExecutors {
+  generateText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<TanStackAiGenerateResult>;
+  streamText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<TanStackAiStreamResult>;
+  decide: (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => Promise<TanStackAiDecideResult>;
+}
+/** The text adapter inside a map entry, whichever form it takes. */
+export declare function toTextAdapter(entry: TanStackAiModelEntry): AnyTextAdapter;
+/**
+ * Builds the `{ generateText, streamText, decide }` executor set over TanStack
+ * AI's `chat()`. Compare `createAiSdkExecutors` — same shape, different SDK
+ * underneath.
+ *
+ * - Structured output uses `chat({ outputSchema })` around the
+ *   `{ result, reasoning? }` provider output schema.
+ * - Tools run in `chat()`'s own loop, for `generateText` and `streamText`
+ *   alike, bounded by the request's `maxSteps` (default 1). A tool with no
+ *   `execute` stops the run at its call.
+ * - Decisions offer one tool per candidate event, with no `execute`, so the
+ *   run stops at the model's first call; the tool choice is forced where the
+ *   provider supports it (see {@link toTanStackAiModelOptions}).
+ *
+ * Pass the options object, or pass the machine (or its `setupAgent(...)`
+ * result) to reuse the `models` declared in `setupAgent({ models })`. Anything
+ * else throws here, at construction.
+ *
+ * @example
+ * ```ts
+ * import { openaiText } from '@tanstack/ai-openai';
+ *
+ * const executors = createTanStackAiExecutors({ models: { quick: openaiText('gpt-6-luna') } });
+ * const result = await runToQuiescence(createAgentRuntime(machine, { executors }), { input });
+ * ```
+ */
+export declare function createTanStackAiExecutors<TModels extends TanStackAiModelMap>(options: CreateTanStackAiExecutorsOptions<TModels>): TanStackAiExecutors;
+export declare function createTanStackAiExecutors(machine: AnyStateMachine): TanStackAiExecutors;
+//#endregion