@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
package/dist/index.d.cts
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
|
-
import { A as
|
|
2
|
-
import {
|
|
3
|
-
import { n as
|
|
4
|
-
import { C as
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
7
|
-
import { n as
|
|
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";
|
|
1
|
+
import { $ as AgentRequestOptions, A as AgentActInput, At as SystemMessage, B as DecisionAttempt, C as getAgentOutputMode, Ct as FilePart, D as parseProviderOutput, Dt as NormalizedEventSchemas, E as parseOutput, Et as InferOutput, F as AgentDecisionOption, Ft as ToolResultPart, G as createDecisionRequest, H as DecisionLogicConfig, I as AgentDecisionRejection, It as UserMessage, J as DecisionStrategy, K as renderDecisionAttempts, L as AgentDecisionRequest, Lt as WithAgentInputSchema, M as AgentDecisionExecutor, Mt as ToolCallPart, N as AgentDecisionExhaustedError, Nt as ToolMessage, O as providerOutputSchema, Ot as ProviderOptions, P as AgentDecisionInput, Pt as ToolResultOutput, Q as AgentInvalidEventPayloadError, R as AgentExecutorDecisionRequest, S as createTextLogic, St as EventUnion, T as getCallUsage, Tt as InferInput, U as ResolveDecisionOptions, V as DecisionLogic, W as createDecisionLogic, X as MAX_FINITE_PAYLOADS, Y as GROUPED_EVENT_THRESHOLD, Z as AgentEventDescriptor, _ as TextLogic, _t as AllowedEvents, a as AgentModelRef, at as AgentError, b as TextLogicExecutor, bt as DataContent, c as AgentRequestExecutorInfo, ct as AgentEventSchemaInputMap, d as AgentRequestMode, dt as AgentToolChoice, et as AgentRequestSource, f as AgentTextRequest, ft as AgentToolDescriptor, g as ProviderStructuredOutput, gt as AllowedEventPattern, h as BuiltinAgentActors, ht as AgentTools, i as AgentModelMap, it as parseAgentEvent, j as DEFAULT_ACT_MAX_STEPS, jt as TextPart, k as ACT_STATE_EXITED, kt as StandardSchemaV1, l as AgentRequestExecutorResult, lt as AgentMessage, m as AgentUsage, mt as AgentToolSchema, n as AgentExecutorTextRequest, nt as EventFromSnapshot, o as AgentOutputMode, ot as AgentTruncatedError, p as AgentTextResult, pt as AgentToolExecute, q as resolveDecision, r as AgentFinishReason, rt as getAcceptedEvents, s as AgentRequestExecutor, st as AgentEventSchemaInput, t as AgentCallUsage, tt as AgentSchemas, u as AgentRequestExecutors, ut as AgentTool, v as TextLogicConfig, vt as AssistantMessage, w as getCallFinishReason, wt as ImagePart, x as bindRequestExecutor, xt as EventPayload, y as TextLogicExecuteArgs, yt as ChosenEvent, z as CreateDecisionRequestOptions } from "./text-logic-x17uLBwA.cjs";
|
|
2
|
+
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-DvGcoK6x.cjs";
|
|
3
|
+
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-Cv8Hk3mX.cjs";
|
|
4
|
+
import { C as runAgent, D as AgentStepRequest, E as AgentRequest, S as isAgentIdle, T as traceTransitions, _ as AgentTraceEvent, a as AgentMaxModelCallsExceededError, b as createAgentInbox, c as AgentRunMeta, d as AgentRunStart, f as AgentRuntime, g as AgentTimerScheduler, h as AgentTimerEvent, i as AgentInputFrom, 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 serializeTraceEvent, x as createAgentRuntime, y as JsonSerializableTraceEvent } from "./run-agent-BO9RSb7i.cjs";
|
|
5
|
+
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-aFXK6yZX.cjs";
|
|
6
|
+
import { t as PresetMachine } from "./internal-BzlpzSux.cjs";
|
|
7
|
+
import { a as getMessageText, b as RecordCallOptions, c as isStandardSchema, d as userMessage, i as getJsonSchemaSync, j as Recorder, l as systemMessage, n as assistantMessage, o as getStateMeta, r as getJsonSchema, s as getStatePath, t as MetaOfSnapshot, u as toolMessage } from "./utils-DAclF-kw.cjs";
|
|
9
8
|
import { AnyActorLogic, AnyMachineSnapshot, AnyStateMachine, ContextFrom, DoneActorEvent, EventFromLogic, InputFrom, OutputFrom, SnapshotFrom, StateValueFrom } from "xstate";
|
|
10
9
|
//#region src/type-helpers.d.ts
|
|
11
10
|
type SchemaAt<T, TKey extends PropertyKey> = T extends {
|
|
@@ -118,155 +117,103 @@ interface DescribeMachineOptions {
|
|
|
118
117
|
*/
|
|
119
118
|
export declare function describeMachine(machine: AnyStateMachine, options?: DescribeMachineOptions): string;
|
|
120
119
|
//#endregion
|
|
121
|
-
//#region src/
|
|
122
|
-
/** Options for {@link decideNext}. */
|
|
123
|
-
interface DecideNextOptions<TSnapshot extends AnyMachineSnapshot = AnyMachineSnapshot> {
|
|
124
|
-
/** The decide executor that asks a model to pick one option. */
|
|
125
|
-
decide: AgentDecisionExecutor;
|
|
126
|
-
/** Model ref, passed through to the executor. */
|
|
127
|
-
model: string;
|
|
128
|
-
/** Event types the model may choose: exact types or wildcards (`'desk.*'`, `'*'`). */
|
|
129
|
-
allowedEvents: string | readonly string[];
|
|
130
|
-
/**
|
|
131
|
-
* Concrete payloads per event type, without `type`. One option per payload.
|
|
132
|
-
* A candidate type with no key is offered bare, as `{ type }`; an empty list
|
|
133
|
-
* offers nothing for it. To withhold a type, give it `[]`:
|
|
134
|
-
* `(s) => ({ "desk.refund": [{ amount: s.context.requested }], "desk.close": [] })`.
|
|
135
|
-
*/
|
|
136
|
-
payloads?: (snapshot: TSnapshot) => Partial<Record<string, Record<string, unknown>[]>>;
|
|
137
|
-
system?: string;
|
|
138
|
-
prompt?: string;
|
|
139
|
-
/** Semantic request name, for traces and scripted executors. Default `'decideNext'`. */
|
|
140
|
-
name?: string;
|
|
141
|
-
/**
|
|
142
|
-
* Describe what each option changes: the state value and the changed
|
|
143
|
-
* top-level context keys, computed with xstate's pure `transition()`.
|
|
144
|
-
* An array limits which context keys are reported (a state value change is
|
|
145
|
-
* always reported). Each reported value is cut to 120 characters.
|
|
146
|
-
*/
|
|
147
|
-
lookahead?: boolean | readonly string[];
|
|
148
|
-
/** Retries after a failed choice. Default `2`. */
|
|
149
|
-
maxRetries?: number;
|
|
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;
|
|
159
|
-
}
|
|
160
|
-
/** Result of {@link decideNext}. */
|
|
161
|
-
interface DecideNextResult<TEvent = ChosenEvent> {
|
|
162
|
-
/** The chosen event, or `null` when the snapshot accepts none of the options. */
|
|
163
|
-
event: TEvent | null;
|
|
164
|
-
/** Failed attempts before the choice landed. */
|
|
165
|
-
attempts: DecisionAttempt[];
|
|
166
|
-
/** The request built for the executor, with the offered `options` and the same `withheld`. */
|
|
167
|
-
request: AgentDecisionRequest;
|
|
168
|
-
/**
|
|
169
|
-
* The candidates the snapshot rejected: every `allowedEvents` type × payload,
|
|
170
|
-
* built the same way as the offered options, where `snapshot.can(event)` was
|
|
171
|
-
* false or the state handles the type through a transition tagged
|
|
172
|
-
* `meta: { actor: "human" }`. Never offered to the model. Filled when
|
|
173
|
-
* nothing is offered too.
|
|
174
|
-
*/
|
|
175
|
-
withheld: ChosenEvent[];
|
|
176
|
-
}
|
|
120
|
+
//#region src/generator-bridge.d.ts
|
|
177
121
|
/**
|
|
178
|
-
*
|
|
179
|
-
*
|
|
180
|
-
*
|
|
181
|
-
* payload, kept only where `snapshot.can(event)` is true and no transition
|
|
182
|
-
* tagged `meta: { actor: "human" }` handles the type; the rest come back as
|
|
183
|
-
* `withheld`. Each option is
|
|
184
|
-
* described from the transition's `description`, else the event schema's,
|
|
185
|
-
* plus (with `lookahead`) what it changes. The chosen event must equal one
|
|
186
|
-
* offered option; anything else is retried.
|
|
187
|
-
*
|
|
188
|
-
* It never sends. The host sends the event, re-checking `can` first, because
|
|
189
|
-
* the actor may have moved while the model was thinking. With no options it
|
|
190
|
-
* returns `{ event: null }` without calling the executor. Exhausting retries
|
|
191
|
-
* throws `AgentDecisionExhaustedError`.
|
|
192
|
-
*
|
|
193
|
-
* @example
|
|
194
|
-
* ```ts no-check
|
|
195
|
-
* let busy = false;
|
|
196
|
-
* actor.subscribe(async (snapshot) => {
|
|
197
|
-
* if (busy || !snapshot.matches('reviewing')) return;
|
|
198
|
-
* busy = true;
|
|
199
|
-
* try {
|
|
200
|
-
* const { event } = await decideNext(snapshot, {
|
|
201
|
-
* decide,
|
|
202
|
-
* model: 'quick',
|
|
203
|
-
* allowedEvents: 'desk.*',
|
|
204
|
-
* payloads: (s) => ({ 'desk.refund': [{ amount: s.context.requested }] }),
|
|
205
|
-
* lookahead: true,
|
|
206
|
-
* });
|
|
207
|
-
* if (event && actor.getSnapshot().can(event)) actor.send(event);
|
|
208
|
-
* } finally {
|
|
209
|
-
* busy = false;
|
|
210
|
-
* }
|
|
211
|
-
* });
|
|
212
|
-
* ```
|
|
122
|
+
* `createGeneratorBridge`: an async generator's pull contract, across an
|
|
123
|
+
* actor boundary.
|
|
124
|
+
* @module
|
|
213
125
|
*/
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
126
|
+
/** What {@link GeneratorBridge.forward} reports once the generator stops. */
|
|
127
|
+
type ForwardResult<TReturn> =
|
|
128
|
+
/**
|
|
129
|
+
* The generator returned. Also when the consumer stopped and then pulled a
|
|
130
|
+
* value yielded while unwinding: as with `yield*`, that resumes the
|
|
131
|
+
* generator, which then completes normally with `value`.
|
|
132
|
+
*/
|
|
133
|
+
{
|
|
134
|
+
closed: false;
|
|
135
|
+
value: TReturn | undefined;
|
|
136
|
+
} |
|
|
137
|
+
/** The consumer stopped reading; `value` is what the generator returned while unwinding. */
|
|
138
|
+
{
|
|
139
|
+
closed: true;
|
|
140
|
+
value: TReturn | undefined;
|
|
141
|
+
};
|
|
142
|
+
/** The two ends of a {@link createGeneratorBridge} bridge. */
|
|
143
|
+
interface GeneratorBridge<T> {
|
|
144
|
+
/**
|
|
145
|
+
* Producer side, inside an actor: hands `value` to the consumer and waits
|
|
146
|
+
* until the consumer pulls again, as a generator suspended at `yield`
|
|
147
|
+
* does. Resolves `true` when the consumer pulled, `false` when it stopped
|
|
148
|
+
* (`.return()`, a `break`) or the run settled. Rejects with what the
|
|
149
|
+
* consumer passed to `.throw()`.
|
|
150
|
+
*/
|
|
151
|
+
put(value: T): Promise<boolean>;
|
|
219
152
|
/**
|
|
220
|
-
*
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
224
|
-
*
|
|
225
|
-
* call and attempt and stays the same when a crashed run re-issues the call;
|
|
226
|
-
* the hash keeps a machine that asks something else at the same call site
|
|
227
|
-
* after a version bridge, which keeps the call key, off the earlier thread. Required
|
|
228
|
-
* with a `store` when the decider is called without a `callKey`.
|
|
153
|
+
* Producer side: drives `generator` through {@link put}. A consumer's
|
|
154
|
+
* `.throw(error)` becomes `generator.throw(error)`; a consumer that stops
|
|
155
|
+
* gets `generator.return()`, so its `finally` blocks run before this
|
|
156
|
+
* resolves. Values the generator yields while unwinding still reach the
|
|
157
|
+
* consumer, as with `yield*`.
|
|
229
158
|
*/
|
|
230
|
-
|
|
159
|
+
forward<TReturn>(generator: AsyncGenerator<T, TReturn, undefined>): Promise<ForwardResult<TReturn>>;
|
|
231
160
|
/**
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
161
|
+
* Consumer side: yields each value the producer puts until `settled`
|
|
162
|
+
* resolves, then returns what it resolved to. Pass the run:
|
|
163
|
+
* `const result = yield* bridge.stream(runAgent(machine, options))`. When
|
|
164
|
+
* the consumer stops, it waits for `settled` before it returns, so the
|
|
165
|
+
* producer has unwound by then, and returns what `settled` resolved to
|
|
166
|
+
* rather than the value passed to `.return()`. As with any `yield*`, a
|
|
167
|
+
* stopped consumer skips the code after it in the enclosing generator;
|
|
168
|
+
* cleanup that must run either way goes in a `finally`. A run that fails
|
|
169
|
+
* while a stopped consumer waits (a legacy `finally` that throws) throws
|
|
170
|
+
* its error from `.return()` instead. A consumer that pulls again after
|
|
171
|
+
* stopping (`.next()` on a value yielded while unwinding) resumes, as with
|
|
172
|
+
* `yield*`: the code after it runs and gets the run's result, failed or not.
|
|
236
173
|
*/
|
|
237
|
-
|
|
174
|
+
stream<TSettled>(settled: PromiseLike<TSettled>): AsyncGenerator<T, TSettled, undefined>;
|
|
238
175
|
}
|
|
239
176
|
/**
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
177
|
+
* A backpressured hand-off between an actor and an async generator's
|
|
178
|
+
* consumer, for a loop whose public surface is an `AsyncGenerator`: the
|
|
179
|
+
* machine owns the loop head, each pass is an actor, and the events it
|
|
180
|
+
* yields still reach the consumer one pull at a time.
|
|
244
181
|
*
|
|
245
|
-
*
|
|
246
|
-
* like any other decider's choice. The policy's input must be JSON (it opens
|
|
247
|
-
* the policy run's event log): the default drops keys whose value is
|
|
248
|
-
* `undefined`, and any other value that is not JSON throws before the run. The policy's token usage is reported on the
|
|
249
|
-
* result, and left out when the policy made no model call. A run that does not
|
|
250
|
-
* end `done` with an event throws `AgentError` with code `policy-not-done`.
|
|
182
|
+
* One bridge serves one run.
|
|
251
183
|
*
|
|
252
184
|
* @example
|
|
253
|
-
* ```ts
|
|
254
|
-
*
|
|
255
|
-
*
|
|
185
|
+
* ```ts
|
|
186
|
+
* async function* carvedLoop(input: Input): AsyncGenerator<Event, Result> {
|
|
187
|
+
* const bridge = createGeneratorBridge<Event>();
|
|
188
|
+
* const pass = createAsyncLogic({
|
|
189
|
+
* run: async () => {
|
|
190
|
+
* const step = await bridge.forward(legacyPass(input));
|
|
191
|
+
* return step.closed ? { kind: "closed" } : step.value;
|
|
192
|
+
* },
|
|
193
|
+
* });
|
|
194
|
+
* const result = yield* bridge.stream(runAgent(loopMachine, { input, actors: { pass } }));
|
|
195
|
+
* if (result.status === "error") throw result.error;
|
|
196
|
+
* return toResult(result);
|
|
197
|
+
* }
|
|
256
198
|
* ```
|
|
257
199
|
*/
|
|
258
|
-
export declare function
|
|
200
|
+
export declare function createGeneratorBridge<T>(): GeneratorBridge<T>;
|
|
259
201
|
//#endregion
|
|
260
202
|
//#region src/wrap-workflow.d.ts
|
|
261
203
|
/** The effects a wrapped workflow calls: async functions, by name. */
|
|
262
204
|
type WorkflowEffects<TEffects> = { [K in keyof TEffects]: (...args: never[]) => PromiseLike<unknown>; };
|
|
263
205
|
/** What a wrapped workflow's `run` gets besides its input and effects. */
|
|
264
|
-
interface WorkflowRunContext {
|
|
206
|
+
interface WorkflowRunContext<TLive = undefined> {
|
|
265
207
|
/** Aborted when the run is aborted or the machine stops the workflow. */
|
|
266
208
|
signal: AbortSignal;
|
|
209
|
+
/**
|
|
210
|
+
* The live object this call passed as `live` (the instance a class-shaped
|
|
211
|
+
* loop runs on), so one wrapped workflow serves every instance.
|
|
212
|
+
*/
|
|
213
|
+
live: TLive;
|
|
267
214
|
}
|
|
268
215
|
/** Options for {@link wrapWorkflow}. */
|
|
269
|
-
interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects
|
|
216
|
+
interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>, TLive = undefined> {
|
|
270
217
|
/** The machine id. */
|
|
271
218
|
id: string;
|
|
272
219
|
/** The machine version, for the event log. Default `"1"`. */
|
|
@@ -281,7 +228,7 @@ interface WrapWorkflowConfig<TInput, TOutput, TEffects extends WorkflowEffects<T
|
|
|
281
228
|
* functions is passed as is. An effect that resolves to a stream (anything
|
|
282
229
|
* `for await` reads) settles once the stream is read, with its chunks.
|
|
283
230
|
*/
|
|
284
|
-
run: (input: TInput, effects: TEffects, context: WorkflowRunContext) => PromiseLike<TOutput>;
|
|
231
|
+
run: (input: TInput, effects: TEffects, context: WorkflowRunContext<TLive>) => PromiseLike<TOutput>;
|
|
285
232
|
/**
|
|
286
233
|
* Maps an effect's arguments, result, or error before it is journaled as an
|
|
287
234
|
* event. Return a redacted value for secrets and private records: every
|
|
@@ -329,7 +276,7 @@ type WrappedWorkflowContext<TInput, TOutput> = {
|
|
|
329
276
|
failures: number;
|
|
330
277
|
};
|
|
331
278
|
/** 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"> {
|
|
279
|
+
interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput, TLive = undefined> extends Pick<AgentRunOptions<WrappedWorkflowMachine<TInput, TOutput>>, "signal" | "inspect" | "onTransition" | "onTrace" | "onEvent" | "metadata" | "verification"> {
|
|
333
280
|
/** Replaces some effects for this run: fakes, stubs, replay wrappers. */
|
|
334
281
|
effects?: Partial<TEffects>;
|
|
335
282
|
/**
|
|
@@ -337,9 +284,16 @@ interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<Agen
|
|
|
337
284
|
* result with `recorder.output`, so `recorder.recording` is a golden run.
|
|
338
285
|
*/
|
|
339
286
|
recorder?: Recorder;
|
|
287
|
+
/**
|
|
288
|
+
* `recorder.fn` options per effect: `serialize` for a result that is not
|
|
289
|
+
* JSON, `revive` to rebuild it in replay, `redact` for arguments.
|
|
290
|
+
*/
|
|
291
|
+
recordOptions?: { [K in keyof TEffects]?: RecordCallOptions; };
|
|
292
|
+
/** Passed to the workflow as `context.live`: this call's live object. */
|
|
293
|
+
live?: TLive;
|
|
340
294
|
}
|
|
341
295
|
/** The result of {@link wrapWorkflow}. */
|
|
342
|
-
interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
296
|
+
interface WrappedWorkflow<TInput, TOutput, TEffects, TLive = undefined> {
|
|
343
297
|
/**
|
|
344
298
|
* `running` invokes the workflow and counts its effect calls; `done` is
|
|
345
299
|
* final with the workflow's result as output. A rejection is unhandled, so
|
|
@@ -354,7 +308,9 @@ interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
|
354
308
|
* workflow that returns an `aborted` result still returns it. Once it
|
|
355
309
|
* aborts, an effect call throws `signal.reason` instead of running.
|
|
356
310
|
*/
|
|
357
|
-
run(input: TInput, options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput>
|
|
311
|
+
run(input: TInput, ...options: undefined extends TLive ? [options?: WrappedWorkflowRunOptions<TEffects, TInput, TOutput, TLive>] : [options: WrappedWorkflowRunOptions<TEffects, TInput, TOutput, TLive> & {
|
|
312
|
+
live: TLive;
|
|
313
|
+
}]): Promise<TOutput>;
|
|
358
314
|
}
|
|
359
315
|
/** The events a {@link wrapWorkflow} machine handles. */
|
|
360
316
|
type WrappedWorkflowEvent = EffectCallEvent | EffectDoneEvent | EffectErrorEvent;
|
|
@@ -388,7 +344,7 @@ type WrappedWorkflowMachine<TInput, TOutput> = PresetMachine<WrappedWorkflowCont
|
|
|
388
344
|
* const reply = await support.run(ticket); // what legacyRunTicket returned
|
|
389
345
|
* ```
|
|
390
346
|
*/
|
|
391
|
-
export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects
|
|
347
|
+
export declare function wrapWorkflow<TInput, TOutput, TEffects extends WorkflowEffects<TEffects>, TLive = undefined>(config: WrapWorkflowConfig<TInput, TOutput, TEffects, TLive>): WrappedWorkflow<TInput, TOutput, TEffects, TLive>;
|
|
392
348
|
//#endregion
|
|
393
349
|
//#region src/provide-executors.d.ts
|
|
394
350
|
/** Options for {@link provideExecutors}. */
|
|
@@ -460,4 +416,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
460
416
|
*/
|
|
461
417
|
export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
|
|
462
418
|
//#endregion
|
|
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
|
|
419
|
+
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 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 ForwardResult, type FromConfigOptions, type FromConfigResult, GROUPED_EVENT_THRESHOLD, type GeneratorBridge, type GetInteractionOptions, type ImagePart, type InferInput, type InferOutput, type InputOf, type JsonSerializableTraceEvent, MAX_FINITE_PAYLOADS, type MetaOf, type MetaOfSnapshot, type NormalizedEventSchemas, type OutputOf, 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, getMessageText, getStateMeta, getStatePath, interactionMetaSchema, isAgentIdle, isStandardSchema, parseAgentEvent, parseOutput, parseProviderOutput, providerOutputSchema, renderDecisionAttempts, resolveDecision, runAgent, serializeTraceEvent, setupAgent, systemMessage, toolMessage, traceTransitions, userMessage };
|