@statelyai/agent 2.0.0-alpha.22 → 2.0.0-alpha.23

package/dist/openai.d.cts

@@ -0,0 +1,177 @@
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-CjHk5OdH.cjs";
+import { F as AgentDecisionRequest, K as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-C7bSnH_B.cjs";
+import OpenAI from "openai";
+import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
+
+//#region src/openai/index.d.ts
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
+declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
+  messages?: AgentMessage[];
+}): ChatCompletionMessageParam[];
+/**
+ * Maps the generation settings a text and a decision request share onto OpenAI
+ * Chat Completions parameters, with unset keys omitted.
+ *
+ * Omitting matters: these are the top layer of a stack — the host's
+ * {@link CreateOpenAiExecutorsOptions.settings}, then the request's — and an
+ * `undefined` spread over the layer below would erase it.
+ *
+ * `max_tokens` is deprecated by OpenAI in favor of `max_completion_tokens`, so
+ * that's what `maxOutputTokens` targets. Chat Completions has no `top_k`
+ * parameter, so `topK` is dropped.
+ */
+declare function toOpenAiCallSettings(request: Pick<AgentTextRequest, "temperature" | "maxOutputTokens" | "topP" | "seed" | "stopSequences">): Partial<{
+  temperature: number | undefined;
+  max_completion_tokens: number | undefined;
+  top_p: number | undefined;
+  seed: number | undefined;
+  stop: string[] | undefined;
+}>;
+/** One OpenAI function tool per `AgentTools` entry. */
+declare function toOpenAiTools(tools: AgentTools): ChatCompletionTool[];
+/**
+ * Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
+ * `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
+ * `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
+ * `undefined` stays `undefined`, so the key is omitted.
+ */
+declare function toOpenAiToolChoice(toolChoice: AgentToolChoice | undefined): "auto" | "none" | "required" | {
+  type: "function";
+  function: {
+    name: string;
+  };
+} | undefined;
+/** One OpenAI function tool per candidate decision event — the "tool-per-event
+ * + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
+declare function toOpenAiEventTools(events: AgentEventDescriptor[]): ChatCompletionTool[];
+/**
+ * Messages for a decision request, with prior failed `attempts` rendered as an
+ * appended user message so retries converge. Mirrors the AI SDK adapter's
+ * `toDecisionMessages`.
+ */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ChatCompletionMessageParam[];
+type OpenAiUsage = NonNullable<ChatCompletion["usage"]>;
+/**
+ * Folds OpenAI's usage payload onto the flat {@link AgentCallUsage} field names
+ * core aggregates. OpenAI nests the reasoning count under
+ * `completion_tokens_details` and the cache-read count under
+ * `prompt_tokens_details`; a field the response omitted stays omitted, so it
+ * never contributes a `0` to a run's partial sums.
+ */
+declare function toAgentCallUsage(usage: OpenAiUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Maps an OpenAI `finish_reason` onto the portable {@link AgentFinishReason}.
+ * `'function_call'` (the deprecated legacy path) joins `'tool_calls'` under
+ * `'tool-calls'`; anything unrecognized, including a missing reason, lands on
+ * `'other'`. OpenAI's own string stays on the result's `raw`.
+ */
+declare function toAgentFinishReason(finishReason: ChatCompletion.Choice["finish_reason"] | null | undefined): AgentFinishReason;
+/**
+ * Per-call OpenAI Chat Completions parameters a host can apply on top of what
+ * the machine asked for — `reasoning_effort`, `service_tier`,
+ * `max_completion_tokens`, and anything else the API accepts. Typed straight
+ * off the installed `openai` package, so it tracks that version instead of
+ * restating its vocabulary.
+ *
+ * The request's own fields are excluded: `model`, `messages`, `tools`,
+ * `tool_choice`, `response_format`, `n`, and the streaming switches belong to
+ * the machine and the adapter, and a host override would silently contradict
+ * them.
+ */
+type OpenAiCallSettings = Omit<Partial<ChatCompletionCreateParamsNonStreaming>, "model" | "messages" | "tools" | "tool_choice" | "response_format" | "n" | "stream">;
+/**
+ * Options for {@link createOpenAiExecutors}.
+ *
+ * `client` is the injected `OpenAI` instance — this adapter never constructs
+ * one, so the API key, base URL, and transport stay the host's business.
+ *
+ * `resolveModel` maps a machine's model *ref* (e.g. `'ticketTriage'`) to a real
+ * OpenAI model id. A machine's requests carry refs, not ids, so a raw-SDK host
+ * must resolve them (the AI SDK adapter does this via its `models` map).
+ * Defaults to identity, for machines that already use real ids.
+ *
+ * `settings` carries provider knobs that are the HOST's business rather than
+ * the machine's, such as reasoning effort. Pass a map keyed by model ref to
+ * give a ref a persona — `deep` thinks harder than `quick` — without the
+ * machine naming a provider knob, or a function to vary settings per request
+ * (`request.name` is the request's registered key; return `undefined` for the
+ * defaults). Settings are merged UNDER what the request declared, so a machine
+ * that set `maxOutputTokens` still wins.
+ */
+type CreateOpenAiExecutorsOptions = {
+  client: OpenAI;
+  resolveModel?: (modelRef: string) => string;
+  settings?: Record<string, OpenAiCallSettings> | ((request: AgentTextRequest | AgentDecisionRequest) => OpenAiCallSettings | undefined);
+};
+/**
+ * Raw result shape from {@link OpenAiExecutors.generateText} — the `{ output }`
+ * envelope (the validated structured object for structured-output requests, or
+ * the model's text otherwise) plus the call metadata. Core only reads `output`; everything else flows
+ * verbatim to `runAgent`'s `onResult(request, { raw })`.
+ */
+type OpenAiGenerateResult = {
+  output: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `includeReasoning` and the model produced it. Never enters machine
+   * context/output. */
+  reasoning?: string;
+  /** The call's token usage, on the flat field names `runAgent` folds into the
+   * run result's aggregated `AgentUsage`. Absent when OpenAI reported none. */
+  usage?: AgentCallUsage; /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
+  finishReason: AgentFinishReason; /** The untouched OpenAI response. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.streamText} — the accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata. */
+type OpenAiStreamResult = {
+  output: string; /** Present when the stream carried a usage chunk (the adapter asks for one via `stream_options`). */
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason; /** The last chunk seen, which carries the stream's finish metadata. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event plus the call metadata, delivered per decision attempt to `onResult`. */
+type OpenAiDecideResult = {
+  event: ChosenEvent;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  raw: unknown;
+};
+/** `createOpenAiExecutors` always populates all three slots (unlike the general
+ * `AgentRequestExecutors`, where `streamText`/`decide` are optional), and its
+ * results are concretely typed. */
+interface OpenAiExecutors {
+  generateText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiGenerateResult>;
+  streamText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiStreamResult>;
+  decide: (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => Promise<OpenAiDecideResult>;
+}
+/**
+ * Adds two calls' usage together, field by field. A tool loop makes several
+ * OpenAI calls per request, and core folds ONE `usage` per executor result into
+ * the run's totals, so the steps' usages have to be summed here or the run
+ * undercounts. A field neither call reported stays absent.
+ */
+declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: AgentCallUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Builds the `{ generateText, streamText, decide }` executor set for the raw
+ * `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
+ * same shape, different SDK underneath.
+ *
+ * Structured output uses `response_format: { type: 'json_schema' }` around the
+ * uniform `{ result, reasoning? }` envelope, and decisions force a tool call
+ * with `tool_choice: 'required'`, one function tool per candidate event.
+ *
+ * @example
+ * ```ts
+ * const executors = createOpenAiExecutors({
+ *   client: new OpenAI(),
+ *   resolveModel: () => 'gpt-5.4-mini',
+ * });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createOpenAiExecutors(options: CreateOpenAiExecutorsOptions): OpenAiExecutors;
+//#endregion
+export { CreateOpenAiExecutorsOptions, OpenAiCallSettings, OpenAiDecideResult, OpenAiExecutors, OpenAiGenerateResult, OpenAiStreamResult, addAgentCallUsage, createOpenAiExecutors, toAgentCallUsage, toAgentFinishReason, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiToolChoice, toOpenAiTools };

package/dist/openai.d.mts

@@ -0,0 +1,177 @@
+import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-DWA6X9R-.mjs";
+import { F as AgentDecisionRequest, K as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-DJBK3LbG.mjs";
+import OpenAI from "openai";
+import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
+
+//#region src/openai/index.d.ts
+/** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
+declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
+  messages?: AgentMessage[];
+}): ChatCompletionMessageParam[];
+/**
+ * Maps the generation settings a text and a decision request share onto OpenAI
+ * Chat Completions parameters, with unset keys omitted.
+ *
+ * Omitting matters: these are the top layer of a stack — the host's
+ * {@link CreateOpenAiExecutorsOptions.settings}, then the request's — and an
+ * `undefined` spread over the layer below would erase it.
+ *
+ * `max_tokens` is deprecated by OpenAI in favor of `max_completion_tokens`, so
+ * that's what `maxOutputTokens` targets. Chat Completions has no `top_k`
+ * parameter, so `topK` is dropped.
+ */
+declare function toOpenAiCallSettings(request: Pick<AgentTextRequest, "temperature" | "maxOutputTokens" | "topP" | "seed" | "stopSequences">): Partial<{
+  temperature: number | undefined;
+  max_completion_tokens: number | undefined;
+  top_p: number | undefined;
+  seed: number | undefined;
+  stop: string[] | undefined;
+}>;
+/** One OpenAI function tool per `AgentTools` entry. */
+declare function toOpenAiTools(tools: AgentTools): ChatCompletionTool[];
+/**
+ * Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
+ * `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
+ * `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
+ * `undefined` stays `undefined`, so the key is omitted.
+ */
+declare function toOpenAiToolChoice(toolChoice: AgentToolChoice | undefined): "auto" | "none" | "required" | {
+  type: "function";
+  function: {
+    name: string;
+  };
+} | undefined;
+/** One OpenAI function tool per candidate decision event — the "tool-per-event
+ * + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
+declare function toOpenAiEventTools(events: AgentEventDescriptor[]): ChatCompletionTool[];
+/**
+ * Messages for a decision request, with prior failed `attempts` rendered as an
+ * appended user message so retries converge. Mirrors the AI SDK adapter's
+ * `toDecisionMessages`.
+ */
+declare function toDecisionMessages(request: Pick<AgentDecisionRequest, "messages" | "prompt" | "events" | "attempts">): ChatCompletionMessageParam[];
+type OpenAiUsage = NonNullable<ChatCompletion["usage"]>;
+/**
+ * Folds OpenAI's usage payload onto the flat {@link AgentCallUsage} field names
+ * core aggregates. OpenAI nests the reasoning count under
+ * `completion_tokens_details` and the cache-read count under
+ * `prompt_tokens_details`; a field the response omitted stays omitted, so it
+ * never contributes a `0` to a run's partial sums.
+ */
+declare function toAgentCallUsage(usage: OpenAiUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Maps an OpenAI `finish_reason` onto the portable {@link AgentFinishReason}.
+ * `'function_call'` (the deprecated legacy path) joins `'tool_calls'` under
+ * `'tool-calls'`; anything unrecognized, including a missing reason, lands on
+ * `'other'`. OpenAI's own string stays on the result's `raw`.
+ */
+declare function toAgentFinishReason(finishReason: ChatCompletion.Choice["finish_reason"] | null | undefined): AgentFinishReason;
+/**
+ * Per-call OpenAI Chat Completions parameters a host can apply on top of what
+ * the machine asked for — `reasoning_effort`, `service_tier`,
+ * `max_completion_tokens`, and anything else the API accepts. Typed straight
+ * off the installed `openai` package, so it tracks that version instead of
+ * restating its vocabulary.
+ *
+ * The request's own fields are excluded: `model`, `messages`, `tools`,
+ * `tool_choice`, `response_format`, `n`, and the streaming switches belong to
+ * the machine and the adapter, and a host override would silently contradict
+ * them.
+ */
+type OpenAiCallSettings = Omit<Partial<ChatCompletionCreateParamsNonStreaming>, "model" | "messages" | "tools" | "tool_choice" | "response_format" | "n" | "stream">;
+/**
+ * Options for {@link createOpenAiExecutors}.
+ *
+ * `client` is the injected `OpenAI` instance — this adapter never constructs
+ * one, so the API key, base URL, and transport stay the host's business.
+ *
+ * `resolveModel` maps a machine's model *ref* (e.g. `'ticketTriage'`) to a real
+ * OpenAI model id. A machine's requests carry refs, not ids, so a raw-SDK host
+ * must resolve them (the AI SDK adapter does this via its `models` map).
+ * Defaults to identity, for machines that already use real ids.
+ *
+ * `settings` carries provider knobs that are the HOST's business rather than
+ * the machine's, such as reasoning effort. Pass a map keyed by model ref to
+ * give a ref a persona — `deep` thinks harder than `quick` — without the
+ * machine naming a provider knob, or a function to vary settings per request
+ * (`request.name` is the request's registered key; return `undefined` for the
+ * defaults). Settings are merged UNDER what the request declared, so a machine
+ * that set `maxOutputTokens` still wins.
+ */
+type CreateOpenAiExecutorsOptions = {
+  client: OpenAI;
+  resolveModel?: (modelRef: string) => string;
+  settings?: Record<string, OpenAiCallSettings> | ((request: AgentTextRequest | AgentDecisionRequest) => OpenAiCallSettings | undefined);
+};
+/**
+ * Raw result shape from {@link OpenAiExecutors.generateText} — the `{ output }`
+ * envelope (the validated structured object for structured-output requests, or
+ * the model's text otherwise) plus the call metadata. Core only reads `output`; everything else flows
+ * verbatim to `runAgent`'s `onResult(request, { raw })`.
+ */
+type OpenAiGenerateResult = {
+  output: unknown;
+  /** The model's reasoning, present only when the request opted in via
+   * `includeReasoning` and the model produced it. Never enters machine
+   * context/output. */
+  reasoning?: string;
+  /** The call's token usage, on the flat field names `runAgent` folds into the
+   * run result's aggregated `AgentUsage`. Absent when OpenAI reported none. */
+  usage?: AgentCallUsage; /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
+  finishReason: AgentFinishReason; /** The untouched OpenAI response. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.streamText} — the accumulated text once the stream finishes (chunks are delivered separately via `onChunk`), plus the stream's final usage/finish metadata. */
+type OpenAiStreamResult = {
+  output: string; /** Present when the stream carried a usage chunk (the adapter asks for one via `stream_options`). */
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason; /** The last chunk seen, which carries the stream's finish metadata. */
+  raw: unknown;
+};
+/** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event plus the call metadata, delivered per decision attempt to `onResult`. */
+type OpenAiDecideResult = {
+  event: ChosenEvent;
+  usage?: AgentCallUsage;
+  finishReason: AgentFinishReason;
+  raw: unknown;
+};
+/** `createOpenAiExecutors` always populates all three slots (unlike the general
+ * `AgentRequestExecutors`, where `streamText`/`decide` are optional), and its
+ * results are concretely typed. */
+interface OpenAiExecutors {
+  generateText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiGenerateResult>;
+  streamText: (request: AgentTextRequest & {
+    tools: AgentTools;
+  }, info?: AgentRequestExecutorInfo) => Promise<OpenAiStreamResult>;
+  decide: (request: AgentDecisionRequest, info?: AgentRequestExecutorInfo) => Promise<OpenAiDecideResult>;
+}
+/**
+ * Adds two calls' usage together, field by field. A tool loop makes several
+ * OpenAI calls per request, and core folds ONE `usage` per executor result into
+ * the run's totals, so the steps' usages have to be summed here or the run
+ * undercounts. A field neither call reported stays absent.
+ */
+declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: AgentCallUsage | undefined): AgentCallUsage | undefined;
+/**
+ * Builds the `{ generateText, streamText, decide }` executor set for the raw
+ * `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
+ * same shape, different SDK underneath.
+ *
+ * Structured output uses `response_format: { type: 'json_schema' }` around the
+ * uniform `{ result, reasoning? }` envelope, and decisions force a tool call
+ * with `tool_choice: 'required'`, one function tool per candidate event.
+ *
+ * @example
+ * ```ts
+ * const executors = createOpenAiExecutors({
+ *   client: new OpenAI(),
+ *   resolveModel: () => 'gpt-5.4-mini',
+ * });
+ * const result = await runAgent(machine, { input, executors });
+ * ```
+ */
+declare function createOpenAiExecutors(options: CreateOpenAiExecutorsOptions): OpenAiExecutors;
+//#endregion
+export { CreateOpenAiExecutorsOptions, OpenAiCallSettings, OpenAiDecideResult, OpenAiExecutors, OpenAiGenerateResult, OpenAiStreamResult, addAgentCallUsage, createOpenAiExecutors, toAgentCallUsage, toAgentFinishReason, toDecisionMessages, toOpenAiCallSettings, toOpenAiEventTools, toOpenAiMessages, toOpenAiToolChoice, toOpenAiTools };