@statelyai/agent 2.0.0-alpha.11 → 2.0.0-alpha.13
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/dist/ai-sdk.cjs +4 -5
- package/dist/ai-sdk.d.cts +7 -4
- package/dist/ai-sdk.d.mts +7 -4
- package/dist/ai-sdk.mjs +1 -2
- package/dist/{events-JiVPYrct.mjs → decision-BezSD_YC.mjs} +327 -20
- package/dist/{events-CRQj3VtP.cjs → decision-dWGhBh0P.cjs} +401 -28
- package/dist/errors-BQRk9eiZ.d.cts +19 -0
- package/dist/errors-C9rxnWbX.d.mts +19 -0
- package/dist/errors-CeSXQx0v.mjs +23 -0
- package/dist/errors-DUBBzRLP.cjs +28 -0
- package/dist/event-log-store-CNT_7F0V.cjs +452 -0
- package/dist/event-log-store-CriMgX1D.d.mts +144 -0
- package/dist/event-log-store-D7pWtIhb.mjs +411 -0
- package/dist/event-log-store-Ruq18mGp.d.cts +144 -0
- package/dist/index.cjs +1050 -705
- package/dist/index.d.cts +538 -565
- package/dist/index.d.mts +538 -565
- package/dist/index.mjs +950 -644
- package/dist/machines.cjs +752 -0
- package/dist/machines.d.cts +372 -0
- package/dist/machines.d.mts +372 -0
- package/dist/machines.mjs +741 -0
- package/dist/otel.cjs +268 -0
- package/dist/otel.d.cts +67 -0
- package/dist/otel.d.mts +67 -0
- package/dist/otel.mjs +267 -0
- package/dist/run-agent-C3mFDGTf.d.mts +1111 -0
- package/dist/run-agent-DnvtcnTZ.d.cts +1111 -0
- package/dist/setup-agent-DAZZSjDS.mjs +1711 -0
- package/dist/setup-agent-DP95MFrI.cjs +1836 -0
- package/dist/sqlite.cjs +135 -0
- package/dist/sqlite.d.cts +57 -0
- package/dist/sqlite.d.mts +57 -0
- package/dist/sqlite.mjs +133 -0
- package/dist/{text-logic-CaKqgX4Y.d.mts → text-logic-BDxwQNsD.d.cts} +155 -72
- package/dist/{text-logic-Ckhr2kKC.d.cts → text-logic-TkKPw8Aq.d.mts} +155 -72
- package/dist/{types-qm00QF91.d.mts → types-QbEfCVny.d.cts} +1 -1
- package/dist/{types-C9QiMjre.d.cts → types-_FXoFBGO.d.mts} +1 -1
- package/package.json +47 -39
- package/readme.md +49 -12
- package/schemas/agent-workflow.json +40 -21
- package/skills/generate-machine/SKILL.md +267 -0
- package/dist/adapter.cjs +0 -15
- package/dist/adapter.d.cts +0 -4
- package/dist/adapter.d.mts +0 -4
- package/dist/adapter.mjs +0 -2
- package/dist/decision-C3k4ve51.mjs +0 -227
- package/dist/decision-D8wJrM8W.cjs +0 -286
- package/dist/openai-compat.cjs +0 -309
- package/dist/openai-compat.d.cts +0 -59
- package/dist/openai-compat.d.mts +0 -59
- package/dist/openai-compat.mjs +0 -308
- package/dist/steps-BALp1eZo.d.mts +0 -198
- package/dist/steps-CVe54GPP.cjs +0 -420
- package/dist/steps-CkyyyuHd.mjs +0 -379
- package/dist/steps-MjnQI4aB.d.cts +0 -198
- package/dist/steps.cjs +0 -12
- package/dist/steps.d.cts +0 -3
- package/dist/steps.d.mts +0 -3
- package/dist/steps.mjs +0 -3
- package/dist/utils-BYqT_Dyv.d.cts +0 -108
- package/dist/utils-Do5wIJrh.d.mts +0 -108
- package/dist/zod.cjs +0 -31
- package/dist/zod.d.cts +0 -30
- package/dist/zod.d.mts +0 -30
- package/dist/zod.mjs +0 -30
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { _ as StandardSchemaV1, a as AgentToolChoice, c as AgentTools, d as ChosenEvent, h as InferOutput, l as AllowedEvents, n as AgentMessage } from "./types-QbEfCVny.cjs";
|
|
2
|
+
import { t as AgentError } from "./errors-BQRk9eiZ.cjs";
|
|
2
3
|
import { AnyMachineSnapshot, AsyncActorLogic, EventObject, LogicActorLogic, MachineSnapshot } from "xstate";
|
|
3
4
|
|
|
4
5
|
//#region src/events.d.ts
|
|
@@ -9,13 +10,6 @@ type AgentEventToolNameResolver = (args: {
|
|
|
9
10
|
eventType: string;
|
|
10
11
|
defaultToolName: string;
|
|
11
12
|
}) => string;
|
|
12
|
-
/**
|
|
13
|
-
* True when an event type matches an `allowedEvents` entry: an exact type,
|
|
14
|
-
* `'*'` (every event), or a `'prefix.*'` wildcard matching any deeper
|
|
15
|
-
* segment (`'todo.*'` matches `'todo.add'` and `'todo.list.clear'`, not
|
|
16
|
-
* `'todo'` itself — mirroring xstate's partial wildcard events).
|
|
17
|
-
*/
|
|
18
|
-
declare function matchesEventPattern(eventType: string, pattern: string): boolean;
|
|
19
13
|
/** One candidate event a decision (or {@link getAcceptedEvents} caller) may choose: its type, the synthetic tool name a model can call to pick it, and its payload schema if one is registered. */
|
|
20
14
|
interface AgentEventDescriptor {
|
|
21
15
|
type: string;
|
|
@@ -31,21 +25,10 @@ interface AgentRequestOptions {
|
|
|
31
25
|
snapshot?: AnyMachineSnapshot;
|
|
32
26
|
events?: Record<string, StandardSchemaV1>;
|
|
33
27
|
schemas?: AgentSchemas;
|
|
34
|
-
|
|
28
|
+
actors?: Record<string, unknown>;
|
|
35
29
|
/** Customize machine-event tool names. Defaults to send_event_<TYPE>. */
|
|
36
30
|
eventToolName?: AgentEventToolNameResolver;
|
|
37
31
|
}
|
|
38
|
-
/**
|
|
39
|
-
* Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
|
|
40
|
-
* a model can be offered (via `resolveDecision`/an adapter's tool-per-event
|
|
41
|
-
* mapping). **Filters by event TYPE only** — it does not evaluate guards, so
|
|
42
|
-
* a type-legal-but-guard-rejected event can still appear here. Guard
|
|
43
|
-
* legality is checked separately, at decision-resolution time, via
|
|
44
|
-
* `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
|
|
45
|
-
* {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
|
|
46
|
-
* declared `allowedEvents` set — entries may be exact types or wildcard
|
|
47
|
-
* patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
|
|
48
|
-
*/
|
|
49
32
|
/** Recovers a machine's event union from its snapshot type, so {@link parseAgentEvent} returns the machine-typed event without a downstream cast. @internal */
|
|
50
33
|
type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer TEvent, any, any, any, any, any, any> ? TEvent : EventObject;
|
|
51
34
|
/**
|
|
@@ -72,6 +55,22 @@ type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer
|
|
|
72
55
|
declare function parseAgentEvent<TSnapshot extends AnyMachineSnapshot>(snapshot: TSnapshot, event: {
|
|
73
56
|
type: string;
|
|
74
57
|
} & Record<string, unknown>, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName">): EventFromSnapshot<TSnapshot>;
|
|
58
|
+
/**
|
|
59
|
+
* Lists the events a snapshot can currently accept, as {@link AgentEventDescriptor}s
|
|
60
|
+
* a model can be offered (via `resolveDecision`/an adapter's tool-per-event
|
|
61
|
+
* mapping). **Filters by event TYPE only** — it does not evaluate guards, so
|
|
62
|
+
* a type-legal-but-guard-rejected event can still appear here. Guard
|
|
63
|
+
* legality is checked separately, at decision-resolution time, via
|
|
64
|
+
* `snapshot.can(event)` (the `canTake` option of {@link resolveDecision} /
|
|
65
|
+
* {@link ResolveDecisionOptions}). Pass `eventTypes` to further narrow to a
|
|
66
|
+
* declared `allowedEvents` set — entries may be exact types or wildcard
|
|
67
|
+
* patterns (`'*'`, `'todo.*'`; see {@link matchesEventPattern}).
|
|
68
|
+
*
|
|
69
|
+
* XState-internal (`xstate.*`) and library-reserved
|
|
70
|
+
* ({@link RESERVED_AGENT_EVENT_PREFIX}) event types are always excluded, before
|
|
71
|
+
* any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
|
|
72
|
+
* never offers it to a model.
|
|
73
|
+
*/
|
|
75
74
|
declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName"> & {
|
|
76
75
|
eventTypes?: readonly string[];
|
|
77
76
|
}): AgentEventDescriptor[];
|
|
@@ -209,21 +208,6 @@ interface DecisionLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSc
|
|
|
209
208
|
stopSequences?: ResolveTextLogicValue<string[] | undefined, InferOutput<TInputSchema>>;
|
|
210
209
|
metadata?: ResolveTextLogicValue<TMetadata | undefined, InferOutput<TInputSchema>>;
|
|
211
210
|
}
|
|
212
|
-
/**
|
|
213
|
-
* Actor logic for a decision: an async effect that resolves to exactly one
|
|
214
|
-
* currently-legal {@link ChosenEvent} (never a plain value). Under `runAgent`
|
|
215
|
-
* the chosen event is delivered to the invoking actor automatically — the
|
|
216
|
-
* transition it triggers usually exits the invoking state and ends the invoke.
|
|
217
|
-
* Built by {@link createDecisionLogic}. Register it under `actorSources:` to reuse/export/
|
|
218
|
-
* test it standalone; for a state-local, zero-config decision, use the
|
|
219
|
-
* `agent.decide` builtin invoke instead.
|
|
220
|
-
*/
|
|
221
|
-
interface DecisionLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata extends Record<string, unknown> = Record<string, unknown>> extends AsyncActorLogic<ChosenEvent, InferOutput<TInputSchema>> {
|
|
222
|
-
readonly kind: "statelyai.decisionLogic";
|
|
223
|
-
readonly maxRetries: number;
|
|
224
|
-
request(input: InferOutput<TInputSchema>): AgentDecisionRequest;
|
|
225
|
-
withExecutor(execute: AgentDecisionExecutor): DecisionLogic<TInputSchema, TMetadata>;
|
|
226
|
-
}
|
|
227
211
|
/**
|
|
228
212
|
* A decision request: resolves to exactly one currently-legal event. See
|
|
229
213
|
* `resolveDecision`.
|
|
@@ -258,6 +242,15 @@ interface AgentDecisionRequest {
|
|
|
258
242
|
* `info.signal`). Runtime-only — never serialized into a provider request.
|
|
259
243
|
*/
|
|
260
244
|
signal?: AbortSignal;
|
|
245
|
+
/**
|
|
246
|
+
* The `runAgent` run this decision belongs to (`run_<n>`, matching trace
|
|
247
|
+
* events), injected by runAgent like `signal` (symmetric with the text
|
|
248
|
+
* executors' `info.runId`). Runtime-only correlation for executor
|
|
249
|
+
* middleware; unset off the runAgent path. Per-attempt context is already
|
|
250
|
+
* on the request: `id` is the durable invoke id and `attempts.length` is
|
|
251
|
+
* the current attempt index.
|
|
252
|
+
*/
|
|
253
|
+
runId?: string;
|
|
261
254
|
}
|
|
262
255
|
/**
|
|
263
256
|
* A single failed decision attempt, recorded by {@link resolveDecision} and
|
|
@@ -280,8 +273,8 @@ interface DecisionAttempt {
|
|
|
280
273
|
* diagnostics; a machine typically routes this via the decision invoke's
|
|
281
274
|
* `onError`.
|
|
282
275
|
*/
|
|
283
|
-
declare class
|
|
284
|
-
attempts: DecisionAttempt[];
|
|
276
|
+
declare class AgentDecisionExhaustedError extends AgentError {
|
|
277
|
+
readonly attempts: DecisionAttempt[];
|
|
285
278
|
constructor(attempts: DecisionAttempt[]);
|
|
286
279
|
}
|
|
287
280
|
/**
|
|
@@ -307,12 +300,15 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
|
|
|
307
300
|
* adapter business; core only validates and retries the returned choice (see
|
|
308
301
|
* {@link resolveDecision}). The optional `reason` is carried through to
|
|
309
302
|
* `onResult`/event-sourcing but never affects validation. Like text
|
|
310
|
-
* executors' `{ output, ...extras }` envelope, any extra keys (
|
|
311
|
-
*
|
|
303
|
+
* executors' `{ output, ...extras }` envelope, any extra keys (finish reason,
|
|
304
|
+
* …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
|
|
305
|
+
* report this attempt's tokens there and `runAgent` folds them into the run's
|
|
306
|
+
* aggregated {@link AgentUsage}.
|
|
312
307
|
*/
|
|
313
308
|
type AgentDecisionExecutor = (request: AgentDecisionRequest) => PromiseLike<{
|
|
314
309
|
event: ChosenEvent;
|
|
315
|
-
reason?: string;
|
|
310
|
+
reason?: string; /** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
|
|
311
|
+
usage?: AgentCallUsage;
|
|
316
312
|
[key: string]: unknown;
|
|
317
313
|
}>;
|
|
318
314
|
/**
|
|
@@ -354,7 +350,7 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
|
|
|
354
350
|
* the next attempt via `request.attempts`, so an adapter can render "your
|
|
355
351
|
* last choice failed because X — try again" into the next model call; core
|
|
356
352
|
* never rewrites the request itself. Exhausting all attempts throws
|
|
357
|
-
* {@link
|
|
353
|
+
* {@link AgentDecisionExhaustedError} with the full attempts list.
|
|
358
354
|
*
|
|
359
355
|
* @example
|
|
360
356
|
* ```ts
|
|
@@ -450,6 +446,34 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>> {
|
|
|
450
446
|
*/
|
|
451
447
|
metadata?: TMetadata;
|
|
452
448
|
}
|
|
449
|
+
/**
|
|
450
|
+
* Aggregated model-call usage for ONE `runAgent` call — the run-level total
|
|
451
|
+
* attached to every settled {@link RunAgentResult} (and therefore to
|
|
452
|
+
* `generateResult`'s `{ output, snapshot, events, usage }`).
|
|
453
|
+
*
|
|
454
|
+
* - `modelCalls` counts every model/decision call this run made (each decision
|
|
455
|
+
* retry counts separately) — the same seam `maxModelCalls` budgets. Always a
|
|
456
|
+
* number, even when no executor reported tokens.
|
|
457
|
+
* - Token fields are OPTIONAL and are PARTIAL SUMS: each one sums only the
|
|
458
|
+
* calls that reported it, and stays `undefined` when NO call reported it.
|
|
459
|
+
* Executors that report nothing (custom hosts, test mocks) simply do not
|
|
460
|
+
* contribute — a run mixing reporting and non-reporting calls yields a sum
|
|
461
|
+
* over the reporting subset, not `undefined`.
|
|
462
|
+
* - Aggregation is per-run: a resumed run counts only ITS OWN calls, never the
|
|
463
|
+
* history behind `snapshot`/`events`. Add prior runs' totals yourself if you
|
|
464
|
+
* want a conversation-wide figure.
|
|
465
|
+
*/
|
|
466
|
+
interface AgentUsage {
|
|
467
|
+
inputTokens?: number;
|
|
468
|
+
outputTokens?: number;
|
|
469
|
+
totalTokens?: number;
|
|
470
|
+
reasoningTokens?: number;
|
|
471
|
+
cachedInputTokens?: number;
|
|
472
|
+
/** Model/decision calls made by this run (decision retries count separately). */
|
|
473
|
+
modelCalls: number;
|
|
474
|
+
}
|
|
475
|
+
/** One model call's reported usage — {@link AgentUsage} without the run-level `modelCalls` count. What an executor puts on its result's `usage` field. */
|
|
476
|
+
type AgentCallUsage = Omit<AgentUsage, "modelCalls">;
|
|
453
477
|
/**
|
|
454
478
|
* Inline input for the `agent.userInput` builtin actor — a human-input request
|
|
455
479
|
* (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
|
|
@@ -486,13 +510,19 @@ type ResolveTextLogicValue<TValue, TInput> = TValue | ((args: {
|
|
|
486
510
|
* that validate it. Each request-shaping field (`model`, `system`, `prompt`,
|
|
487
511
|
* …) is either a static value or a `({ input }) => value` resolver.
|
|
488
512
|
*/
|
|
489
|
-
interface TextLogicConfig<TInputSchema extends StandardSchemaV1
|
|
513
|
+
interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string> {
|
|
490
514
|
mode?: AgentRequestMode;
|
|
491
515
|
/** Stamped onto every lowered request as {@link AgentTextRequest.name}. `setupAgent({ requests })` sets this to the request's key. */
|
|
492
516
|
name?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
517
|
+
/**
|
|
518
|
+
* The request's input/output schemas. Both are optional:
|
|
519
|
+
* - `output` defaults to a string schema (a plain text request).
|
|
520
|
+
* - `input` defaults to a schema that accepts (and types) `undefined`, so
|
|
521
|
+
* the request takes no `input` at the invoke site.
|
|
522
|
+
*/
|
|
523
|
+
schemas?: {
|
|
524
|
+
input?: TInputSchema;
|
|
525
|
+
output?: TOutputSchema;
|
|
496
526
|
};
|
|
497
527
|
model: ResolveTextLogicValue<TModel, InferOutput<TInputSchema>>;
|
|
498
528
|
system?: ResolveTextLogicValue<string | undefined, InferOutput<TInputSchema>>;
|
|
@@ -524,7 +554,7 @@ type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema exte
|
|
|
524
554
|
/**
|
|
525
555
|
* Actor logic for a text request: an async effect that resolves typed input
|
|
526
556
|
* to typed, schema-validated output via a model call. Built by
|
|
527
|
-
* {@link createTextLogic}; register under `
|
|
557
|
+
* {@link createTextLogic}; register under `actors:` and invoke by name, or
|
|
528
558
|
* bind an executor later with `withExecutor`. The `agent.generateText`/
|
|
529
559
|
* `agent.streamText` builtins and `setupAgent({ requests })` entries are
|
|
530
560
|
* both `TextLogic` under the hood.
|
|
@@ -540,14 +570,10 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
|
|
|
540
570
|
execute(input: InferOutput<TInputSchema>, executors: AgentRequestExecutors): Promise<InferOutput<TOutputSchema>>;
|
|
541
571
|
withExecutor(execute: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
|
|
542
572
|
}
|
|
543
|
-
/** Extracts a {@link TextLogic}'s validated input type. */
|
|
544
|
-
type TextLogicInput<TLogic extends TextLogic> = TLogic extends TextLogic<infer TInputSchema, StandardSchemaV1, infer _TMetadata> ? InferOutput<TInputSchema> : never;
|
|
545
|
-
/** Extracts a {@link TextLogic}'s validated output type. */
|
|
546
|
-
type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<StandardSchemaV1, infer TOutputSchema, infer _TMetadata> ? InferOutput<TOutputSchema> : never;
|
|
547
573
|
/**
|
|
548
574
|
* Creates reusable, standalone {@link TextLogic}: an actor that, when run,
|
|
549
575
|
* resolves typed input to typed output via a model call. Register the
|
|
550
|
-
* result under `
|
|
576
|
+
* result under `actors:` and invoke it by name (equivalent to what
|
|
551
577
|
* `setupAgent({ requests })` builds internally for each request entry). Pass
|
|
552
578
|
* `execute` here, or bind it later with `.withExecutor(...)`, a runtime
|
|
553
579
|
* adapter's `machine.provide(...)`, or `runAgent`'s `generateText`/
|
|
@@ -564,7 +590,7 @@ type TextLogicOutput<TLogic extends TextLogic> = TLogic extends TextLogic<Standa
|
|
|
564
590
|
* });
|
|
565
591
|
* ```
|
|
566
592
|
*/
|
|
567
|
-
declare function createTextLogic<TInputSchema extends StandardSchemaV1
|
|
593
|
+
declare function createTextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1<undefined>, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1<string>, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
|
|
568
594
|
/**
|
|
569
595
|
* Binds a child machine's {@link TextLogic} to a raw
|
|
570
596
|
* {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
|
|
@@ -576,7 +602,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1, TOutputS
|
|
|
576
602
|
* @example
|
|
577
603
|
* ```ts
|
|
578
604
|
* childMachine.provide({
|
|
579
|
-
*
|
|
605
|
+
* actors: {
|
|
580
606
|
* researchTopic: bindRequestExecutor(setup.requests.researchTopic, generateText),
|
|
581
607
|
* },
|
|
582
608
|
* });
|
|
@@ -586,12 +612,18 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
|
|
|
586
612
|
/**
|
|
587
613
|
* The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
|
|
588
614
|
* `output` is the request's value (a text string or a structured object).
|
|
589
|
-
* Passthrough fields (
|
|
590
|
-
*
|
|
615
|
+
* Passthrough fields (toolCalls, finishReason, raw, …) are allowed alongside
|
|
616
|
+
* `output` and preserved on the raw result. {@link normalizeGeneratorResult}
|
|
591
617
|
* unwraps `output`; a non-envelope return is a runtime error.
|
|
618
|
+
*
|
|
619
|
+
* `usage` is the one passthrough field core reads: report this call's tokens
|
|
620
|
+
* there and `runAgent` folds them into the run's aggregated
|
|
621
|
+
* {@link AgentUsage}. Optional — an executor that reports nothing still counts
|
|
622
|
+
* toward `modelCalls`.
|
|
592
623
|
*/
|
|
593
624
|
type AgentRequestExecutorResult<TOutput = unknown> = {
|
|
594
|
-
output: TOutput;
|
|
625
|
+
output: TOutput; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
|
|
626
|
+
usage?: AgentCallUsage;
|
|
595
627
|
[key: string]: unknown;
|
|
596
628
|
};
|
|
597
629
|
/**
|
|
@@ -602,6 +634,20 @@ type AgentRequestExecutorResult<TOutput = unknown> = {
|
|
|
602
634
|
interface AgentRequestExecutorInfo {
|
|
603
635
|
onChunk?: (chunk: string) => void;
|
|
604
636
|
signal?: AbortSignal;
|
|
637
|
+
/**
|
|
638
|
+
* The `runAgent` run this call belongs to (`run_<n>`, matching trace
|
|
639
|
+
* events). Undefined off the runAgent path (bare `provideExecutors` /
|
|
640
|
+
* direct `TextLogic.execute`). Lets executor middleware (caching, rate
|
|
641
|
+
* limits, span parenting) correlate calls without side channels.
|
|
642
|
+
*/
|
|
643
|
+
runId?: string;
|
|
644
|
+
/**
|
|
645
|
+
* The durable invoke id of the request making this call (e.g.
|
|
646
|
+
* `'0.(machine).asking'`) — stable across resume/replay, and it encodes the
|
|
647
|
+
* invoking state, so per-state middleware can key on it. Undefined when the
|
|
648
|
+
* call has no invoking actor.
|
|
649
|
+
*/
|
|
650
|
+
requestId?: string;
|
|
605
651
|
}
|
|
606
652
|
/**
|
|
607
653
|
* A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
|
|
@@ -614,7 +660,12 @@ interface AgentRequestExecutorInfo {
|
|
|
614
660
|
*/
|
|
615
661
|
type AiSdkShapedTextResult = {
|
|
616
662
|
text: string | PromiseLike<string>;
|
|
617
|
-
|
|
663
|
+
output?: unknown;
|
|
664
|
+
usage?: unknown;
|
|
665
|
+
reasoning?: unknown;
|
|
666
|
+
finishReason?: unknown;
|
|
667
|
+
toolCalls?: unknown;
|
|
668
|
+
toolResults?: unknown;
|
|
618
669
|
};
|
|
619
670
|
/**
|
|
620
671
|
* A raw Vercel AI SDK `streamText` result shape: exposes a `textStream` async
|
|
@@ -628,21 +679,55 @@ type AiSdkShapedTextResult = {
|
|
|
628
679
|
type AiSdkShapedStreamResult = {
|
|
629
680
|
textStream: AsyncIterable<string>;
|
|
630
681
|
text?: PromiseLike<string>;
|
|
631
|
-
|
|
682
|
+
output?: unknown;
|
|
683
|
+
usage?: unknown;
|
|
684
|
+
reasoning?: unknown;
|
|
685
|
+
finishReason?: unknown;
|
|
686
|
+
toolCalls?: unknown;
|
|
687
|
+
toolResults?: unknown;
|
|
632
688
|
};
|
|
689
|
+
/**
|
|
690
|
+
* The lowered request as an {@link AgentRequestExecutor} receives it. At
|
|
691
|
+
* runtime this is exactly the {@link AgentTextRequest} core built (plus the
|
|
692
|
+
* merged `tools` map); the TYPE is deliberately shaped so the Vercel AI SDK's
|
|
693
|
+
* own `generateText`/`streamText` are directly assignable as executors
|
|
694
|
+
* (function parameters are contravariant, so this type must be assignable to
|
|
695
|
+
* `ai`'s options type):
|
|
696
|
+
*
|
|
697
|
+
* - `prompt`/`messages` are mutually exclusive, matching `ai`'s `Prompt`
|
|
698
|
+
* union (core always sets exactly one).
|
|
699
|
+
* - `tools`, `toolChoice`, and `messages` are widened to `any` — their
|
|
700
|
+
* portable shapes ({@link AgentTools}, {@link AgentToolChoice},
|
|
701
|
+
* {@link AgentMessage}) are structural supersets of `ai`'s branded types
|
|
702
|
+
* and would otherwise fail the contravariant check.
|
|
703
|
+
*
|
|
704
|
+
* Hand-written executors that want the precise shapes can annotate their
|
|
705
|
+
* parameter as `AgentTextRequest & { tools: AgentTools }` — that wider
|
|
706
|
+
* parameter type keeps the executor assignable.
|
|
707
|
+
*/
|
|
708
|
+
type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "prompt" | "messages" | "tools" | "toolChoice"> & {
|
|
709
|
+
tools: any;
|
|
710
|
+
toolChoice?: any;
|
|
711
|
+
} & ({
|
|
712
|
+
prompt: string;
|
|
713
|
+
messages?: undefined;
|
|
714
|
+
} | {
|
|
715
|
+
prompt?: undefined;
|
|
716
|
+
messages: any[];
|
|
717
|
+
});
|
|
633
718
|
/**
|
|
634
719
|
* Host implementation of one text call (`generateText` or `streamText`) —
|
|
635
|
-
* resolves a lowered {@link
|
|
636
|
-
* {@link AgentRequestExecutorResult}), unwrapped by
|
|
637
|
-
* {@link normalizeGeneratorResult}.
|
|
638
|
-
*
|
|
639
|
-
*
|
|
640
|
-
*
|
|
641
|
-
*
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
720
|
+
* resolves a lowered {@link AgentExecutorTextRequest} to an `{ output }`
|
|
721
|
+
* envelope (see {@link AgentRequestExecutorResult}), unwrapped by
|
|
722
|
+
* {@link normalizeGeneratorResult}. Both sides are shaped so `ai`'s own
|
|
723
|
+
* `generateText`/`streamText` pass through without a cast: the request
|
|
724
|
+
* parameter is assignable to `ai`'s options (see
|
|
725
|
+
* {@link AgentExecutorTextRequest}), and the return type is widened to also
|
|
726
|
+
* admit the raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
|
|
727
|
+
* {@link AiSdkShapedStreamResult}) — `normalizeGeneratorResult` checks for
|
|
728
|
+
* `{ output }` first, then falls back to those shapes at runtime.
|
|
729
|
+
*/
|
|
730
|
+
type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
|
|
646
731
|
/**
|
|
647
732
|
* The full set of host executors a machine's agent actors are resolved
|
|
648
733
|
* with — passed to `runAgent`, `executeAgentRequest`, and
|
|
@@ -670,8 +755,6 @@ type AgentOutputMode = "structured" | "text";
|
|
|
670
755
|
* as `'text'`.
|
|
671
756
|
*/
|
|
672
757
|
declare function getAgentOutputMode(schema?: StandardSchemaV1): AgentOutputMode;
|
|
673
|
-
/** True when {@link getAgentOutputMode} classifies `schema` as `'structured'`. */
|
|
674
|
-
declare function isStructuredOutputSchema(schema?: StandardSchemaV1): boolean;
|
|
675
758
|
/** The unwrapped shape a {@link buildEnvelopeSchema} validate returns: the inner
|
|
676
759
|
* `result` value plus, when opted in and present, the model's `reasoning`. */
|
|
677
760
|
interface StructuredOutputEnvelope {
|
|
@@ -707,4 +790,4 @@ declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
|
|
|
707
790
|
*/
|
|
708
791
|
declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "reasoning">, value: unknown): StructuredOutputEnvelope;
|
|
709
792
|
//#endregion
|
|
710
|
-
export {
|
|
793
|
+
export { AgentDecisionExhaustedError as A, renderDecisionAttempts as B, buildEnvelopeSchema as C, parseOutput as D, parseModelRef as E, DecisionAttempt as F, AgentRequestSource as G, AgentEventDescriptor as H, DecisionLogicConfig as I, getAcceptedEvents as K, PLAN_DONE_EVENT_TYPE as L, AgentDecisionRequest as M, AgentPlanInput as N, parseStructuredEnvelope as O, AgentPlanOutput as P, PlanLogic as R, bindRequestExecutor as S, getAgentOutputMode as T, AgentEventToolNameResolver as U, resolveDecision as V, AgentRequestOptions as W, StructuredOutputEnvelope as _, AgentOutputMode as a, TextLogicExecuteArgs as b, AgentRequestExecutorResult as c, AgentTextRequest as d, AgentUsage as f, BuiltinAgentActors as g, AiSdkShapedTextResult as h, AgentModelRef as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutors as l, AiSdkShapedStreamResult as m, AgentExecutorTextRequest as n, AgentRequestExecutor as o, AgentUserInput as p, parseAgentEvent as q, AgentModelMap as r, AgentRequestExecutorInfo as s, AgentCallUsage as t, AgentRequestMode as u, TextLogic as v, createTextLogic as w, TextLogicExecutor as x, TextLogicConfig as y, ResolveDecisionOptions as z };
|