@statelyai/agent 2.0.0-alpha.37 → 2.0.0-alpha.39
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.
- package/CHANGELOG.md +51 -0
- package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
- package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
- package/dist/ai-sdk.cjs +4 -4
- package/dist/ai-sdk.d.cts +2 -3
- package/dist/ai-sdk.d.mts +2 -3
- package/dist/ai-sdk.mjs +4 -4
- package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
- package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
- package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
- package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
- package/dist/effects-B9IvUPVh.mjs +23 -0
- package/dist/effects-DrWcUGgc.cjs +34 -0
- package/dist/evals.cjs +810 -0
- package/dist/evals.d.cts +595 -0
- package/dist/evals.d.mts +595 -0
- package/dist/evals.mjs +801 -0
- package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
- package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
- package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
- package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
- package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
- package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
- package/dist/index.cjs +136 -98
- package/dist/index.d.cts +73 -134
- package/dist/index.d.mts +73 -134
- package/dist/index.mjs +117 -75
- package/dist/internal-BzlpzSux.d.cts +14 -0
- package/dist/internal-BzlpzSux.d.mts +14 -0
- package/dist/log.cjs +2 -3
- package/dist/log.d.cts +2 -2
- package/dist/log.d.mts +2 -2
- package/dist/log.mjs +3 -3
- package/dist/machines.cjs +1 -719
- package/dist/machines.d.cts +2 -424
- package/dist/machines.d.mts +2 -424
- package/dist/machines.mjs +2 -709
- package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
- package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
- package/dist/openai.cjs +3 -3
- package/dist/openai.d.cts +2 -3
- package/dist/openai.d.mts +2 -3
- package/dist/openai.mjs +3 -3
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +77 -0
- package/dist/policy.d.cts +143 -0
- package/dist/policy.d.mts +143 -0
- package/dist/policy.mjs +75 -0
- package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
- package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
- package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
- package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
- package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
- package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
- package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
- package/dist/tanstack-ai.cjs +4 -4
- package/dist/tanstack-ai.d.cts +2 -3
- package/dist/tanstack-ai.d.mts +2 -3
- package/dist/tanstack-ai.mjs +4 -4
- package/dist/testing.cjs +122 -996
- package/dist/testing.d.cts +36 -695
- package/dist/testing.d.mts +36 -695
- package/dist/testing.mjs +112 -977
- package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
- package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
- package/dist/trajectory-BFjXaooB.d.cts +96 -0
- package/dist/trajectory-BFjXaooB.d.mts +96 -0
- package/dist/trajectory-BUXj_1Ue.mjs +152 -0
- package/dist/trajectory-CoZSv4wF.cjs +157 -0
- package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
- package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
- package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
- package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
- package/dist/validate.cjs +4 -4
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +4 -4
- package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
- package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
- package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
- package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
- package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
- package/docs/advanced.md +5 -5
- package/docs/choosing-a-run-mode.md +7 -7
- package/docs/debugging.md +6 -8
- package/docs/decisions.md +6 -5
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +14 -16
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +22 -29
- package/docs/human-in-the-loop.md +5 -8
- package/docs/index.md +4 -4
- package/docs/judgments.md +5 -7
- package/docs/langgraph-comparison.md +6 -6
- package/docs/machines-as-data.md +12 -17
- package/docs/machines-presets.md +17 -120
- package/docs/machines.md +13 -13
- package/docs/models-and-providers.md +19 -25
- package/docs/multi-agent.md +1 -1
- package/docs/observability.md +6 -8
- package/docs/persistence.md +15 -25
- package/docs/quickstart.md +4 -4
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +72 -7
- package/docs/text-requests.md +10 -12
- package/docs/thinking-in-state-machines.md +8 -8
- package/docs/tools.md +10 -12
- package/docs/upgrading.md +1 -1
- package/docs/usage-and-budgets.md +51 -56
- package/docs/validate-and-repair.md +9 -14
- package/docs/verify.md +53 -7
- package/docs/xstate-4-and-5-apps.md +19 -28
- package/llms.txt +1 -1
- package/package.json +31 -6
- package/readme.md +32 -24
- package/dist/internal-C3Lqu538.d.cts +0 -43
- package/dist/internal-DUcdhk-i.d.mts +0 -43
- package/dist/types-DQUOOaZO.d.cts +0 -238
- package/dist/types-DQUOOaZO.d.mts +0 -238
- package/skills/add-evals/SKILL.md +0 -152
- package/skills/add-traces/SKILL.md +0 -152
- package/skills/build-machine/SKILL.md +0 -84
- package/skills/generate-machine/SKILL.md +0 -335
- package/skills/graph-engineering/SKILL.md +0 -43
- package/skills/improve-machine/SKILL.md +0 -261
- package/skills/improve-machine/reference.md +0 -101
- package/skills/loop-to-machine/SKILL.md +0 -205
- package/skills/loop-to-machine/policy.md +0 -154
- package/skills/loop-to-machine/reference.md +0 -260
|
@@ -1,5 +1,241 @@
|
|
|
1
|
-
import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, d as AllowedEvents, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.mjs";
|
|
2
1
|
import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
|
|
2
|
+
//#region src/types.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The [Standard Schema](https://standardschema.dev) interface. Every schema
|
|
5
|
+
* this library accepts (context, events, input/output, tool schemas, …) is a
|
|
6
|
+
* `StandardSchemaV1` — Zod, Valibot, ArkType, and hand-written validators all
|
|
7
|
+
* implement it, so the library never depends on a specific validation
|
|
8
|
+
* library. JSON workflow configs use a caller-provided {@link SchemaCompiler}.
|
|
9
|
+
*/
|
|
10
|
+
interface StandardSchemaV1<Input = unknown, Output = Input> {
|
|
11
|
+
readonly "~standard": {
|
|
12
|
+
readonly version: 1;
|
|
13
|
+
readonly vendor: string;
|
|
14
|
+
readonly validate: (value: unknown) => any;
|
|
15
|
+
readonly types?: {
|
|
16
|
+
readonly input: Input;
|
|
17
|
+
readonly output: Output;
|
|
18
|
+
} | undefined;
|
|
19
|
+
readonly jsonSchema?: {
|
|
20
|
+
readonly input?: (...args: any[]) => unknown;
|
|
21
|
+
readonly output?: (...args: any[]) => unknown;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
/** The validated output type of a {@link StandardSchemaV1}. */
|
|
26
|
+
type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
|
|
27
|
+
/**
|
|
28
|
+
* The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
|
|
29
|
+
* passes in, before defaults are filled and transforms applied. Standard Schema
|
|
30
|
+
* carries both sides (`~standard.types.input` / `.output`), so a schema
|
|
31
|
+
* declaring a defaulted field makes that field optional here and required in
|
|
32
|
+
* {@link InferOutput} — which is exactly the split between what a run
|
|
33
|
+
* accepts as machine `input` and what the `context` factory then sees.
|
|
34
|
+
*/
|
|
35
|
+
type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
|
|
36
|
+
/**
|
|
37
|
+
* Phantom brand carrying a machine's declared input schema on the machine type.
|
|
38
|
+
*
|
|
39
|
+
* XState resolves `schemas.input` to a single type and uses it for both
|
|
40
|
+
* `createActor`'s `input` option and the `context: ({ input })` factory, so the
|
|
41
|
+
* caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
|
|
42
|
+
* `createMachine` brands the machine's input type with the schema itself, which
|
|
43
|
+
* lets `AgentInputFrom` recover the looser input side for a run's `input` while the
|
|
44
|
+
* `context` factory keeps the strict validated side.
|
|
45
|
+
*
|
|
46
|
+
* The key is a `~`-prefixed phantom property (the same convention Standard
|
|
47
|
+
* Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
|
|
48
|
+
* have to be exported as a runtime value for declaration emit to name it in
|
|
49
|
+
* every machine type it touches.
|
|
50
|
+
*/
|
|
51
|
+
type WithAgentInputSchema<TInputSchema> = {
|
|
52
|
+
readonly "~agent.inputSchema"?: TInputSchema;
|
|
53
|
+
};
|
|
54
|
+
/** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
|
|
55
|
+
type EventPayload<T> = T extends Record<string, never> ? unknown : T;
|
|
56
|
+
/**
|
|
57
|
+
* One entry in an event schema map: a Standard Schema for the event's
|
|
58
|
+
* payload, or the `{}` shorthand for a payload-less event
|
|
59
|
+
* (`events: { CONFIRM: {} }` ≡ `events: { CONFIRM: z.object({}) }`).
|
|
60
|
+
*/
|
|
61
|
+
type AgentEventSchemaInput = StandardSchemaV1 | Record<string, never>;
|
|
62
|
+
/** An event schema map as authored: payload schemas and/or `{}` payload-less shorthands, keyed by event type. */
|
|
63
|
+
type AgentEventSchemaInputMap = Record<string, AgentEventSchemaInput>;
|
|
64
|
+
/** Resolves an authored event schema map's `{}` shorthands to real (empty-payload) schemas — the type-level counterpart of the runtime normalization in `createAgentSchemas`. */
|
|
65
|
+
type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof T]: T[K] extends StandardSchemaV1 ? T[K] : StandardSchemaV1<{}>; };
|
|
66
|
+
/**
|
|
67
|
+
* The discriminated event union derived from a machine's event schema map
|
|
68
|
+
* (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
|
|
69
|
+
* question: string }`; a `{}` shorthand entry yields its bare `{ type: K }`).
|
|
70
|
+
* Used internally by {@link createAgentSchemas} and `setupAgent` to type a
|
|
71
|
+
* machine's `TEvent`.
|
|
72
|
+
*/
|
|
73
|
+
type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
|
|
74
|
+
type: K;
|
|
75
|
+
} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown); }[keyof T & string];
|
|
76
|
+
/** Raw binary or string content for an {@link ImagePart}/{@link FilePart}. */
|
|
77
|
+
type DataContent = string | Uint8Array | ArrayBuffer;
|
|
78
|
+
/** Provider-specific passthrough options, keyed by provider name (e.g. `{ anthropic: { cacheControl: ... } }`). */
|
|
79
|
+
type ProviderOptions = Record<string, Record<string, unknown>>;
|
|
80
|
+
/** A plain-text segment of a multi-part {@link AgentMessage} content array. */
|
|
81
|
+
interface TextPart {
|
|
82
|
+
type: "text";
|
|
83
|
+
text: string;
|
|
84
|
+
providerOptions?: ProviderOptions;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
|
|
88
|
+
* JSON-serializable. Machines that persist snapshots/event logs should use
|
|
89
|
+
* URL strings or base64-encoded strings in `image` instead.
|
|
90
|
+
*/
|
|
91
|
+
interface ImagePart {
|
|
92
|
+
type: "image";
|
|
93
|
+
image: DataContent | URL;
|
|
94
|
+
mediaType?: string;
|
|
95
|
+
providerOptions?: ProviderOptions;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
|
|
99
|
+
* JSON-serializable. Machines that persist snapshots/event logs should use
|
|
100
|
+
* URL strings or base64-encoded strings in `data` instead.
|
|
101
|
+
*/
|
|
102
|
+
interface FilePart {
|
|
103
|
+
type: "file";
|
|
104
|
+
data: DataContent | URL;
|
|
105
|
+
mediaType: string;
|
|
106
|
+
filename?: string;
|
|
107
|
+
providerOptions?: ProviderOptions;
|
|
108
|
+
}
|
|
109
|
+
/** A model-issued tool call, as an {@link AssistantMessage} content part. */
|
|
110
|
+
interface ToolCallPart {
|
|
111
|
+
type: "tool-call";
|
|
112
|
+
toolCallId: string;
|
|
113
|
+
toolName: string;
|
|
114
|
+
input: unknown;
|
|
115
|
+
providerOptions?: ProviderOptions;
|
|
116
|
+
}
|
|
117
|
+
/** The result payload of a {@link ToolResultPart}, discriminated by shape (plain text/JSON, or an error variant of either). */
|
|
118
|
+
type ToolResultOutput = {
|
|
119
|
+
type: "text";
|
|
120
|
+
value: string;
|
|
121
|
+
} | {
|
|
122
|
+
type: "json";
|
|
123
|
+
value: unknown;
|
|
124
|
+
} | {
|
|
125
|
+
type: "error-text";
|
|
126
|
+
value: string;
|
|
127
|
+
} | {
|
|
128
|
+
type: "error-json";
|
|
129
|
+
value: unknown;
|
|
130
|
+
} | {
|
|
131
|
+
type: "content";
|
|
132
|
+
value: Array<TextPart | ImagePart>;
|
|
133
|
+
};
|
|
134
|
+
/** A tool's result, as a {@link ToolMessage} content part. */
|
|
135
|
+
interface ToolResultPart {
|
|
136
|
+
type: "tool-result";
|
|
137
|
+
toolCallId: string;
|
|
138
|
+
toolName: string;
|
|
139
|
+
output: ToolResultOutput;
|
|
140
|
+
providerOptions?: ProviderOptions;
|
|
141
|
+
}
|
|
142
|
+
/** A system-role {@link AgentMessage}. Create with {@link systemMessage}. */
|
|
143
|
+
type SystemMessage = {
|
|
144
|
+
role: "system";
|
|
145
|
+
content: string;
|
|
146
|
+
providerOptions?: ProviderOptions;
|
|
147
|
+
};
|
|
148
|
+
/** A user-role {@link AgentMessage}, optionally multimodal. Create with {@link userMessage}. */
|
|
149
|
+
type UserMessage = {
|
|
150
|
+
role: "user";
|
|
151
|
+
content: string | Array<TextPart | ImagePart | FilePart>;
|
|
152
|
+
providerOptions?: ProviderOptions;
|
|
153
|
+
};
|
|
154
|
+
/** An assistant-role {@link AgentMessage}, which may carry tool calls/results inline. Create with {@link assistantMessage}. */
|
|
155
|
+
type AssistantMessage = {
|
|
156
|
+
role: "assistant";
|
|
157
|
+
content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>;
|
|
158
|
+
providerOptions?: ProviderOptions;
|
|
159
|
+
};
|
|
160
|
+
/** A tool-role {@link AgentMessage} carrying one or more tool results. Create with {@link toolMessage}. */
|
|
161
|
+
type ToolMessage = {
|
|
162
|
+
role: "tool";
|
|
163
|
+
content: Array<ToolResultPart>;
|
|
164
|
+
providerOptions?: ProviderOptions;
|
|
165
|
+
};
|
|
166
|
+
/**
|
|
167
|
+
* Optional framework-neutral message helpers. Requests also accept native
|
|
168
|
+
* framework message values directly; core never converts between formats.
|
|
169
|
+
* Store messages as plain context state: a text request's `onDone` output
|
|
170
|
+
* carries the executor's response messages as `output.messages`.
|
|
171
|
+
*/
|
|
172
|
+
type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
|
|
173
|
+
/**
|
|
174
|
+
* A schema value on an {@link AgentToolDescriptor}: deliberately just `object`,
|
|
175
|
+
* because an SDK-native tool's `inputSchema` is the SDK's own union type (a Zod
|
|
176
|
+
* schema, the SDK's `Schema`, a lazy thunk, ...) and must assign structurally
|
|
177
|
+
* with no cast. The contract is runtime, not static: core narrows with
|
|
178
|
+
* `isStandardSchema` and reads {@link StandardSchemaV1} schemas via
|
|
179
|
+
* `getJsonSchema`; anything else passes through to the executor untouched.
|
|
180
|
+
*/
|
|
181
|
+
type AgentToolSchema = object;
|
|
182
|
+
/**
|
|
183
|
+
* A tool exposed to a text request, described for both the model and
|
|
184
|
+
* (optionally) host execution. This is a **minimal structural contract**: any
|
|
185
|
+
* object matching it — an AI SDK `tool({...})`, an MCP-style descriptor, or a
|
|
186
|
+
* hand-written `{ description, inputSchema, execute }` — is a valid entry, and
|
|
187
|
+
* extra properties (`providerOptions`, `toModelOutput`, …) pass through
|
|
188
|
+
* untouched via the index signature. `execute` is typed permissively so a
|
|
189
|
+
* native tool's `(input, options)` executor is structurally assignable; the
|
|
190
|
+
* SDK you built the tool with owns its precise input typing.
|
|
191
|
+
*/
|
|
192
|
+
interface AgentToolDescriptor {
|
|
193
|
+
/**
|
|
194
|
+
* Text shown to the model. Typed loosely enough to accept an SDK tool whose
|
|
195
|
+
* description is computed per call (the AI SDK v7 `tool({ description })`
|
|
196
|
+
* accepts a function of the call's context); core never reads it.
|
|
197
|
+
*/
|
|
198
|
+
description?: string | ((...args: any[]) => string);
|
|
199
|
+
inputSchema?: AgentToolSchema;
|
|
200
|
+
outputSchema?: AgentToolSchema;
|
|
201
|
+
execute?: (...args: any[]) => unknown;
|
|
202
|
+
[key: string]: unknown;
|
|
203
|
+
}
|
|
204
|
+
/** A bare tool implementation (no description/schema) — shorthand for {@link AgentToolDescriptor.execute}. */
|
|
205
|
+
type AgentToolExecute = (input?: unknown) => unknown | Promise<unknown>;
|
|
206
|
+
/** A tool entry in {@link AgentTools}: either a full descriptor or a bare execute function. */
|
|
207
|
+
type AgentTool = AgentToolDescriptor | AgentToolExecute;
|
|
208
|
+
/** The `tools` map passed on an {@link AgentTextRequest}, keyed by tool name. */
|
|
209
|
+
type AgentTools = Record<string, AgentTool | undefined>;
|
|
210
|
+
/** How a text request's model should select among its `tools`; `{ type: 'tool', name }` forces one specific tool. */
|
|
211
|
+
type AgentToolChoice = "auto" | "none" | "required" | {
|
|
212
|
+
type: "tool";
|
|
213
|
+
name: string;
|
|
214
|
+
};
|
|
215
|
+
/** The event chosen and raised by a decision. */
|
|
216
|
+
type ChosenEvent = {
|
|
217
|
+
type: string;
|
|
218
|
+
[key: string]: unknown;
|
|
219
|
+
};
|
|
220
|
+
type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${infer Rest}` ? `${Head}.*` | `${Head}.${EventWildcardsOf<Rest>}` : never;
|
|
221
|
+
/** One `allowedEvents` entry: an exact declared event type, `'*'` (every event), or a `'prefix.*'` wildcard derived from the declared dotted event types. */
|
|
222
|
+
type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventWildcardsOf<TEvent>;
|
|
223
|
+
/**
|
|
224
|
+
* Candidate event types for a decision (declared on the `agent.decide`
|
|
225
|
+
* builtin's `allowedEvents` input). A single
|
|
226
|
+
* entry or an array; entries are exact event types or wildcard patterns
|
|
227
|
+
* (`'*'` for every event, `'todo.*'` for a dotted namespace). The effective
|
|
228
|
+
* candidate set offered to the model is this declaration **intersected with
|
|
229
|
+
* the snapshot's currently-legal events** (via `getAcceptedEvents`) —
|
|
230
|
+
* omitting `allowedEvents` means "all currently-legal events." A resolver
|
|
231
|
+
* function can therefore only ever narrow, never widen, the real surface.
|
|
232
|
+
* Wildcards expand against the live snapshot, so they need a snapshot-aware
|
|
233
|
+
* host (`createAgentRuntime`).
|
|
234
|
+
*/
|
|
235
|
+
type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
|
|
236
|
+
input: TInput;
|
|
237
|
+
}) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
|
|
238
|
+
//#endregion
|
|
3
239
|
//#region src/errors.d.ts
|
|
4
240
|
/**
|
|
5
241
|
* Base class for every error this package throws. Carries a stable, kebab-case
|
|
@@ -1015,4 +1251,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
|
|
|
1015
1251
|
*/
|
|
1016
1252
|
declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
|
|
1017
1253
|
//#endregion
|
|
1018
|
-
export { AgentRequestOptions as $, AgentActInput as A, DecisionAttempt as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentDecisionOption as F, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, providerOutputSchema as O, AgentDecisionInput as P, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, getCallUsage as T, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentRequestSource as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, ACT_STATE_EXITED as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, CreateDecisionRequestOptions as z };
|
|
1254
|
+
export { AgentRequestOptions as $, AgentActInput as A, SystemMessage as At, DecisionAttempt as B, getAgentOutputMode as C, FilePart as Ct, parseProviderOutput as D, NormalizedEventSchemas as Dt, parseOutput as E, InferOutput as Et, AgentDecisionOption as F, ToolResultPart as Ft, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, UserMessage as It, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, WithAgentInputSchema as Lt, AgentDecisionExecutor as M, ToolCallPart as Mt, AgentDecisionExhaustedError as N, ToolMessage as Nt, providerOutputSchema as O, ProviderOptions as Ot, AgentDecisionInput as P, ToolResultOutput as Pt, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, EventUnion as St, getCallUsage as T, InferInput as Tt, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AllowedEvents as _t, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, DataContent as bt, AgentRequestExecutorInfo as c, AgentEventSchemaInputMap as ct, AgentRequestMode as d, AgentToolChoice as dt, AgentRequestSource as et, AgentTextRequest as f, AgentToolDescriptor as ft, ProviderStructuredOutput as g, AllowedEventPattern as gt, BuiltinAgentActors as h, AgentTools as ht, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, TextPart as jt, ACT_STATE_EXITED as k, StandardSchemaV1 as kt, AgentRequestExecutorResult as l, AgentMessage as lt, AgentUsage as m, AgentToolSchema as mt, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, AgentToolExecute as pt, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentEventSchemaInput as st, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, AgentTool as ut, TextLogicConfig as v, AssistantMessage as vt, getCallFinishReason as w, ImagePart as wt, bindRequestExecutor as x, EventPayload as xt, TextLogicExecuteArgs as y, ChosenEvent as yt, CreateDecisionRequestOptions as z };
|
|
@@ -1,5 +1,241 @@
|
|
|
1
|
-
import { C as StandardSchemaV1, a as AgentToolChoice, b as InferOutput, d as AllowedEvents, l as AgentTools, p as ChosenEvent, r as AgentMessage } from "./types-DQUOOaZO.cjs";
|
|
2
1
|
import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
|
|
2
|
+
//#region src/types.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* The [Standard Schema](https://standardschema.dev) interface. Every schema
|
|
5
|
+
* this library accepts (context, events, input/output, tool schemas, …) is a
|
|
6
|
+
* `StandardSchemaV1` — Zod, Valibot, ArkType, and hand-written validators all
|
|
7
|
+
* implement it, so the library never depends on a specific validation
|
|
8
|
+
* library. JSON workflow configs use a caller-provided {@link SchemaCompiler}.
|
|
9
|
+
*/
|
|
10
|
+
interface StandardSchemaV1<Input = unknown, Output = Input> {
|
|
11
|
+
readonly "~standard": {
|
|
12
|
+
readonly version: 1;
|
|
13
|
+
readonly vendor: string;
|
|
14
|
+
readonly validate: (value: unknown) => any;
|
|
15
|
+
readonly types?: {
|
|
16
|
+
readonly input: Input;
|
|
17
|
+
readonly output: Output;
|
|
18
|
+
} | undefined;
|
|
19
|
+
readonly jsonSchema?: {
|
|
20
|
+
readonly input?: (...args: any[]) => unknown;
|
|
21
|
+
readonly output?: (...args: any[]) => unknown;
|
|
22
|
+
};
|
|
23
|
+
};
|
|
24
|
+
}
|
|
25
|
+
/** The validated output type of a {@link StandardSchemaV1}. */
|
|
26
|
+
type InferOutput<T> = T extends StandardSchemaV1<any, infer O> ? O : never;
|
|
27
|
+
/**
|
|
28
|
+
* The *pre*-validation input type of a {@link StandardSchemaV1}: what a caller
|
|
29
|
+
* passes in, before defaults are filled and transforms applied. Standard Schema
|
|
30
|
+
* carries both sides (`~standard.types.input` / `.output`), so a schema
|
|
31
|
+
* declaring a defaulted field makes that field optional here and required in
|
|
32
|
+
* {@link InferOutput} — which is exactly the split between what a run
|
|
33
|
+
* accepts as machine `input` and what the `context` factory then sees.
|
|
34
|
+
*/
|
|
35
|
+
type InferInput<T> = T extends StandardSchemaV1<infer I, any> ? I : never;
|
|
36
|
+
/**
|
|
37
|
+
* Phantom brand carrying a machine's declared input schema on the machine type.
|
|
38
|
+
*
|
|
39
|
+
* XState resolves `schemas.input` to a single type and uses it for both
|
|
40
|
+
* `createActor`'s `input` option and the `context: ({ input })` factory, so the
|
|
41
|
+
* caller-facing and factory-facing sides cannot differ there. `setupAgent`'s
|
|
42
|
+
* `createMachine` brands the machine's input type with the schema itself, which
|
|
43
|
+
* lets `AgentInputFrom` recover the looser input side for a run's `input` while the
|
|
44
|
+
* `context` factory keeps the strict validated side.
|
|
45
|
+
*
|
|
46
|
+
* The key is a `~`-prefixed phantom property (the same convention Standard
|
|
47
|
+
* Schema uses for `~standard`) rather than a `unique symbol`: a symbol would
|
|
48
|
+
* have to be exported as a runtime value for declaration emit to name it in
|
|
49
|
+
* every machine type it touches.
|
|
50
|
+
*/
|
|
51
|
+
type WithAgentInputSchema<TInputSchema> = {
|
|
52
|
+
readonly "~agent.inputSchema"?: TInputSchema;
|
|
53
|
+
};
|
|
54
|
+
/** An event schema's output, widened to `unknown` when it validates an empty object (no payload fields). */
|
|
55
|
+
type EventPayload<T> = T extends Record<string, never> ? unknown : T;
|
|
56
|
+
/**
|
|
57
|
+
* One entry in an event schema map: a Standard Schema for the event's
|
|
58
|
+
* payload, or the `{}` shorthand for a payload-less event
|
|
59
|
+
* (`events: { CONFIRM: {} }` ≡ `events: { CONFIRM: z.object({}) }`).
|
|
60
|
+
*/
|
|
61
|
+
type AgentEventSchemaInput = StandardSchemaV1 | Record<string, never>;
|
|
62
|
+
/** An event schema map as authored: payload schemas and/or `{}` payload-less shorthands, keyed by event type. */
|
|
63
|
+
type AgentEventSchemaInputMap = Record<string, AgentEventSchemaInput>;
|
|
64
|
+
/** Resolves an authored event schema map's `{}` shorthands to real (empty-payload) schemas — the type-level counterpart of the runtime normalization in `createAgentSchemas`. */
|
|
65
|
+
type NormalizedEventSchemas<T extends AgentEventSchemaInputMap> = { [K in keyof T]: T[K] extends StandardSchemaV1 ? T[K] : StandardSchemaV1<{}>; };
|
|
66
|
+
/**
|
|
67
|
+
* The discriminated event union derived from a machine's event schema map
|
|
68
|
+
* (e.g. `{ ASK: z.object({ question: z.string() }) }` → `{ type: 'ASK';
|
|
69
|
+
* question: string }`; a `{}` shorthand entry yields its bare `{ type: K }`).
|
|
70
|
+
* Used internally by {@link createAgentSchemas} and `setupAgent` to type a
|
|
71
|
+
* machine's `TEvent`.
|
|
72
|
+
*/
|
|
73
|
+
type EventUnion<T extends AgentEventSchemaInputMap> = { [K in keyof T & string]: {
|
|
74
|
+
type: K;
|
|
75
|
+
} & (T[K] extends StandardSchemaV1 ? EventPayload<InferOutput<T[K]>> : unknown); }[keyof T & string];
|
|
76
|
+
/** Raw binary or string content for an {@link ImagePart}/{@link FilePart}. */
|
|
77
|
+
type DataContent = string | Uint8Array | ArrayBuffer;
|
|
78
|
+
/** Provider-specific passthrough options, keyed by provider name (e.g. `{ anthropic: { cacheControl: ... } }`). */
|
|
79
|
+
type ProviderOptions = Record<string, Record<string, unknown>>;
|
|
80
|
+
/** A plain-text segment of a multi-part {@link AgentMessage} content array. */
|
|
81
|
+
interface TextPart {
|
|
82
|
+
type: "text";
|
|
83
|
+
text: string;
|
|
84
|
+
providerOptions?: ProviderOptions;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
|
|
88
|
+
* JSON-serializable. Machines that persist snapshots/event logs should use
|
|
89
|
+
* URL strings or base64-encoded strings in `image` instead.
|
|
90
|
+
*/
|
|
91
|
+
interface ImagePart {
|
|
92
|
+
type: "image";
|
|
93
|
+
image: DataContent | URL;
|
|
94
|
+
mediaType?: string;
|
|
95
|
+
providerOptions?: ProviderOptions;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Binary (`Uint8Array`/`ArrayBuffer`) and `URL` values are not
|
|
99
|
+
* JSON-serializable. Machines that persist snapshots/event logs should use
|
|
100
|
+
* URL strings or base64-encoded strings in `data` instead.
|
|
101
|
+
*/
|
|
102
|
+
interface FilePart {
|
|
103
|
+
type: "file";
|
|
104
|
+
data: DataContent | URL;
|
|
105
|
+
mediaType: string;
|
|
106
|
+
filename?: string;
|
|
107
|
+
providerOptions?: ProviderOptions;
|
|
108
|
+
}
|
|
109
|
+
/** A model-issued tool call, as an {@link AssistantMessage} content part. */
|
|
110
|
+
interface ToolCallPart {
|
|
111
|
+
type: "tool-call";
|
|
112
|
+
toolCallId: string;
|
|
113
|
+
toolName: string;
|
|
114
|
+
input: unknown;
|
|
115
|
+
providerOptions?: ProviderOptions;
|
|
116
|
+
}
|
|
117
|
+
/** The result payload of a {@link ToolResultPart}, discriminated by shape (plain text/JSON, or an error variant of either). */
|
|
118
|
+
type ToolResultOutput = {
|
|
119
|
+
type: "text";
|
|
120
|
+
value: string;
|
|
121
|
+
} | {
|
|
122
|
+
type: "json";
|
|
123
|
+
value: unknown;
|
|
124
|
+
} | {
|
|
125
|
+
type: "error-text";
|
|
126
|
+
value: string;
|
|
127
|
+
} | {
|
|
128
|
+
type: "error-json";
|
|
129
|
+
value: unknown;
|
|
130
|
+
} | {
|
|
131
|
+
type: "content";
|
|
132
|
+
value: Array<TextPart | ImagePart>;
|
|
133
|
+
};
|
|
134
|
+
/** A tool's result, as a {@link ToolMessage} content part. */
|
|
135
|
+
interface ToolResultPart {
|
|
136
|
+
type: "tool-result";
|
|
137
|
+
toolCallId: string;
|
|
138
|
+
toolName: string;
|
|
139
|
+
output: ToolResultOutput;
|
|
140
|
+
providerOptions?: ProviderOptions;
|
|
141
|
+
}
|
|
142
|
+
/** A system-role {@link AgentMessage}. Create with {@link systemMessage}. */
|
|
143
|
+
type SystemMessage = {
|
|
144
|
+
role: "system";
|
|
145
|
+
content: string;
|
|
146
|
+
providerOptions?: ProviderOptions;
|
|
147
|
+
};
|
|
148
|
+
/** A user-role {@link AgentMessage}, optionally multimodal. Create with {@link userMessage}. */
|
|
149
|
+
type UserMessage = {
|
|
150
|
+
role: "user";
|
|
151
|
+
content: string | Array<TextPart | ImagePart | FilePart>;
|
|
152
|
+
providerOptions?: ProviderOptions;
|
|
153
|
+
};
|
|
154
|
+
/** An assistant-role {@link AgentMessage}, which may carry tool calls/results inline. Create with {@link assistantMessage}. */
|
|
155
|
+
type AssistantMessage = {
|
|
156
|
+
role: "assistant";
|
|
157
|
+
content: string | Array<TextPart | FilePart | ToolCallPart | ToolResultPart>;
|
|
158
|
+
providerOptions?: ProviderOptions;
|
|
159
|
+
};
|
|
160
|
+
/** A tool-role {@link AgentMessage} carrying one or more tool results. Create with {@link toolMessage}. */
|
|
161
|
+
type ToolMessage = {
|
|
162
|
+
role: "tool";
|
|
163
|
+
content: Array<ToolResultPart>;
|
|
164
|
+
providerOptions?: ProviderOptions;
|
|
165
|
+
};
|
|
166
|
+
/**
|
|
167
|
+
* Optional framework-neutral message helpers. Requests also accept native
|
|
168
|
+
* framework message values directly; core never converts between formats.
|
|
169
|
+
* Store messages as plain context state: a text request's `onDone` output
|
|
170
|
+
* carries the executor's response messages as `output.messages`.
|
|
171
|
+
*/
|
|
172
|
+
type AgentMessage = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
|
|
173
|
+
/**
|
|
174
|
+
* A schema value on an {@link AgentToolDescriptor}: deliberately just `object`,
|
|
175
|
+
* because an SDK-native tool's `inputSchema` is the SDK's own union type (a Zod
|
|
176
|
+
* schema, the SDK's `Schema`, a lazy thunk, ...) and must assign structurally
|
|
177
|
+
* with no cast. The contract is runtime, not static: core narrows with
|
|
178
|
+
* `isStandardSchema` and reads {@link StandardSchemaV1} schemas via
|
|
179
|
+
* `getJsonSchema`; anything else passes through to the executor untouched.
|
|
180
|
+
*/
|
|
181
|
+
type AgentToolSchema = object;
|
|
182
|
+
/**
|
|
183
|
+
* A tool exposed to a text request, described for both the model and
|
|
184
|
+
* (optionally) host execution. This is a **minimal structural contract**: any
|
|
185
|
+
* object matching it — an AI SDK `tool({...})`, an MCP-style descriptor, or a
|
|
186
|
+
* hand-written `{ description, inputSchema, execute }` — is a valid entry, and
|
|
187
|
+
* extra properties (`providerOptions`, `toModelOutput`, …) pass through
|
|
188
|
+
* untouched via the index signature. `execute` is typed permissively so a
|
|
189
|
+
* native tool's `(input, options)` executor is structurally assignable; the
|
|
190
|
+
* SDK you built the tool with owns its precise input typing.
|
|
191
|
+
*/
|
|
192
|
+
interface AgentToolDescriptor {
|
|
193
|
+
/**
|
|
194
|
+
* Text shown to the model. Typed loosely enough to accept an SDK tool whose
|
|
195
|
+
* description is computed per call (the AI SDK v7 `tool({ description })`
|
|
196
|
+
* accepts a function of the call's context); core never reads it.
|
|
197
|
+
*/
|
|
198
|
+
description?: string | ((...args: any[]) => string);
|
|
199
|
+
inputSchema?: AgentToolSchema;
|
|
200
|
+
outputSchema?: AgentToolSchema;
|
|
201
|
+
execute?: (...args: any[]) => unknown;
|
|
202
|
+
[key: string]: unknown;
|
|
203
|
+
}
|
|
204
|
+
/** A bare tool implementation (no description/schema) — shorthand for {@link AgentToolDescriptor.execute}. */
|
|
205
|
+
type AgentToolExecute = (input?: unknown) => unknown | Promise<unknown>;
|
|
206
|
+
/** A tool entry in {@link AgentTools}: either a full descriptor or a bare execute function. */
|
|
207
|
+
type AgentTool = AgentToolDescriptor | AgentToolExecute;
|
|
208
|
+
/** The `tools` map passed on an {@link AgentTextRequest}, keyed by tool name. */
|
|
209
|
+
type AgentTools = Record<string, AgentTool | undefined>;
|
|
210
|
+
/** How a text request's model should select among its `tools`; `{ type: 'tool', name }` forces one specific tool. */
|
|
211
|
+
type AgentToolChoice = "auto" | "none" | "required" | {
|
|
212
|
+
type: "tool";
|
|
213
|
+
name: string;
|
|
214
|
+
};
|
|
215
|
+
/** The event chosen and raised by a decision. */
|
|
216
|
+
type ChosenEvent = {
|
|
217
|
+
type: string;
|
|
218
|
+
[key: string]: unknown;
|
|
219
|
+
};
|
|
220
|
+
type EventWildcardsOf<TEvent extends string> = TEvent extends `${infer Head}.${infer Rest}` ? `${Head}.*` | `${Head}.${EventWildcardsOf<Rest>}` : never;
|
|
221
|
+
/** One `allowedEvents` entry: an exact declared event type, `'*'` (every event), or a `'prefix.*'` wildcard derived from the declared dotted event types. */
|
|
222
|
+
type AllowedEventPattern<TEvent extends string = string> = TEvent | "*" | EventWildcardsOf<TEvent>;
|
|
223
|
+
/**
|
|
224
|
+
* Candidate event types for a decision (declared on the `agent.decide`
|
|
225
|
+
* builtin's `allowedEvents` input). A single
|
|
226
|
+
* entry or an array; entries are exact event types or wildcard patterns
|
|
227
|
+
* (`'*'` for every event, `'todo.*'` for a dotted namespace). The effective
|
|
228
|
+
* candidate set offered to the model is this declaration **intersected with
|
|
229
|
+
* the snapshot's currently-legal events** (via `getAcceptedEvents`) —
|
|
230
|
+
* omitting `allowedEvents` means "all currently-legal events." A resolver
|
|
231
|
+
* function can therefore only ever narrow, never widen, the real surface.
|
|
232
|
+
* Wildcards expand against the live snapshot, so they need a snapshot-aware
|
|
233
|
+
* host (`createAgentRuntime`).
|
|
234
|
+
*/
|
|
235
|
+
type AllowedEvents<TEvent extends string = string, TInput = unknown> = AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[] | ((args: {
|
|
236
|
+
input: TInput;
|
|
237
|
+
}) => AllowedEventPattern<TEvent> | readonly AllowedEventPattern<TEvent>[]);
|
|
238
|
+
//#endregion
|
|
3
239
|
//#region src/errors.d.ts
|
|
4
240
|
/**
|
|
5
241
|
* Base class for every error this package throws. Carries a stable, kebab-case
|
|
@@ -1015,4 +1251,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
|
|
|
1015
1251
|
*/
|
|
1016
1252
|
declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
|
|
1017
1253
|
//#endregion
|
|
1018
|
-
export { AgentRequestOptions as $, AgentActInput as A, DecisionAttempt as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentDecisionOption as F, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, providerOutputSchema as O, AgentDecisionInput as P, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, getCallUsage as T, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentRequestSource as et, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, ACT_STATE_EXITED as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, CreateDecisionRequestOptions as z };
|
|
1254
|
+
export { AgentRequestOptions as $, AgentActInput as A, SystemMessage as At, DecisionAttempt as B, getAgentOutputMode as C, FilePart as Ct, parseProviderOutput as D, NormalizedEventSchemas as Dt, parseOutput as E, InferOutput as Et, AgentDecisionOption as F, ToolResultPart as Ft, createDecisionRequest as G, DecisionLogicConfig as H, AgentDecisionRejection as I, UserMessage as It, DecisionStrategy as J, renderDecisionAttempts as K, AgentDecisionRequest as L, WithAgentInputSchema as Lt, AgentDecisionExecutor as M, ToolCallPart as Mt, AgentDecisionExhaustedError as N, ToolMessage as Nt, providerOutputSchema as O, ProviderOptions as Ot, AgentDecisionInput as P, ToolResultOutput as Pt, AgentInvalidEventPayloadError as Q, AgentExecutorDecisionRequest as R, createTextLogic as S, EventUnion as St, getCallUsage as T, InferInput as Tt, ResolveDecisionOptions as U, DecisionLogic as V, createDecisionLogic as W, MAX_FINITE_PAYLOADS as X, GROUPED_EVENT_THRESHOLD as Y, AgentEventDescriptor as Z, TextLogic as _, AllowedEvents as _t, AgentModelRef as a, AgentError as at, TextLogicExecutor as b, DataContent as bt, AgentRequestExecutorInfo as c, AgentEventSchemaInputMap as ct, AgentRequestMode as d, AgentToolChoice as dt, AgentRequestSource as et, AgentTextRequest as f, AgentToolDescriptor as ft, ProviderStructuredOutput as g, AllowedEventPattern as gt, BuiltinAgentActors as h, AgentTools as ht, AgentModelMap as i, parseAgentEvent as it, DEFAULT_ACT_MAX_STEPS as j, TextPart as jt, ACT_STATE_EXITED as k, StandardSchemaV1 as kt, AgentRequestExecutorResult as l, AgentMessage as lt, AgentUsage as m, AgentToolSchema as mt, AgentExecutorTextRequest as n, EventFromSnapshot as nt, AgentOutputMode as o, AgentTruncatedError as ot, AgentTextResult as p, AgentToolExecute as pt, resolveDecision as q, AgentFinishReason as r, getAcceptedEvents as rt, AgentRequestExecutor as s, AgentEventSchemaInput as st, AgentCallUsage as t, AgentSchemas as tt, AgentRequestExecutors as u, AgentTool as ut, TextLogicConfig as v, AssistantMessage as vt, getCallFinishReason as w, ImagePart as wt, bindRequestExecutor as x, EventPayload as xt, TextLogicExecuteArgs as y, ChosenEvent as yt, CreateDecisionRequestOptions as z };
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
import { StateValue } from "xstate";
|
|
2
|
+
//#region src/trajectory.d.ts
|
|
3
|
+
/** An event-shaped trajectory item: anything with a string `type`. */
|
|
4
|
+
interface TrajectoryEvent {
|
|
5
|
+
type: string;
|
|
6
|
+
[key: string]: unknown;
|
|
7
|
+
}
|
|
8
|
+
/** Any host-owned envelope around an event. */
|
|
9
|
+
interface TrajectoryEventEnvelope {
|
|
10
|
+
event: TrajectoryEvent;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* One item in a trajectory, on either side of the comparison:
|
|
14
|
+
*
|
|
15
|
+
* - a state value — `'drafting'`, a dot path `'review.editing'`, or the nested
|
|
16
|
+
* object XState reports (`{ review: 'editing' }`),
|
|
17
|
+
* - an event object, or just the event type as a string,
|
|
18
|
+
* - a machine snapshot, whose `value` is used.
|
|
19
|
+
*/
|
|
20
|
+
type TrajectoryItem = StateValue | TrajectoryEvent | TrajectoryEventEnvelope | {
|
|
21
|
+
value: StateValue;
|
|
22
|
+
};
|
|
23
|
+
/** Options for {@link matchesTrajectory}. */
|
|
24
|
+
interface MatchTrajectoryOptions {
|
|
25
|
+
/**
|
|
26
|
+
* Require the trajectories to be equal: same length, item for item. Default
|
|
27
|
+
* `false` — expected items must appear in `actual` in order, gaps allowed.
|
|
28
|
+
*/
|
|
29
|
+
exact?: boolean;
|
|
30
|
+
}
|
|
31
|
+
/** The first expected item that could not be found. */
|
|
32
|
+
interface TrajectoryMiss {
|
|
33
|
+
/** Its position in `expected`. */
|
|
34
|
+
index: number;
|
|
35
|
+
/** The expected item itself. */
|
|
36
|
+
expected: TrajectoryItem;
|
|
37
|
+
/** Where the search for it started in `actual` (everything before was already consumed). */
|
|
38
|
+
searchedFrom: number;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* The result of {@link matchesTrajectory}: a boolean for tests, plus enough
|
|
42
|
+
* detail for a scorer's partial credit and a failure message's diagnosis.
|
|
43
|
+
*/
|
|
44
|
+
interface TrajectoryMatch {
|
|
45
|
+
/** Every expected item was found, in order (and, in `exact` mode, nothing else). */
|
|
46
|
+
matched: boolean;
|
|
47
|
+
/** How many expected items were matched before the first miss. */
|
|
48
|
+
matchedCount: number;
|
|
49
|
+
/** `expected.length`, so a scorer can compute its own ratio. */
|
|
50
|
+
expectedCount: number;
|
|
51
|
+
/**
|
|
52
|
+
* Partial credit, 0..1. `1` for an empty expectation. Denominator is
|
|
53
|
+
* `max(expectedCount, actual.length)` in `exact` mode, `expectedCount` otherwise.
|
|
54
|
+
*/
|
|
55
|
+
score: number;
|
|
56
|
+
/** Absent when `matched`. */
|
|
57
|
+
firstMiss?: TrajectoryMiss;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Matches a run's trajectory against an expected one.
|
|
61
|
+
*
|
|
62
|
+
* Both trajectories may be state values or events collected from
|
|
63
|
+
* `onTransition`;
|
|
64
|
+
* items are compared by shape, so `['prompting', 'drafting']` scores a state
|
|
65
|
+
* path and `['PROMPT_SUBMITTED', 'SEND']` scores an event log with the same
|
|
66
|
+
* call.
|
|
67
|
+
*
|
|
68
|
+
* Semantics are an ordered subsequence: every expected item must appear in
|
|
69
|
+
* `actual`, in order, with gaps allowed. Pass `{ exact: true }` to require
|
|
70
|
+
* equality instead.
|
|
71
|
+
*
|
|
72
|
+
* @example Trajectory assertions in a test
|
|
73
|
+
* ```ts
|
|
74
|
+
* const statePath: unknown[] = [];
|
|
75
|
+
* const result = await runToQuiescence(
|
|
76
|
+
* createAgentRuntime(machine, {
|
|
77
|
+
* executors,
|
|
78
|
+
* onTransition: (snapshot) => statePath.push(snapshot.value),
|
|
79
|
+
* }),
|
|
80
|
+
* { input },
|
|
81
|
+
* );
|
|
82
|
+
*
|
|
83
|
+
* const path = matchesTrajectory(statePath, ['prompting', 'drafting', 'sent']);
|
|
84
|
+
* expect(path.matched, JSON.stringify(path.firstMiss)).toBe(true);
|
|
85
|
+
* expect(matchesTrajectory(events, ['PROMPT_SUBMITTED', 'SEND']).matched).toBe(true);
|
|
86
|
+
* ```
|
|
87
|
+
*
|
|
88
|
+
* @example Partial credit in an eval scorer
|
|
89
|
+
* ```ts
|
|
90
|
+
* const match = matchesTrajectory(output.statePath, expected.statePath);
|
|
91
|
+
* return { name: 'state_path', score: match.score, metadata: { ...match.firstMiss } };
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
declare function matchesTrajectory(actual: readonly unknown[], expected: readonly TrajectoryItem[], options?: MatchTrajectoryOptions): TrajectoryMatch;
|
|
95
|
+
//#endregion
|
|
96
|
+
export { TrajectoryMatch as a, TrajectoryItem as i, TrajectoryEvent as n, TrajectoryMiss as o, TrajectoryEventEnvelope as r, matchesTrajectory as s, MatchTrajectoryOptions as t };
|