@statelyai/agent 2.0.0-alpha.23 → 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.
- package/dist/ai-sdk.cjs +30 -34
- package/dist/ai-sdk.d.cts +27 -31
- package/dist/ai-sdk.d.mts +27 -31
- package/dist/ai-sdk.mjs +27 -31
- package/dist/decision-CM9CYZ6t.cjs +519 -0
- package/dist/decision-DzSv1NpD.mjs +453 -0
- package/dist/event-log-store-Ba2fsc4E.mjs +576 -0
- package/dist/event-log-store-DQmImLYk.cjs +702 -0
- package/dist/event-log-store-DvOcs10J.d.cts +338 -0
- package/dist/event-log-store-DxyVgnas.d.mts +338 -0
- package/dist/index.cjs +429 -4272
- package/dist/index.d.cts +104 -1005
- package/dist/index.d.mts +104 -1005
- package/dist/index.mjs +389 -4202
- package/dist/log.cjs +392 -0
- package/dist/log.d.cts +32 -0
- package/dist/log.d.mts +32 -0
- package/dist/log.mjs +371 -0
- package/dist/machines.cjs +27 -16
- package/dist/machines.d.cts +1 -1
- package/dist/machines.d.mts +1 -1
- package/dist/machines.mjs +27 -16
- package/dist/openai.cjs +16 -15
- package/dist/openai.d.cts +9 -9
- package/dist/openai.d.mts +9 -9
- package/dist/openai.mjs +10 -9
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-Ck7Sa3Tb.d.mts → run-agent-BOfoJg5B.d.cts} +86 -387
- package/dist/{run-agent-DWqA8KiI.d.cts → run-agent-CG343kFs.d.mts} +86 -387
- package/dist/run-agent-Cb1-LS5P.cjs +1783 -0
- package/dist/run-agent-DvDQd4If.mjs +1669 -0
- package/dist/{setup-agent-CeO2fARv.mjs → setup-agent-CFW-jPI8.mjs} +9 -20
- package/dist/{setup-agent-Dl2VELLi.cjs → setup-agent-CPf7MxnG.cjs} +20 -37
- package/dist/testing.cjs +1222 -0
- package/dist/testing.d.cts +602 -0
- package/dist/testing.d.mts +602 -0
- package/dist/testing.mjs +1212 -0
- package/dist/{text-logic-DJBK3LbG.d.mts → text-logic-BFEOxyxv.d.cts} +71 -147
- package/dist/text-logic-Bl_ZRxDi.mjs +833 -0
- package/dist/text-logic-C8xyr6Ag.cjs +1091 -0
- package/dist/{text-logic-C7bSnH_B.d.cts → text-logic-hZSiRUo1.d.mts} +71 -147
- package/dist/{types-CjHk5OdH.d.cts → types-B1Qs2q3q.d.cts} +2 -1
- package/dist/{types-DWA6X9R-.d.mts → types-tA3SdczG.d.mts} +2 -1
- package/dist/usage-BdEjFuIi.mjs +5 -0
- package/dist/usage-efOQPdf_.cjs +10 -0
- package/dist/utils-C1p37X_c.d.mts +209 -0
- package/dist/utils-RalRn9sk.d.cts +209 -0
- package/package.json +24 -4
- package/readme.md +2 -2
- package/skills/generate-machine/SKILL.md +4 -6
- package/dist/decision-BBZ2jMO1.mjs +0 -1490
- 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-
|
|
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
|
|
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"
|
|
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' `{
|
|
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
|
-
*
|
|
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 `{
|
|
587
|
-
*
|
|
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 {
|
|
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
|
-
*
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
*
|
|
608
|
-
*
|
|
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
|
|
611
|
-
|
|
612
|
-
|
|
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
|
|
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<
|
|
617
|
-
[STREAM_TEXT_ACTOR]: AsyncActorLogic<
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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 `{
|
|
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
|
-
*
|
|
742
|
-
*
|
|
743
|
-
*
|
|
744
|
-
*
|
|
745
|
-
*
|
|
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
|
-
|
|
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
|
-
*
|
|
802
|
-
*
|
|
803
|
-
*
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
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
|
-
*
|
|
839
|
-
*
|
|
840
|
-
*
|
|
841
|
-
*
|
|
842
|
-
*
|
|
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
|
|
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
|
-
/**
|
|
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
|
|
833
|
+
interface ProviderStructuredOutput {
|
|
909
834
|
result: unknown;
|
|
910
835
|
reasoning?: string;
|
|
911
836
|
}
|
|
912
837
|
/**
|
|
913
|
-
* Builds the
|
|
914
|
-
*
|
|
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
|
-
*
|
|
923
|
-
* `reasoning` when present) and exposes the
|
|
924
|
-
*
|
|
925
|
-
*
|
|
926
|
-
*
|
|
927
|
-
|
|
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<
|
|
855
|
+
}): StandardSchemaV1<ProviderStructuredOutput>;
|
|
932
856
|
/**
|
|
933
|
-
* Validates a raw provider value against the
|
|
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
|
|
936
|
-
* Pair with {@link
|
|
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
|
|
863
|
+
declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
|
|
940
864
|
//#endregion
|
|
941
|
-
export {
|
|
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 };
|