@statelyai/agent 2.0.0-alpha.33 → 2.0.0-alpha.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/CHANGELOG.md +32 -0
  2. package/dist/ai-sdk.cjs +114 -63
  3. package/dist/ai-sdk.d.cts +11 -2
  4. package/dist/ai-sdk.d.mts +11 -2
  5. package/dist/ai-sdk.mjs +115 -64
  6. package/dist/{decision-BPdEaxPf.cjs → decision-BEsATcr1.cjs} +18 -2
  7. package/dist/{decision-CV7WiV5C.mjs → decision-COkJNjOW.mjs} +18 -2
  8. package/dist/{event-log-CKWeC7H-.cjs → event-log-BWSSLUff.cjs} +139 -10
  9. package/dist/{event-log-DAqsalT1.mjs → event-log-C7jeH0y8.mjs} +123 -12
  10. package/dist/{event-log-store-C2NjVlWU.d.mts → event-log-store-BzXehP7R.d.cts} +28 -3
  11. package/dist/{event-log-store-s73r1Hxf.d.cts → event-log-store-CWjN6lmM.d.mts} +28 -3
  12. package/dist/{event-log-store-DKyE7JKr.cjs → event-log-store-CleWpsp5.cjs} +1 -1
  13. package/dist/{event-log-store-BGehvVTb.mjs → event-log-store-W49TCJXi.mjs} +1 -1
  14. package/dist/index.cjs +5 -5
  15. package/dist/index.d.cts +7 -7
  16. package/dist/index.d.mts +7 -7
  17. package/dist/index.mjs +5 -5
  18. package/dist/log.cjs +2 -2
  19. package/dist/log.d.cts +1 -1
  20. package/dist/log.d.mts +1 -1
  21. package/dist/log.mjs +2 -2
  22. package/dist/machines.cjs +1 -1
  23. package/dist/machines.mjs +1 -1
  24. package/dist/{model-source-BilDEyqk.mjs → model-source-CK3F4YuU.mjs} +1 -1
  25. package/dist/{model-source-BQ97_l1-.cjs → model-source-DmhTMK39.cjs} +1 -1
  26. package/dist/openai.cjs +377 -95
  27. package/dist/openai.d.cts +55 -20
  28. package/dist/openai.d.mts +55 -20
  29. package/dist/openai.mjs +375 -96
  30. package/dist/otel.d.cts +1 -1
  31. package/dist/otel.d.mts +1 -1
  32. package/dist/{run-agent-B5QhabdY.d.cts → run-agent-B1-Eqviq.d.cts} +13 -5
  33. package/dist/{run-agent-Atu-wEk7.d.mts → run-agent-BGdx5913.d.mts} +13 -5
  34. package/dist/{run-agent-2UnSUhDb.mjs → run-agent-Ct_GZw_f.mjs} +124 -38
  35. package/dist/{run-agent-Cg0xd3K-.cjs → run-agent-s5D32w99.cjs} +123 -37
  36. package/dist/{setup-agent-CmhB-U5P.mjs → setup-agent-05uw4dPZ.mjs} +2 -2
  37. package/dist/{setup-agent-BiF1N3td.d.cts → setup-agent-BtfeFfF6.d.cts} +2 -2
  38. package/dist/{setup-agent-J9f_Wu5T.d.mts → setup-agent-C6nqzv_X.d.mts} +2 -2
  39. package/dist/{setup-agent-CwUJyqKB.cjs → setup-agent-CXEBURdo.cjs} +2 -2
  40. package/dist/tanstack-ai.cjs +91 -59
  41. package/dist/tanstack-ai.d.cts +13 -2
  42. package/dist/tanstack-ai.d.mts +13 -2
  43. package/dist/tanstack-ai.mjs +91 -59
  44. package/dist/testing.cjs +539 -13
  45. package/dist/testing.d.cts +202 -6
  46. package/dist/testing.d.mts +202 -6
  47. package/dist/testing.mjs +536 -14
  48. package/dist/{text-logic-CYP502VT.d.cts → text-logic-CV_4KGr6.d.cts} +28 -3
  49. package/dist/{text-logic-DuK9HIFM.d.mts → text-logic-Ckh-rJFV.d.mts} +28 -3
  50. package/dist/{usage-D7JKAxLc.d.mts → usage-BDiJKyv9.d.cts} +11 -1
  51. package/dist/{usage-DVw-646x.d.cts → usage-DOoVUGVq.d.mts} +11 -1
  52. package/dist/validate.cjs +3 -3
  53. package/dist/validate.d.cts +2 -2
  54. package/dist/validate.d.mts +2 -2
  55. package/dist/validate.mjs +3 -3
  56. package/dist/{verify-Dk3Vwnha.d.cts → verify-BQpE8hUz.d.cts} +1 -1
  57. package/dist/{verify-DgB8P-Wx.mjs → verify-Bpahmr34.mjs} +2 -2
  58. package/dist/{verify-BVz4cURF.d.mts → verify-CqeuEmIk.d.mts} +1 -1
  59. package/dist/{verify-CS_WLRXn.cjs → verify-DCLZa9R0.cjs} +2 -2
  60. package/dist/with-model-calls-BXYdBdcu.cjs +45 -0
  61. package/dist/with-model-calls-Bv4V4EHC.mjs +34 -0
  62. package/package.json +5 -5
  63. package/readme.md +14 -13
  64. package/skills/loop-to-machine/SKILL.md +40 -2
