@statelyai/agent 2.0.0-alpha.37 → 2.0.0-alpha.39
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +51 -0
- package/dist/{act-CrX0JwWY.cjs → act-B0CVbmo4.cjs} +1 -1
- package/dist/{act-B9hLQls6.mjs → act-Bsz-hUfD.mjs} +1 -1
- package/dist/ai-sdk.cjs +4 -4
- package/dist/ai-sdk.d.cts +2 -3
- package/dist/ai-sdk.d.mts +2 -3
- package/dist/ai-sdk.mjs +4 -4
- package/dist/{decision-m5hGmHpF.mjs → decision-B41YBx5U.mjs} +1 -1
- package/dist/{decision-CMeuNZ1g.cjs → decision-D8bcIGXQ.cjs} +1 -1
- package/dist/{decision-object-DBcLWVvv.d.cts → decision-object-BB8XV5Ec.d.cts} +1 -1
- package/dist/{decision-object-B5zGSPFp.d.mts → decision-object-CH_sE694.d.mts} +1 -1
- package/dist/effects-B9IvUPVh.mjs +23 -0
- package/dist/effects-DrWcUGgc.cjs +34 -0
- package/dist/evals.cjs +810 -0
- package/dist/evals.d.cts +595 -0
- package/dist/evals.d.mts +595 -0
- package/dist/evals.mjs +801 -0
- package/dist/{event-log-DkVlk3Rh.mjs → event-log-CEq_bVXQ.mjs} +8 -4
- package/dist/{event-log-Dkc-yIYu.cjs → event-log-dSOnXHuG.cjs} +7 -15
- package/dist/{event-log-store-Brx9tOHt.mjs → event-log-store-DLAfNM34.mjs} +1 -1
- package/dist/{event-log-store-BBS8so8a.d.mts → event-log-store-DYun526m.d.mts} +15 -14
- package/dist/{event-log-store-Cl-YWDnq.cjs → event-log-store-Dey9ufA4.cjs} +1 -1
- package/dist/{event-log-store-bc4ICGcS.d.cts → event-log-store-aFXK6yZX.d.cts} +15 -14
- package/dist/index.cjs +136 -98
- package/dist/index.d.cts +73 -134
- package/dist/index.d.mts +73 -134
- package/dist/index.mjs +117 -75
- package/dist/internal-BzlpzSux.d.cts +14 -0
- package/dist/internal-BzlpzSux.d.mts +14 -0
- package/dist/log.cjs +2 -3
- package/dist/log.d.cts +2 -2
- package/dist/log.d.mts +2 -2
- package/dist/log.mjs +3 -3
- package/dist/machines.cjs +1 -719
- package/dist/machines.d.cts +2 -424
- package/dist/machines.d.mts +2 -424
- package/dist/machines.mjs +2 -709
- package/dist/{model-source-kjGwqAV8.mjs → model-source-BrsLDvHL.mjs} +1 -1
- package/dist/{model-source-B4WQ8Idp.cjs → model-source-YpxjmWuX.cjs} +1 -1
- package/dist/openai.cjs +3 -3
- package/dist/openai.d.cts +2 -3
- package/dist/openai.d.mts +2 -3
- package/dist/openai.mjs +3 -3
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/policy.cjs +77 -0
- package/dist/policy.d.cts +143 -0
- package/dist/policy.d.mts +143 -0
- package/dist/policy.mjs +75 -0
- package/dist/{effects-BT_cSY0j.mjs → run-agent-BE7DOWD6.mjs} +150 -184
- package/dist/{run-agent-DlPzBWj-.d.mts → run-agent-DHlq87G7.d.mts} +18 -34
- package/dist/{effects-DDseYtJk.cjs → run-agent-De3xVFGw.cjs} +149 -201
- package/dist/{run-agent-30mH2moE.d.cts → run-agent-Dq0oSFRm.d.cts} +18 -34
- package/dist/{setup-agent-BDmNr6PC.mjs → setup-agent-CLm6QVGy.mjs} +3 -3
- package/dist/{setup-agent-BaNyz6Q3.d.cts → setup-agent-Cv8Hk3mX.d.cts} +12 -11
- package/dist/{setup-agent-C1CG_nfX.d.mts → setup-agent-DgFAhaPJ.d.mts} +12 -11
- package/dist/{setup-agent-CmEToB8y.cjs → setup-agent-Dv5VpuHe.cjs} +3 -3
- package/dist/tanstack-ai.cjs +4 -4
- package/dist/tanstack-ai.d.cts +2 -3
- package/dist/tanstack-ai.d.mts +2 -3
- package/dist/tanstack-ai.mjs +4 -4
- package/dist/testing.cjs +122 -996
- package/dist/testing.d.cts +36 -695
- package/dist/testing.d.mts +36 -695
- package/dist/testing.mjs +112 -977
- package/dist/{text-logic-BqxalgMr.d.mts → text-logic-x17uLBwA.d.cts} +238 -2
- package/dist/{text-logic-CSf9bqpP.d.cts → text-logic-x17uLBwA.d.mts} +238 -2
- package/dist/trajectory-BFjXaooB.d.cts +96 -0
- package/dist/trajectory-BFjXaooB.d.mts +96 -0
- package/dist/trajectory-BUXj_1Ue.mjs +152 -0
- package/dist/trajectory-CoZSv4wF.cjs +157 -0
- package/dist/{usage-Bm5nvpow.d.cts → usage-B4B-TQSV.d.mts} +1 -1
- package/dist/{usage-BnikdOca.d.mts → usage-DvGcoK6x.d.cts} +1 -1
- package/dist/{utils-7lSa4H-i.d.cts → utils-B8k-YPYI.d.mts} +23 -17
- package/dist/{utils-CBbKw2fM.d.mts → utils-DAclF-kw.d.cts} +23 -17
- package/dist/validate.cjs +4 -4
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +4 -4
- package/dist/{verify-DJHfEfm6.d.cts → verify-BM0sGmsf.d.cts} +42 -6
- package/dist/{verify-ChyX6jq0.mjs → verify-CWlg3j7B.mjs} +153 -45
- package/dist/{verify-CwlombbC.cjs → verify-Dek6gHCS.cjs} +153 -45
- package/dist/{verify-i9Hiwc5g.d.mts → verify-H3Pr2gNw.d.mts} +42 -6
- package/dist/{with-model-calls-B_WLmOSl.cjs → with-model-calls-D50Ca6qW.cjs} +2 -2
- package/dist/{with-model-calls-BkOwdroS.mjs → with-model-calls-uY-KKliA.mjs} +2 -2
- package/docs/advanced.md +5 -5
- package/docs/choosing-a-run-mode.md +7 -7
- package/docs/debugging.md +6 -8
- package/docs/decisions.md +6 -5
- package/docs/environment-and-policy.md +1 -1
- package/docs/evals.md +57 -43
- package/docs/event-log.md +14 -16
- package/docs/from-a-loop.md +3 -3
- package/docs/generate-machines.md +4 -4
- package/docs/hosts.md +22 -29
- package/docs/human-in-the-loop.md +5 -8
- package/docs/index.md +4 -4
- package/docs/judgments.md +5 -7
- package/docs/langgraph-comparison.md +6 -6
- package/docs/machines-as-data.md +12 -17
- package/docs/machines-presets.md +17 -120
- package/docs/machines.md +13 -13
- package/docs/models-and-providers.md +19 -25
- package/docs/multi-agent.md +1 -1
- package/docs/observability.md +6 -8
- package/docs/persistence.md +15 -25
- package/docs/quickstart.md +4 -4
- package/docs/statechart-policy-examples.md +1 -1
- package/docs/steps.md +5 -6
- package/docs/strangler-fig.md +72 -7
- package/docs/text-requests.md +10 -12
- package/docs/thinking-in-state-machines.md +8 -8
- package/docs/tools.md +10 -12
- package/docs/upgrading.md +1 -1
- package/docs/usage-and-budgets.md +51 -56
- package/docs/validate-and-repair.md +9 -14
- package/docs/verify.md +53 -7
- package/docs/xstate-4-and-5-apps.md +19 -28
- package/llms.txt +1 -1
- package/package.json +31 -6
- package/readme.md +32 -24
- package/dist/internal-C3Lqu538.d.cts +0 -43
- package/dist/internal-DUcdhk-i.d.mts +0 -43
- package/dist/types-DQUOOaZO.d.cts +0 -238
- package/dist/types-DQUOOaZO.d.mts +0 -238
- package/skills/add-evals/SKILL.md +0 -152
- package/skills/add-traces/SKILL.md +0 -152
- package/skills/build-machine/SKILL.md +0 -84
- package/skills/generate-machine/SKILL.md +0 -335
- package/skills/graph-engineering/SKILL.md +0 -43
- package/skills/improve-machine/SKILL.md +0 -261
- package/skills/improve-machine/reference.md +0 -101
- package/skills/loop-to-machine/SKILL.md +0 -205
- package/skills/loop-to-machine/policy.md +0 -154
- package/skills/loop-to-machine/reference.md +0 -260
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-Dq0oSFRm.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,144 +117,79 @@ 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
|
+
closed: false;
|
|
129
|
+
value: TReturn;
|
|
130
|
+
} |
|
|
131
|
+
/** The consumer stopped reading; `value` is what the generator returned while unwinding. */
|
|
132
|
+
{
|
|
133
|
+
closed: true;
|
|
134
|
+
value: TReturn | undefined;
|
|
135
|
+
};
|
|
136
|
+
/** The two ends of a {@link createGeneratorBridge} bridge. */
|
|
137
|
+
interface GeneratorBridge<T> {
|
|
138
|
+
/**
|
|
139
|
+
* Producer side, inside an actor: hands `value` to the consumer and waits
|
|
140
|
+
* until the consumer pulls again, as a generator suspended at `yield`
|
|
141
|
+
* does. Resolves `true` when the consumer pulled, `false` when it stopped
|
|
142
|
+
* (`.return()`, a `break`) or the run settled. Rejects with what the
|
|
143
|
+
* consumer passed to `.throw()`.
|
|
144
|
+
*/
|
|
145
|
+
put(value: T): Promise<boolean>;
|
|
219
146
|
/**
|
|
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`.
|
|
147
|
+
* Producer side: drives `generator` through {@link put}. A consumer's
|
|
148
|
+
* `.throw(error)` becomes `generator.throw(error)`; a consumer that stops
|
|
149
|
+
* gets `generator.return()`, so its `finally` blocks run before this
|
|
150
|
+
* resolves. Values the generator yields while unwinding still reach the
|
|
151
|
+
* consumer, as with `yield*`.
|
|
229
152
|
*/
|
|
230
|
-
|
|
153
|
+
forward<TReturn>(generator: AsyncGenerator<T, TReturn, undefined>): Promise<ForwardResult<TReturn>>;
|
|
231
154
|
/**
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
155
|
+
* Consumer side: yields each value the producer puts until `settled`
|
|
156
|
+
* resolves, then returns what it resolved to. Pass the run:
|
|
157
|
+
* `const result = yield* bridge.stream(runAgent(machine, options))`. When
|
|
158
|
+
* the consumer stops, it waits for `settled` before it returns, so the
|
|
159
|
+
* producer has unwound by then, and returns what `settled` resolved to
|
|
160
|
+
* rather than the value passed to `.return()`. As with any `yield*`, a
|
|
161
|
+
* stopped consumer skips the code after it in the enclosing generator;
|
|
162
|
+
* cleanup that must run either way goes in a `finally`. A run that fails
|
|
163
|
+
* while a stopped consumer waits (a legacy `finally` that throws) throws
|
|
164
|
+
* its error from `.return()` instead.
|
|
236
165
|
*/
|
|
237
|
-
|
|
166
|
+
stream<TSettled>(settled: PromiseLike<TSettled>): AsyncGenerator<T, TSettled, undefined>;
|
|
238
167
|
}
|
|
239
168
|
/**
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
169
|
+
* A backpressured hand-off between an actor and an async generator's
|
|
170
|
+
* consumer, for a loop whose public surface is an `AsyncGenerator`: the
|
|
171
|
+
* machine owns the loop head, each pass is an actor, and the events it
|
|
172
|
+
* yields still reach the consumer one pull at a time.
|
|
244
173
|
*
|
|
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`.
|
|
174
|
+
* One bridge serves one run.
|
|
251
175
|
*
|
|
252
176
|
* @example
|
|
253
|
-
* ```ts
|
|
254
|
-
*
|
|
255
|
-
*
|
|
177
|
+
* ```ts
|
|
178
|
+
* async function* carvedLoop(input: Input): AsyncGenerator<Event, Result> {
|
|
179
|
+
* const bridge = createGeneratorBridge<Event>();
|
|
180
|
+
* const pass = createAsyncLogic({
|
|
181
|
+
* run: async () => {
|
|
182
|
+
* const step = await bridge.forward(legacyPass(input));
|
|
183
|
+
* return step.closed ? { kind: "closed" } : step.value;
|
|
184
|
+
* },
|
|
185
|
+
* });
|
|
186
|
+
* const result = yield* bridge.stream(runAgent(loopMachine, { input, actors: { pass } }));
|
|
187
|
+
* if (result.status === "error") throw result.error;
|
|
188
|
+
* return toResult(result);
|
|
189
|
+
* }
|
|
256
190
|
* ```
|
|
257
191
|
*/
|
|
258
|
-
export declare function
|
|
192
|
+
export declare function createGeneratorBridge<T>(): GeneratorBridge<T>;
|
|
259
193
|
//#endregion
|
|
260
194
|
//#region src/wrap-workflow.d.ts
|
|
261
195
|
/** The effects a wrapped workflow calls: async functions, by name. */
|
|
@@ -337,6 +271,11 @@ interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<Agen
|
|
|
337
271
|
* result with `recorder.output`, so `recorder.recording` is a golden run.
|
|
338
272
|
*/
|
|
339
273
|
recorder?: Recorder;
|
|
274
|
+
/**
|
|
275
|
+
* `recorder.fn` options per effect: `serialize` for a result that is not
|
|
276
|
+
* JSON, `revive` to rebuild it in replay, `redact` for arguments.
|
|
277
|
+
*/
|
|
278
|
+
recordOptions?: { [K in keyof TEffects]?: RecordCallOptions; };
|
|
340
279
|
}
|
|
341
280
|
/** The result of {@link wrapWorkflow}. */
|
|
342
281
|
interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
@@ -460,4 +399,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
460
399
|
*/
|
|
461
400
|
export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
|
|
462
401
|
//#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
|
|
402
|
+
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 };
|
package/dist/index.d.mts
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-CBbKw2fM.mjs";
|
|
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.mjs";
|
|
2
|
+
import { n as AgentUsageEvent, t as AGENT_USAGE_EVENT_TYPE } from "./usage-B4B-TQSV.mjs";
|
|
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-DgFAhaPJ.mjs";
|
|
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-DHlq87G7.mjs";
|
|
5
|
+
import { c as AgentLogEntry, d as AgentMachineVersionMismatchError, h as JsonValue, n as AgentEventLogStore, t as AgentEventLogConflictError } from "./event-log-store-DYun526m.mjs";
|
|
6
|
+
import { t as PresetMachine } from "./internal-BzlpzSux.mjs";
|
|
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-B8k-YPYI.mjs";
|
|
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,144 +117,79 @@ 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
|
+
closed: false;
|
|
129
|
+
value: TReturn;
|
|
130
|
+
} |
|
|
131
|
+
/** The consumer stopped reading; `value` is what the generator returned while unwinding. */
|
|
132
|
+
{
|
|
133
|
+
closed: true;
|
|
134
|
+
value: TReturn | undefined;
|
|
135
|
+
};
|
|
136
|
+
/** The two ends of a {@link createGeneratorBridge} bridge. */
|
|
137
|
+
interface GeneratorBridge<T> {
|
|
138
|
+
/**
|
|
139
|
+
* Producer side, inside an actor: hands `value` to the consumer and waits
|
|
140
|
+
* until the consumer pulls again, as a generator suspended at `yield`
|
|
141
|
+
* does. Resolves `true` when the consumer pulled, `false` when it stopped
|
|
142
|
+
* (`.return()`, a `break`) or the run settled. Rejects with what the
|
|
143
|
+
* consumer passed to `.throw()`.
|
|
144
|
+
*/
|
|
145
|
+
put(value: T): Promise<boolean>;
|
|
219
146
|
/**
|
|
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`.
|
|
147
|
+
* Producer side: drives `generator` through {@link put}. A consumer's
|
|
148
|
+
* `.throw(error)` becomes `generator.throw(error)`; a consumer that stops
|
|
149
|
+
* gets `generator.return()`, so its `finally` blocks run before this
|
|
150
|
+
* resolves. Values the generator yields while unwinding still reach the
|
|
151
|
+
* consumer, as with `yield*`.
|
|
229
152
|
*/
|
|
230
|
-
|
|
153
|
+
forward<TReturn>(generator: AsyncGenerator<T, TReturn, undefined>): Promise<ForwardResult<TReturn>>;
|
|
231
154
|
/**
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
235
|
-
*
|
|
155
|
+
* Consumer side: yields each value the producer puts until `settled`
|
|
156
|
+
* resolves, then returns what it resolved to. Pass the run:
|
|
157
|
+
* `const result = yield* bridge.stream(runAgent(machine, options))`. When
|
|
158
|
+
* the consumer stops, it waits for `settled` before it returns, so the
|
|
159
|
+
* producer has unwound by then, and returns what `settled` resolved to
|
|
160
|
+
* rather than the value passed to `.return()`. As with any `yield*`, a
|
|
161
|
+
* stopped consumer skips the code after it in the enclosing generator;
|
|
162
|
+
* cleanup that must run either way goes in a `finally`. A run that fails
|
|
163
|
+
* while a stopped consumer waits (a legacy `finally` that throws) throws
|
|
164
|
+
* its error from `.return()` instead.
|
|
236
165
|
*/
|
|
237
|
-
|
|
166
|
+
stream<TSettled>(settled: PromiseLike<TSettled>): AsyncGenerator<T, TSettled, undefined>;
|
|
238
167
|
}
|
|
239
168
|
/**
|
|
240
|
-
*
|
|
241
|
-
*
|
|
242
|
-
*
|
|
243
|
-
*
|
|
169
|
+
* A backpressured hand-off between an actor and an async generator's
|
|
170
|
+
* consumer, for a loop whose public surface is an `AsyncGenerator`: the
|
|
171
|
+
* machine owns the loop head, each pass is an actor, and the events it
|
|
172
|
+
* yields still reach the consumer one pull at a time.
|
|
244
173
|
*
|
|
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`.
|
|
174
|
+
* One bridge serves one run.
|
|
251
175
|
*
|
|
252
176
|
* @example
|
|
253
|
-
* ```ts
|
|
254
|
-
*
|
|
255
|
-
*
|
|
177
|
+
* ```ts
|
|
178
|
+
* async function* carvedLoop(input: Input): AsyncGenerator<Event, Result> {
|
|
179
|
+
* const bridge = createGeneratorBridge<Event>();
|
|
180
|
+
* const pass = createAsyncLogic({
|
|
181
|
+
* run: async () => {
|
|
182
|
+
* const step = await bridge.forward(legacyPass(input));
|
|
183
|
+
* return step.closed ? { kind: "closed" } : step.value;
|
|
184
|
+
* },
|
|
185
|
+
* });
|
|
186
|
+
* const result = yield* bridge.stream(runAgent(loopMachine, { input, actors: { pass } }));
|
|
187
|
+
* if (result.status === "error") throw result.error;
|
|
188
|
+
* return toResult(result);
|
|
189
|
+
* }
|
|
256
190
|
* ```
|
|
257
191
|
*/
|
|
258
|
-
export declare function
|
|
192
|
+
export declare function createGeneratorBridge<T>(): GeneratorBridge<T>;
|
|
259
193
|
//#endregion
|
|
260
194
|
//#region src/wrap-workflow.d.ts
|
|
261
195
|
/** The effects a wrapped workflow calls: async functions, by name. */
|
|
@@ -337,6 +271,11 @@ interface WrappedWorkflowRunOptions<TEffects, TInput, TOutput> extends Pick<Agen
|
|
|
337
271
|
* result with `recorder.output`, so `recorder.recording` is a golden run.
|
|
338
272
|
*/
|
|
339
273
|
recorder?: Recorder;
|
|
274
|
+
/**
|
|
275
|
+
* `recorder.fn` options per effect: `serialize` for a result that is not
|
|
276
|
+
* JSON, `revive` to rebuild it in replay, `redact` for arguments.
|
|
277
|
+
*/
|
|
278
|
+
recordOptions?: { [K in keyof TEffects]?: RecordCallOptions; };
|
|
340
279
|
}
|
|
341
280
|
/** The result of {@link wrapWorkflow}. */
|
|
342
281
|
interface WrappedWorkflow<TInput, TOutput, TEffects> {
|
|
@@ -460,4 +399,4 @@ interface ProvideExecutorsOptions<TMachine extends AnyStateMachine = AnyStateMac
|
|
|
460
399
|
*/
|
|
461
400
|
export declare function provideExecutors<TMachine extends AnyStateMachine>(machine: TMachine, executors: AgentRequestExecutors, options?: ProvideExecutorsOptions<TMachine>): TMachine;
|
|
462
401
|
//#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
|
|
402
|
+
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 };
|