@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.
Files changed (66) hide show
  1. package/dist/ai-sdk.cjs +4 -5
  2. package/dist/ai-sdk.d.cts +7 -4
  3. package/dist/ai-sdk.d.mts +7 -4
  4. package/dist/ai-sdk.mjs +1 -2
  5. package/dist/{events-JiVPYrct.mjs → decision-BezSD_YC.mjs} +327 -20
  6. package/dist/{events-CRQj3VtP.cjs → decision-dWGhBh0P.cjs} +401 -28
  7. package/dist/errors-BQRk9eiZ.d.cts +19 -0
  8. package/dist/errors-C9rxnWbX.d.mts +19 -0
  9. package/dist/errors-CeSXQx0v.mjs +23 -0
  10. package/dist/errors-DUBBzRLP.cjs +28 -0
  11. package/dist/event-log-store-CNT_7F0V.cjs +452 -0
  12. package/dist/event-log-store-CriMgX1D.d.mts +144 -0
  13. package/dist/event-log-store-D7pWtIhb.mjs +411 -0
  14. package/dist/event-log-store-Ruq18mGp.d.cts +144 -0
  15. package/dist/index.cjs +1050 -705
  16. package/dist/index.d.cts +538 -565
  17. package/dist/index.d.mts +538 -565
  18. package/dist/index.mjs +950 -644
  19. package/dist/machines.cjs +752 -0
  20. package/dist/machines.d.cts +372 -0
  21. package/dist/machines.d.mts +372 -0
  22. package/dist/machines.mjs +741 -0
  23. package/dist/otel.cjs +268 -0
  24. package/dist/otel.d.cts +67 -0
  25. package/dist/otel.d.mts +67 -0
  26. package/dist/otel.mjs +267 -0
  27. package/dist/run-agent-C3mFDGTf.d.mts +1111 -0
  28. package/dist/run-agent-DnvtcnTZ.d.cts +1111 -0
  29. package/dist/setup-agent-DAZZSjDS.mjs +1711 -0
  30. package/dist/setup-agent-DP95MFrI.cjs +1836 -0
  31. package/dist/sqlite.cjs +135 -0
  32. package/dist/sqlite.d.cts +57 -0
  33. package/dist/sqlite.d.mts +57 -0
  34. package/dist/sqlite.mjs +133 -0
  35. package/dist/{text-logic-CaKqgX4Y.d.mts → text-logic-BDxwQNsD.d.cts} +155 -72
  36. package/dist/{text-logic-Ckhr2kKC.d.cts → text-logic-TkKPw8Aq.d.mts} +155 -72
  37. package/dist/{types-qm00QF91.d.mts → types-QbEfCVny.d.cts} +1 -1
  38. package/dist/{types-C9QiMjre.d.cts → types-_FXoFBGO.d.mts} +1 -1
  39. package/package.json +47 -39
  40. package/readme.md +49 -12
  41. package/schemas/agent-workflow.json +40 -21
  42. package/skills/generate-machine/SKILL.md +267 -0
  43. package/dist/adapter.cjs +0 -15
  44. package/dist/adapter.d.cts +0 -4
  45. package/dist/adapter.d.mts +0 -4
  46. package/dist/adapter.mjs +0 -2
  47. package/dist/decision-C3k4ve51.mjs +0 -227
  48. package/dist/decision-D8wJrM8W.cjs +0 -286
  49. package/dist/openai-compat.cjs +0 -309
  50. package/dist/openai-compat.d.cts +0 -59
  51. package/dist/openai-compat.d.mts +0 -59
  52. package/dist/openai-compat.mjs +0 -308
  53. package/dist/steps-BALp1eZo.d.mts +0 -198
  54. package/dist/steps-CVe54GPP.cjs +0 -420
  55. package/dist/steps-CkyyyuHd.mjs +0 -379
  56. package/dist/steps-MjnQI4aB.d.cts +0 -198
  57. package/dist/steps.cjs +0 -12
  58. package/dist/steps.d.cts +0 -3
  59. package/dist/steps.d.mts +0 -3
  60. package/dist/steps.mjs +0 -3
  61. package/dist/utils-BYqT_Dyv.d.cts +0 -108
  62. package/dist/utils-Do5wIJrh.d.mts +0 -108
  63. package/dist/zod.cjs +0 -31
  64. package/dist/zod.d.cts +0 -30
  65. package/dist/zod.d.mts +0 -30
  66. package/dist/zod.mjs +0 -30