package/dist/openai.d.cts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
2
- import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-CYP502VT.cjs";
2
+ import { G as AgentEventDescriptor, N as AgentDecisionRejection, P as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-CV_4KGr6.cjs";
3
3
  import OpenAI from "openai";
4
- import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
4
+ import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam } from "openai/resources/chat/completions/completions.js";
5
+ import { FunctionTool, Response, ResponseInputItem, ResponseUsage } from "openai/resources/responses/responses.js";
5
6
  //#region src/openai/index.d.ts
6
7
  /** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
7
8
  export declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
@@ -26,23 +27,31 @@ export declare function toOpenAiCallSettings(request: Pick<AgentTextRequest, "te
26
27
  seed: number | undefined;
27
28
  stop: string[] | undefined;
28
29
  }>;
29
- /** One OpenAI function tool per `AgentTools` entry. */
30
- export declare function toOpenAiTools(tools: AgentTools): ChatCompletionTool[];
30
+ /** One Responses API function tool per `AgentTools` entry. `strict` is sent as
31
+ * `false` because the Responses API defaults it to `true`, and arbitrary JSON
32
+ * Schema (e.g. from Zod) may fall outside OpenAI's strict-mode subset. */
33
+ export declare function toOpenAiTools(tools: AgentTools): FunctionTool[];
31
34
  /**
32
- * Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
33
- * `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
35
+ * Maps an {@link AgentToolChoice} onto the Responses API's `tool_choice` —
36
+ * `{ type: 'tool', name }` becomes `{ type: 'function', name }`;
34
37
  * `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
35
38
  * `undefined` stays `undefined`, so the key is omitted.
36
39
  */
37
40
  export declare function toOpenAiToolChoice(toolChoice: AgentToolChoice | undefined): "auto" | "none" | "required" | {
38
41
  type: "function";
39
- function: {
40
- name: string;
41
- };
42
+ name: string;
42
43
  } | undefined;
43
- /** One OpenAI function tool per candidate decision event — the "tool-per-event
44
- * + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
45
- export declare function toOpenAiEventTools(events: AgentEventDescriptor[]): ChatCompletionTool[];
44
+ /** One Responses API function tool per candidate decision event — the
45
+ * "tool-per-event + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
46
+ export declare function toOpenAiEventTools(events: AgentEventDescriptor[]): FunctionTool[];
47
+ /**
48
+ * Maps the Chat Completions messages {@link toOpenAiMessages} builds onto
49
+ * Responses API input items: assistant `tool_calls` become `function_call`
50
+ * items and tool messages become `function_call_output` items. Reusing the
51
+ * Chat Completions mapping keeps one place that decides what a message part
52
+ * means.
53
+ */
54
+ export declare function toResponsesInput(messages: ChatCompletionMessageParam[]): ResponseInputItem[];
46
55
  /**
47
56
  * Messages for a decision request, with prior failed `attempts` rendered as an
48
57
  * appended user message so retries converge. Mirrors the AI SDK adapter's
@@ -65,12 +74,24 @@ export declare function toAgentCallUsage(usage: OpenAiUsage | undefined): AgentC
65
74
  * `'other'`. OpenAI's own string stays on the result's `raw`.
66
75
  */
67
76
  export declare function toAgentFinishReason(finishReason: ChatCompletion.Choice["finish_reason"] | null | undefined): AgentFinishReason;
