@statelyai/agent 2.0.0-alpha.24 → 2.0.0-alpha.25

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 (53) hide show
  1. package/dist/ai-sdk.cjs +30 -34
  2. package/dist/ai-sdk.d.cts +27 -31
  3. package/dist/ai-sdk.d.mts +27 -31
  4. package/dist/ai-sdk.mjs +27 -31
  5. package/dist/decision-CM9CYZ6t.cjs +519 -0
  6. package/dist/decision-DzSv1NpD.mjs +453 -0
  7. package/dist/event-log-store-Ba2fsc4E.mjs +576 -0
  8. package/dist/event-log-store-DQmImLYk.cjs +702 -0
  9. package/dist/event-log-store-DvOcs10J.d.cts +338 -0
  10. package/dist/event-log-store-DxyVgnas.d.mts +338 -0
  11. package/dist/index.cjs +429 -4272
  12. package/dist/index.d.cts +104 -1005
  13. package/dist/index.d.mts +104 -1005
  14. package/dist/index.mjs +389 -4202
  15. package/dist/log.cjs +392 -0
  16. package/dist/log.d.cts +32 -0
  17. package/dist/log.d.mts +32 -0
  18. package/dist/log.mjs +371 -0
  19. package/dist/machines.cjs +27 -16
  20. package/dist/machines.d.cts +1 -1
  21. package/dist/machines.d.mts +1 -1
  22. package/dist/machines.mjs +27 -16
  23. package/dist/openai.cjs +16 -15
  24. package/dist/openai.d.cts +9 -9
  25. package/dist/openai.d.mts +9 -9
  26. package/dist/openai.mjs +10 -9
  27. package/dist/otel.d.cts +1 -1
  28. package/dist/otel.d.mts +1 -1
  29. package/dist/{run-agent-Ck7Sa3Tb.d.mts → run-agent-BOfoJg5B.d.cts} +86 -387
  30. package/dist/{run-agent-DWqA8KiI.d.cts → run-agent-CG343kFs.d.mts} +86 -387
  31. package/dist/run-agent-Cb1-LS5P.cjs +1783 -0
  32. package/dist/run-agent-DvDQd4If.mjs +1669 -0
  33. package/dist/{setup-agent-CeO2fARv.mjs → setup-agent-CFW-jPI8.mjs} +9 -20
  34. package/dist/{setup-agent-Dl2VELLi.cjs → setup-agent-CPf7MxnG.cjs} +20 -37
  35. package/dist/testing.cjs +1222 -0
  36. package/dist/testing.d.cts +602 -0
  37. package/dist/testing.d.mts +602 -0
  38. package/dist/testing.mjs +1212 -0
  39. package/dist/{text-logic-DJBK3LbG.d.mts → text-logic-BFEOxyxv.d.cts} +71 -147
  40. package/dist/text-logic-Bl_ZRxDi.mjs +833 -0
  41. package/dist/text-logic-C8xyr6Ag.cjs +1091 -0
  42. package/dist/{text-logic-C7bSnH_B.d.cts → text-logic-hZSiRUo1.d.mts} +71 -147
  43. package/dist/{types-CjHk5OdH.d.cts → types-B1Qs2q3q.d.cts} +2 -1
  44. package/dist/{types-DWA6X9R-.d.mts → types-tA3SdczG.d.mts} +2 -1
  45. package/dist/usage-BdEjFuIi.mjs +5 -0
  46. package/dist/usage-efOQPdf_.cjs +10 -0
  47. package/dist/utils-C1p37X_c.d.mts +209 -0
  48. package/dist/utils-RalRn9sk.d.cts +209 -0
  49. package/package.json +24 -4
  50. package/readme.md +2 -2
  51. package/skills/generate-machine/SKILL.md +4 -6
  52. package/dist/decision-BBZ2jMO1.mjs +0 -1490
  53. package/dist/decision-Cv6SfNWl.cjs +0 -1856
