@statelyai/agent 2.0.0-alpha.35 → 2.0.0-alpha.36
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 +111 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +399 -20
- package/dist/testing.d.cts +196 -255
- package/dist/testing.d.mts +196 -255
- package/dist/testing.mjs +395 -20
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -192
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
package/dist/index.d.cts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { $ as
|
|
3
|
-
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-
|
|
4
|
-
import { C as
|
|
5
|
-
import { C as
|
|
6
|
-
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-
|
|
7
|
-
import {
|
|
1
|
+
import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as FilePart, a as AgentToolChoice, b as InferOutput, c as AgentToolSchema, d as AllowedEvents, f as AssistantMessage, g as EventUnion, h as EventPayload, i as AgentTool, j as WithAgentInputSchema, k as ToolResultPart, l as AgentTools, m as DataContent, n as AgentEventSchemaInputMap, o as AgentToolDescriptor, p as ChosenEvent, r as AgentMessage, s as AgentToolExecute, t as AgentEventSchemaInput, u as AllowedEventPattern, v as ImagePart, w as SystemMessage, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.cjs";
|
|
2
|
+
import { $ as AgentRequestOptions, A as AgentActInput, B as DecisionAttempt, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentDecisionOption, G as createDecisionRequest, H as DecisionLogicConfig, I as AgentDecisionRejection, J as DecisionStrategy, K as renderDecisionAttempts, L as AgentDecisionRequest, M as AgentDecisionExecutor, N as AgentDecisionExhaustedError, O as providerOutputSchema, P as AgentDecisionInput, Q as AgentInvalidEventPayloadError, R as AgentExecutorDecisionRequest, S as createTextLogic, T as getCallUsage, U as ResolveDecisionOptions, V as DecisionLogic, W as createDecisionLogic, X as MAX_FINITE_PAYLOADS, Y as GROUPED_EVENT_THRESHOLD, Z as AgentEventDescriptor, _ as TextLogic, a as AgentModelRef, at as AgentError, b as TextLogicExecutor, c as AgentRequestExecutorInfo, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, g as ProviderStructuredOutput, h as BuiltinAgentActors, i as AgentModelMap, it as parseAgentEvent, j as DEFAULT_ACT_MAX_STEPS, k as ACT_STATE_EXITED, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, nt as EventFromSnapshot, o as AgentOutputMode, ot as AgentTruncatedError, p as AgentTextResult, q as resolveDecision, r as AgentFinishReason, rt as getAcceptedEvents, s as AgentRequestExecutor, t as AgentCallUsage, tt as AgentSchemas, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as CreateDecisionRequestOptions } from "./text-logic-CSf9bqpP.cjs";
|
|
3
|
+
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-HtnrUsl9.cjs";
|
|
4
|
+
import { C as AgentInteractionEvent, D as eventFromInteraction, E as GetInteractionOptions, O as getInteraction, S as AgentInteractionDescriptor, T as AgentInteractionMeta, _ as FromConfigOptions, a as WithAgentEvents, b as AgentInteraction, c as getAgentSchemas, d as AgentWorkflowActorConfig, f as AgentWorkflowConfig, g as AgentWorkflowTransitionConfig, h as AgentWorkflowStateConfig, i as SetupAgentResult, k as interactionMetaSchema, l as setupAgent, m as AgentWorkflowRequestConfig, n as AgentSchemaPack, o as WithAgentUsageEvent, p as AgentWorkflowInvokeConfig, r as AgentUsageEventPayload, s as createAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActionConfig, v as FromConfigResult, w as AgentInteractionEventMeta, x as AgentInteractionChoice, y as SchemaCompiler } from "./setup-agent-jlo4vtaZ.cjs";
|
|
5
|
+
import { A as AgentStepRequest, C as inspectTransitions, D as serializeTraceEvent, E as runToQuiescence, O as traceTransitions, S as createAgentRuntime, T as runAgent, _ as AgentTraceEvent, a as AgentMaxModelCallsExceededError, b as JsonSerializableTraceEvent, c as AgentRunMeta, d as AgentRunStart, f as AgentRuntime, g as AgentTimerScheduler, h as AgentTimerEvent, i as AgentInputFrom, k as AgentRequest, l as AgentRunOptions, m as AgentSnapshotDivergedError, n as AgentEffects, o as AgentRunErrorCause, p as AgentRuntimeOptions, r as AgentInbox, s as AgentRunInit, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunResult, v as AgentTransitionHandler, w as isAgentIdle, x as createAgentInbox, y as InspectedActorRef } from "./run-agent-BcQ-9NRT.cjs";
|
|
6
|
+
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-bc4ICGcS.cjs";
|
|
7
|
+
import { n as PresetMachine } from "./internal-C3Lqu538.cjs";
|
|
8
|
+
import { M as Recorder, a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, t as MetaOfSnapshot, u as systemMessage } from "./utils-7lSa4H-i.cjs";
|
|
8
9
|
import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
|
|
9
10
|
//#region src/type-helpers.d.ts
|
|
10
11
|
type SchemaAt<T, TKey extends PropertyKey> = T extends {
|
|
@@ -76,6 +77,17 @@ export declare function isAgentMessages(value: unknown): value is AgentMessage[]
|
|
|
76
77
|
interface DescribeMachineOptions {
|
|
77
78
|
/** Marks the state nodes active in this snapshot with `*`. */
|
|
78
79
|
snapshot?: AnyMachineSnapshot;
|
|
80
|
+
/**
|
|
81
|
+
* Prints each transition written as a function under its line, so one read
|
|
82
|
+
* shows both where it goes and what it computes.
|
|
83
|
+
*/
|
|
84
|
+
source?: boolean;
|
|
85
|
+
/**
|
|
86
|
+
* Functions the machine's transitions call by name (guards, reducers), each
|
|
87
|
+
* printed with its source in a `Helpers` section, so a call such as
|
|
88
|
+
* `withinLimit(context.turn, context.limit)` can be read through.
|
|
89
|
+
*/
|
|
90
|
+
helpers?: Record<string, (...args: never[]) => unknown>;
|
|
79
91
|
}
|
|
80
92
|
/**
|
|
81
93
|
* Describes a machine in plain text for a model to read. The machine's
|
|
@@ -92,7 +104,11 @@ interface DescribeMachineOptions {
|
|
|
92
104
|
* A transition written as a function shows the targets its source names
|
|
93
105
|
* (`→ review (conditional)` when it may decline or pick among several),
|
|
94
106
|
* `(stays)` when its source has no `target`, or `→ ?` when no target can be
|
|
95
|
-
* read
|
|
107
|
+
* read (a variable's value, a helper call's result). Function sources are
|
|
108
|
+
* parsed, so every return path counts: ternaries, `&&`/`||`, early returns and
|
|
109
|
+
* local constants. With `source: true`, each function is printed under its
|
|
110
|
+
* line, along with entry and exit actions; pass `helpers` to print the
|
|
111
|
+
* functions they call by name. A `setupAgent.fromConfig(...)` machine is read from its config, so
|
|
96
112
|
* its targets, guards and context patches are always known.
|
|
97
113
|
*
|
|
98
114
|
* @example
|
|
@@ -132,6 +148,14 @@ interface DecideNextOptions<TSnapshot extends AnyMachineSnapshot = AnyMachineSna
|
|
|
132
148
|
/** Retries after a failed choice. Default `2`. */
|
|
133
149
|
maxRetries?: number;
|
|
134
150
|
signal?: AbortSignal;
|
|
151
|
+
/** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
|
|
152
|
+
strategy?: DecisionStrategy;
|
|
153
|
+
/** Model ref that fills open payload fields under `'pick-then-fill'`. */
|
|
154
|
+
fillModel?: string;
|
|
155
|
+
/** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
|
|
156
|
+
groups?: Record<string, readonly string[]>;
|
|
157
|
+
/** Fills open payload fields with `fillModel`. */
|
|
158
|
+
generateText?: AgentRequestExecutor;
|
|
135
159
|
}
|
|
136
160
|
/** Result of {@link decideNext}. */
|
|
137
161
|
interface DecideNextResult<TEvent = ChosenEvent> {
|
|
@@ -233,6 +257,139 @@ interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<Age
|
|
|
233
257
|
*/
|
|
234
258
|
export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
|
|
235
259
|
//#endregion
|
|
260
|
+
//#region src/wrap-workflow.d.ts
|
|
261
|
+
/** The effects a wrapped workflow calls: async functions, by name. */
|
|
262
|
+
type WorkflowEffects<TEffects> = { [K in keyof TEffects]: (...args: never[]) => PromiseLike<unknown>; };
|
|
263
|
+
/** What a wrapped workflow's `run` gets besides its input and effects. */
|
|
264
|
+
interface WorkflowRunContext {
|
|
265
|
+
/** Aborted when the run is aborted or the machine stops the workflow. */
|
|
266
|
+
signal: AbortSignal;
|
|
267
|
+
}
|
|
268
|
+
/** Options for {@link wrapWorkflow}. */
|
|
269
|
+
interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>> {
|
|
270
|
+
/** The machine id. */
|
|
271
|
+
id: string;
|
|
272
|
+
/** The machine version, for the event log. Default `"1"`. */
|
|
273
|
+
version?: string;
|
|
274
|
+
/** Every side effect the workflow makes: model calls, tools, writes. */
|
|
275
|
+
effects: TEffects;
|
|
276
|
+
/**
|
|
277
|
+
* The existing workflow. It must reach the outside world only through
|
|
278
|
+
* `effects`; a call it makes around them is invisible to the machine, to
|
|
279
|
+
* traces, and to {@link Recorder} recordings. It gets its own deep copy of
|
|
280
|
+
* a plain-data input, free to mutate; an input holding class instances or
|
|
281
|
+
* functions is passed as is. An effect that resolves to a stream (anything
|
|
282
|
+
* `for await` reads) settles once the stream is read, with its chunks.
|
|
283
|
+
*/
|
|
284
|
+
run: (input: TInput, effects: TEffects, context: WorkflowRunContext) => PromiseLike<TOutput>;
|
|
285
|
+
/**
|
|
286
|
+
* Maps an effect's arguments, result, or error before it is journaled as an
|
|
287
|
+
* event. Return a redacted value for secrets and private records: every
|
|
288
|
+
* `effect.*` event reaches traces, the event log, and the inspector.
|
|
289
|
+
* Default: journal each value as is (JSON-safe).
|
|
290
|
+
*/
|
|
291
|
+
redact?: (name: string, part: "args" | "result" | "error", value: unknown) => unknown;
|
|
292
|
+
}
|
|
293
|
+
/** An effect call, as the machine sees it. `call` pairs it with its result. */
|
|
294
|
+
interface EffectCallEvent {
|
|
295
|
+
type: "effect.call";
|
|
296
|
+
name: string;
|
|
297
|
+
/** 0-based, across all effects of the run. */
|
|
298
|
+
call: number;
|
|
299
|
+
/** The arguments, JSON-safe. */
|
|
300
|
+
args: JsonValue[];
|
|
301
|
+
}
|
|
302
|
+
/** An effect call that resolved. */
|
|
303
|
+
interface EffectDoneEvent {
|
|
304
|
+
type: "effect.done";
|
|
305
|
+
name: string;
|
|
306
|
+
call: number;
|
|
307
|
+
/**
|
|
308
|
+
* The resolved value, JSON-safe (`null` for `undefined`). For a stream, the
|
|
309
|
+
* chunks read, or `{ chunks, returned }` when a generator returned a value.
|
|
310
|
+
*/
|
|
311
|
+
result: JsonValue;
|
|
312
|
+
}
|
|
313
|
+
/** An effect call that rejected. */
|
|
314
|
+
interface EffectErrorEvent {
|
|
315
|
+
type: "effect.error";
|
|
316
|
+
name: string;
|
|
317
|
+
call: number;
|
|
318
|
+
/** The error, JSON-safe: `{ name, message, stack?, code? }`. */
|
|
319
|
+
error: JsonValue;
|
|
320
|
+
}
|
|
321
|
+
/** The wrapped machine's context. */
|
|
322
|
+
type WrappedWorkflowContext<TInput, TOutput> = {
|
|
323
|
+
input: TInput;
|
|
324
|
+
/** What the workflow returned, once it did. */
|
|
325
|
+
output?: TOutput;
|
|
326
|
+
/** Effect calls started. */
|
|
327
|
+
calls: number;
|
|
328
|
+
/** Effect calls that rejected. */
|
|
329
|
+
failures: number;
|
|
330
|
+
};
|
|
331
|
+
/** Options for {@link WrappedWorkflow.run}: `runAgent` options that fit a black box, plus fakes and a recorder. */
|
|
332
|
+
interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<AgentRunOptions<WrappedWorkflowMachine<TInput, TOutput>>, "signal" | "inspect" | "onTransition" | "onTrace" | "onEvent" | "metadata" | "verification"> {
|
|
333
|
+
/** Replaces some effects for this run: fakes, stubs, replay wrappers. */
|
|
334
|
+
effects?: Partial<TEffects>;
|
|
335
|
+
/**
|
|
336
|
+
* Wraps every function effect with `recorder.fn(name, fn)` and records the
|
|
337
|
+
* result with `recorder.output`, so `recorder.recording` is a golden run.
|
|
338
|
+
*/
|
|
339
|
+
recorder?: Recorder;
|
|
340
|
+
}
|
|
341
|
+
/** The result of {@link wrapWorkflow}. */
|
|
342
|
+
interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
343
|
+
/**
|
|
344
|
+
* `running` invokes the workflow and counts its effect calls; `done` is
|
|
345
|
+
* final with the workflow's result as output. A rejection is unhandled, so
|
|
346
|
+
* the run settles `{ status: "error", cause: "machine" }` with the thrown
|
|
347
|
+
* error. Runs with `runAgent`, `describeMachine`, `canReach` and the inspector.
|
|
348
|
+
*/
|
|
349
|
+
machine: WrappedWorkflowMachine<TInput, TOutput>;
|
|
350
|
+
/**
|
|
351
|
+
* Runs the machine with `runAgent` and returns what the workflow returned,
|
|
352
|
+
* or rethrows what it threw (the same error object). `signal` reaches the
|
|
353
|
+
* workflow, which decides what an abort means, as it did before: a
|
|
354
|
+
* workflow that returns an `aborted` result still returns it. Once it
|
|
355
|
+
* aborts, an effect call throws `signal.reason` instead of running.
|
|
356
|
+
*/
|
|
357
|
+
run(input: TInput, options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput>): Promise<TOutput>;
|
|
358
|
+
}
|
|
359
|
+
/** The events a {@link wrapWorkflow} machine handles. */
|
|
360
|
+
type WrappedWorkflowEvent = EffectCallEvent | EffectDoneEvent | EffectErrorEvent;
|
|
361
|
+
/** The machine {@link wrapWorkflow} returns. */
|
|
362
|
+
type WrappedWorkflowMachine<TInput, TOutput> = PresetMachine<WrappedWorkflowContext<TInput, TOutput>, TInput, TOutput, WrappedWorkflowEvent>;
|
|
363
|
+
/**
|
|
364
|
+
* Wraps an existing async workflow, unchanged, as an agent machine: step 0 of
|
|
365
|
+
* a strangler-fig retrofit. Pass every side effect it makes as `effects`; each
|
|
366
|
+
* call becomes an `effect.call` event, then `effect.done` or `effect.error`, so
|
|
367
|
+
* it shows up in transitions, traces, the event log and the inspector.
|
|
368
|
+
*
|
|
369
|
+
* What it buys today: inspection and traces of a workflow nobody rewrote, a
|
|
370
|
+
* recorded baseline (`run(input, { recorder })`, or `checkParity` from
|
|
371
|
+
* `@statelyai/agent/testing`), `signal` to abort it, and a seam to carve
|
|
372
|
+
* phases out of, one at a time.
|
|
373
|
+
*
|
|
374
|
+
* What it does not: the workflow is a black box. The machine has one state
|
|
375
|
+
* for all of it, so there is no resume in the middle of the function (a
|
|
376
|
+
* resumed run starts it again), and `canReach` or `explorePaths` prove nothing
|
|
377
|
+
* about what happens inside. Those arrive per phase, as phases move into
|
|
378
|
+
* states. Effect arguments and results are journaled JSON-safe; values that
|
|
379
|
+
* are not JSON lose what JSON cannot hold.
|
|
380
|
+
*
|
|
381
|
+
* @example
|
|
382
|
+
* ```ts
|
|
383
|
+
* const support = wrapWorkflow({
|
|
384
|
+
* id: "support",
|
|
385
|
+
* effects: { generate, lookupOrder, issueRefund },
|
|
386
|
+
* run: (input: Ticket, effects) => legacyRunTicket(input, effects),
|
|
387
|
+
* });
|
|
388
|
+
* const reply = await support.run(ticket); // what legacyRunTicket returned
|
|
389
|
+
* ```
|
|
390
|
+
*/
|
|
391
|
+
export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>>(config: WrapWorkflowConfig<TInput, TOutput, TEffects>): WrappedWorkflow<TInput, TOutput, TEffects>;
|
|
392
|
+
//#endregion
|
|
236
393
|
//#region src/provide-executors.d.ts
|
|
237
394
|
/** Options for {@link provideExecutors}. */
|
|
238
395
|
interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
|
|
@@ -279,6 +436,8 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
279
436
|
* - decision / `agent.decide` source → `executors.decide` (snapshot-driven
|
|
280
437
|
* candidate events, guard `canTake`, and auto-delivery of the chosen event,
|
|
281
438
|
* mirroring `createAgentRuntime` but without its model-call counting)
|
|
439
|
+
* - `agent.act` → `executors.generateText` (accepted events as tools, each
|
|
440
|
+
* call sent to the invoking actor)
|
|
282
441
|
*
|
|
283
442
|
* Pass `options.onTrace` to observe request-level trace events (identical in
|
|
284
443
|
* shape to `createAgentRuntime`'s); pair it with {@link traceTransitions} on the actor's
|
|
@@ -301,4 +460,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
301
460
|
*/
|
|
302
461
|
export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
|
|
303
462
|
//#endregion
|
|
304
|
-
export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
|
|
463
|
+
export { ACT_STATE_EXITED, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActInput, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInbox, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type BuiltinAgentActors, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, DEFAULT_ACT_MAX_STEPS, type DataContent, type DecideNextOptions, type DecideNextResult, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DecisionStrategy, type DescribeMachineOptions, type DoneActorEventOf, type EffectCallEvent, type EffectDoneEvent, type EffectErrorEvent, type EventFromSnapshot, type EventOf, type EventPayload, type EventUnion, type FilePart, type FromConfigOptions, type FromConfigResult, GROUPED_EVENT_THRESHOLD, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, MAX_FINITE_PAYLOADS, type MetaOf, type MetaOfSnapshot, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SetupAgentResult, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentInputSchema, type WithAgentUsageEvent, type WorkflowEffects, type WorkflowRunContext, type WrapWorkflowConfig, type WrappedWorkflow, type WrappedWorkflowContext, type WrappedWorkflowEvent, type WrappedWorkflowMachine, type WrappedWorkflowRunOptions, assistantMessage, bindRequestExecutor, createAgentInbox, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
|
package/dist/index.d.mts
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { $ as
|
|
3
|
-
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-
|
|
4
|
-
import { C as
|
|
5
|
-
import { C as
|
|
6
|
-
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-
|
|
7
|
-
import {
|
|
1
|
+
import { A as UserMessage, C as StandardSchemaV1, D as ToolMessage, E as ToolCallPart, O as ToolResultOutput, S as ProviderOptions, T as TextPart, _ as FilePart, a as AgentToolChoice, b as InferOutput, c as AgentToolSchema, d as AllowedEvents, f as AssistantMessage, g as EventUnion, h as EventPayload, i as AgentTool, j as WithAgentInputSchema, k as ToolResultPart, l as AgentTools, m as DataContent, n as AgentEventSchemaInputMap, o as AgentToolDescriptor, p as ChosenEvent, r as AgentMessage, s as AgentToolExecute, t as AgentEventSchemaInput, u as AllowedEventPattern, v as ImagePart, w as SystemMessage, x as NormalizedEventSchemas, y as InferInput } from "./types-DQUOOaZO.mjs";
|
|
2
|
+
import { $ as AgentRequestOptions, A as AgentActInput, B as DecisionAttempt, C as getAgentOutputMode, D as parseProviderOutput, E as parseOutput, F as AgentDecisionOption, G as createDecisionRequest, H as DecisionLogicConfig, I as AgentDecisionRejection, J as DecisionStrategy, K as renderDecisionAttempts, L as AgentDecisionRequest, M as AgentDecisionExecutor, N as AgentDecisionExhaustedError, O as providerOutputSchema, P as AgentDecisionInput, Q as AgentInvalidEventPayloadError, R as AgentExecutorDecisionRequest, S as createTextLogic, T as getCallUsage, U as ResolveDecisionOptions, V as DecisionLogic, W as createDecisionLogic, X as MAX_FINITE_PAYLOADS, Y as GROUPED_EVENT_THRESHOLD, Z as AgentEventDescriptor, _ as TextLogic, a as AgentModelRef, at as AgentError, b as TextLogicExecutor, c as AgentRequestExecutorInfo, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, g as ProviderStructuredOutput, h as BuiltinAgentActors, i as AgentModelMap, it as parseAgentEvent, j as DEFAULT_ACT_MAX_STEPS, k as ACT_STATE_EXITED, l as AgentRequestExecutorResult, m as AgentUsage, n as AgentExecutorTextRequest, nt as EventFromSnapshot, o as AgentOutputMode, ot as AgentTruncatedError, p as AgentTextResult, q as resolveDecision, r as AgentFinishReason, rt as getAcceptedEvents, s as AgentRequestExecutor, t as AgentCallUsage, tt as AgentSchemas, u as AgentRequestExecutors, v as TextLogicConfig, w as getCallFinishReason, x as bindRequestExecutor, y as TextLogicExecuteArgs, z as CreateDecisionRequestOptions } from "./text-logic-BqxalgMr.mjs";
|
|
3
|
+
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DoP0Oi84.mjs";
|
|
4
|
+
import { C as AgentInteractionEvent, D as eventFromInteraction, E as GetInteractionOptions, O as getInteraction, S as AgentInteractionDescriptor, T as AgentInteractionMeta, _ as FromConfigOptions, a as WithAgentEvents, b as AgentInteraction, c as getAgentSchemas, d as AgentWorkflowActorConfig, f as AgentWorkflowConfig, g as AgentWorkflowTransitionConfig, h as AgentWorkflowStateConfig, i as SetupAgentResult, k as interactionMetaSchema, l as setupAgent, m as AgentWorkflowRequestConfig, n as AgentSchemaPack, o as WithAgentUsageEvent, p as AgentWorkflowInvokeConfig, r as AgentUsageEventPayload, s as createAgentSchemas, t as AgentDefaultMeta, u as AgentWorkflowActionConfig, v as FromConfigResult, w as AgentInteractionEventMeta, x as AgentInteractionChoice, y as SchemaCompiler } from "./setup-agent-BIKcbVXV.mjs";
|
|
5
|
+
import { A as AgentStepRequest, C as inspectTransitions, D as serializeTraceEvent, E as runToQuiescence, O as traceTransitions, S as createAgentRuntime, T as runAgent, _ as AgentTraceEvent, a as AgentMaxModelCallsExceededError, b as JsonSerializableTraceEvent, c as AgentRunMeta, d as AgentRunStart, f as AgentRuntime, g as AgentTimerScheduler, h as AgentTimerEvent, i as AgentInputFrom, k as AgentRequest, l as AgentRunOptions, m as AgentSnapshotDivergedError, n as AgentEffects, o as AgentRunErrorCause, p as AgentRuntimeOptions, r as AgentInbox, s as AgentRunInit, t as AGENT_TRACE_SCHEMA_VERSION, u as AgentRunResult, v as AgentTransitionHandler, w as isAgentIdle, x as createAgentInbox, y as InspectedActorRef } from "./run-agent-C86drZtN.mjs";
|
|
6
|
+
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-BBS8so8a.mjs";
|
|
7
|
+
import { n as PresetMachine } from "./internal-DUcdhk-i.mjs";
|
|
8
|
+
import { M as Recorder, a as getMachineStructuralHash, c as getStatePath, d as toolMessage, f as userMessage, i as getJsonSchemaSync, l as isStandardSchema, n as assistantMessage, o as getMessageText, r as getJsonSchema, s as getStateMeta, t as MetaOfSnapshot, u as systemMessage } from "./utils-CBbKw2fM.mjs";
|
|
8
9
|
import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
|
|
9
10
|
//#region src/type-helpers.d.ts
|
|
10
11
|
type SchemaAt<T, TKey extends PropertyKey> = T extends {
|
|
@@ -76,6 +77,17 @@ export declare function isAgentMessages(value: unknown): value is AgentMessage[]
|
|
|
76
77
|
interface DescribeMachineOptions {
|
|
77
78
|
/** Marks the state nodes active in this snapshot with `*`. */
|
|
78
79
|
snapshot?: AnyMachineSnapshot;
|
|
80
|
+
/**
|
|
81
|
+
* Prints each transition written as a function under its line, so one read
|
|
82
|
+
* shows both where it goes and what it computes.
|
|
83
|
+
*/
|
|
84
|
+
source?: boolean;
|
|
85
|
+
/**
|
|
86
|
+
* Functions the machine's transitions call by name (guards, reducers), each
|
|
87
|
+
* printed with its source in a `Helpers` section, so a call such as
|
|
88
|
+
* `withinLimit(context.turn, context.limit)` can be read through.
|
|
89
|
+
*/
|
|
90
|
+
helpers?: Record<string, (...args: never[]) => unknown>;
|
|
79
91
|
}
|
|
80
92
|
/**
|
|
81
93
|
* Describes a machine in plain text for a model to read. The machine's
|
|
@@ -92,7 +104,11 @@ interface DescribeMachineOptions {
|
|
|
92
104
|
* A transition written as a function shows the targets its source names
|
|
93
105
|
* (`→ review (conditional)` when it may decline or pick among several),
|
|
94
106
|
* `(stays)` when its source has no `target`, or `→ ?` when no target can be
|
|
95
|
-
* read
|
|
107
|
+
* read (a variable's value, a helper call's result). Function sources are
|
|
108
|
+
* parsed, so every return path counts: ternaries, `&&`/`||`, early returns and
|
|
109
|
+
* local constants. With `source: true`, each function is printed under its
|
|
110
|
+
* line, along with entry and exit actions; pass `helpers` to print the
|
|
111
|
+
* functions they call by name. A `setupAgent.fromConfig(...)` machine is read from its config, so
|
|
96
112
|
* its targets, guards and context patches are always known.
|
|
97
113
|
*
|
|
98
114
|
* @example
|
|
@@ -132,6 +148,14 @@ interface DecideNextOptions<TSnapshot extends AnyMachineSnapshot = AnyMachineSna
|
|
|
132
148
|
/** Retries after a failed choice. Default `2`. */
|
|
133
149
|
maxRetries?: number;
|
|
134
150
|
signal?: AbortSignal;
|
|
151
|
+
/** How the decision is split into model calls. Default `'auto'`; see {@link DecisionStrategy}. */
|
|
152
|
+
strategy?: DecisionStrategy;
|
|
153
|
+
/** Model ref that fills open payload fields under `'pick-then-fill'`. */
|
|
154
|
+
fillModel?: string;
|
|
155
|
+
/** Named groups of event types for `'grouped'`; the rest group by prefix before the first `.`. */
|
|
156
|
+
groups?: Record<string, readonly string[]>;
|
|
157
|
+
/** Fills open payload fields with `fillModel`. */
|
|
158
|
+
generateText?: AgentRequestExecutor;
|
|
135
159
|
}
|
|
136
160
|
/** Result of {@link decideNext}. */
|
|
137
161
|
interface DecideNextResult<TEvent = ChosenEvent> {
|
|
@@ -233,6 +257,139 @@ interface PolicyDeciderOptions<TPolicy extends AnyStateMachine> extends Omit<Age
|
|
|
233
257
|
*/
|
|
234
258
|
export declare function createPolicyDecider<TPolicy extends AnyStateMachine>(policy: TPolicy, options?: PolicyDeciderOptions<TPolicy>): AgentDecisionExecutor;
|
|
235
259
|
//#endregion
|
|
260
|
+
//#region src/wrap-workflow.d.ts
|
|
261
|
+
/** The effects a wrapped workflow calls: async functions, by name. */
|
|
262
|
+
type WorkflowEffects<TEffects> = { [K in keyof TEffects]: (...args: never[]) => PromiseLike<unknown>; };
|
|
263
|
+
/** What a wrapped workflow's `run` gets besides its input and effects. */
|
|
264
|
+
interface WorkflowRunContext {
|
|
265
|
+
/** Aborted when the run is aborted or the machine stops the workflow. */
|
|
266
|
+
signal: AbortSignal;
|
|
267
|
+
}
|
|
268
|
+
/** Options for {@link wrapWorkflow}. */
|
|
269
|
+
interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>> {
|
|
270
|
+
/** The machine id. */
|
|
271
|
+
id: string;
|
|
272
|
+
/** The machine version, for the event log. Default `"1"`. */
|
|
273
|
+
version?: string;
|
|
274
|
+
/** Every side effect the workflow makes: model calls, tools, writes. */
|
|
275
|
+
effects: TEffects;
|
|
276
|
+
/**
|
|
277
|
+
* The existing workflow. It must reach the outside world only through
|
|
278
|
+
* `effects`; a call it makes around them is invisible to the machine, to
|
|
279
|
+
* traces, and to {@link Recorder} recordings. It gets its own deep copy of
|
|
280
|
+
* a plain-data input, free to mutate; an input holding class instances or
|
|
281
|
+
* functions is passed as is. An effect that resolves to a stream (anything
|
|
282
|
+
* `for await` reads) settles once the stream is read, with its chunks.
|
|
283
|
+
*/
|
|
284
|
+
run: (input: TInput, effects: TEffects, context: WorkflowRunContext) => PromiseLike<TOutput>;
|
|
285
|
+
/**
|
|
286
|
+
* Maps an effect's arguments, result, or error before it is journaled as an
|
|
287
|
+
* event. Return a redacted value for secrets and private records: every
|
|
288
|
+
* `effect.*` event reaches traces, the event log, and the inspector.
|
|
289
|
+
* Default: journal each value as is (JSON-safe).
|
|
290
|
+
*/
|
|
291
|
+
redact?: (name: string, part: "args" | "result" | "error", value: unknown) => unknown;
|
|
292
|
+
}
|
|
293
|
+
/** An effect call, as the machine sees it. `call` pairs it with its result. */
|
|
294
|
+
interface EffectCallEvent {
|
|
295
|
+
type: "effect.call";
|
|
296
|
+
name: string;
|
|
297
|
+
/** 0-based, across all effects of the run. */
|
|
298
|
+
call: number;
|
|
299
|
+
/** The arguments, JSON-safe. */
|
|
300
|
+
args: JsonValue[];
|
|
301
|
+
}
|
|
302
|
+
/** An effect call that resolved. */
|
|
303
|
+
interface EffectDoneEvent {
|
|
304
|
+
type: "effect.done";
|
|
305
|
+
name: string;
|
|
306
|
+
call: number;
|
|
307
|
+
/**
|
|
308
|
+
* The resolved value, JSON-safe (`null` for `undefined`). For a stream, the
|
|
309
|
+
* chunks read, or `{ chunks, returned }` when a generator returned a value.
|
|
310
|
+
*/
|
|
311
|
+
result: JsonValue;
|
|
312
|
+
}
|
|
313
|
+
/** An effect call that rejected. */
|
|
314
|
+
interface EffectErrorEvent {
|
|
315
|
+
type: "effect.error";
|
|
316
|
+
name: string;
|
|
317
|
+
call: number;
|
|
318
|
+
/** The error, JSON-safe: `{ name, message, stack?, code? }`. */
|
|
319
|
+
error: JsonValue;
|
|
320
|
+
}
|
|
321
|
+
/** The wrapped machine's context. */
|
|
322
|
+
type WrappedWorkflowContext<TInput, TOutput> = {
|
|
323
|
+
input: TInput;
|
|
324
|
+
/** What the workflow returned, once it did. */
|
|
325
|
+
output?: TOutput;
|
|
326
|
+
/** Effect calls started. */
|
|
327
|
+
calls: number;
|
|
328
|
+
/** Effect calls that rejected. */
|
|
329
|
+
failures: number;
|
|
330
|
+
};
|
|
331
|
+
/** Options for {@link WrappedWorkflow.run}: `runAgent` options that fit a black box, plus fakes and a recorder. */
|
|
332
|
+
interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<AgentRunOptions<WrappedWorkflowMachine<TInput, TOutput>>, "signal" | "inspect" | "onTransition" | "onTrace" | "onEvent" | "metadata" | "verification"> {
|
|
333
|
+
/** Replaces some effects for this run: fakes, stubs, replay wrappers. */
|
|
334
|
+
effects?: Partial<TEffects>;
|
|
335
|
+
/**
|
|
336
|
+
* Wraps every function effect with `recorder.fn(name, fn)` and records the
|
|
337
|
+
* result with `recorder.output`, so `recorder.recording` is a golden run.
|
|
338
|
+
*/
|
|
339
|
+
recorder?: Recorder;
|
|
340
|
+
}
|
|
341
|
+
/** The result of {@link wrapWorkflow}. */
|
|
342
|
+
interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
343
|
+
/**
|
|
344
|
+
* `running` invokes the workflow and counts its effect calls; `done` is
|
|
345
|
+
* final with the workflow's result as output. A rejection is unhandled, so
|
|
346
|
+
* the run settles `{ status: "error", cause: "machine" }` with the thrown
|
|
347
|
+
* error. Runs with `runAgent`, `describeMachine`, `canReach` and the inspector.
|
|
348
|
+
*/
|
|
349
|
+
machine: WrappedWorkflowMachine<TInput, TOutput>;
|
|
350
|
+
/**
|
|
351
|
+
* Runs the machine with `runAgent` and returns what the workflow returned,
|
|
352
|
+
* or rethrows what it threw (the same error object). `signal` reaches the
|
|
353
|
+
* workflow, which decides what an abort means, as it did before: a
|
|
354
|
+
* workflow that returns an `aborted` result still returns it. Once it
|
|
355
|
+
* aborts, an effect call throws `signal.reason` instead of running.
|
|
356
|
+
*/
|
|
357
|
+
run(input: TInput, options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput>): Promise<TOutput>;
|
|
358
|
+
}
|
|
359
|
+
/** The events a {@link wrapWorkflow} machine handles. */
|
|
360
|
+
type WrappedWorkflowEvent = EffectCallEvent | EffectDoneEvent | EffectErrorEvent;
|
|
361
|
+
/** The machine {@link wrapWorkflow} returns. */
|
|
362
|
+
type WrappedWorkflowMachine<TInput, TOutput> = PresetMachine<WrappedWorkflowContext<TInput, TOutput>, TInput, TOutput, WrappedWorkflowEvent>;
|
|
363
|
+
/**
|
|
364
|
+
* Wraps an existing async workflow, unchanged, as an agent machine: step 0 of
|
|
365
|
+
* a strangler-fig retrofit. Pass every side effect it makes as `effects`; each
|
|
366
|
+
* call becomes an `effect.call` event, then `effect.done` or `effect.error`, so
|
|
367
|
+
* it shows up in transitions, traces, the event log and the inspector.
|
|
368
|
+
*
|
|
369
|
+
* What it buys today: inspection and traces of a workflow nobody rewrote, a
|
|
370
|
+
* recorded baseline (`run(input, { recorder })`, or `checkParity` from
|
|
371
|
+
* `@statelyai/agent/testing`), `signal` to abort it, and a seam to carve
|
|
372
|
+
* phases out of, one at a time.
|
|
373
|
+
*
|
|
374
|
+
* What it does not: the workflow is a black box. The machine has one state
|
|
375
|
+
* for all of it, so there is no resume in the middle of the function (a
|
|
376
|
+
* resumed run starts it again), and `canReach` or `explorePaths` prove nothing
|
|
377
|
+
* about what happens inside. Those arrive per phase, as phases move into
|
|
378
|
+
* states. Effect arguments and results are journaled JSON-safe; values that
|
|
379
|
+
* are not JSON lose what JSON cannot hold.
|
|
380
|
+
*
|
|
381
|
+
* @example
|
|
382
|
+
* ```ts
|
|
383
|
+
* const support = wrapWorkflow({
|
|
384
|
+
* id: "support",
|
|
385
|
+
* effects: { generate, lookupOrder, issueRefund },
|
|
386
|
+
* run: (input: Ticket, effects) => legacyRunTicket(input, effects),
|
|
387
|
+
* });
|
|
388
|
+
* const reply = await support.run(ticket); // what legacyRunTicket returned
|
|
389
|
+
* ```
|
|
390
|
+
*/
|
|
391
|
+
export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>>(config: WrapWorkflowConfig<TInput, TOutput, TEffects>): WrappedWorkflow<TInput, TOutput, TEffects>;
|
|
392
|
+
//#endregion
|
|
236
393
|
//#region src/provide-executors.d.ts
|
|
237
394
|
/** Options for {@link provideExecutors}. */
|
|
238
395
|
interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMachine> {
|
|
@@ -279,6 +436,8 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
279
436
|
* - decision / `agent.decide` source → `executors.decide` (snapshot-driven
|
|
280
437
|
* candidate events, guard `canTake`, and auto-delivery of the chosen event,
|
|
281
438
|
* mirroring `createAgentRuntime` but without its model-call counting)
|
|
439
|
+
* - `agent.act` → `executors.generateText` (accepted events as tools, each
|
|
440
|
+
* call sent to the invoking actor)
|
|
282
441
|
*
|
|
283
442
|
* Pass `options.onTrace` to observe request-level trace events (identical in
|
|
284
443
|
* shape to `createAgentRuntime`'s); pair it with {@link traceTransitions} on the actor's
|
|
@@ -301,4 +460,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
301
460
|
*/
|
|
302
461
|
export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
|
|
303
462
|
//#endregion
|
|
304
|
-
export { AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEvents, type AssistantMessage, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DoneActorEventOf, type EventOf, type FilePart, type FromConfigOptions, type FromConfigResult, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, type MetaOf, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentUsageEvent, assistantMessage, bindRequestExecutor, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
|
|
463
|
+
export { ACT_STATE_EXITED, AGENT_TRACE_SCHEMA_VERSION, AGENT_USAGE_EVENT_TYPE, type AgentActInput, type AgentCallUsage, type AgentDecisionExecutor, AgentDecisionExhaustedError, type AgentDecisionInput, type AgentDecisionOption, type AgentDecisionRejection, type AgentDecisionRequest, type AgentDefaultMeta, type AgentEffects, AgentError, type AgentEventDescriptor, AgentEventLogConflictError, type AgentEventLogStore, type AgentEventSchemaInput, type AgentEventSchemaInputMap, type AgentExecutorDecisionRequest, type AgentExecutorTextRequest, type AgentFinishReason, type AgentInbox, type AgentInputFrom, type AgentInteraction, type AgentInteractionChoice, type AgentInteractionDescriptor, type AgentInteractionEvent, type AgentInteractionEventMeta, type AgentInteractionMeta, AgentInvalidEventPayloadError, type AgentLogEntry, AgentMachineVersionMismatchError, AgentMaxModelCallsExceededError, type AgentMessage, type AgentModelMap, type AgentModelRef, type AgentOutputMode, type AgentRequest, type AgentRequestExecutor, type AgentRequestExecutorInfo, type AgentRequestExecutorResult, type AgentRequestExecutors, type AgentRequestMode, type AgentRequestOptions, type AgentRequestSource, type AgentRunErrorCause, type AgentRunInit, type AgentRunMeta, type AgentRunOptions, type AgentRunResult, type AgentRunStart, type AgentRuntime, type AgentRuntimeOptions, type AgentSchemaPack, type AgentSchemas, AgentSnapshotDivergedError, type AgentStepRequest, type AgentTextRequest, type AgentTextResult, type AgentTimerEvent, type AgentTimerScheduler, type AgentTool, type AgentToolChoice, type AgentToolDescriptor, type AgentToolExecute, type AgentToolSchema, type AgentTools, type AgentTraceEvent, type AgentTransitionHandler, AgentTruncatedError, type AgentUsage, type AgentUsageEvent, type AgentUsageEventPayload, type AgentWorkflowActionConfig, type AgentWorkflowActorConfig, type AgentWorkflowConfig, type AgentWorkflowInvokeConfig, type AgentWorkflowRequestConfig, type AgentWorkflowStateConfig, type AgentWorkflowTransitionConfig, type AllowedEventPattern, type AllowedEvents, type AssistantMessage, type BuiltinAgentActors, type ChosenEvent, type ContextOf, type CreateDecisionRequestOptions, DEFAULT_ACT_MAX_STEPS, type DataContent, type DecideNextOptions, type DecideNextResult, type DecisionAttempt, type DecisionLogic, type DecisionLogicConfig, type DecisionStrategy, type DescribeMachineOptions, type DoneActorEventOf, type EffectCallEvent, type EffectDoneEvent, type EffectErrorEvent, type EventFromSnapshot, type EventOf, type EventPayload, type EventUnion, type FilePart, type FromConfigOptions, type FromConfigResult, GROUPED_EVENT_THRESHOLD, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type InspectedActorRef, type JsonSerializableTraceEvent, MAX_FINITE_PAYLOADS, type MetaOf, type MetaOfSnapshot, type NormalizedEventSchemas, type OutputOf, type PolicyDeciderOptions, type ProvideExecutorsOptions, type ProviderOptions, type ProviderStructuredOutput, type RequestNamesOf, type ResolveDecisionOptions, type SchemaCompiler, type SetupAgentResult, type SnapshotOf, type StandardSchemaV1, type StateValueOf, type SystemMessage, type TextLogic, type TextLogicConfig, type TextLogicExecuteArgs, type TextLogicExecutor, type TextPart, type ToolCallPart, type ToolMessage, type ToolResultOutput, type ToolResultPart, type UserMessage, type WithAgentEvents, type WithAgentInputSchema, type WithAgentUsageEvent, type WorkflowEffects, type WorkflowRunContext, type WrapWorkflowConfig, type WrappedWorkflow, type WrappedWorkflowContext, type WrappedWorkflowEvent, type WrappedWorkflowMachine, type WrappedWorkflowRunOptions, assistantMessage, bindRequestExecutor, createAgentInbox, createAgentRuntime, createAgentSchemas, createDecisionLogic, createDecisionRequest, createTextLogic, eventFromInteraction, getAcceptedEvents, getAgentOutputMode, getAgentSchemas, getCallFinishReason, getCallUsage, getInteraction, getJsonSchema, getJsonSchemaSync, getMachineStructuralHash, getMessageText, getStateMeta, getStatePath, inspectTransitions, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, runToQuiescence, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
|