77
+ /** {@link toAgentCallUsage} for a Responses API usage payload, which names its
78
+ * fields `input_tokens`/`output_tokens`. */
79
+ export declare function toAgentResponseUsage(usage: ResponseUsage | null | undefined): AgentCallUsage | undefined;
80
+ /**
81
+ * The portable {@link AgentFinishReason} of a Responses API response, which has
82
+ * no `finish_reason`: an `incomplete` status carries the reason, and a
83
+ * completed response that asked for function calls stopped for them.
84
+ */
85
+ export declare function toAgentResponseFinishReason(response: Pick<Response, "status" | "incomplete_details" | "output">): AgentFinishReason;
68
86
  /**
69
87
  * Per-call OpenAI Chat Completions parameters a host can apply on top of what
70
88
  * the machine asked for — `reasoning_effort`, `service_tier`,
71
89
  * `max_completion_tokens`, and anything else the API accepts. Typed straight
72
90
  * off the installed `openai` package, so it tracks that version instead of
73
- * restating its vocabulary.
91
+ * restating its vocabulary. Calls that go through the Responses API translate
92
+ * `reasoning_effort`, `max_completion_tokens`, and `verbosity` onto its names
93
+ * and drop, with a warning, the settings it has no equivalent for, such as `seed`, `stop`,
94
+ * `logprobs`, and `prediction`.
74
95
  *
75
96
  * The request's own fields are excluded: `model`, `messages`, `tools`,
76
97
  * `tool_choice`, `response_format`, `n`, and the streaming switches belong to
@@ -99,6 +120,10 @@ export type OpenAiCallSettings = Omit<Partial<ChatCompletionCreateParamsNonStrea
99
120
  */
100
121
  export type CreateOpenAiExecutorsOptions = {
101
122
  client: OpenAI;
123
+ /** Where tool-free text calls go: `'chat'` (default, `chat.completions.create`)
124
+ * or `'responses'` (`responses.create`), for a host whose recorded traffic uses
125
+ * it. Decisions and tool calls always use the Responses API. */
126
+ api?: "chat" | "responses";
102
127
  resolveModel?: (modelRef: string) => string;
103
128
  settings?: Record<string, OpenAiCallSettings> | ((request: AgentTextRequest | AgentDecisionRequest) => OpenAiCallSettings | undefined);
104
129
  };
@@ -119,6 +144,8 @@ export type OpenAiGenerateResult = {
119
144
  usage?: AgentCallUsage;
120
145
  /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
121
146
  finishReason: AgentFinishReason;
147
+ /** OpenAI calls the tool loop made. */
148
+ modelCalls: number;
122
149
  /** The untouched OpenAI response. */
123
150
  raw: unknown;
124
151
  };
@@ -131,9 +158,14 @@ export type OpenAiStreamResult = {
131
158
  /** The last chunk seen, which carries the stream's finish metadata. */
132
159
  raw: unknown;
133
160
  };
