@statelyai/agent 2.0.0-alpha.34 → 2.0.0-alpha.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +124 -0
- package/dist/act-B9hLQls6.mjs +19 -0
- package/dist/act-CrX0JwWY.cjs +42 -0
- package/dist/ai-sdk.cjs +63 -7
- package/dist/ai-sdk.d.cts +13 -3
- package/dist/ai-sdk.d.mts +13 -3
- package/dist/ai-sdk.mjs +63 -7
- package/dist/{decision-BEsATcr1.cjs → decision-CMeuNZ1g.cjs} +262 -4
- package/dist/{decision-COkJNjOW.mjs → decision-m5hGmHpF.mjs} +239 -5
- package/dist/decision-object-B5zGSPFp.d.mts +15 -0
- package/dist/decision-object-DBcLWVvv.d.cts +15 -0
- package/dist/{run-agent-s5D32w99.cjs → effects-B23bFZEs.cjs} +948 -102
- package/dist/{run-agent-Ct_GZw_f.mjs → effects-CuOUNYtZ.mjs} +914 -104
- package/dist/{event-log-C7jeH0y8.mjs → event-log-DkVlk3Rh.mjs} +30 -15
- package/dist/{event-log-BWSSLUff.cjs → event-log-Dkc-yIYu.cjs} +41 -14
- package/dist/{event-log-store-BzXehP7R.d.cts → event-log-store-BBS8so8a.d.mts} +2 -2
- package/dist/{event-log-store-W49TCJXi.mjs → event-log-store-Brx9tOHt.mjs} +1 -1
- package/dist/{event-log-store-CleWpsp5.cjs → event-log-store-Cl-YWDnq.cjs} +1 -1
- package/dist/{event-log-store-CWjN6lmM.d.mts → event-log-store-bc4ICGcS.d.cts} +2 -2
- package/dist/index.cjs +660 -286
- package/dist/index.d.cts +168 -9
- package/dist/index.d.mts +168 -9
- package/dist/index.mjs +639 -271
- package/dist/internal-C3Lqu538.d.cts +43 -0
- package/dist/internal-DUcdhk-i.d.mts +43 -0
- package/dist/log.cjs +2 -2
- package/dist/log.d.cts +1 -1
- package/dist/log.d.mts +1 -1
- package/dist/log.mjs +2 -2
- package/dist/machines.cjs +457 -41
- package/dist/machines.d.cts +114 -43
- package/dist/machines.d.mts +114 -43
- package/dist/machines.mjs +457 -42
- package/dist/{model-source-DmhTMK39.cjs → model-source-B4WQ8Idp.cjs} +1 -1
- package/dist/{model-source-CK3F4YuU.mjs → model-source-kjGwqAV8.mjs} +1 -1
- package/dist/openai.cjs +149 -36
- package/dist/openai.d.cts +28 -10
- package/dist/openai.d.mts +28 -10
- package/dist/openai.mjs +149 -36
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-BGdx5913.d.mts → run-agent-BcQ-9NRT.d.cts} +91 -9
- package/dist/{run-agent-B1-Eqviq.d.cts → run-agent-C86drZtN.d.mts} +91 -9
- package/dist/{setup-agent-05uw4dPZ.mjs → setup-agent-BDmNr6PC.mjs} +9 -3
- package/dist/{setup-agent-BtfeFfF6.d.cts → setup-agent-BIKcbVXV.d.mts} +4 -4
- package/dist/{setup-agent-CXEBURdo.cjs → setup-agent-CmEToB8y.cjs} +9 -3
- package/dist/{setup-agent-C6nqzv_X.d.mts → setup-agent-jlo4vtaZ.d.cts} +4 -4
- package/dist/tanstack-ai.cjs +62 -4
- package/dist/tanstack-ai.d.cts +18 -6
- package/dist/tanstack-ai.d.mts +18 -6
- package/dist/tanstack-ai.mjs +62 -4
- package/dist/testing.cjs +536 -67
- package/dist/testing.d.cts +197 -180
- package/dist/testing.d.mts +197 -180
- package/dist/testing.mjs +532 -67
- package/dist/{text-logic-CV_4KGr6.d.cts → text-logic-BqxalgMr.d.mts} +87 -4
- package/dist/{text-logic-Ckh-rJFV.d.mts → text-logic-CSf9bqpP.d.cts} +87 -4
- package/dist/{types-Dp5_Ru4R.d.cts → types-DQUOOaZO.d.cts} +1 -1
- package/dist/{types-Dp5_Ru4R.d.mts → types-DQUOOaZO.d.mts} +1 -1
- package/dist/{usage-BDiJKyv9.d.cts → usage-DoP0Oi84.d.mts} +1 -1
- package/dist/{usage-DOoVUGVq.d.mts → usage-HtnrUsl9.d.cts} +1 -1
- package/dist/utils-7lSa4H-i.d.cts +403 -0
- package/dist/utils-CBbKw2fM.d.mts +403 -0
- package/dist/validate.cjs +44 -12
- package/dist/validate.d.cts +6 -6
- package/dist/validate.d.mts +6 -6
- package/dist/validate.mjs +44 -12
- package/dist/verify-Bink-Drw.cjs +2304 -0
- package/dist/{verify-BQpE8hUz.d.cts → verify-Buh8XSUr.d.mts} +208 -14
- package/dist/{verify-CqeuEmIk.d.mts → verify-CciG8UP-.d.cts} +208 -14
- package/dist/verify-Dpz1u5Pe.mjs +2251 -0
- package/dist/with-model-calls-B_WLmOSl.cjs +248 -0
- package/dist/with-model-calls-BkOwdroS.mjs +213 -0
- package/docs/act.md +102 -0
- package/docs/advanced.md +105 -0
- package/docs/any-stack.md +62 -0
- package/docs/choosing-a-run-mode.md +55 -0
- package/docs/debugging.md +29 -0
- package/docs/decisions.md +473 -0
- package/docs/environment-and-policy.md +188 -0
- package/docs/evals.md +509 -0
- package/docs/event-log.md +311 -0
- package/docs/from-a-loop.md +528 -0
- package/docs/generate-machines.md +110 -0
- package/docs/hosts.md +414 -0
- package/docs/human-in-the-loop.md +177 -0
- package/docs/index.md +48 -0
- package/docs/judgments.md +281 -0
- package/docs/langgraph-comparison.md +198 -0
- package/docs/machines-as-data.md +454 -0
- package/docs/machines-presets.md +198 -0
- package/docs/machines.md +497 -0
- package/docs/messages.md +67 -0
- package/docs/meta.json +52 -0
- package/docs/models-and-providers.md +268 -0
- package/docs/multi-agent.md +68 -0
- package/docs/observability.md +109 -0
- package/docs/patterns.md +31 -0
- package/docs/persistence.md +136 -0
- package/docs/quickstart.md +121 -0
- package/docs/roadmap.md +22 -0
- package/docs/scope.md +75 -0
- package/docs/statechart-policy-examples.md +69 -0
- package/docs/steps.md +54 -0
- package/docs/strangler-fig.md +323 -0
- package/docs/text-requests.md +250 -0
- package/docs/thinking-in-state-machines.md +324 -0
- package/docs/tools.md +249 -0
- package/docs/upgrading.md +37 -0
- package/docs/usage-and-budgets.md +516 -0
- package/docs/validate-and-repair.md +253 -0
- package/docs/verify.md +487 -0
- package/docs/xstate-4-and-5-apps.md +161 -0
- package/llms.txt +53 -0
- package/package.json +10 -3
- package/readme.md +30 -15
- package/skills/add-evals/SKILL.md +3 -1
- package/skills/add-traces/SKILL.md +6 -1
- package/skills/build-machine/SKILL.md +81 -0
- package/skills/generate-machine/SKILL.md +1 -1
- package/skills/graph-engineering/SKILL.md +13 -3
- package/skills/improve-machine/SKILL.md +21 -2
- package/skills/loop-to-machine/SKILL.md +147 -190
- package/skills/loop-to-machine/reference.md +260 -0
- package/dist/utils-BnXdWih3.d.mts +0 -108
- package/dist/utils-ebVpCYoF.d.cts +0 -108
- package/dist/verify-Bpahmr34.mjs +0 -1241
- package/dist/verify-DCLZa9R0.cjs +0 -1288
- package/dist/with-model-calls-BXYdBdcu.cjs +0 -45
- package/dist/with-model-calls-Bv4V4EHC.mjs +0 -34
package/dist/machines.d.cts
CHANGED
|
@@ -1,45 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* The machine type a preset factory returns: its context, event union, input
|
|
6
|
-
* and output are all concrete, so callers get typed run input and
|
|
7
|
-
* output instead of `AnyStateMachine`. The remaining slots (children, state
|
|
8
|
-
* value/tags/config, source maps) are left permissive — a preset builds its
|
|
9
|
-
* states dynamically, so there is no literal state schema to infer.
|
|
10
|
-
*
|
|
11
|
-
* @internal
|
|
12
|
-
*/
|
|
13
|
-
type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
|
|
14
|
-
/** One delegated unit of work, lowered to an inline text request. */
|
|
15
|
-
interface PresetRequestEntry {
|
|
16
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
17
|
-
description?: string;
|
|
18
|
-
/** System prompt for this entry's model call. */
|
|
19
|
-
instructions?: string;
|
|
20
|
-
/** Model ref (or `models` alias). Falls back to the factory's `model`. */
|
|
21
|
-
model?: string;
|
|
22
|
-
/** Structured output schema. Omitted means plain text. */
|
|
23
|
-
outputSchema?: StandardSchemaV1;
|
|
24
|
-
/** Tools the host runs inside this one request. */
|
|
25
|
-
tools?: AgentTools;
|
|
26
|
-
/** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
|
|
27
|
-
maxSteps?: number;
|
|
28
|
-
}
|
|
29
|
-
/** One delegated unit of work, lowered to an invoked child machine. */
|
|
30
|
-
interface PresetMachineEntry {
|
|
31
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
32
|
-
description?: string;
|
|
33
|
-
/** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
|
|
34
|
-
machine: AnyStateMachine;
|
|
35
|
-
/** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
|
|
36
|
-
input?: (args: {
|
|
37
|
-
prompt: string;
|
|
38
|
-
}) => unknown;
|
|
39
|
-
}
|
|
40
|
-
/** A route/branch/worker/agent entry: an inline request, or a child machine. */
|
|
41
|
-
type PresetEntry = PresetRequestEntry | PresetMachineEntry;
|
|
42
|
-
//#endregion
|
|
1
|
+
import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.cjs";
|
|
2
|
+
import { i as PresetRequestEntry, n as PresetMachine, r as PresetMachineEntry, t as PresetEntry } from "./internal-C3Lqu538.cjs";
|
|
3
|
+
import { ActorLogic } from "xstate";
|
|
43
4
|
//#region src/machines/tool-loop.d.ts
|
|
44
5
|
/** Config for {@link createToolLoopMachine}. */
|
|
45
6
|
interface CreateToolLoopMachineConfig {
|
|
@@ -461,4 +422,114 @@ export declare function transferEventType(agent: string): string;
|
|
|
461
422
|
*/
|
|
462
423
|
export declare function createHandoffMachine<const TAgents extends Record<string, PresetEntry>>(config: CreateHandoffMachineConfig<TAgents>): HandoffMachine<keyof TAgents & string>;
|
|
463
424
|
//#endregion
|
|
464
|
-
|
|
425
|
+
//#region src/machines/approval-batch.d.ts
|
|
426
|
+
/** One tool call a model proposed: its call id, tool name, and arguments. */
|
|
427
|
+
type ProposedCall = {
|
|
428
|
+
id: string;
|
|
429
|
+
name: string;
|
|
430
|
+
args: unknown;
|
|
431
|
+
};
|
|
432
|
+
/** What the approval policy decides for one call. */
|
|
433
|
+
type ApprovalDecision = "allow" | "ask" | "deny";
|
|
434
|
+
/** The input the policy and execute actors receive. */
|
|
435
|
+
type ApprovalCallInput = {
|
|
436
|
+
call: ProposedCall;
|
|
437
|
+
};
|
|
438
|
+
/** One call's outcome in {@link ApprovalBatchOutput}. */
|
|
439
|
+
type ApprovalCallResult = {
|
|
440
|
+
id: string;
|
|
441
|
+
status: "executed" | "rejected" | "failed" | "cancelled";
|
|
442
|
+
/** The execute actor's output, when `executed`. */
|
|
443
|
+
result?: unknown;
|
|
444
|
+
/** The policy or execute failure, when `failed`. */
|
|
445
|
+
error?: string;
|
|
446
|
+
/** The `REJECT` reason, or `"denied by policy"`, when `rejected`. */
|
|
447
|
+
reason?: string;
|
|
448
|
+
};
|
|
449
|
+
/** A standing approval granted with `APPROVE_ALWAYS`. The host persists it and feeds it to its policy. */
|
|
450
|
+
type ApproveAlwaysRule = {
|
|
451
|
+
name: string;
|
|
452
|
+
};
|
|
453
|
+
/** Config for {@link createApprovalBatchMachine}. */
|
|
454
|
+
interface CreateApprovalBatchMachineConfig {
|
|
455
|
+
/**
|
|
456
|
+
* Decides each call: `"allow"` runs it, `"ask"` waits for a person,
|
|
457
|
+
* `"deny"` rejects it. Receives `{ call }`. Default: every call is `"ask"`.
|
|
458
|
+
*/
|
|
459
|
+
policy?: ActorLogic<any, any, ApprovalCallInput, any, any>;
|
|
460
|
+
/** Runs one approved call. Receives `{ call }`; its output is the call's `result`. */
|
|
461
|
+
execute: ActorLogic<any, any, ApprovalCallInput, any, any>;
|
|
462
|
+
/**
|
|
463
|
+
* `"allReady"` (default): no call executes until every call has settled its
|
|
464
|
+
* approval. `"eachReady"`: each call executes as soon as it is approved.
|
|
465
|
+
*/
|
|
466
|
+
executeWhen?: "allReady" | "eachReady";
|
|
467
|
+
}
|
|
468
|
+
/** Context of a {@link createApprovalBatchMachine} machine. */
|
|
469
|
+
type ApprovalBatchContext = {
|
|
470
|
+
calls: ProposedCall[];
|
|
471
|
+
/** Calls waiting on a person, in arrival order. */
|
|
472
|
+
awaiting: ProposedCall[];
|
|
473
|
+
/** One payload choice per awaiting call and verb, read by `getInteraction`. */
|
|
474
|
+
choices: Array<{
|
|
475
|
+
label: string;
|
|
476
|
+
event: ApprovalBatchEvent;
|
|
477
|
+
}>;
|
|
478
|
+
/** Approved call ids held at the `allReady` barrier. */
|
|
479
|
+
ready: string[];
|
|
480
|
+
results: Record<string, ApprovalCallResult>;
|
|
481
|
+
approveAlways: ApproveAlwaysRule[];
|
|
482
|
+
};
|
|
483
|
+
/** Machine input of a {@link createApprovalBatchMachine} machine. */
|
|
484
|
+
type ApprovalBatchInput = {
|
|
485
|
+
calls: ProposedCall[];
|
|
486
|
+
};
|
|
487
|
+
/** Machine output: one result per input call, in input order, plus the `APPROVE_ALWAYS` rules. */
|
|
488
|
+
type ApprovalBatchOutput = {
|
|
489
|
+
results: ApprovalCallResult[];
|
|
490
|
+
approveAlways: ApproveAlwaysRule[];
|
|
491
|
+
};
|
|
492
|
+
/** The host events a {@link createApprovalBatchMachine} machine accepts, routed by `callId`. */
|
|
493
|
+
type ApprovalBatchEvent = {
|
|
494
|
+
type: "APPROVE";
|
|
495
|
+
callId: string;
|
|
496
|
+
} | {
|
|
497
|
+
type: "APPROVE_ALWAYS";
|
|
498
|
+
callId: string;
|
|
499
|
+
} | {
|
|
500
|
+
type: "REJECT";
|
|
501
|
+
callId: string;
|
|
502
|
+
reason?: string;
|
|
503
|
+
} | {
|
|
504
|
+
type: "CANCEL_ALL";
|
|
505
|
+
};
|
|
506
|
+
/** The machine {@link createApprovalBatchMachine} returns. */
|
|
507
|
+
type ApprovalBatchMachine = PresetMachine<ApprovalBatchContext, ApprovalBatchInput, ApprovalBatchOutput, ApprovalBatchEvent>;
|
|
508
|
+
/**
|
|
509
|
+
* One model turn's tool calls, each approved or rejected individually; only
|
|
510
|
+
* approved calls execute. One child actor per call:
|
|
511
|
+
*
|
|
512
|
+
* `checking` (policy) → `awaitingApproval` (person) → `approved` → `executing`
|
|
513
|
+
* → `executed` | `rejected` | `failed`.
|
|
514
|
+
*
|
|
515
|
+
* The parent routes `APPROVE` / `APPROVE_ALWAYS` / `REJECT` to the child by
|
|
516
|
+
* `callId`, holds approved calls at the `executeWhen` barrier, and collects
|
|
517
|
+
* outputs. `CANCEL_ALL` stops every unfinished child and ends the batch; those
|
|
518
|
+
* calls report `cancelled`, including one whose execute was in flight.
|
|
519
|
+
*
|
|
520
|
+
* States: `running` → `done` | `cancelled`.
|
|
521
|
+
*
|
|
522
|
+
* ```ts
|
|
523
|
+
* const machine = createApprovalBatchMachine({
|
|
524
|
+
* policy: createAsyncLogic({
|
|
525
|
+
* run: async ({ input }) => (input.call.name === "search" ? "allow" : "ask"),
|
|
526
|
+
* }),
|
|
527
|
+
* execute: createAsyncLogic({
|
|
528
|
+
* run: async ({ input }) => tools[input.call.name](input.call.args),
|
|
529
|
+
* }),
|
|
530
|
+
* });
|
|
531
|
+
* ```
|
|
532
|
+
*/
|
|
533
|
+
export declare function createApprovalBatchMachine(config: CreateApprovalBatchMachineConfig): ApprovalBatchMachine;
|
|
534
|
+
//#endregion
|
|
535
|
+
export type { ApprovalBatchContext, ApprovalBatchEvent, ApprovalBatchInput, ApprovalBatchMachine, ApprovalBatchOutput, ApprovalCallInput, ApprovalCallResult, ApprovalDecision, ApproveAlwaysRule, CreateApprovalBatchMachineConfig, CreateHandoffMachineConfig, CreateLoopMachineConfig, CreateParallelMachineConfig, CreateRouterMachineConfig, CreateSequentialMachineConfig, CreateSupervisorMachineConfig, CreateToolLoopMachineConfig, HandoffContext, HandoffEvent, HandoffInput, HandoffMachine, LoopContext, LoopInput, LoopMachine, LoopOutput, LoopState, ParallelContext, ParallelInput, ParallelMachine, ParallelOutput, PresetEntry, PresetMachine, PresetMachineEntry, PresetRequestEntry, ProposedCall, RouterContext, RouterEvent, RouterInput, RouterMachine, RouterOutput, SequentialContext, SequentialInput, SequentialMachine, SequentialOutput, SequentialPromptArgs, SequentialStep, SupervisorContext, SupervisorEvent, SupervisorInput, SupervisorMachine, SupervisorOutput, ToolLoopContext, ToolLoopInput, ToolLoopMachine, ToolLoopOutput };
|
package/dist/machines.d.mts
CHANGED
|
@@ -1,45 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import {
|
|
3
|
-
|
|
4
|
-
/**
|
|
5
|
-
* The machine type a preset factory returns: its context, event union, input
|
|
6
|
-
* and output are all concrete, so callers get typed run input and
|
|
7
|
-
* output instead of `AnyStateMachine`. The remaining slots (children, state
|
|
8
|
-
* value/tags/config, source maps) are left permissive — a preset builds its
|
|
9
|
-
* states dynamically, so there is no literal state schema to infer.
|
|
10
|
-
*
|
|
11
|
-
* @internal
|
|
12
|
-
*/
|
|
13
|
-
type PresetMachine<TContext extends MachineContext, TInput, TOutput, TEvent extends EventObject = EventObject> = StateMachine<TContext, TEvent, Record<string, AnyActorRef | undefined>, StateValue, string, TInput, TOutput, EventObject, MetaObject, StateSchema, any, any, any, any>;
|
|
14
|
-
/** One delegated unit of work, lowered to an inline text request. */
|
|
15
|
-
interface PresetRequestEntry {
|
|
16
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
17
|
-
description?: string;
|
|
18
|
-
/** System prompt for this entry's model call. */
|
|
19
|
-
instructions?: string;
|
|
20
|
-
/** Model ref (or `models` alias). Falls back to the factory's `model`. */
|
|
21
|
-
model?: string;
|
|
22
|
-
/** Structured output schema. Omitted means plain text. */
|
|
23
|
-
outputSchema?: StandardSchemaV1;
|
|
24
|
-
/** Tools the host runs inside this one request. */
|
|
25
|
-
tools?: AgentTools;
|
|
26
|
-
/** Bounds the host-side tool loop (lowered to the request's typed `maxSteps`). */
|
|
27
|
-
maxSteps?: number;
|
|
28
|
-
}
|
|
29
|
-
/** One delegated unit of work, lowered to an invoked child machine. */
|
|
30
|
-
interface PresetMachineEntry {
|
|
31
|
-
/** What this entry is for. Shown to the routing/supervising model. */
|
|
32
|
-
description?: string;
|
|
33
|
-
/** The child machine to invoke. Registered as an actor source, so the runtime binds its executors. */
|
|
34
|
-
machine: AnyStateMachine;
|
|
35
|
-
/** Builds the child's `input`. Defaults to `{ prompt }` (`{ message }` for handoff). */
|
|
36
|
-
input?: (args: {
|
|
37
|
-
prompt: string;
|
|
38
|
-
}) => unknown;
|
|
39
|
-
}
|
|
40
|
-
/** A route/branch/worker/agent entry: an inline request, or a child machine. */
|
|
41
|
-
type PresetEntry = PresetRequestEntry | PresetMachineEntry;
|
|
42
|
-
//#endregion
|
|
1
|
+
import { C as StandardSchemaV1, l as AgentTools } from "./types-DQUOOaZO.mjs";
|
|
2
|
+
import { i as PresetRequestEntry, n as PresetMachine, r as PresetMachineEntry, t as PresetEntry } from "./internal-DUcdhk-i.mjs";
|
|
3
|
+
import { ActorLogic } from "xstate";
|
|
43
4
|
//#region src/machines/tool-loop.d.ts
|
|
44
5
|
/** Config for {@link createToolLoopMachine}. */
|
|
45
6
|
interface CreateToolLoopMachineConfig {
|
|
@@ -461,4 +422,114 @@ export declare function transferEventType(agent: string): string;
|
|
|
461
422
|
*/
|
|
462
423
|
export declare function createHandoffMachine<const TAgents extends Record<string, PresetEntry>>(config: CreateHandoffMachineConfig<TAgents>): HandoffMachine<keyof TAgents & string>;
|
|
463
424
|
//#endregion
|
|
464
|
-
|
|
425
|
+
//#region src/machines/approval-batch.d.ts
|
|
426
|
+
/** One tool call a model proposed: its call id, tool name, and arguments. */
|
|
427
|
+
type ProposedCall = {
|
|
428
|
+
id: string;
|
|
429
|
+
name: string;
|
|
430
|
+
args: unknown;
|
|
431
|
+
};
|
|
432
|
+
/** What the approval policy decides for one call. */
|
|
433
|
+
type ApprovalDecision = "allow" | "ask" | "deny";
|
|
434
|
+
/** The input the policy and execute actors receive. */
|
|
435
|
+
type ApprovalCallInput = {
|
|
436
|
+
call: ProposedCall;
|
|
437
|
+
};
|
|
438
|
+
/** One call's outcome in {@link ApprovalBatchOutput}. */
|
|
439
|
+
type ApprovalCallResult = {
|
|
440
|
+
id: string;
|
|
441
|
+
status: "executed" | "rejected" | "failed" | "cancelled";
|
|
442
|
+
/** The execute actor's output, when `executed`. */
|
|
443
|
+
result?: unknown;
|
|
444
|
+
/** The policy or execute failure, when `failed`. */
|
|
445
|
+
error?: string;
|
|
446
|
+
/** The `REJECT` reason, or `"denied by policy"`, when `rejected`. */
|
|
447
|
+
reason?: string;
|
|
448
|
+
};
|
|
449
|
+
/** A standing approval granted with `APPROVE_ALWAYS`. The host persists it and feeds it to its policy. */
|
|
450
|
+
type ApproveAlwaysRule = {
|
|
451
|
+
name: string;
|
|
452
|
+
};
|
|
453
|
+
/** Config for {@link createApprovalBatchMachine}. */
|
|
454
|
+
interface CreateApprovalBatchMachineConfig {
|
|
455
|
+
/**
|
|
456
|
+
* Decides each call: `"allow"` runs it, `"ask"` waits for a person,
|
|
457
|
+
* `"deny"` rejects it. Receives `{ call }`. Default: every call is `"ask"`.
|
|
458
|
+
*/
|
|
459
|
+
policy?: ActorLogic<any, any, ApprovalCallInput, any, any>;
|
|
460
|
+
/** Runs one approved call. Receives `{ call }`; its output is the call's `result`. */
|
|
461
|
+
execute: ActorLogic<any, any, ApprovalCallInput, any, any>;
|
|
462
|
+
/**
|
|
463
|
+
* `"allReady"` (default): no call executes until every call has settled its
|
|
464
|
+
* approval. `"eachReady"`: each call executes as soon as it is approved.
|
|
465
|
+
*/
|
|
466
|
+
executeWhen?: "allReady" | "eachReady";
|
|
467
|
+
}
|
|
468
|
+
/** Context of a {@link createApprovalBatchMachine} machine. */
|
|
469
|
+
type ApprovalBatchContext = {
|
|
470
|
+
calls: ProposedCall[];
|
|
471
|
+
/** Calls waiting on a person, in arrival order. */
|
|
472
|
+
awaiting: ProposedCall[];
|
|
473
|
+
/** One payload choice per awaiting call and verb, read by `getInteraction`. */
|
|
474
|
+
choices: Array<{
|
|
475
|
+
label: string;
|
|
476
|
+
event: ApprovalBatchEvent;
|
|
477
|
+
}>;
|
|
478
|
+
/** Approved call ids held at the `allReady` barrier. */
|
|
479
|
+
ready: string[];
|
|
480
|
+
results: Record<string, ApprovalCallResult>;
|
|
481
|
+
approveAlways: ApproveAlwaysRule[];
|
|
482
|
+
};
|
|
483
|
+
/** Machine input of a {@link createApprovalBatchMachine} machine. */
|
|
484
|
+
type ApprovalBatchInput = {
|
|
485
|
+
calls: ProposedCall[];
|
|
486
|
+
};
|
|
487
|
+
/** Machine output: one result per input call, in input order, plus the `APPROVE_ALWAYS` rules. */
|
|
488
|
+
type ApprovalBatchOutput = {
|
|
489
|
+
results: ApprovalCallResult[];
|
|
490
|
+
approveAlways: ApproveAlwaysRule[];
|
|
491
|
+
};
|
|
492
|
+
/** The host events a {@link createApprovalBatchMachine} machine accepts, routed by `callId`. */
|
|
493
|
+
type ApprovalBatchEvent = {
|
|
494
|
+
type: "APPROVE";
|
|
495
|
+
callId: string;
|
|
496
|
+
} | {
|
|
497
|
+
type: "APPROVE_ALWAYS";
|
|
498
|
+
callId: string;
|
|
499
|
+
} | {
|
|
500
|
+
type: "REJECT";
|
|
501
|
+
callId: string;
|
|
502
|
+
reason?: string;
|
|
503
|
+
} | {
|
|
504
|
+
type: "CANCEL_ALL";
|
|
505
|
+
};
|
|
506
|
+
/** The machine {@link createApprovalBatchMachine} returns. */
|
|
507
|
+
type ApprovalBatchMachine = PresetMachine<ApprovalBatchContext, ApprovalBatchInput, ApprovalBatchOutput, ApprovalBatchEvent>;
|
|
508
|
+
/**
|
|
509
|
+
* One model turn's tool calls, each approved or rejected individually; only
|
|
510
|
+
* approved calls execute. One child actor per call:
|
|
511
|
+
*
|
|
512
|
+
* `checking` (policy) → `awaitingApproval` (person) → `approved` → `executing`
|
|
513
|
+
* → `executed` | `rejected` | `failed`.
|
|
514
|
+
*
|
|
515
|
+
* The parent routes `APPROVE` / `APPROVE_ALWAYS` / `REJECT` to the child by
|
|
516
|
+
* `callId`, holds approved calls at the `executeWhen` barrier, and collects
|
|
517
|
+
* outputs. `CANCEL_ALL` stops every unfinished child and ends the batch; those
|
|
518
|
+
* calls report `cancelled`, including one whose execute was in flight.
|
|
519
|
+
*
|
|
520
|
+
* States: `running` → `done` | `cancelled`.
|
|
521
|
+
*
|
|
522
|
+
* ```ts
|
|
523
|
+
* const machine = createApprovalBatchMachine({
|
|
524
|
+
* policy: createAsyncLogic({
|
|
525
|
+
* run: async ({ input }) => (input.call.name === "search" ? "allow" : "ask"),
|
|
526
|
+
* }),
|
|
527
|
+
* execute: createAsyncLogic({
|
|
528
|
+
* run: async ({ input }) => tools[input.call.name](input.call.args),
|
|
529
|
+
* }),
|
|
530
|
+
* });
|
|
531
|
+
* ```
|
|
532
|
+
*/
|
|
533
|
+
export declare function createApprovalBatchMachine(config: CreateApprovalBatchMachineConfig): ApprovalBatchMachine;
|
|
534
|
+
//#endregion
|
|
535
|
+
export type { ApprovalBatchContext, ApprovalBatchEvent, ApprovalBatchInput, ApprovalBatchMachine, ApprovalBatchOutput, ApprovalCallInput, ApprovalCallResult, ApprovalDecision, ApproveAlwaysRule, CreateApprovalBatchMachineConfig, CreateHandoffMachineConfig, CreateLoopMachineConfig, CreateParallelMachineConfig, CreateRouterMachineConfig, CreateSequentialMachineConfig, CreateSupervisorMachineConfig, CreateToolLoopMachineConfig, HandoffContext, HandoffEvent, HandoffInput, HandoffMachine, LoopContext, LoopInput, LoopMachine, LoopOutput, LoopState, ParallelContext, ParallelInput, ParallelMachine, ParallelOutput, PresetEntry, PresetMachine, PresetMachineEntry, PresetRequestEntry, ProposedCall, RouterContext, RouterEvent, RouterInput, RouterMachine, RouterOutput, SequentialContext, SequentialInput, SequentialMachine, SequentialOutput, SequentialPromptArgs, SequentialStep, SupervisorContext, SupervisorEvent, SupervisorInput, SupervisorMachine, SupervisorOutput, ToolLoopContext, ToolLoopInput, ToolLoopMachine, ToolLoopOutput };
|