@statelyai/agent 2.0.0-alpha.33 → 2.0.0-alpha.34
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 +32 -0
- package/dist/ai-sdk.cjs +114 -63
- package/dist/ai-sdk.d.cts +11 -2
- package/dist/ai-sdk.d.mts +11 -2
- package/dist/ai-sdk.mjs +115 -64
- package/dist/{decision-BPdEaxPf.cjs → decision-BEsATcr1.cjs} +18 -2
- package/dist/{decision-CV7WiV5C.mjs → decision-COkJNjOW.mjs} +18 -2
- package/dist/{event-log-CKWeC7H-.cjs → event-log-BWSSLUff.cjs} +139 -10
- package/dist/{event-log-DAqsalT1.mjs → event-log-C7jeH0y8.mjs} +123 -12
- package/dist/{event-log-store-C2NjVlWU.d.mts → event-log-store-BzXehP7R.d.cts} +28 -3
- package/dist/{event-log-store-s73r1Hxf.d.cts → event-log-store-CWjN6lmM.d.mts} +28 -3
- package/dist/{event-log-store-DKyE7JKr.cjs → event-log-store-CleWpsp5.cjs} +1 -1
- package/dist/{event-log-store-BGehvVTb.mjs → event-log-store-W49TCJXi.mjs} +1 -1
- package/dist/index.cjs +5 -5
- package/dist/index.d.cts +7 -7
- package/dist/index.d.mts +7 -7
- package/dist/index.mjs +5 -5
- 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 +1 -1
- package/dist/machines.mjs +1 -1
- package/dist/{model-source-BilDEyqk.mjs → model-source-CK3F4YuU.mjs} +1 -1
- package/dist/{model-source-BQ97_l1-.cjs → model-source-DmhTMK39.cjs} +1 -1
- package/dist/openai.cjs +377 -95
- package/dist/openai.d.cts +55 -20
- package/dist/openai.d.mts +55 -20
- package/dist/openai.mjs +375 -96
- package/dist/otel.d.cts +1 -1
- package/dist/otel.d.mts +1 -1
- package/dist/{run-agent-B5QhabdY.d.cts → run-agent-B1-Eqviq.d.cts} +13 -5
- package/dist/{run-agent-Atu-wEk7.d.mts → run-agent-BGdx5913.d.mts} +13 -5
- package/dist/{run-agent-2UnSUhDb.mjs → run-agent-Ct_GZw_f.mjs} +124 -38
- package/dist/{run-agent-Cg0xd3K-.cjs → run-agent-s5D32w99.cjs} +123 -37
- package/dist/{setup-agent-CmhB-U5P.mjs → setup-agent-05uw4dPZ.mjs} +2 -2
- package/dist/{setup-agent-BiF1N3td.d.cts → setup-agent-BtfeFfF6.d.cts} +2 -2
- package/dist/{setup-agent-J9f_Wu5T.d.mts → setup-agent-C6nqzv_X.d.mts} +2 -2
- package/dist/{setup-agent-CwUJyqKB.cjs → setup-agent-CXEBURdo.cjs} +2 -2
- package/dist/tanstack-ai.cjs +91 -59
- package/dist/tanstack-ai.d.cts +13 -2
- package/dist/tanstack-ai.d.mts +13 -2
- package/dist/tanstack-ai.mjs +91 -59
- package/dist/testing.cjs +539 -13
- package/dist/testing.d.cts +202 -6
- package/dist/testing.d.mts +202 -6
- package/dist/testing.mjs +536 -14
- package/dist/{text-logic-CYP502VT.d.cts → text-logic-CV_4KGr6.d.cts} +28 -3
- package/dist/{text-logic-DuK9HIFM.d.mts → text-logic-Ckh-rJFV.d.mts} +28 -3
- package/dist/{usage-D7JKAxLc.d.mts → usage-BDiJKyv9.d.cts} +11 -1
- package/dist/{usage-DVw-646x.d.cts → usage-DOoVUGVq.d.mts} +11 -1
- package/dist/validate.cjs +3 -3
- package/dist/validate.d.cts +2 -2
- package/dist/validate.d.mts +2 -2
- package/dist/validate.mjs +3 -3
- package/dist/{verify-Dk3Vwnha.d.cts → verify-BQpE8hUz.d.cts} +1 -1
- package/dist/{verify-DgB8P-Wx.mjs → verify-Bpahmr34.mjs} +2 -2
- package/dist/{verify-BVz4cURF.d.mts → verify-CqeuEmIk.d.mts} +1 -1
- package/dist/{verify-CS_WLRXn.cjs → verify-DCLZa9R0.cjs} +2 -2
- package/dist/with-model-calls-BXYdBdcu.cjs +45 -0
- package/dist/with-model-calls-Bv4V4EHC.mjs +34 -0
- package/package.json +5 -5
- package/readme.md +14 -13
- package/skills/loop-to-machine/SKILL.md +40 -2
|
@@ -402,14 +402,35 @@ declare function renderDecisionAttempts(request: Pick<AgentDecisionRequest, "eve
|
|
|
402
402
|
* …) flow untouched to `onResult`'s `raw`; `usage` is the one core reads —
|
|
403
403
|
* report this attempt's tokens there and the runtime folds them into the run's
|
|
404
404
|
* aggregated {@link AgentUsage}.
|
|
405
|
+
*
|
|
406
|
+
* An answer that names no valid event (no tool call, a tool that was not
|
|
407
|
+
* offered, arguments that are not JSON) is returned as `rejected` instead of
|
|
408
|
+
* `event`: {@link resolveDecision} records it as a failed attempt with that
|
|
409
|
+
* reason and asks again.
|
|
405
410
|
*/
|
|
406
|
-
type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<{
|
|
411
|
+
type AgentDecisionExecutor = (request: AgentExecutorDecisionRequest, info?: AgentRequestExecutorInfo) => PromiseLike<({
|
|
407
412
|
event: ChosenEvent;
|
|
413
|
+
rejected?: undefined;
|
|
414
|
+
} | {
|
|
415
|
+
event?: undefined;
|
|
416
|
+
rejected: AgentDecisionRejection;
|
|
417
|
+
}) & {
|
|
408
418
|
reason?: string;
|
|
409
419
|
/** This attempt's token usage, aggregated into the run result's {@link AgentUsage}. */
|
|
410
420
|
usage?: AgentCallUsage;
|
|
411
421
|
[key: string]: unknown;
|
|
412
422
|
}>;
|
|
423
|
+
/**
|
|
424
|
+
* An answer a decide executor could not read as a candidate event, returned as
|
|
425
|
+
* `rejected` (see {@link AgentDecisionExecutor}). `reason` is fed back to the
|
|
426
|
+
* model as written.
|
|
427
|
+
*/
|
|
428
|
+
type AgentDecisionRejection = {
|
|
429
|
+
failure: "unknown-event" | "invalid-payload";
|
|
430
|
+
reason: string;
|
|
431
|
+
/** What the model sent, as far as it could be read. */
|
|
432
|
+
event?: ChosenEvent;
|
|
433
|
+
};
|
|
413
434
|
/**
|
|
414
435
|
* Options for {@link resolveDecision}. The `TEvent` parameter (the machine's
|
|
415
436
|
* event union, defaulting to the loose {@link ChosenEvent}) types both
|
|
@@ -784,6 +805,8 @@ type AgentRequestExecutorResult<TOutput = unknown, TMessage = unknown> = {
|
|
|
784
805
|
usage?: AgentCallUsage;
|
|
785
806
|
/** Why this call stopped, normalized (see {@link AgentFinishReason}). Surfaced on the `request.end` trace event. */
|
|
786
807
|
finishReason?: AgentFinishReason;
|
|
808
|
+
/** Provider calls this request made: a tool loop's steps. Default 1. Counted in `usage.modelCalls` and against `maxModelCalls`. */
|
|
809
|
+
modelCalls?: number;
|
|
787
810
|
[key: string]: unknown;
|
|
788
811
|
};
|
|
789
812
|
/**
|
|
@@ -816,7 +839,9 @@ interface AgentRequestExecutorInfo {
|
|
|
816
839
|
* the first attempt's result instead of paying for it twice. A decision
|
|
817
840
|
* retry appends its attempt ordinal (`${executionId}:${requestId}#${n}.${a}`,
|
|
818
841
|
* `a` being the number of prior failed attempts), so a retry never collides
|
|
819
|
-
* with the rejected attempt it is replacing.
|
|
842
|
+
* with the rejected attempt it is replacing. A call inside an invoked child
|
|
843
|
+
* machine is keyed under the root-level child that owns it:
|
|
844
|
+
* `${executionId}:${childId}#${m}/${requestId}#${k}`.
|
|
820
845
|
*
|
|
821
846
|
* It identifies the CALL SITE, not the request: a version bridge keeps the
|
|
822
847
|
* lineage id, so a migrated machine can ask something else under the same
|
|
@@ -907,4 +932,4 @@ declare function providerOutputSchema(inner: StandardSchemaV1, options?: {
|
|
|
907
932
|
*/
|
|
908
933
|
declare function parseProviderOutput(request: Pick<AgentTextRequest, "outputSchema" | "includeReasoning">, value: unknown): ProviderStructuredOutput;
|
|
909
934
|
//#endregion
|
|
910
|
-
export {
|
|
935
|
+
export { AgentError as $, AgentDecisionExhaustedError as A, ResolveDecisionOptions as B, getAgentOutputMode as C, parseProviderOutput as D, parseOutput as E, AgentExecutorDecisionRequest as F, AgentEventDescriptor as G, createDecisionRequest as H, CreateDecisionRequestOptions as I, AgentRequestSource as J, AgentInvalidEventPayloadError as K, DecisionAttempt as L, AgentDecisionOption as M, AgentDecisionRejection as N, providerOutputSchema as O, AgentDecisionRequest as P, parseAgentEvent as Q, DecisionLogic as R, createTextLogic as S, getCallUsage as T, renderDecisionAttempts as U, createDecisionLogic as V, resolveDecision as W, EventFromSnapshot as X, AgentSchemas as Y, getAcceptedEvents as Z, TextLogic as _, AgentModelRef as a, TextLogicExecutor as b, AgentRequestExecutorInfo as c, AgentRequestMode as d, AgentTruncatedError as et, 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, AgentRequestOptions 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, DecisionLogicConfig as z };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { t as AgentCallUsage } from "./text-logic-
|
|
1
|
+
import { t as AgentCallUsage } from "./text-logic-CV_4KGr6.cjs";
|
|
2
2
|
import { EventObject } from "xstate";
|
|
3
3
|
//#region src/usage.d.ts
|
|
4
4
|
/** Reserved event delivered after a model call reports token usage. */
|
|
@@ -12,6 +12,16 @@ interface AgentUsageEvent extends EventObject {
|
|
|
12
12
|
src?: string;
|
|
13
13
|
model?: string;
|
|
14
14
|
name?: string;
|
|
15
|
+
/**
|
|
16
|
+
* The run's model-call budget after this call: `modelCalls` counted against
|
|
17
|
+
* `maxModelCalls` so far, including `modelCallsSpent`. Guard on
|
|
18
|
+
* `maxModelCalls - modelCalls` to keep calls in reserve. Absent under
|
|
19
|
+
* `provideExecutors`, which has no budget.
|
|
20
|
+
*/
|
|
21
|
+
budget?: {
|
|
22
|
+
modelCalls: number;
|
|
23
|
+
maxModelCalls: number;
|
|
24
|
+
};
|
|
15
25
|
}
|
|
16
26
|
//#endregion
|
|
17
27
|
export { AgentUsageEvent as n, AGENT_USAGE_EVENT_TYPE as t };
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { t as AgentCallUsage } from "./text-logic-
|
|
1
|
+
import { t as AgentCallUsage } from "./text-logic-Ckh-rJFV.mjs";
|
|
2
2
|
import { EventObject } from "xstate";
|
|
3
3
|
//#region src/usage.d.ts
|
|
4
4
|
/** Reserved event delivered after a model call reports token usage. */
|
|
@@ -12,6 +12,16 @@ interface AgentUsageEvent extends EventObject {
|
|
|
12
12
|
src?: string;
|
|
13
13
|
model?: string;
|
|
14
14
|
name?: string;
|
|
15
|
+
/**
|
|
16
|
+
* The run's model-call budget after this call: `modelCalls` counted against
|
|
17
|
+
* `maxModelCalls` so far, including `modelCallsSpent`. Guard on
|
|
18
|
+
* `maxModelCalls - modelCalls` to keep calls in reserve. Absent under
|
|
19
|
+
* `provideExecutors`, which has no budget.
|
|
20
|
+
*/
|
|
21
|
+
budget?: {
|
|
22
|
+
modelCalls: number;
|
|
23
|
+
maxModelCalls: number;
|
|
24
|
+
};
|
|
15
25
|
}
|
|
16
26
|
//#endregion
|
|
17
27
|
export { AgentUsageEvent as n, AGENT_USAGE_EVENT_TYPE as t };
|
package/dist/validate.cjs
CHANGED
|
@@ -21,9 +21,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
|
|
|
21
21
|
enumerable: true
|
|
22
22
|
}) : target, mod));
|
|
23
23
|
//#endregion
|
|
24
|
-
const require_event_log = require("./event-log-
|
|
25
|
-
const require_setup_agent = require("./setup-agent-
|
|
26
|
-
const require_verify = require("./verify-
|
|
24
|
+
const require_event_log = require("./event-log-BWSSLUff.cjs");
|
|
25
|
+
const require_setup_agent = require("./setup-agent-CXEBURdo.cjs");
|
|
26
|
+
const require_verify = require("./verify-DCLZa9R0.cjs");
|
|
27
27
|
let ajv_dist_2020_js = require("ajv/dist/2020.js");
|
|
28
28
|
ajv_dist_2020_js = __toESM(ajv_dist_2020_js, 1);
|
|
29
29
|
//#region schemas/agent-workflow.json
|
package/dist/validate.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-
|
|
2
|
-
import { u as ExplorePathsOptions } from "./verify-
|
|
1
|
+
import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-BtfeFfF6.cjs";
|
|
2
|
+
import { u as ExplorePathsOptions } from "./verify-BQpE8hUz.cjs";
|
|
3
3
|
import { AnyActorLogic, AnyStateMachine } from "xstate";
|
|
4
4
|
//#region src/validate/validate-config.d.ts
|
|
5
5
|
/**
|
package/dist/validate.d.mts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-
|
|
2
|
-
import { u as ExplorePathsOptions } from "./verify-
|
|
1
|
+
import { d as AgentWorkflowConfig, g as FromConfigOptions, v as SchemaCompiler } from "./setup-agent-C6nqzv_X.mjs";
|
|
2
|
+
import { u as ExplorePathsOptions } from "./verify-CqeuEmIk.mjs";
|
|
3
3
|
import { AnyActorLogic, AnyStateMachine } from "xstate";
|
|
4
4
|
//#region src/validate/validate-config.d.ts
|
|
5
5
|
/**
|
package/dist/validate.mjs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { D as
|
|
2
|
-
import { i as setupAgentFromConfig } from "./setup-agent-
|
|
3
|
-
import { a as explorePaths, s as lintAgentMachine } from "./verify-
|
|
1
|
+
import { D as GENERATE_TEXT_ACTOR, E as DECIDE_ACTOR, O as STREAM_TEXT_ACTOR } from "./event-log-C7jeH0y8.mjs";
|
|
2
|
+
import { i as setupAgentFromConfig } from "./setup-agent-05uw4dPZ.mjs";
|
|
3
|
+
import { a as explorePaths, s as lintAgentMachine } from "./verify-Bpahmr34.mjs";
|
|
4
4
|
import Ajv2020 from "ajv/dist/2020.js";
|
|
5
5
|
//#region schemas/agent-workflow.json
|
|
6
6
|
var agent_workflow_default = {
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { u as ChosenEvent } from "./types-Dp5_Ru4R.cjs";
|
|
2
|
-
import {
|
|
2
|
+
import { $ as AgentError } from "./text-logic-CV_4KGr6.cjs";
|
|
3
3
|
import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
|
|
4
4
|
//#region src/verify.d.ts
|
|
5
5
|
/** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { d as getAcceptedEvents, f as getHumanEventTypes, l as resolveDecision, n as acceptedDecisionOptions, p as isEventPattern, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-
|
|
1
|
+
import { G as getRegisteredAgentExecutionOptions, I as isTextLogic, Q as getJsonSchemaSync, U as executorBoundLogics, ft as isRecord, pt as AgentError } from "./event-log-C7jeH0y8.mjs";
|
|
2
|
+
import { d as getAcceptedEvents, f as getHumanEventTypes, l as resolveDecision, n as acceptedDecisionOptions, p as isEventPattern, s as isDecisionLogic, t as AgentDecisionExhaustedError } from "./decision-COkJNjOW.mjs";
|
|
3
3
|
import { getNextTransitions, initialTransition, machineToJSON, transition } from "xstate";
|
|
4
4
|
//#region src/steps.ts
|
|
5
5
|
/**
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { u as ChosenEvent } from "./types-Dp5_Ru4R.mjs";
|
|
2
|
-
import {
|
|
2
|
+
import { $ as AgentError } from "./text-logic-Ckh-rJFV.mjs";
|
|
3
3
|
import { AnyMachineSnapshot, AnyStateMachine } from "xstate";
|
|
4
4
|
//#region src/verify.d.ts
|
|
5
5
|
/** Severity of an {@link AgentLintDiagnostic}. `error` findings fail CI/the CLI; `warning`s are advisory. */
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
const require_event_log = require("./event-log-
|
|
2
|
-
const require_decision = require("./decision-
|
|
1
|
+
const require_event_log = require("./event-log-BWSSLUff.cjs");
|
|
2
|
+
const require_decision = require("./decision-BEsATcr1.cjs");
|
|
3
3
|
let xstate = require("xstate");
|
|
4
4
|
//#region src/steps.ts
|
|
5
5
|
/**
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
//#region src/internal/rejected-answer.ts
|
|
2
|
+
/**
|
|
3
|
+
* The rejection for a decision answer that names no candidate event: no tool
|
|
4
|
+
* call, a call to a tool that was not offered, or arguments that are not JSON.
|
|
5
|
+
* `resolveDecision` records it as a failed attempt and asks again. @internal
|
|
6
|
+
*/
|
|
7
|
+
function rejectedAnswer(toolCall, toolNames) {
|
|
8
|
+
const valid = toolNames.join(", ") || "none";
|
|
9
|
+
if (!toolCall) return {
|
|
10
|
+
failure: "unknown-event",
|
|
11
|
+
reason: `no tool was called; call exactly one of: ${valid}`
|
|
12
|
+
};
|
|
13
|
+
if (toolCall.invalidJson) return {
|
|
14
|
+
failure: "invalid-payload",
|
|
15
|
+
reason: `the arguments for tool '${toolCall.toolName}' were not valid JSON`
|
|
16
|
+
};
|
|
17
|
+
return {
|
|
18
|
+
failure: "unknown-event",
|
|
19
|
+
reason: `tool '${toolCall.toolName}' was not offered; valid tools: ${valid}`
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
//#endregion
|
|
23
|
+
//#region src/internal/with-model-calls.ts
|
|
24
|
+
/**
|
|
25
|
+
* Records on a thrown error how many provider calls its request made, so the
|
|
26
|
+
* runtime counts a failed tool loop's steps too (see `getCallModelCalls`).
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
function withModelCalls(error, modelCalls) {
|
|
30
|
+
if (modelCalls > 1 && typeof error === "object" && error !== null && Object.isExtensible(error)) error.modelCalls ??= modelCalls;
|
|
31
|
+
return error;
|
|
32
|
+
}
|
|
33
|
+
//#endregion
|
|
34
|
+
Object.defineProperty(exports, "rejectedAnswer", {
|
|
35
|
+
enumerable: true,
|
|
36
|
+
get: function() {
|
|
37
|
+
return rejectedAnswer;
|
|
38
|
+
}
|
|
39
|
+
});
|
|
40
|
+
Object.defineProperty(exports, "withModelCalls", {
|
|
41
|
+
enumerable: true,
|
|
42
|
+
get: function() {
|
|
43
|
+
return withModelCalls;
|
|
44
|
+
}
|
|
45
|
+
});
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
//#region src/internal/rejected-answer.ts
|
|
2
|
+
/**
|
|
3
|
+
* The rejection for a decision answer that names no candidate event: no tool
|
|
4
|
+
* call, a call to a tool that was not offered, or arguments that are not JSON.
|
|
5
|
+
* `resolveDecision` records it as a failed attempt and asks again. @internal
|
|
6
|
+
*/
|
|
7
|
+
function rejectedAnswer(toolCall, toolNames) {
|
|
8
|
+
const valid = toolNames.join(", ") || "none";
|
|
9
|
+
if (!toolCall) return {
|
|
10
|
+
failure: "unknown-event",
|
|
11
|
+
reason: `no tool was called; call exactly one of: ${valid}`
|
|
12
|
+
};
|
|
13
|
+
if (toolCall.invalidJson) return {
|
|
14
|
+
failure: "invalid-payload",
|
|
15
|
+
reason: `the arguments for tool '${toolCall.toolName}' were not valid JSON`
|
|
16
|
+
};
|
|
17
|
+
return {
|
|
18
|
+
failure: "unknown-event",
|
|
19
|
+
reason: `tool '${toolCall.toolName}' was not offered; valid tools: ${valid}`
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
//#endregion
|
|
23
|
+
//#region src/internal/with-model-calls.ts
|
|
24
|
+
/**
|
|
25
|
+
* Records on a thrown error how many provider calls its request made, so the
|
|
26
|
+
* runtime counts a failed tool loop's steps too (see `getCallModelCalls`).
|
|
27
|
+
* @internal
|
|
28
|
+
*/
|
|
29
|
+
function withModelCalls(error, modelCalls) {
|
|
30
|
+
if (modelCalls > 1 && typeof error === "object" && error !== null && Object.isExtensible(error)) error.modelCalls ??= modelCalls;
|
|
31
|
+
return error;
|
|
32
|
+
}
|
|
33
|
+
//#endregion
|
|
34
|
+
export { rejectedAnswer as n, withModelCalls as t };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@statelyai/agent",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.34",
|
|
4
4
|
"description": "Make invalid agent actions impossible. Agent logic as state machines: deterministic, inspectable, resumable, runs anywhere.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -188,10 +188,10 @@
|
|
|
188
188
|
},
|
|
189
189
|
"peerDependencies": {
|
|
190
190
|
"@opentelemetry/api": "^1",
|
|
191
|
-
"@tanstack/ai": "
|
|
192
|
-
"ai": "
|
|
193
|
-
"ajv": "
|
|
194
|
-
"openai": "
|
|
191
|
+
"@tanstack/ai": "*",
|
|
192
|
+
"ai": "*",
|
|
193
|
+
"ajv": "*",
|
|
194
|
+
"openai": "*",
|
|
195
195
|
"xstate": "6.0.0-alpha.69"
|
|
196
196
|
},
|
|
197
197
|
"peerDependenciesMeta": {
|
package/readme.md
CHANGED
|
@@ -65,14 +65,15 @@ Requirements:
|
|
|
65
65
|
- TypeScript 5.4 or newer. Older versions accept the code, but callback parameters in `createMachine` silently become `any`.
|
|
66
66
|
- A [Standard Schema](https://standardschema.dev) library: zod 4, zod 3.24 or newer, Valibot, or ArkType. `setupAgent` throws `invalid-schema` for zod 3.23 and earlier.
|
|
67
67
|
- The package is ESM-first. CommonJS builds are published too, so `require()` works. Subpath imports (`@statelyai/agent/testing`) resolve under every `moduleResolution`, including `node`.
|
|
68
|
-
- `@statelyai/agent/ai-sdk` needs `ai` 7.0.128 or newer. Provider packages must match your `ai` major: `@ai-sdk/openai@^4` pairs with `ai@^7`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch
|
|
68
|
+
- `@statelyai/agent/ai-sdk` needs `ai` 7.0.128 or newer. Provider packages must match your `ai` major: `@ai-sdk/openai@^4` pairs with `ai@^7`. A bare `@ai-sdk/openai` resolves to `@latest`, which can mismatch your `ai`. `@statelyai/agent/openai` needs `openai` 5 or newer, `@statelyai/agent/tanstack-ai` needs `@tanstack/ai` 0.66 or newer, and `@statelyai/agent/validate` needs `ajv` 8.20 or newer.
|
|
69
|
+
- Adapter SDKs (`ai`, `openai`, `@tanstack/ai`, `ajv`) are optional peers with no version range, so an app on an older SDK installs the core without `--legacy-peer-deps`. An adapter used with an older SDK fails when imported or called, not at install.
|
|
69
70
|
|
|
70
71
|
An app that already uses XState 4 or 5 keeps it: put the agent in its own workspace package. See [Use in an XState 4 or 5 app](https://github.com/statelyai/agent/blob/next/docs/xstate-4-and-5-apps.md). If both versions land in one `node_modules`, the package fails with errors that do not mention a version:
|
|
71
72
|
|
|
72
|
-
| Error
|
|
73
|
-
|
|
|
74
|
-
| `createAsyncLogic is not a function`
|
|
75
|
-
| `Cannot find module '…/node_modules/xstate/durable'`
|
|
73
|
+
| Error | Cause |
|
|
74
|
+
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
|
75
|
+
| `createAsyncLogic is not a function` | `xstate` resolved to 4 or 5 from CommonJS |
|
|
76
|
+
| `Cannot find module '…/node_modules/xstate/durable'` | `xstate` resolved to 4 or 5 from ESM |
|
|
76
77
|
| `unmet peer dependency "xstate@6.0.0-alpha.69"` (pnpm, npm) or `has incorrect peer dependency "xstate@6.0.0-alpha.69"` (yarn 1) | The install's only warning of the two above |
|
|
77
78
|
|
|
78
79
|
## Agent skills
|
|
@@ -84,14 +85,14 @@ mkdir -p .claude/skills
|
|
|
84
85
|
cp -R node_modules/@statelyai/agent/skills/* .claude/skills/
|
|
85
86
|
```
|
|
86
87
|
|
|
87
|
-
| Skill
|
|
88
|
-
|
|
|
89
|
-
| [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill
|
|
90
|
-
| [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md)
|
|
91
|
-
| [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md)
|
|
92
|
-
| [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md)
|
|
93
|
-
| [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md)
|
|
94
|
-
| [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md)
|
|
88
|
+
| Skill | What it does |
|
|
89
|
+
| ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
90
|
+
| [`graph-engineering`](https://github.com/statelyai/agent/blob/next/skills/graph-engineering/SKILL.md) | Finds which step a project is at and routes to the next skill |
|
|
91
|
+
| [`loop-to-machine`](https://github.com/statelyai/agent/blob/next/skills/loop-to-machine/SKILL.md) | Converts existing agent code into a machine and checks parity with `compareRuns` |
|
|
92
|
+
| [`generate-machine`](https://github.com/statelyai/agent/blob/next/skills/generate-machine/SKILL.md) | Authors a JSON policy machine from scratch and runs `verifyAgentConfig` |
|
|
93
|
+
| [`add-traces`](https://github.com/statelyai/agent/blob/next/skills/add-traces/SKILL.md) | Stamps and persists every run so it replays |
|
|
94
|
+
| [`add-evals`](https://github.com/statelyai/agent/blob/next/skills/add-evals/SKILL.md) | Writes evals per state, at the cheapest level that catches the failure |
|
|
95
|
+
| [`improve-machine`](https://github.com/statelyai/agent/blob/next/skills/improve-machine/SKILL.md) | Improves a policy from traces and hands the change to a person as a pull request |
|
|
95
96
|
|
|
96
97
|
## Quick start
|
|
97
98
|
|
|
@@ -16,7 +16,7 @@ This is step 1 of 4. Next: `add-traces`, then `add-evals`, then `improve-machine
|
|
|
16
16
|
## Hard rules
|
|
17
17
|
|
|
18
18
|
- **Pin the baseline before you change anything.** The parity test runs against the old code, which stays in the repo, untouched, until a person deletes it.
|
|
19
|
-
- **Never promise "behaves exactly like".** Promise what the parity report
|
|
19
|
+
- **Never promise "behaves exactly like".** Promise what the parity report and the replayed recordings show: equivalent effects on these scenarios, with every difference labeled.
|
|
20
20
|
- **Never copy a rule break.** Where the old code broke a rule, the machine blocks it. That difference is `intended`, not a regression.
|
|
21
21
|
- **Rules are code, not prompt text.** A rule that lived only in a system prompt becomes a guard. Keep the prompt line only as context for the model.
|
|
22
22
|
- **Business rules belong to people.** If a rule is ambiguous (which threshold, which order of checks), ask. Never pick one silently.
|
|
@@ -55,7 +55,20 @@ The parity test exists before the machine does.
|
|
|
55
55
|
2. **Deterministic stand-in models.** Parity with a live model drifts between runs. Use the code's scripted or mock models if it has them; otherwise write one: a function from the request (its prompt, or its `name`) to a fixed answer. ([`examples/mock-model.ts`](https://github.com/statelyai/agent/blob/next/examples/mock-model.ts) in the `statelyai/agent` repo is one, built on the AI SDK's `MockLanguageModelV3`; it is not in the package.) You want two: one that follows the rules, and one that breaks them. A seeded random model needs its seed derived from the scenario id and a fresh instance per run, or every scenario replays the same draws.
|
|
56
56
|
3. **Ground truth.** Read outcomes and effects from the world, not from the agent's own report. `effects` holds **every write the world records**: the refunds, and also the approvals, the verifications, the questions asked, the escalations. A refund issued without its approval looks correct if `effects` holds only refunds. Text a model wrote (an escalation reason) differs on every run: compare its count or presence, not the text. If the world can check rules after the fact, return those violations. If it cannot, write the check as a plain function over the effects.
|
|
57
57
|
4. **A baseline with no function to call.** When the loop lives inline in a framework handler (a tRPC procedure, a route), call the handler itself in the test, with its model client and storage replaced by the stand-ins (a module mock, or the framework's test caller). Do not extract the loop into a function first: that changes the code you are trying to pin.
|
|
58
|
-
5. **
|
|
58
|
+
5. **Record golden runs.** When the code calls the model through the AI SDK or the `openai` client, record each scenario's effects: every model call, every tool call with its arguments and result, and the output. Wrap the model and tools with a recorder from `@statelyai/agent/testing`, run the old code, and save the recording as a JSON fixture. Step 7 replays it against the machine with no API key and no side effects.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import { createRecorder } from "@statelyai/agent/testing";
|
|
62
|
+
|
|
63
|
+
const recorder = createRecorder();
|
|
64
|
+
const model = recorder.model(openai("gpt-5")); // or recorder.openai(new OpenAI())
|
|
65
|
+
const tools = recorder.tools(appTools); // AI SDK tools; recorder.tool(name, fn) for plain functions
|
|
66
|
+
recorder.output(await runLoop({ ...scenario, model, tools }));
|
|
67
|
+
writeFileSync(`fixtures/${scenario.id}.json`, JSON.stringify(recorder.recording));
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Record with the live model to capture real answers, or with a stand-in model. Either way the recording is the script for replay. One recording per scenario and per stand-in.
|
|
71
|
+
6. **The harness check.** Run the old code on both sides with each stand-in model. Each row's baseline must equal its candidate (the runs are deterministic), and with the rule-following model every row must be `same`. With a rule-breaking model, rows are `regression` by design: the candidate breaks rules.
|
|
59
72
|
|
|
60
73
|
```ts
|
|
61
74
|
import { compareRuns, type ParityResult, type ParityRun } from "@statelyai/agent/testing";
|
|
@@ -194,6 +207,31 @@ const REVIEWED: Record<string, (row: ParityResult<Scenario>) => void> = {
|
|
|
194
207
|
};
|
|
195
208
|
```
|
|
196
209
|
|
|
210
|
+
Then prove effect equivalence on every recording from step 2. Replay answers each model and tool call from the recording, so the machine needs no key and causes no side effects:
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
import { compareRecordings, createRecorder, type EffectDivergence, type Recording } from "@statelyai/agent/testing";
|
|
214
|
+
|
|
215
|
+
test.each(SCENARIOS)("equivalent to the recorded loop: $id", async (scenario) => {
|
|
216
|
+
const recording: Recording = JSON.parse(readFileSync(`fixtures/${scenario.id}.json`, "utf8"));
|
|
217
|
+
const replay = createRecorder({ replay: recording });
|
|
218
|
+
const model = replay.model(openai("gpt-5")); // never called in replay
|
|
219
|
+
replay.output(await runMachine({ ...scenario, model, tools: replay.tools(appTools) }));
|
|
220
|
+
const report = compareRecordings(recording, replay.recording);
|
|
221
|
+
expect(report.divergences.map(({ reason, message }) => ({ reason, message }))).toEqual(INTENDED[scenario.id] ?? []);
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
// Differences a person accepted: who, and the exact divergences.
|
|
225
|
+
const INTENDED: Record<string, Array<Pick<EffectDivergence, "reason" | "message">>> = {};
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
- Equivalent means the same model calls (count and shape: offered tool names, response format), the same tool calls with the same arguments, and the same output. Prompts and states may differ. Tool calls between two model calls compare in any order.
|
|
229
|
+
- Values that differ on every run (generated ids, branch names, timestamps) fail `tool-input`. Pass the same `normalize` to `createRecorder({ replay, normalize })` and `compareRecordings(a, b, { normalize })` to redact them on both sides; never edit the fixtures.
|
|
230
|
+
- `divergences` lists every difference, lined up so one extra call does not shift the rest; `divergence` is the first.
|
|
231
|
+
- In replay, a model call past the recorded ones or a tool call the old code never made throws `RecordingDivergenceError`, and `compareRecordings` names it.
|
|
232
|
+
- `model-call-shape`: the machine changed a call's tools or output format, for example a model-picked action that became `agent.decide`. The recorded answer does not fit the new call, so equivalence ends there. Port the call unchanged first, prove equivalence, then change it in a separate step whose divergences are `INTENDED`. To keep replaying past a call you changed on purpose, pass the same `modelCalls` function to `createRecorder({ replay, modelCalls })` and `compareRecordings`: `(expected, actual) => expected.call === 2 || sameModelCallShape(expected, actual)`. The recorded answer must still fit the new call.
|
|
233
|
+
- A guard that blocks a rule break diverges on purpose. List it in `INTENDED` with the exact divergence.
|
|
234
|
+
|
|
197
235
|
- Every `regression` row: fix the machine, or, when the old behavior was wrong but broke no rule, ask the user. If the outcomes differ, the answer may become the scenario's `expected`. If only effects differ (the loop asked three times, the machine once), list the row in a reviewed-differences list in the test, with the exact difference asserted and the person who accepted it. Never edit a scenario to make a row pass.
|
|
198
236
|
- Every `intended` row: check that its reason is a real rule. A candidate that fixed a rule break with the same outcome is `intended` too.
|
|
199
237
|
- Run once with a live model if a key is available. Report it as one sample, not a guarantee.
|