@@ -1,4 +1,4 @@
1
- import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-DWA6X9R-.mjs";
1
+ import { _ as StandardSchemaV1, c as AllowedEvents, h as InferOutput, i as AgentToolChoice, n as AgentMessage, s as AgentTools, u as ChosenEvent } from "./types-B1Qs2q3q.cjs";
2
2
  import { AnyMachineSnapshot, AnyStateMachine, AsyncActorLogic, EventFromLogic, EventObject, MachineSnapshot } from "xstate";
3
3
 
4
4
  //#region src/errors.d.ts
@@ -21,7 +21,7 @@ declare class AgentError extends Error {
21
21
  /**
22
22
  * A model call ran out of output tokens before it produced anything usable.
23
23
  * Core never throws this: it is the adapter's signal that a `'length'` finish
24
- * reason left nothing to return — a structured request whose envelope never
24
+ * reason left nothing to return — a structured request whose JSON never
25
25
  * closed, say. A text request that WAS cut off still returns its text, with
26
26
  * `finishReason: 'length'`.
27
27
  *
@@ -68,11 +68,6 @@ declare class AgentInvalidEventPayloadError extends AgentError {
68
68
  }
69
69
  /** The invoke `src` of an {@link AgentRequest}/{@link AgentDecisionRequest} — a plain string, widened so literal `src` values still narrow in editor hints. */
70
70
  type AgentRequestSource = string & {};
71
- /** Customizes the tool name generated for a candidate event; see {@link AgentRequestOptions.eventToolName}. */
72
- type AgentEventToolNameResolver = (args: {
73
- eventType: string;
74
- defaultToolName: string;
75
- }) => string;
76
71
  /** 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. */
77
72
  interface AgentEventDescriptor {
78
73
  type: string;
@@ -91,8 +86,6 @@ interface AgentRequestOptions {
91
86
  events?: Record<string, StandardSchemaV1>;
92
87
  schemas?: AgentSchemas;
93
88
  actors?: Record<string, unknown>;
94
- /** Customize machine-event tool names. Defaults to send_event_<TYPE>. */
95
- eventToolName?: AgentEventToolNameResolver;
96
89
  }
97
90
  /** Recovers a machine's event union from its snapshot type, so {@link parseAgentEvent} returns the machine-typed event without a downstream cast. @internal */
98
91
  type EventFromSnapshot<TSnapshot> = TSnapshot extends MachineSnapshot<any, infer TEvent, any, any, any, any, any, any> ? TEvent : EventObject;
@@ -138,7 +131,7 @@ declare function parseAgentEvent<TSource extends AnyStateMachine | AnyMachineSna
138
131
  * any `allowedEvents` matching — a machine that handles `'@agent.usage'` still
139
132
  * never offers it to a model.
140
133
  */
141
- declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas" | "eventToolName"> & {
134
+ declare function getAcceptedEvents(snapshot: AnyMachineSnapshot, options?: Pick<AgentRequestOptions, "events" | "schemas"> & {
142
135
  eventTypes?: readonly string[];
143
136
  }): AgentEventDescriptor[];
144
137
  //#endregion
@@ -367,7 +360,7 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
367
360
  * `runId`, `requestId`); `onChunk` is never set for a decision.
368
361
  * The optional `reason` is carried through to
369
362
  * `onResult`/event-sourcing but never affects validation. Like text
370
- * executors' `{ output, ...extras }` envelope, any extra keys (finish reason,
363
+ * executors' `{ result, ...extras }`, any extra keys (finish reason,
371
364
  * …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
372
365
  * report this attempt's tokens there and `runAgent` folds them into the run's
373
366
  * aggregated {@link AgentUsage}.
@@ -429,7 +422,6 @@ interface ResolveDecisionOptions<TEvent extends ChosenEvent = ChosenEvent> {
429
422
  declare function resolveDecision<TEvent extends ChosenEvent = ChosenEvent>(request: AgentDecisionRequest, executors: Pick<Partial<AgentRequestExecutors>, "decide">, options?: ResolveDecisionOptions<TEvent>): Promise<TEvent>;
430
423
  //#endregion
431
424
  //#region src/text-logic.d.ts
432
- declare const USER_INPUT_ACTOR: "agent.userInput";
433
425
  declare const GENERATE_TEXT_ACTOR: "agent.generateText";
434
426
  declare const STREAM_TEXT_ACTOR: "agent.streamText";
435
427
  declare const DECIDE_ACTOR: "agent.decide";
@@ -443,21 +435,6 @@ type AgentModelMap = Record<string, unknown>;
443
435
  * adapter's models map / `resolveModel`) resolves them to a real model.
444
436
  */
445
437
  type AgentModelRef<TModels extends AgentModelMap = {}> = [keyof TModels] extends [never] ? string : keyof TModels & string;
446
- /**
447
- * Splits a portable `"provider/model-id"` model ref (the convention JSON
448
- * workflows and registry-less hosts use, e.g. `"openai/gpt-5.4-mini"`) into
449
- * its parts. A ref with no `/` has no provider — `modelId` is the whole ref.
450
- * The standard building block for a host's `resolveModel`:
451
- *
452
- * @example
453
- * ```ts
454
- * const resolveModel = (ref: string) => openai(parseModelRef(ref).modelId);
455
- * ```
456
- */
457
- declare function parseModelRef(modelRef: string): {
458
- provider: string | undefined;
459
- modelId: string;
460
- };
461
438
  /**
462
439
  * Portable, provider-agnostic input a text request passes to a host
463
440
  * executor (`generateText`/`streamText` on {@link AgentRequestExecutors}).
@@ -489,7 +466,7 @@ interface AgentTextRequest<TMetadata = Record<string, unknown>, TMessage = any>
489
466
  /**
490
467
  * Opt-in reasoning for a structured-output request: when `true`, adapters add
491
468
  * an optional string `reasoning` property (listed BEFORE `result`) to the
492
- * structured-output envelope schema, nudging the model to reason before
469
+ * provider output schema, nudging the model to reason before
493
470
  * committing to the result. The reasoning is surfaced on the executor's raw
494
471
  * result (never in machine context/output). Ignored for text-mode requests.
495
472
  *
@@ -583,15 +560,15 @@ declare function getCallFinishReason(raw: unknown): AgentFinishReason | undefine
583
560
  * Reads a settled call's per-call {@link AgentCallUsage} off a RAW executor
584
561
  * result's `usage` field, keeping only finite numbers — the same normalization
585
562
  * `runAgent` applies before it delivers `'@agent.usage'`. Returns `undefined`
586
- * when the result reports no usage at all. Works for our `{ output, usage }`
587
- * envelope, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
563
+ * when the result reports no usage at all. Works for our `{ result, usage }`
564
+ * shape, for a raw Vercel AI SDK result (its `LanguageModelUsage` carries
588
565
  * the same flat field names), and for any custom executor that follows the
589
566
  * shape.
590
567
  *
591
568
  * The seam for the step-loop path, where the host holds the raw result itself:
592
569
  *
593
570
  * ```ts
594
- * const { output, raw } = await executeAgentRequest(effect, executors);
571
+ * const { result, messages } = await executeAgentRequest(effect, executors);
595
572
  * const usage = getCallUsage(raw);
596
573
  * if (usage) append({ type: AGENT_USAGE_EVENT_TYPE, usage }); // journal + transition, like any event
597
574
  * append(effect.toDoneEvent(output));
@@ -601,21 +578,28 @@ declare function getCallFinishReason(raw: unknown): AgentFinishReason | undefine
601
578
  */
602
579
  declare function getCallUsage(raw: unknown): AgentCallUsage | undefined;
603
580
  /**
604
- * Inline input for the `agent.userInput` builtin actor — a human-input request
605
- * (CLI prompt, chat reply, …) that resolves to the `string` the human typed.
606
- * See {@link RunAgentOptions.userInput}. For structured input, parse/classify
607
- * the string in a follow-up state, or register a custom actor source; host
608
- * rendering hints (a form spec, say) belong in `metadata`.
581
+ * What a text request's invoke resolves to: the validated `result` (the
582
+ * request's `outputSchema` type, or a string) and the response `messages`
583
+ * the executor returned (empty when it returned none). Read it in `onDone`:
584
+ *
585
+ * ```ts
586
+ * onDone: ({ context, output }) => ({
587
+ * context: {
588
+ * draft: output.result,
589
+ * messages: [...context.messages, ...output.messages],
590
+ * },
591
+ * }),
592
+ * ```
609
593
  */
610
- interface AgentUserInput<TMetadata = Record<string, unknown>> {
611
- prompt?: string;
612
- metadata?: TMetadata;
594
+ interface AgentTextResult<TOutput = unknown, TMessage = AgentMessage> {
595
+ result: TOutput;
596
+ /** Framework-native response messages, exactly as the executor returned them. */
597
+ messages: TMessage[];
613
598
  }
614
- /** The four `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
599
+ /** The three `agent.*` builtin actor logics every setupAgent-built machine registers. @internal */
615
600
  type BuiltinAgentActors<TEvent extends string = string, TModel extends string = string> = {
616
- [GENERATE_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
617
- [STREAM_TEXT_ACTOR]: AsyncActorLogic<unknown, AgentTextRequest>;
618
- [USER_INPUT_ACTOR]: AsyncActorLogic<string, AgentUserInput>;
601
+ [GENERATE_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
602
+ [STREAM_TEXT_ACTOR]: AsyncActorLogic<AgentTextResult, AgentTextRequest>;
619
603
  [DECIDE_ACTOR]: AsyncActorLogic<ChosenEvent, AgentDecisionInput<TEvent, Record<string, unknown>, TModel>>;
620
604
  };
621
605
  /**
@@ -656,7 +640,7 @@ interface TextLogicConfig<TInputSchema extends StandardSchemaV1 = StandardSchema
656
640
  messages?: ResolveTextLogicValue<any[] | undefined, InferOutput<TInputSchema>>;
657
641
  tools?: ResolveTextLogicValue<AgentTools | undefined, InferOutput<TInputSchema>>;
658
642
  toolChoice?: ResolveTextLogicValue<AgentToolChoice | undefined, InferOutput<TInputSchema>>;
659
- /** Opt into the structured-output envelope's `reasoning` field (see {@link AgentTextRequest.includeReasoning}). */
643
+ /** Opt into the provider output's `reasoning` field (see {@link AgentTextRequest.includeReasoning}). */
660
644
  includeReasoning?: ResolveTextLogicValue<boolean | undefined, InferOutput<TInputSchema>>;
661
645
  temperature?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
662
646
  maxOutputTokens?: ResolveTextLogicValue<number | undefined, InferOutput<TInputSchema>>;
@@ -677,7 +661,7 @@ interface TextLogicExecuteArgs<TInput, TMetadata = Record<string, unknown>> {
677
661
  self: unknown;
678
662
  emit: (emitted: EventObject) => void;
679
663
  }
680
- /** Host implementation bound to a specific {@link TextLogic} via `withExecutor`/`createTextLogic`'s second argument — resolves one text request to an `{ output }` envelope typed from the logic's output schema (`{ output: T }`). Passthrough fields (usage, raw, …) are allowed alongside `output`. */
664
+ /** Host implementation bound to a specific {@link TextLogic} via `withExecutor`/`createTextLogic`'s second argument — resolves one text request to a `{ result }` typed from the logic's output schema (`{ result: T }`). Passthrough fields (messages, usage, raw, …) are allowed alongside `result`. */
681
665
  type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata = unknown> = (args: TextLogicExecuteArgs<InferOutput<TInputSchema>, TMetadata>) => PromiseLike<AgentRequestExecutorResult<InferOutput<TOutputSchema>>> | AgentRequestExecutorResult<InferOutput<TOutputSchema>>;
682
666
  /**
683
667
  * Actor logic for a text request: an async effect that resolves typed input
@@ -687,7 +671,7 @@ type TextLogicExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema exte
687
671
  * `agent.streamText` builtins and `setupAgent({ requests })` entries are
688
672
  * both `TextLogic` under the hood.
689
673
  */
690
- interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata = Record<string, unknown>> extends AsyncActorLogic<InferOutput<TOutputSchema>, InferOutput<TInputSchema>> {
674
+ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TOutputSchema extends StandardSchemaV1 = StandardSchemaV1, TMetadata = Record<string, unknown>> extends AsyncActorLogic<AgentTextResult<InferOutput<TOutputSchema>>, InferOutput<TInputSchema>> {
691
675
  readonly kind: "statelyai.textLogic";
692
676
  readonly mode: AgentRequestMode;
693
677
  readonly schemas: {
@@ -695,7 +679,8 @@ interface TextLogic<TInputSchema extends StandardSchemaV1 = StandardSchemaV1, TO
695
679
  readonly output: TOutputSchema;
696
680
  };
697
681
  request(input: InferOutput<TInputSchema>): AgentTextRequest<TMetadata>;
698
- execute(input: InferOutput<TInputSchema>, executors: AgentRequestExecutors): Promise<InferOutput<TOutputSchema>>;
682
+ /** Runs this request once against `executors`; resolves the same `{ result, messages }` the invoke's `onDone` would receive. */
683
+ execute(input: InferOutput<TInputSchema>, executors: AgentRequestExecutors): Promise<AgentTextResult<InferOutput<TOutputSchema>>>;
699
684
  withExecutor(execute: TextLogicExecutor<TInputSchema, TOutputSchema, TMetadata>): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
700
685
  }
701
686
  /**
@@ -724,7 +709,7 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1 = Standar
724
709
  * {@link AgentRequestExecutor} (the `generateText`/`streamText` shape hosts
725
710
  * implement). Encapsulates the `withExecutor` idiom child agents repeat:
726
711
  * default the request's `tools` to `{}`, forward the actor `signal`, call the
727
- * executor, and return its `{ output }` envelope. Use this to share ONE
712
+ * executor, and return its `{ result }`. Use this to share ONE
728
713
  * executor across a parent and its nested children.
729
714
  *
730
715
  * @example
@@ -738,11 +723,13 @@ declare function createTextLogic<TInputSchema extends StandardSchemaV1 = Standar
738
723
  */
739
724
  declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOutputSchema extends StandardSchemaV1, TMetadata>(logic: TextLogic<TInputSchema, TOutputSchema, TMetadata>, executor: AgentRequestExecutor, info?: Pick<AgentRequestExecutorInfo, "onChunk">): TextLogic<TInputSchema, TOutputSchema, TMetadata>;
740
725
  /**
741
- * The envelope an {@link AgentRequestExecutor} must return: `{ output }` where
742
- * `output` is the request's value (a text string or a structured object).
743
- * Passthrough fields (toolCalls, finishReason, raw, …) are allowed alongside
744
- * `output` and preserved on the raw result. {@link normalizeGeneratorResult}
745
- * unwraps `output`; a non-envelope return is a runtime error.
726
+ * What an {@link AgentRequestExecutor} returns: the same `{ result, messages }`
727
+ * shape the machine receives in the invoke's `onDone` (see
728
+ * {@link AgentTextResult}), with `messages` optional. `result` is the
729
+ * request's value (a text string or a structured object). Passthrough fields
730
+ * (toolCalls, finishReason, raw, …) are allowed alongside it and preserved on
731
+ * the raw result. {@link normalizeGeneratorResult} unwraps `result`; a return
732
+ * without it is a runtime error.
746
733
  *
747
734
  * `usage` is the one passthrough field core reads: report this call's tokens
748
735
  * there and `runAgent` folds them into the run's aggregated
@@ -750,7 +737,7 @@ declare function bindRequestExecutor<TInputSchema extends StandardSchemaV1, TOut
750
737
  * toward `modelCalls`.
751
738
  */
752
739
  type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
753
- output: TOutput; /** Framework-native response messages, preserved without normalization. */
740
+ result: TOutput; /** The provider's response messages for this call (the assistant turn, tool calls and results). */
754
741
  messages?: TMessage[]; /** This call's token usage, aggregated into the run result's {@link AgentUsage}. */
755
742
  usage?: AgentCallUsage; /** Why this call stopped, normalized (see {@link AgentFinishReason}). Surfaced on the `request.end` trace event. */
756
743
  finishReason?: AgentFinishReason;
@@ -798,84 +785,22 @@ interface AgentRequestExecutorInfo {
798
785
  callKey?: string;
799
786
  }
800
787
  /**
801
- * A raw Vercel AI SDK `generateText` result shape: resolves `{ text }` (a
802
- * string or a promise of one) instead of the `{ output }`
803
- * {@link AgentRequestExecutorResult} envelope. Admitted directly as an executor
804
- * return type so `ai`'s `generateText` passes to `runAgent`/executors without a
805
- * cast — {@link normalizeGeneratorResult} unwraps `text` at runtime (text-only;
806
- * structured output is best-effort JSON parsing against the request's
807
- * `outputSchema`). Extra fields (`content`, `usage`, …) are ignored.
808
- */
809
- type AiSdkShapedTextResult = {
810
- text: string | PromiseLike<string>;
811
- output?: unknown;
812
- usage?: unknown;
813
- reasoning?: unknown;
814
- finishReason?: unknown;
815
- toolCalls?: unknown;
816
- toolResults?: unknown;
817
- };
818
- /**
819
- * A raw Vercel AI SDK `streamText` result shape: exposes a `textStream` async
820
- * iterable of string chunks (and, optionally, a `text` promise for the final
821
- * text) instead of the `{ output }` {@link AgentRequestExecutorResult} envelope.
822
- * Admitted directly as an executor return type so `ai`'s `streamText` passes to
823
- * `runAgent`/executors without a cast — {@link normalizeGeneratorResult}
824
- * iterates `textStream`, forwarding chunks, then resolves the final text
825
- * (text-only; structured output is best-effort). Extra fields are ignored.
826
- */
827
- type AiSdkShapedStreamResult = {
828
- textStream: AsyncIterable<string>;
829
- text?: PromiseLike<string>;
830
- output?: unknown;
831
- usage?: unknown;
832
- reasoning?: unknown;
833
- finishReason?: unknown;
834
- toolCalls?: unknown;
835
- toolResults?: unknown;
788
+ * The lowered request as an {@link AgentRequestExecutor} receives it: the
789
+ * {@link AgentTextRequest} core built, with `name` resolved and the request's
790
+ * `tools` merged in. Exactly one of `prompt`/`messages` is set.
791
+ */
792
+ type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "name" | "tools"> & {
793
+ /** Semantic request identity; always resolved before an executor is called. */name: string;
794
+ tools: AgentTools;
836
795
  };
837
796
  /**
838
- * The lowered request as an {@link AgentRequestExecutor} receives it. At
839
- * runtime this is exactly the {@link AgentTextRequest} core built (plus the
840
- * merged `tools` map); the TYPE is deliberately shaped so the Vercel AI SDK's
841
- * own `generateText`/`streamText` are directly assignable as executors
842
- * (function parameters are contravariant, so this type must be assignable to
843
- * `ai`'s options type):
844
- *
845
- * - `prompt`/`messages` are mutually exclusive, matching `ai`'s `Prompt`
846
- * union (core always sets exactly one).
847
- * - `tools`, `toolChoice`, and `messages` are widened to `any` — their
848
- * framework-native shapes may be branded and would otherwise fail the
849
- * contravariant check.
850
- *
851
- * Hand-written executors that want the precise shapes can annotate their
852
- * parameter as `AgentTextRequest & { tools: AgentTools }` — that wider
853
- * parameter type keeps the executor assignable.
797
+ * Host implementation of one text call (`generateText` or `streamText`):
798
+ * resolves a lowered {@link AgentExecutorTextRequest} to a `{ result, messages? }`
799
+ * (see {@link AgentRequestExecutorResult}). Adapters such as
800
+ * `createAiSdkExecutors` and `createOpenAiExecutors` produce this shape; a
801
+ * hand-written executor is a plain async function returning it.
854
802
  */
855
- type AgentExecutorTextRequest<TMetadata = Record<string, unknown>> = Omit<AgentTextRequest<TMetadata>, "name" | "prompt" | "messages" | "tools" | "toolChoice"> & {
856
- /** Semantic request identity; always resolved before an executor is called. */name: string;
857
- tools: any;
858
- toolChoice?: any;
859
- } & ({
860
- prompt: string;
861
- messages?: undefined;
862
- } | {
863
- prompt?: undefined;
864
- messages: any[];
865
- });
866
- /**
867
- * Host implementation of one text call (`generateText` or `streamText`) —
868
- * resolves a lowered {@link AgentExecutorTextRequest} to an `{ output }`
869
- * envelope (see {@link AgentRequestExecutorResult}), unwrapped by
870
- * {@link normalizeGeneratorResult}. Both sides are shaped so `ai`'s own
871
- * `generateText`/`streamText` pass through without a cast: the request
872
- * parameter is assignable to `ai`'s options (see
873
- * {@link AgentExecutorTextRequest}), and the return type is widened to also
874
- * admit the raw Vercel AI SDK shapes ({@link AiSdkShapedTextResult} /
875
- * {@link AiSdkShapedStreamResult}) — `normalizeGeneratorResult` checks for
876
- * `{ output }` first, then falls back to those shapes at runtime.
877
- */
878
- type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => PromiseLike<TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult> | TResult | AiSdkShapedTextResult | AiSdkShapedStreamResult;
803
+ type AgentRequestExecutor<TResult extends AgentRequestExecutorResult = AgentRequestExecutorResult> = (request: AgentExecutorTextRequest, info?: AgentRequestExecutorInfo) => TResult | PromiseLike<TResult>;
879
804
  /**
880
805
  * The full set of host executors a machine's agent actors are resolved
881
806
  * with — passed to `runAgent`, `executeAgentRequest`, and
@@ -903,15 +828,15 @@ type AgentOutputMode = "structured" | "text";
903
828
  * as `'text'`.
904
829
  */
905
830
  declare function getAgentOutputMode(schema?: StandardSchemaV1): AgentOutputMode;
906
- /** The unwrapped shape a {@link buildEnvelopeSchema} validate returns: the inner
831
+ /** What a {@link providerOutputSchema} validate returns: the declared schema's
907
832
  * `result` value plus, when opted in and present, the model's `reasoning`. */
908
- interface StructuredOutputEnvelope {
833
+ interface ProviderStructuredOutput {
909
834
  result: unknown;
910
835
  reasoning?: string;
911
836
  }
912
837
  /**
913
- * Builds the uniform structured-output envelope schema every structured request
914
- * is sent to the provider as: a root object `{ result: <inner> }`, plus — when
838
+ * Builds the schema every structured request is sent to the provider as: a
839
+ * root object `{ result: <inner> }` wrapping the declared schema, plus — when
915
840
  * `options.reasoning` is `true` — an optional string `reasoning` property listed
916
841
  * BEFORE `result` (property order nudges the model to reason first). This is THE
917
842
  * wire contract for structured output: a root object is universally accepted as
@@ -919,23 +844,22 @@ interface StructuredOutputEnvelope {
919
844
  * reject.
920
845
  *
921
846
  * The returned {@link StandardSchemaV1} validates the `{ reasoning?, result }`
922
- * envelope (unwrapping `result` through the original schema, capturing a string
923
- * `reasoning` when present) and exposes the enveloped JSON Schema. Adapters read
924
- * `.result` off the provider output before the machine validates it — so this is
925
- * transparent: user-facing output types stay the declared (un-enveloped) schema,
926
- * and `reasoning` is surfaced only on the raw executor result, never in machine
927
- * context/output.
928
- */
929
- declare function buildEnvelopeSchema(inner: StandardSchemaV1, options?: {
847
+ * object (validating `result` through the original schema, capturing a string
848
+ * `reasoning` when present) and exposes the wrapped JSON Schema. An executor
849
+ * returns the parsed `{ result, reasoning? }` as-is: `result` is what the
850
+ * machine validates against the declared schema, and `reasoning` stays on the
851
+ * raw executor result, never in machine context/output.
852
+ */
853
+ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
930
854
  reasoning?: boolean;
931
- }): StandardSchemaV1<StructuredOutputEnvelope>;
855
+ }): StandardSchemaV1<ProviderStructuredOutput>;
932
856
  /**
933
- * Validates a raw provider value against the structured-output envelope for
857
+ * Validates a raw provider value against the provider output schema for
934
858
  * `request` and returns the unwrapped `{ result, reasoning? }` — the checked
935
- * replacement for `raw as StructuredOutputEnvelope` in hand-written hosts.
936
- * Pair with {@link buildEnvelopeSchema} (which produced the schema the
859
+ * replacement for `raw as ProviderStructuredOutput` in hand-written hosts.
860
+ * Pair with {@link providerOutputSchema} (which produced the schema the
937
861
  * provider was asked to satisfy).
938
862
  */
939
- declare function parseStructuredEnvelope(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): StructuredOutputEnvelope;
863
+ declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
940
864
  //#endregion
941
- export { getAcceptedEvents as $, parseOutput as A, DecisionLogicConfig as B, bindRequestExecutor as C, getCallFinishReason as D, getAgentOutputMode as E, AgentDecisionRequest as F, resolveDecision as G, createDecisionLogic as H, AgentExecutorDecisionRequest as I, AgentInvalidEventPayloadError as J, AgentEventDescriptor as K, CreateDecisionRequestOptions as L, AgentDecisionExecutor as M, AgentDecisionExhaustedError as N, getCallUsage as O, AgentDecisionInput as P, EventFromSnapshot as Q, DecisionAttempt as R, TextLogicExecutor as S, createTextLogic as T, createDecisionRequest as U, ResolveDecisionOptions as V, renderDecisionAttempts as W, AgentRequestSource as X, AgentRequestOptions as Y, AgentSchemas as Z, BuiltinAgentActors as _, AgentModelRef as a, TextLogicConfig as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, parseAgentEvent as et, AgentTextRequest as f, AiSdkShapedTextResult as g, AiSdkShapedStreamResult as h, AgentModelMap as i, parseStructuredEnvelope as j, parseModelRef as k, AgentRequestExecutorResult as l, AgentUserInput as m, AgentExecutorTextRequest as n, AgentTruncatedError as nt, AgentOutputMode as o, AgentUsage as p, AgentEventToolNameResolver as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentError as tt, AgentRequestExecutors as u, StructuredOutputEnvelope as v, buildEnvelopeSchema as w, TextLogicExecuteArgs as x, TextLogic as y, DecisionLogic as z };
865
+ export { AgentDecisionExhaustedError as A, createDecisionRequest as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, DecisionAttempt as F, AgentRequestOptions as G, resolveDecision as H, DecisionLogic as I, EventFromSnapshot as J, AgentRequestSource as K, DecisionLogicConfig as L, AgentDecisionRequest as M, AgentExecutorDecisionRequest as N, providerOutputSchema as O, CreateDecisionRequestOptions as P, AgentTruncatedError as Q, ResolveDecisionOptions as R, createTextLogic as S, getCallUsage as T, AgentEventDescriptor as U, renderDecisionAttempts as V, AgentInvalidEventPayloadError as W, parseAgentEvent as X, getAcceptedEvents as Y, AgentError as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTextRequest as f, ProviderStructuredOutput as g, BuiltinAgentActors as h, AgentModelMap as i, AgentDecisionInput as j, AgentDecisionExecutor as k, AgentRequestExecutorResult as l, AgentUsage as m, AgentExecutorTextRequest as n, AgentOutputMode as o, AgentTextResult as p, AgentSchemas as q, AgentFinishReason as r, AgentRequestExecutor as s, AgentCallUsage as t, AgentRequestExecutors as u, TextLogicConfig as v, getCallFinishReason as w, bindRequestExecutor as x, TextLogicExecuteArgs as y, createDecisionLogic as z };