@@ -1,4 +1,5 @@
1
- import { C as StandardSchemaV1, b as InferOutput, f as AllowedEvents, m as ChosenEvent, o as AgentToolChoice, r as AgentMessage, u as AgentTools } from "./types-qm00QF91.mjs";
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
- actorSources?: Record<string, unknown>;
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 DecisionExhaustedError extends Error {
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 (usage, finish
311
- * reason, …) flow untouched to `onResult`'s `raw`.
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 DecisionExhaustedError} with the full attempts list.
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, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string> {
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
- schemas: {
494
- input: TInputSchema;
495
- output: TOutputSchema;
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 `actorSources:` and invoke by name, or
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 `actorSources:` and invoke it by name (equivalent to what
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, TOutputSchema extends StandardSchemaV1, TMetadata = Record<string, unknown>, TModel extends string = string>(config: TextLogicConfig<TInputSchema, TOutputSchema, TMetadata, TModel>, execute?: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
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
- * actorSources: {
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 (usage, toolCalls, finishReason, raw, …) are allowed
590
- * alongside `output` and preserved on the raw result. {@link normalizeGeneratorResult}
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
- [key: string]: unknown;
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
- [key: string]: unknown;
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 AgentTextRequest} to an `{ output }` envelope (see
636
- * {@link AgentRequestExecutorResult}), unwrapped by
637
- * {@link normalizeGeneratorResult}. The return type is widened to also admit the
638
- * raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
639
- * {@link AiSdkShapedStreamResult}) so `ai`'s own `generateText`/`streamText`
640
- * pass through without a cast; `normalizeGeneratorResult` checks for `{ output }`
641
- * first, then falls back to those shapes at runtime.
642
- */
643
- type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentTextRequest & {
644
- tools: AgentTools;
645
- }, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
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 { AgentDecisionInput as A, ResolveDecisionOptions as B, createTextLogic as C, parseOutput as D, parseModelRef as E, DecisionExhaustedError as F, AgentRequestOptions as G, resolveDecision as H, DecisionLogic as I, matchesEventPattern as J, AgentRequestSource as K, DecisionLogicConfig as L, AgentPlanInput as M, AgentPlanOutput as N, parseStructuredEnvelope as O, DecisionAttempt as P, PLAN_DONE_EVENT_TYPE as R, buildEnvelopeSchema as S, isStructuredOutputSchema as T, AgentEventDescriptor as U, renderDecisionAttempts as V, AgentEventToolNameResolver as W, parseAgentEvent as Y, TextLogicExecuteArgs as _, AgentRequestExecutorInfo as a, TextLogicOutput as b, AgentRequestMode as c, AiSdkShapedStreamResult as d, AiSdkShapedTextResult as f, TextLogicConfig as g, TextLogic as h, AgentRequestExecutor as i, AgentDecisionRequest as j, AgentDecisionExecutor as k, AgentTextRequest as l, StructuredOutputEnvelope as m, AgentModelRef as n, AgentRequestExecutorResult as o, BuiltinAgentActors as p, getAcceptedEvents as q, AgentOutputMode as r, AgentRequestExecutors as s, AgentModelMap as t, AgentUserInput as u, TextLogicExecutor as v, getAgentOutputMode as w, bindRequestExecutor as x, TextLogicInput as y, PlanLogic as z };
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 };