134
- /** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event plus the call metadata, delivered per decision attempt to `onResult`. */
135
- export type OpenAiDecideResult = {
161
+ /** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event (or the answer's rejection) plus the call metadata, delivered per decision attempt to `onResult`. */
162
+ export type OpenAiDecideResult = ({
136
163
  event: ChosenEvent;
164
+ rejected?: undefined;
165
+ } | {
166
+ event?: undefined;
167
+ rejected: AgentDecisionRejection;
168
+ }) & {
137
169
  usage?: AgentCallUsage;
138
170
  finishReason: AgentFinishReason;
139
171
  raw: unknown;
@@ -159,12 +191,15 @@ export interface OpenAiExecutors {
159
191
  export declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: AgentCallUsage | undefined): AgentCallUsage | undefined;
160
192
  /**
161
193
  * Builds the `{ generateText, streamText, decide }` executor set for the raw
162
- * `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
163
- * same shape, different SDK underneath.
194
+ * `openai` package. Compare `createAiSdkExecutors` — same shape, different SDK
195
+ * underneath.
164
196
  *
165
- * Structured output uses `response_format: { type: 'json_schema' }` around the
166
- * `{ result, reasoning? }` provider output schema, and decisions force a tool call
167
- * with `tool_choice: 'required'`, one function tool per candidate event.
197
+ * Calls with function tools use the Responses API, which reasoning models
198
+ * require for tools: decisions force a call with `tool_choice: 'required'`, one
199
+ * function tool per candidate event, and `generateText` runs its tool loop
200
+ * there. Tool-free calls use Chat Completions. Structured output wraps the
201
+ * `{ result, reasoning? }` provider output schema in a `json_schema` format on
202
+ * either API.
168
203
  *
169
204
  * @example
170
205
  * ```ts
package/dist/openai.d.mts CHANGED
@@ -1,7 +1,8 @@
1
1
  import { i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
2
- import { N as AgentDecisionRequest, W as AgentEventDescriptor, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-DuK9HIFM.mjs";
2
+ import { G as AgentEventDescriptor, N as AgentDecisionRejection, P as AgentDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, r as AgentFinishReason, t as AgentCallUsage } from "./text-logic-Ckh-rJFV.mjs";
3
3
  import OpenAI from "openai";
4
- import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions.js";
4
+ import { ChatCompletion, ChatCompletionCreateParamsNonStreaming, ChatCompletionMessageParam } from "openai/resources/chat/completions/completions.js";
5
+ import { FunctionTool, Response, ResponseInputItem, ResponseUsage } from "openai/resources/responses/responses.js";
5
6
  //#region src/openai/index.d.ts
6
7
  /** Maps `AgentTextRequest.messages`/`system`/`prompt` to OpenAI chat messages. */
7
8
  export declare function toOpenAiMessages(request: Pick<AgentTextRequest, "system" | "prompt"> & {
@@ -26,23 +27,31 @@ export declare function toOpenAiCallSettings(request: Pick<AgentTextRequest, "te
26
27
  seed: number | undefined;
27
28
  stop: string[] | undefined;
28
29
  }>;
29
- /** One OpenAI function tool per `AgentTools` entry. */
30
- export declare function toOpenAiTools(tools: AgentTools): ChatCompletionTool[];
30
+ /** One Responses API function tool per `AgentTools` entry. `strict` is sent as
31
+ * `false` because the Responses API defaults it to `true`, and arbitrary JSON
32
+ * Schema (e.g. from Zod) may fall outside OpenAI's strict-mode subset. */
33
+ export declare function toOpenAiTools(tools: AgentTools): FunctionTool[];
31
34
  /**
32
- * Maps an {@link AgentToolChoice} onto OpenAI's `tool_choice` —
33
- * `{ type: 'tool', name }` becomes `{ type: 'function', function: { name } }`;
35
+ * Maps an {@link AgentToolChoice} onto the Responses API's `tool_choice` —
36
+ * `{ type: 'tool', name }` becomes `{ type: 'function', name }`;
34
37
  * `'auto'`/`'none'`/`'required'` are OpenAI's own vocabulary and pass through.
35
38
  * `undefined` stays `undefined`, so the key is omitted.
36
39
  */
37
40
  export declare function toOpenAiToolChoice(toolChoice: AgentToolChoice | undefined): "auto" | "none" | "required" | {
38
41
  type: "function";
39
- function: {
40
- name: string;
41
- };
42
+ name: string;
42
43
  } | undefined;
43
- /** One OpenAI function tool per candidate decision event — the "tool-per-event
44
- * + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
45
- export declare function toOpenAiEventTools(events: AgentEventDescriptor[]): ChatCompletionTool[];
44
+ /** One Responses API function tool per candidate decision event — the
45
+ * "tool-per-event + tool_choice: 'required'" recipe, mirroring `toAiSdkEventTools`. */
46
+ export declare function toOpenAiEventTools(events: AgentEventDescriptor[]): FunctionTool[];
47
+ /**
48
+ * Maps the Chat Completions messages {@link toOpenAiMessages} builds onto
49
+ * Responses API input items: assistant `tool_calls` become `function_call`
50
+ * items and tool messages become `function_call_output` items. Reusing the
51
+ * Chat Completions mapping keeps one place that decides what a message part
52
+ * means.
53
+ */
54
+ export declare function toResponsesInput(messages: ChatCompletionMessageParam[]): ResponseInputItem[];
46
55
  /**
47
56
  * Messages for a decision request, with prior failed `attempts` rendered as an
48
57
  * appended user message so retries converge. Mirrors the AI SDK adapter's
@@ -65,12 +74,24 @@ export declare function toAgentCallUsage(usage: OpenAiUsage | undefined): AgentC
65
74
  * `'other'`. OpenAI's own string stays on the result's `raw`.
66
75
  */
67
76
  export declare function toAgentFinishReason(finishReason: ChatCompletion.Choice["finish_reason"] | null | undefined): AgentFinishReason;
77
+ /** {@link toAgentCallUsage} for a Responses API usage payload, which names its
78
+ * fields `input_tokens`/`output_tokens`. */
79
+ export declare function toAgentResponseUsage(usage: ResponseUsage | null | undefined): AgentCallUsage | undefined;
80
+ /**
81
+ * The portable {@link AgentFinishReason} of a Responses API response, which has
82
+ * no `finish_reason`: an `incomplete` status carries the reason, and a
83
+ * completed response that asked for function calls stopped for them.
84
+ */
85
+ export declare function toAgentResponseFinishReason(response: Pick<Response, "status" | "incomplete_details" | "output">): AgentFinishReason;
68
86
  /**
69
87
  * Per-call OpenAI Chat Completions parameters a host can apply on top of what
70
88
  * the machine asked for — `reasoning_effort`, `service_tier`,
71
89
  * `max_completion_tokens`, and anything else the API accepts. Typed straight
72
90
  * off the installed `openai` package, so it tracks that version instead of
73
- * restating its vocabulary.
91
+ * restating its vocabulary. Calls that go through the Responses API translate
92
+ * `reasoning_effort`, `max_completion_tokens`, and `verbosity` onto its names
93
+ * and drop, with a warning, the settings it has no equivalent for, such as `seed`, `stop`,
94
+ * `logprobs`, and `prediction`.
74
95
  *
75
96
  * The request's own fields are excluded: `model`, `messages`, `tools`,
76
97
  * `tool_choice`, `response_format`, `n`, and the streaming switches belong to
@@ -99,6 +120,10 @@ export type OpenAiCallSettings = Omit<Partial<ChatCompletionCreateParamsNonStrea
99
120
  */
100
121
  export type CreateOpenAiExecutorsOptions = {
101
122
  client: OpenAI;
123
+ /** Where tool-free text calls go: `'chat'` (default, `chat.completions.create`)
124
+ * or `'responses'` (`responses.create`), for a host whose recorded traffic uses
125
+ * it. Decisions and tool calls always use the Responses API. */
126
+ api?: "chat" | "responses";
102
127
  resolveModel?: (modelRef: string) => string;
103
128
  settings?: Record<string, OpenAiCallSettings> | ((request: AgentTextRequest | AgentDecisionRequest) => OpenAiCallSettings | undefined);
104
129
  };
@@ -119,6 +144,8 @@ export type OpenAiGenerateResult = {
119
144
  usage?: AgentCallUsage;
120
145
  /** Why the call stopped, normalized to the portable {@link AgentFinishReason}. OpenAI's own value stays on `raw`. */
121
146
  finishReason: AgentFinishReason;
147
+ /** OpenAI calls the tool loop made. */
148
+ modelCalls: number;
122
149
  /** The untouched OpenAI response. */
123
150
  raw: unknown;
124
151
  };
@@ -131,9 +158,14 @@ export type OpenAiStreamResult = {
131
158
  /** The last chunk seen, which carries the stream's finish metadata. */
132
159
  raw: unknown;
133
160
  };
134
- /** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event plus the call metadata, delivered per decision attempt to `onResult`. */
135
- export type OpenAiDecideResult = {
161
+ /** Raw result shape from {@link OpenAiExecutors.decide} — the chosen event (or the answer's rejection) plus the call metadata, delivered per decision attempt to `onResult`. */
162
+ export type OpenAiDecideResult = ({
136
163
  event: ChosenEvent;
164
+ rejected?: undefined;
165
+ } | {
166
+ event?: undefined;
167
+ rejected: AgentDecisionRejection;
168
+ }) & {
137
169
  usage?: AgentCallUsage;
138
170
  finishReason: AgentFinishReason;
139
171
  raw: unknown;
@@ -159,12 +191,15 @@ export interface OpenAiExecutors {
159
191
  export declare function addAgentCallUsage(total: AgentCallUsage | undefined, next: AgentCallUsage | undefined): AgentCallUsage | undefined;
160
192
  /**
161
193
  * Builds the `{ generateText, streamText, decide }` executor set for the raw
162
- * `openai` package's Chat Completions API. Compare `createAiSdkExecutors` —
163
- * same shape, different SDK underneath.
194
+ * `openai` package. Compare `createAiSdkExecutors` — same shape, different SDK
195
+ * underneath.
164
196
  *
165
- * Structured output uses `response_format: { type: 'json_schema' }` around the
166
- * `{ result, reasoning? }` provider output schema, and decisions force a tool call
167
- * with `tool_choice: 'required'`, one function tool per candidate event.
197
+ * Calls with function tools use the Responses API, which reasoning models
198
+ * require for tools: decisions force a call with `tool_choice: 'required'`, one
199
+ * function tool per candidate event, and `generateText` runs its tool loop
200
+ * there. Tool-free calls use Chat Completions. Structured output wraps the
201
+ * `{ result, reasoning? }` provider output schema in a `json_schema` format on
202
+ * either API.
168
203
  *
169
204
  * @example
170
205
  * ```ts