@statelyai/agent 2.0.0-alpha.38 → 2.0.0-alpha.40
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 +59 -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 +142 -97
- package/dist/index.d.cts +97 -141
- package/dist/index.d.mts +97 -141
- package/dist/index.mjs +123 -74
- 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/machine-input-0YTPcnCm.mjs +27 -0
- package/dist/machine-input-DU3owLUr.cjs +32 -0
- 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/{run-agent-DlPzBWj-.d.mts → run-agent-BO9RSb7i.d.cts} +33 -40
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-BxkeuAYR.d.mts} +33 -40
- package/dist/{effects-DDseYtJk.cjs → run-agent-COdR9FpM.cjs} +175 -228
- package/dist/{effects-BT_cSY0j.mjs → run-agent-D3gW9wfd.mjs} +176 -211
- 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-CIu4mqIZ.d.mts} +56 -6
- package/dist/{verify-i9Hiwc5g.d.mts → verify-CTHlmBbh.d.cts} +56 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-Cacz6XSk.mjs} +170 -46
- package/dist/{verify-CwlombbC.cjs → verify-D8UDqU4l.cjs} +170 -46
- 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 +5 -4
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +13 -15
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +25 -30
- 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 +7 -12
- 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 +10 -20
- package/docs/quickstart.md +3 -3
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +105 -33
- 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 +54 -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,8 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { n as
|
|
4
|
-
import {
|
|
5
|
-
import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
|
|
1
|
+
import { B as DecisionAttempt, L as AgentDecisionRequest, Lt as WithAgentInputSchema, Tt as InferInput, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, ht as AgentTools, kt as StandardSchemaV1, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.cjs";
|
|
2
|
+
import { n as AgentUsageEvent } from "./usage-DvGcoK6x.cjs";
|
|
3
|
+
import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-aFXK6yZX.cjs";
|
|
4
|
+
import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
|
|
6
5
|
import { DurableExecution } from "xstate/durable";
|
|
7
6
|
//#region src/steps.d.ts
|
|
8
7
|
/**
|
|
@@ -208,6 +207,8 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
|
|
|
208
207
|
declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
|
|
209
208
|
includeRaw?: boolean;
|
|
210
209
|
}): JsonSerializableTraceEvent;
|
|
210
|
+
/** The action implementations `machine.provide` accepts for `TMachine`. */
|
|
211
|
+
type ProvidedActions<TMachine extends AnyStateMachine> = NonNullable<Parameters<TMachine["provide"]>[0]["actions"]>;
|
|
211
212
|
/**
|
|
212
213
|
* Options for {@link createAgentRuntime}: what the runtime binds and observes.
|
|
213
214
|
* The run's `input`/`snapshot`/`events` go to {@link AgentRuntime.start} (or
|
|
@@ -272,6 +273,13 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
|
|
|
272
273
|
metadata?: Record<string, JsonValue$1>;
|
|
273
274
|
/** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
|
|
274
275
|
actors?: Record<string, AnyActorLogic>;
|
|
276
|
+
/**
|
|
277
|
+
* Action implementations for this run, merged onto the machine before
|
|
278
|
+
* binding: sugar for `machine.provide({ actions })`. Each key must be an
|
|
279
|
+
* action declared in `setupAgent`, with the same params. Build them per run
|
|
280
|
+
* to close over live objects (a store, a session) that cannot go in context.
|
|
281
|
+
*/
|
|
282
|
+
actions?: ProvidedActions<TMachine>;
|
|
275
283
|
/**
|
|
276
284
|
* Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
|
|
277
285
|
* chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
|
|
@@ -361,9 +369,12 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
|
|
|
361
369
|
* when the machine has no transition for `event`, when the loop never
|
|
362
370
|
* applies it, when the machine settles still `active` after handling it,
|
|
363
371
|
* or when `timeout` milliseconds pass while it is still working.
|
|
372
|
+
*
|
|
373
|
+
* `event` can be a function of `signal.reason`, so aborts with different
|
|
374
|
+
* reasons (a pause and a stop) send different events.
|
|
364
375
|
*/
|
|
365
376
|
abortWith?: {
|
|
366
|
-
event: EventFromLogic<TMachine
|
|
377
|
+
event: EventFromLogic<TMachine> | ((reason: unknown) => EventFromLogic<TMachine>);
|
|
367
378
|
timeout?: number;
|
|
368
379
|
};
|
|
369
380
|
/** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
|
|
@@ -609,7 +620,8 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
|
|
|
609
620
|
nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
|
|
610
621
|
/**
|
|
611
622
|
* Delivers a host event (a cancel, a user message, a host-owned timer) into
|
|
612
|
-
* the run
|
|
623
|
+
* the run, behind earlier host sends and ahead of completions not yet handed
|
|
624
|
+
* out. Asynchronous: `send`
|
|
613
625
|
* only enqueues; the machine moves when the host loop's next `nextEvent()`
|
|
614
626
|
* hands the event out (a parked `nextEvent()` resolves with it) and the loop
|
|
615
627
|
* calls `transition`. A host that needs the event applied before it returns
|
|
@@ -623,8 +635,9 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
|
|
|
623
635
|
*
|
|
624
636
|
* - Before `start`: queued; the first `nextEvent()` hands it out (after the
|
|
625
637
|
* init event a host delivers itself). Returns `true`.
|
|
626
|
-
* - While an effect, child or timer is in flight: queued
|
|
627
|
-
*
|
|
638
|
+
* - While an effect, child or timer is in flight: queued behind earlier
|
|
639
|
+
* host sends, and handed out before any completion the run holds, so
|
|
640
|
+
* actors that settle in microtasks cannot keep it waiting. Returns `true`.
|
|
628
641
|
* - After the run stopped (cancelled, aborted, journal failure) or the
|
|
629
642
|
* machine left `active` (done, error): dropped. Returns `false`.
|
|
630
643
|
* - After `finish`: throws {@link AgentError} `runtime-finished`.
|
|
@@ -655,13 +668,6 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
|
|
|
655
668
|
*/
|
|
656
669
|
attempts?: DecisionAttempt[];
|
|
657
670
|
}
|
|
658
|
-
/**
|
|
659
|
-
* The blocking host: opens the run, delivers `event` if given, then applies
|
|
660
|
-
* every event that arrives until the run is quiescent, and returns the
|
|
661
|
-
* outcome. A request handler or durable engine writes the same loop with its
|
|
662
|
-
* own stop policy; this one is for scripts and tests.
|
|
663
|
-
*/
|
|
664
|
-
declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
|
|
665
671
|
/** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
|
|
666
672
|
interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
|
|
667
673
|
/**
|
|
@@ -681,17 +687,24 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
|
|
|
681
687
|
* A host that cannot block for the answer (a request handler, a durable
|
|
682
688
|
* object) leaves this out, stores `result.persist()`, and calls
|
|
683
689
|
* {@link runAgent} again later with `{ snapshot, event }`.
|
|
690
|
+
*
|
|
691
|
+
* `"inbox"`: each idle state waits for the next `inbox.send` (a resume
|
|
692
|
+
* after a pause), with no answer of its own. Needs `inbox`.
|
|
684
693
|
*/
|
|
685
|
-
onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
|
|
694
|
+
onIdle?: ((snapshot: SnapshotFrom<TMachine>, options: {
|
|
686
695
|
signal: AbortSignal | undefined;
|
|
687
|
-
}) => Promise<EventFromLogic<TMachine> | AgentTimerEvent
|
|
696
|
+
}) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>) | "inbox";
|
|
688
697
|
/**
|
|
689
698
|
* A send handle for events pushed mid-run (a cancel, a user message), from
|
|
690
699
|
* {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
|
|
691
700
|
* {@link AgentRuntime.send}; one sent before the run starts is delivered
|
|
692
701
|
* after the opening `event`. An inbox event that arrives while the run is
|
|
693
702
|
* idle resumes it, ahead of a pending `onIdle` answer (that answer is then
|
|
694
|
-
* dropped).
|
|
703
|
+
* dropped). Without `onIdle`, the run returns at the first idle state
|
|
704
|
+
* (an event that lands while that pass is finishing still resumes it), and
|
|
705
|
+
* a `send` after `runAgent` returns gets `false`: a pause that waits for a
|
|
706
|
+
* resume needs `onIdle` as well (`onIdle: "inbox"` when only the inbox
|
|
707
|
+
* answers). One inbox serves one `runAgent` call.
|
|
695
708
|
*/
|
|
696
709
|
inbox?: AgentInbox<EventFromLogic<TMachine>>;
|
|
697
710
|
}
|
|
@@ -779,26 +792,6 @@ declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, o
|
|
|
779
792
|
* `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
|
|
780
793
|
*/
|
|
781
794
|
declare function createAgentRuntime<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRuntimeOptions<TMachine>): AgentRuntime<TMachine>;
|
|
782
|
-
/**
|
|
783
|
-
* The actor handed to an {@link inspectTransitions} handler: an
|
|
784
|
-
* {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
|
|
785
|
-
* transition to the root machine or a specific invoked child (xstate's static
|
|
786
|
-
* `ActorRef` type omits them, but they are always present at runtime).
|
|
787
|
-
*/
|
|
788
|
-
type InspectedActorRef = AnyActorRef & {
|
|
789
|
-
id: string;
|
|
790
|
-
src?: string | AnyActorLogic;
|
|
791
|
-
};
|
|
792
|
-
/**
|
|
793
|
-
* Wraps a `(snapshot, actorRef) => void` handler into a function usable as
|
|
794
|
-
* {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
|
|
795
|
-
* `@xstate.transition` events and hands the handler the typed
|
|
796
|
-
* {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
|
|
797
|
-
* transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
|
|
798
|
-
* the manual `event.type === '@xstate.transition'` filtering and the snapshot/
|
|
799
|
-
* actorRef casts.
|
|
800
|
-
*/
|
|
801
|
-
declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
|
|
802
795
|
/**
|
|
803
796
|
* An xstate `inspect` handler that emits `machine.transition` trace events onto
|
|
804
797
|
* `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
|
|
@@ -835,4 +828,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
835
828
|
*/
|
|
836
829
|
declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
|
|
837
830
|
//#endregion
|
|
838
|
-
export {
|
|
831
|
+
export { runAgent as C, AgentStepRequest as D, AgentRequest as E, isAgentIdle as S, traceTransitions as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, createAgentInbox as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, serializeTraceEvent as w, createAgentRuntime as x, JsonSerializableTraceEvent as y };
|
|
@@ -1,8 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
import { n as
|
|
4
|
-
import {
|
|
5
|
-
import { AnyActorLogic, AnyActorRef, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
|
|
1
|
+
import { B as DecisionAttempt, L as AgentDecisionRequest, Lt as WithAgentInputSchema, Tt as InferInput, Z as AgentEventDescriptor, at as AgentError, d as AgentRequestMode, et as AgentRequestSource, f as AgentTextRequest, ht as AgentTools, kt as StandardSchemaV1, m as AgentUsage, r as AgentFinishReason, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-x17uLBwA.mjs";
|
|
2
|
+
import { n as AgentUsageEvent } from "./usage-B4B-TQSV.mjs";
|
|
3
|
+
import { c as AgentLogEntry, h as JsonValue$1, n as AgentEventLogStore } from "./event-log-store-DYun526m.mjs";
|
|
4
|
+
import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EmittedFrom, EventFromLogic, EventObject, InputFrom, InspectionEvent, OutputFrom, Snapshot, SnapshotFrom, StateValue } from "xstate";
|
|
6
5
|
import { DurableExecution } from "xstate/durable";
|
|
7
6
|
//#region src/steps.d.ts
|
|
8
7
|
/**
|
|
@@ -208,6 +207,8 @@ declare const TRACE_ENVELOPE_KEYS: readonly ["schemaVersion", "runId", "seq", "t
|
|
|
208
207
|
declare function serializeTraceEvent(event: AgentTraceEvent, options?: {
|
|
209
208
|
includeRaw?: boolean;
|
|
210
209
|
}): JsonSerializableTraceEvent;
|
|
210
|
+
/** The action implementations `machine.provide` accepts for `TMachine`. */
|
|
211
|
+
type ProvidedActions<TMachine extends AnyStateMachine> = NonNullable<Parameters<TMachine["provide"]>[0]["actions"]>;
|
|
211
212
|
/**
|
|
212
213
|
* Options for {@link createAgentRuntime}: what the runtime binds and observes.
|
|
213
214
|
* The run's `input`/`snapshot`/`events` go to {@link AgentRuntime.start} (or
|
|
@@ -272,6 +273,13 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
|
|
|
272
273
|
metadata?: Record<string, JsonValue$1>;
|
|
273
274
|
/** Actor source implementations, merged onto the machine before binding — sugar for `machine.provide({ actors })` ahead of the run. */
|
|
274
275
|
actors?: Record<string, AnyActorLogic>;
|
|
276
|
+
/**
|
|
277
|
+
* Action implementations for this run, merged onto the machine before
|
|
278
|
+
* binding: sugar for `machine.provide({ actions })`. Each key must be an
|
|
279
|
+
* action declared in `setupAgent`, with the same params. Build them per run
|
|
280
|
+
* to close over live objects (a store, a session) that cannot go in context.
|
|
281
|
+
*/
|
|
282
|
+
actions?: ProvidedActions<TMachine>;
|
|
275
283
|
/**
|
|
276
284
|
* Sugar over {@link onTrace}'s `stream.chunk` events: fires for each streamed
|
|
277
285
|
* chunk of a `mode: 'stream'` text request, alongside the {@link AgentRequest}
|
|
@@ -361,9 +369,12 @@ interface AgentRuntimeOptions<TMachine extends AnyStateMachine> {
|
|
|
361
369
|
* when the machine has no transition for `event`, when the loop never
|
|
362
370
|
* applies it, when the machine settles still `active` after handling it,
|
|
363
371
|
* or when `timeout` milliseconds pass while it is still working.
|
|
372
|
+
*
|
|
373
|
+
* `event` can be a function of `signal.reason`, so aborts with different
|
|
374
|
+
* reasons (a pause and a stop) send different events.
|
|
364
375
|
*/
|
|
365
376
|
abortWith?: {
|
|
366
|
-
event: EventFromLogic<TMachine
|
|
377
|
+
event: EventFromLogic<TMachine> | ((reason: unknown) => EventFromLogic<TMachine>);
|
|
367
378
|
timeout?: number;
|
|
368
379
|
};
|
|
369
380
|
/** Where root `after` timers live. Default `"in-process"`. See {@link AgentTimerScheduler}. */
|
|
@@ -609,7 +620,8 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
|
|
|
609
620
|
nextEvent(): Promise<EventFromLogic<TMachine> | undefined>;
|
|
610
621
|
/**
|
|
611
622
|
* Delivers a host event (a cancel, a user message, a host-owned timer) into
|
|
612
|
-
* the run
|
|
623
|
+
* the run, behind earlier host sends and ahead of completions not yet handed
|
|
624
|
+
* out. Asynchronous: `send`
|
|
613
625
|
* only enqueues; the machine moves when the host loop's next `nextEvent()`
|
|
614
626
|
* hands the event out (a parked `nextEvent()` resolves with it) and the loop
|
|
615
627
|
* calls `transition`. A host that needs the event applied before it returns
|
|
@@ -623,8 +635,9 @@ interface AgentRuntime<TMachine extends AnyStateMachine> {
|
|
|
623
635
|
*
|
|
624
636
|
* - Before `start`: queued; the first `nextEvent()` hands it out (after the
|
|
625
637
|
* init event a host delivers itself). Returns `true`.
|
|
626
|
-
* - While an effect, child or timer is in flight: queued
|
|
627
|
-
*
|
|
638
|
+
* - While an effect, child or timer is in flight: queued behind earlier
|
|
639
|
+
* host sends, and handed out before any completion the run holds, so
|
|
640
|
+
* actors that settle in microtasks cannot keep it waiting. Returns `true`.
|
|
628
641
|
* - After the run stopped (cancelled, aborted, journal failure) or the
|
|
629
642
|
* machine left `active` (done, error): dropped. Returns `false`.
|
|
630
643
|
* - After `finish`: throws {@link AgentError} `runtime-finished`.
|
|
@@ -655,13 +668,6 @@ interface AgentRunInit<TMachine extends AnyStateMachine> extends AgentRunStart<T
|
|
|
655
668
|
*/
|
|
656
669
|
attempts?: DecisionAttempt[];
|
|
657
670
|
}
|
|
658
|
-
/**
|
|
659
|
-
* The blocking host: opens the run, delivers `event` if given, then applies
|
|
660
|
-
* every event that arrives until the run is quiescent, and returns the
|
|
661
|
-
* outcome. A request handler or durable engine writes the same loop with its
|
|
662
|
-
* own stop policy; this one is for scripts and tests.
|
|
663
|
-
*/
|
|
664
|
-
declare function runToQuiescence<TMachine extends AnyStateMachine>(runtime: AgentRuntime<TMachine>, init?: AgentRunInit<TMachine>): Promise<AgentRunResult<TMachine>>;
|
|
665
671
|
/** Everything {@link runAgent} takes: the runtime's options plus how to open the run. */
|
|
666
672
|
interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntimeOptions<TMachine>, AgentRunInit<TMachine> {
|
|
667
673
|
/**
|
|
@@ -681,17 +687,24 @@ interface AgentRunOptions<TMachine extends AnyStateMachine> extends AgentRuntime
|
|
|
681
687
|
* A host that cannot block for the answer (a request handler, a durable
|
|
682
688
|
* object) leaves this out, stores `result.persist()`, and calls
|
|
683
689
|
* {@link runAgent} again later with `{ snapshot, event }`.
|
|
690
|
+
*
|
|
691
|
+
* `"inbox"`: each idle state waits for the next `inbox.send` (a resume
|
|
692
|
+
* after a pause), with no answer of its own. Needs `inbox`.
|
|
684
693
|
*/
|
|
685
|
-
onIdle?: (snapshot: SnapshotFrom<TMachine>, options: {
|
|
694
|
+
onIdle?: ((snapshot: SnapshotFrom<TMachine>, options: {
|
|
686
695
|
signal: AbortSignal | undefined;
|
|
687
|
-
}) => Promise<EventFromLogic<TMachine> | AgentTimerEvent
|
|
696
|
+
}) => Promise<EventFromLogic<TMachine> | AgentTimerEvent>) | "inbox";
|
|
688
697
|
/**
|
|
689
698
|
* A send handle for events pushed mid-run (a cancel, a user message), from
|
|
690
699
|
* {@link createAgentInbox}. Each `inbox.send` goes to the current pass's
|
|
691
700
|
* {@link AgentRuntime.send}; one sent before the run starts is delivered
|
|
692
701
|
* after the opening `event`. An inbox event that arrives while the run is
|
|
693
702
|
* idle resumes it, ahead of a pending `onIdle` answer (that answer is then
|
|
694
|
-
* dropped).
|
|
703
|
+
* dropped). Without `onIdle`, the run returns at the first idle state
|
|
704
|
+
* (an event that lands while that pass is finishing still resumes it), and
|
|
705
|
+
* a `send` after `runAgent` returns gets `false`: a pause that waits for a
|
|
706
|
+
* resume needs `onIdle` as well (`onIdle: "inbox"` when only the inbox
|
|
707
|
+
* answers). One inbox serves one `runAgent` call.
|
|
695
708
|
*/
|
|
696
709
|
inbox?: AgentInbox<EventFromLogic<TMachine>>;
|
|
697
710
|
}
|
|
@@ -779,26 +792,6 @@ declare function runAgent<TMachine extends AnyStateMachine>(machine: TMachine, o
|
|
|
779
792
|
* `createOpenAiExecutors` from '@statelyai/agent/openai' supply all three.
|
|
780
793
|
*/
|
|
781
794
|
declare function createAgentRuntime<TMachine extends AnyStateMachine>(machine: TMachine, options?: AgentRuntimeOptions<TMachine>): AgentRuntime<TMachine>;
|
|
782
|
-
/**
|
|
783
|
-
* The actor handed to an {@link inspectTransitions} handler: an
|
|
784
|
-
* {@link AnyActorRef} widened with the runtime `id`/`src` used to attribute a
|
|
785
|
-
* transition to the root machine or a specific invoked child (xstate's static
|
|
786
|
-
* `ActorRef` type omits them, but they are always present at runtime).
|
|
787
|
-
*/
|
|
788
|
-
type InspectedActorRef = AnyActorRef & {
|
|
789
|
-
id: string;
|
|
790
|
-
src?: string | AnyActorLogic;
|
|
791
|
-
};
|
|
792
|
-
/**
|
|
793
|
-
* Wraps a `(snapshot, actorRef) => void` handler into a function usable as
|
|
794
|
-
* {@link AgentRuntimeOptions.inspect}: it filters the raw inspection stream to
|
|
795
|
-
* `@xstate.transition` events and hands the handler the typed
|
|
796
|
-
* {@link AnyMachineSnapshot} and the {@link InspectedActorRef} that
|
|
797
|
-
* transitioned. Attribute a child actor via `actorRef.id`/`actorRef.src`. Saves
|
|
798
|
-
* the manual `event.type === '@xstate.transition'` filtering and the snapshot/
|
|
799
|
-
* actorRef casts.
|
|
800
|
-
*/
|
|
801
|
-
declare function inspectTransitions(handler: (snapshot: AnyMachineSnapshot, actorRef: InspectedActorRef) => void): (inspectionEvent: InspectionEvent) => void;
|
|
802
795
|
/**
|
|
803
796
|
* An xstate `inspect` handler that emits `machine.transition` trace events onto
|
|
804
797
|
* `onTrace`, sharing the SAME versioned envelope and per-root-actor `seq`
|
|
@@ -835,4 +828,4 @@ declare function traceTransitions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
835
828
|
*/
|
|
836
829
|
declare function isAgentIdle(snapshot: AnyMachineSnapshot): boolean;
|
|
837
830
|
//#endregion
|
|
838
|
-
export {
|
|
831
|
+
export { runAgent as C, AgentStepRequest as D, AgentRequest as E, isAgentIdle as S, traceTransitions as T, AgentTraceEvent as _, AgentMaxModelCallsExceededError as a, createAgentInbox as b, AgentRunMeta as c, AgentRunStart as d, AgentRuntime as f, AgentTimerScheduler as g, AgentTimerEvent as h, AgentInputFrom as i, AgentRunOptions as l, AgentSnapshotDivergedError as m, AgentEffects as n, AgentRunErrorCause as o, AgentRuntimeOptions as p, AgentInbox as r, AgentRunInit as s, AGENT_TRACE_SCHEMA_VERSION as t, AgentRunResult as u, AgentTransitionHandler as v, serializeTraceEvent as w, createAgentRuntime as x, JsonSerializableTraceEvent as y };
|