@statelyai/agent 2.0.0-alpha.36 → 2.0.0-alpha.38

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 (38) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/dist/{effects-CuOUNYtZ.mjs → effects-BT_cSY0j.mjs} +95 -11
  3. package/dist/{effects-B23bFZEs.cjs → effects-DDseYtJk.cjs} +95 -11
  4. package/dist/index.cjs +6 -6
  5. package/dist/index.d.cts +3 -3
  6. package/dist/index.d.mts +3 -3
  7. package/dist/index.mjs +6 -6
  8. package/dist/otel.d.cts +1 -1
  9. package/dist/otel.d.mts +1 -1
  10. package/dist/{run-agent-BcQ-9NRT.d.cts → run-agent-30mH2moE.d.cts} +2 -2
  11. package/dist/{run-agent-C86drZtN.d.mts → run-agent-DlPzBWj-.d.mts} +2 -2
  12. package/dist/{setup-agent-jlo4vtaZ.d.cts → setup-agent-BaNyz6Q3.d.cts} +1 -1
  13. package/dist/{setup-agent-BIKcbVXV.d.mts → setup-agent-C1CG_nfX.d.mts} +1 -1
  14. package/dist/testing.cjs +2411 -1799
  15. package/dist/testing.d.cts +167 -4
  16. package/dist/testing.d.mts +167 -4
  17. package/dist/testing.mjs +2412 -1801
  18. package/dist/{usage-HtnrUsl9.d.cts → usage-Bm5nvpow.d.cts} +5 -0
  19. package/dist/{usage-DoP0Oi84.d.mts → usage-BnikdOca.d.mts} +5 -0
  20. package/dist/validate.cjs +1 -1
  21. package/dist/validate.d.cts +2 -2
  22. package/dist/validate.d.mts +2 -2
  23. package/dist/validate.mjs +1 -1
  24. package/dist/{verify-Dpz1u5Pe.mjs → verify-ChyX6jq0.mjs} +75 -20
  25. package/dist/{verify-Bink-Drw.cjs → verify-CwlombbC.cjs} +75 -20
  26. package/dist/{verify-CciG8UP-.d.cts → verify-DJHfEfm6.d.cts} +9 -4
  27. package/dist/{verify-Buh8XSUr.d.mts → verify-i9Hiwc5g.d.mts} +9 -4
  28. package/docs/decisions.md +1 -1
  29. package/docs/event-log.md +3 -2
  30. package/docs/hosts.md +2 -2
  31. package/docs/machines-as-data.md +5 -5
  32. package/docs/persistence.md +76 -5
  33. package/docs/quickstart.md +1 -1
  34. package/docs/steps.md +2 -0
  35. package/docs/usage-and-budgets.md +2 -0
  36. package/docs/verify.md +7 -2
  37. package/package.json +1 -1
  38. package/skills/build-machine/SKILL.md +4 -1
@@ -1,8 +1,171 @@
1
1
  import { R as AgentExecutorDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-CSf9bqpP.cjs";
2
- import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-BcQ-9NRT.cjs";
2
+ import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-30mH2moE.cjs";
3
+ import { n as AgentEventLogStore } from "./event-log-store-bc4ICGcS.cjs";
3
4
  import { A as RecordedOutput, C as RecordableDecisionModel, D as RecordedEffect, E as RecordedCall, F as compareRecordings, I as createRecorder, L as sameModelCallShape, M as Recorder, N as Recording, O as RecordedError, P as RecordingDivergenceError, S as RecordClientOptions, T as RecordableModel, _ as EquivalenceReport, b as NormalizeEffect, g as EffectDivergenceReason, h as EffectDivergence, j as RecordedToolCall, k as RecordedModelCall, m as CreateRecorderOptions, p as CompareRecordingsOptions, t as MetaOfSnapshot, v as ModelAnswer, w as RecordableLanguageModel, x as RecordCallOptions, y as ModelCallMatch } from "./utils-7lSa4H-i.cjs";
4
- import { S as textOutput, _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-CciG8UP-.cjs";
5
- import { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
5
+ import { S as textOutput, _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-DJHfEfm6.cjs";
6
+ import { AnyActorLogic, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
7
+ //#region src/crash-recovery.d.ts
8
+ /** Options for {@link checkCrashRecovery}. */
9
+ interface CheckCrashRecoveryOptions<TMachine extends AnyStateMachine> {
10
+ /** Machine input for the run. */
11
+ input?: unknown;
12
+ /**
13
+ * Host events, delivered one per turn: each time the run settles `idle`,
14
+ * the next one resumes it. The run ends when it settles `done` or `error`,
15
+ * or `idle` with none left. An uninterrupted run that ends with some left
16
+ * throws. With `timers: "host"`, an id-less `{ type: "xstate.timer" }`
17
+ * here is a timer's turn: the pending timer due soonest fires.
18
+ */
19
+ events?: ReadonlyArray<EventFromLogic<TMachine> | {
20
+ type: "xstate.timer";
21
+ }>;
22
+ /**
23
+ * Host events sent while the run is busy: each one goes out when the effect
24
+ * `during` starts (its first start, or its `occurrence`-th) (a key as {@link CrashEffect.key} names it,
25
+ * such as `draft#1` or `actor:fetch:0`), so it lands while that effect is
26
+ * in flight. After a crash, one the log does not hold is sent again, as a
27
+ * host retrying its delivery would: as its effect starts again, or, when
28
+ * that effect's completion was durable, where the uninterrupted log holds
29
+ * the event. One whose
30
+ * effect the uninterrupted run never starts throws.
31
+ */
32
+ sendDuring?: ReadonlyArray<{
33
+ during: string;
34
+ /** Which start of `during` to send it at, from 0, as {@link CrashPoint}'s `occurrence`. Default 0. */
35
+ occurrence?: number;
36
+ event: EventFromLogic<TMachine>;
37
+ }>;
38
+ /**
39
+ * `"host"` hands root `after` timers to the harness as a host scheduler
40
+ * (see `AgentTimerScheduler`) instead of arming them in process. The run
41
+ * settles `idle` with them pending: an id-less `{ type: "xstate.timer" }`
42
+ * in `events` fires the one due soonest, and once `events` run out, the
43
+ * pending ones fire in due order. Default `"in-process"`.
44
+ */
45
+ timers?: "in-process" | "host";
46
+ /**
47
+ * Model executors. Each call is recorded by its `callKey`. They run in the
48
+ * uninterrupted run only: after a crash, a call it made gets its recorded
49
+ * answer, so a fake may answer by call order.
50
+ */
51
+ executors?: Partial<AgentRequestExecutors>;
52
+ /** Actor sources, as `createAgentRuntime`'s `actors`. */
53
+ actors?: Record<string, AnyActorLogic>;
54
+ /**
55
+ * A fresh, empty store for one run: the baseline, or one crash and its
56
+ * resume. Default: an in-memory store. Pass your own adapter to check that
57
+ * an entry it acknowledged is read back after the crash.
58
+ */
59
+ store?: () => AgentEventLogStore;
60
+ /** Called before the baseline and before each crashed run, to reset fakes the executors or actors keep. Not called before the resume: like a real dependency, a fake keeps what the crashed run did to it. */
61
+ reset?: () => void;
62
+ /** Other runtime options (`maxModelCalls`, `verification`, …), shared by every run. */
63
+ runtime?: Omit<AgentRuntimeOptions<TMachine>, "executors" | "actors" | "store" | "threadId" | "signal" | "timers" | "abortWith">;
64
+ /**
65
+ * Milliseconds one run (the baseline, a crashed run, or its resume) may take.
66
+ * Default 5000. An uninterrupted run that times out throws, so no point
67
+ * runs after it. A crashed run or resume that times out is aborted and
68
+ * starts no more effects, but an effect already running that ignores its
69
+ * abort signal can still finish after the next point's `reset`.
70
+ */
71
+ timeout?: number;
72
+ }
73
+ /**
74
+ * One effect the run started: a model call (keyed by its `callKey` without the
75
+ * execution id, which differs per run) or a plain actor (keyed by its invoke
76
+ * site, as `actor:<site>`).
77
+ */
78
+ interface CrashEffect {
79
+ kind: "model" | "actor";
80
+ key: string;
81
+ }
82
+ /** Where a run was killed. */
83
+ type CrashPoint = {
84
+ /** After the store accepted `entries` entries: the next append never lands. */
85
+ kind: "log";
86
+ entries: number;
87
+ } | {
88
+ /** While `effect` was in flight: it ran, but its result was never recorded. */
89
+ kind: "effect";
90
+ effect: CrashEffect;
91
+ /** The effect's position among the baseline's effects, from 0. */
92
+ index: number;
93
+ /** Which run of `effect.key` it is, from 0: the run dies at that one, whatever order concurrent effects start in. */
94
+ occurrence: number;
95
+ };
96
+ /** What went wrong after a crash. */
97
+ type CrashRecoveryProblem =
98
+ /** An effect whose completion was durable ran again. */
99
+ "reran" |
100
+ /** An effect the uninterrupted run made never ran. */
101
+ "skipped" |
102
+ /** An effect ran that the uninterrupted run never made (a model call under a new key). */
103
+ "unexpected" |
104
+ /** A model call re-executed under its key with a different request. */
105
+ "request-changed" |
106
+ /** The resumed run ended with a different status, output, state, or context. */
107
+ "outcome" |
108
+ /** The final log does not replay to the resumed run's state. */
109
+ "replay" |
110
+ /** A `sendDuring` event the crash lost, which the resume never sent again. */
111
+ "undelivered" |
112
+ /** The crashed run or its resume never settled within `timeout`. */
113
+ "stuck" |
114
+ /** The crashed run, its resume, or the store factory threw. */
115
+ "threw";
116
+ /** One problem at one crash point. */
117
+ interface CrashRecoveryFailure {
118
+ point: CrashPoint;
119
+ problem: CrashRecoveryProblem;
120
+ message: string;
121
+ /** The effect key, for effect problems. */
122
+ key?: string;
123
+ }
124
+ /** What {@link checkCrashRecovery} found. */
125
+ interface CrashRecoveryReport {
126
+ /** True when every crash point was reached and recovered: no failures, nothing unreached. */
127
+ ok: boolean;
128
+ /** The uninterrupted run. */
129
+ baseline: {
130
+ status: AgentRunResult<AnyStateMachine>["status"];
131
+ output?: unknown;
132
+ /** Entries in its log. */
133
+ entries: number;
134
+ /** Effects it started, in start order. */
135
+ effects: CrashEffect[];
136
+ };
137
+ /** Every point a run was killed at, in order. */
138
+ points: CrashPoint[];
139
+ /**
140
+ * Points no run died at, with why: the crashed run never started that
141
+ * effect, or one write took the log past that length. Their resumes were
142
+ * not checked.
143
+ */
144
+ unreached: Array<{
145
+ point: CrashPoint;
146
+ reason: string;
147
+ }>;
148
+ failures: CrashRecoveryFailure[];
149
+ }
150
+ /**
151
+ * Runs `machine` once uninterrupted, then once per crash point: killed after
152
+ * each log append and while each effect is in flight, then resumed from the
153
+ * store's log by a fresh runtime. Each resumed run is checked against the
154
+ * uninterrupted one:
155
+ *
156
+ * - An effect whose completion was durable before the crash never runs again.
157
+ * Only an effect in flight at the crash may (execution is at-least-once).
158
+ * - Every effect of the uninterrupted run runs, and no other: a re-executed
159
+ * model call keeps its `callKey` and its request.
160
+ * - The run ends with the same status, output, state value, and context.
161
+ * - The resumed log replays to that state.
162
+ *
163
+ * Model calls the uninterrupted run made are answered from its recording.
164
+ * Plain actors run live, so they must give the same result however many times
165
+ * they run (pass `reset` for fakes that keep state).
166
+ */
167
+ export declare function checkCrashRecovery<TMachine extends AnyStateMachine>(machine: TMachine, options?: CheckCrashRecoveryOptions<TMachine>): Promise<CrashRecoveryReport>;
168
+ //#endregion
6
169
  //#region src/trajectory.d.ts
7
170
  /** An event-shaped trajectory item: anything with a string `type`. */
8
171
  interface TrajectoryEvent {
@@ -1035,4 +1198,4 @@ interface CheckParityReport<TScenario extends CheckParityScenario, TOutput> {
1035
1198
  */
1036
1199
  export declare function checkParity<TScenario extends CheckParityScenario, TEffects extends object, TOutput>(options: CheckParityOptions<TScenario, TEffects, TOutput>): Promise<CheckParityReport<TScenario, TOutput>>;
1037
1200
  //#endregion
1038
- export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AgreementReport, type AgreementRow, type AgreementSummary, type ApprovalRuleProposal, type ApprovalVerdict, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CapProposal, type CapSpec, type CheckParityOptions, type CheckParityOutcome, type CheckParityReport, type CheckParityRow, type CheckParityScenario, type CompareRecordingsOptions, type CompareRunsOptions, type CoverageReport, type CreateRecorderOptions, type Divergence, type EffectDivergence, type EffectDivergenceReason, type EquivalenceReport, type ExplorePathsOptions, type ExploreSnapshot, type FirstDivergenceOptions, type FoldTracesOptions, type GetDecisionRequestsOptions, type HandlerCoverage, type HandlerRef, type JudgeAgreementOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ModelAnswer, type ModelCallMatch, type NormalizeEffect, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type ProposeApprovalRulesOptions, type ProposeCapsOptions, type RecordCallOptions, type RecordClientOptions, type RecordableDecisionModel, type RecordableLanguageModel, type RecordableModel, type RecordedCall, type RecordedEffect, type RecordedError, type RecordedModelCall, type RecordedOutput, type RecordedToolCall, type Recorder, type Recording, RecordingDivergenceError, type RepeatGroup, type RepeatReport, type RepeatResult, type RepeatRun, type RepeatRunsOptions, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateCoverage, type StateStats, type TraceCoverageOptions, type TraceStep, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryEventEnvelope, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, compareRecordings, createRecorder, explorePaths, lintAgentMachine, sameModelCallShape, simulateAgent, textOutput };
1201
+ export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AgreementReport, type AgreementRow, type AgreementSummary, type ApprovalRuleProposal, type ApprovalVerdict, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CapProposal, type CapSpec, type CheckCrashRecoveryOptions, type CheckParityOptions, type CheckParityOutcome, type CheckParityReport, type CheckParityRow, type CheckParityScenario, type CompareRecordingsOptions, type CompareRunsOptions, type CoverageReport, type CrashEffect, type CrashPoint, type CrashRecoveryFailure, type CrashRecoveryProblem, type CrashRecoveryReport, type CreateRecorderOptions, type Divergence, type EffectDivergence, type EffectDivergenceReason, type EquivalenceReport, type ExplorePathsOptions, type ExploreSnapshot, type FirstDivergenceOptions, type FoldTracesOptions, type GetDecisionRequestsOptions, type HandlerCoverage, type HandlerRef, type JudgeAgreementOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ModelAnswer, type ModelCallMatch, type NormalizeEffect, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type ProposeApprovalRulesOptions, type ProposeCapsOptions, type RecordCallOptions, type RecordClientOptions, type RecordableDecisionModel, type RecordableLanguageModel, type RecordableModel, type RecordedCall, type RecordedEffect, type RecordedError, type RecordedModelCall, type RecordedOutput, type RecordedToolCall, type Recorder, type Recording, RecordingDivergenceError, type RepeatGroup, type RepeatReport, type RepeatResult, type RepeatRun, type RepeatRunsOptions, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateCoverage, type StateStats, type TraceCoverageOptions, type TraceStep, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryEventEnvelope, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, compareRecordings, createRecorder, explorePaths, lintAgentMachine, sameModelCallShape, simulateAgent, textOutput };
@@ -1,8 +1,171 @@
1
1
  import { R as AgentExecutorDecisionRequest, c as AgentRequestExecutorInfo, f as AgentTextRequest, s as AgentRequestExecutor, t as AgentCallUsage, u as AgentRequestExecutors } from "./text-logic-BqxalgMr.mjs";
2
- import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-C86drZtN.mjs";
2
+ import { p as AgentRuntimeOptions, s as AgentRunInit, u as AgentRunResult } from "./run-agent-DlPzBWj-.mjs";
3
+ import { n as AgentEventLogStore } from "./event-log-store-BBS8so8a.mjs";
3
4
  import { A as RecordedOutput, C as RecordableDecisionModel, D as RecordedEffect, E as RecordedCall, F as compareRecordings, I as createRecorder, L as sameModelCallShape, M as Recorder, N as Recording, O as RecordedError, P as RecordingDivergenceError, S as RecordClientOptions, T as RecordableModel, _ as EquivalenceReport, b as NormalizeEffect, g as EffectDivergenceReason, h as EffectDivergence, j as RecordedToolCall, k as RecordedModelCall, m as CreateRecorderOptions, p as CompareRecordingsOptions, t as MetaOfSnapshot, v as ModelAnswer, w as RecordableLanguageModel, x as RecordCallOptions, y as ModelCallMatch } from "./utils-CBbKw2fM.mjs";
4
- import { S as textOutput, _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-Buh8XSUr.mjs";
5
- import { AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
5
+ import { S as textOutput, _ as assertAgentMachine, a as AgentPathTerminal, b as lintAgentMachine, c as CanReachResult, d as ExploreSnapshot, f as LintAgentMachineOptions, g as SimulationTrailEntry, h as SimulationScript, i as AgentPathReport, l as CanReachTarget, m as SimulateAgentResult, n as AgentLintError, o as AgentUnknownStateError, p as SimulateAgentOptions, r as AgentLintSeverity, s as AssertAgentMachineOptions, t as AgentLintDiagnostic, u as ExplorePathsOptions, v as canReach, x as simulateAgent, y as explorePaths } from "./verify-i9Hiwc5g.mjs";
6
+ import { AnyActorLogic, AnyStateMachine, EventFromLogic, InputFrom, SnapshotFrom, StateValue } from "xstate";
7
+ //#region src/crash-recovery.d.ts
8
+ /** Options for {@link checkCrashRecovery}. */
9
+ interface CheckCrashRecoveryOptions<TMachine extends AnyStateMachine> {
10
+ /** Machine input for the run. */
11
+ input?: unknown;
12
+ /**
13
+ * Host events, delivered one per turn: each time the run settles `idle`,
14
+ * the next one resumes it. The run ends when it settles `done` or `error`,
15
+ * or `idle` with none left. An uninterrupted run that ends with some left
16
+ * throws. With `timers: "host"`, an id-less `{ type: "xstate.timer" }`
17
+ * here is a timer's turn: the pending timer due soonest fires.
18
+ */
19
+ events?: ReadonlyArray<EventFromLogic<TMachine> | {
20
+ type: "xstate.timer";
21
+ }>;
22
+ /**
23
+ * Host events sent while the run is busy: each one goes out when the effect
24
+ * `during` starts (its first start, or its `occurrence`-th) (a key as {@link CrashEffect.key} names it,
25
+ * such as `draft#1` or `actor:fetch:0`), so it lands while that effect is
26
+ * in flight. After a crash, one the log does not hold is sent again, as a
27
+ * host retrying its delivery would: as its effect starts again, or, when
28
+ * that effect's completion was durable, where the uninterrupted log holds
29
+ * the event. One whose
30
+ * effect the uninterrupted run never starts throws.
31
+ */
32
+ sendDuring?: ReadonlyArray<{
33
+ during: string;
34
+ /** Which start of `during` to send it at, from 0, as {@link CrashPoint}'s `occurrence`. Default 0. */
35
+ occurrence?: number;
36
+ event: EventFromLogic<TMachine>;
37
+ }>;
38
+ /**
39
+ * `"host"` hands root `after` timers to the harness as a host scheduler
40
+ * (see `AgentTimerScheduler`) instead of arming them in process. The run
41
+ * settles `idle` with them pending: an id-less `{ type: "xstate.timer" }`
42
+ * in `events` fires the one due soonest, and once `events` run out, the
43
+ * pending ones fire in due order. Default `"in-process"`.
44
+ */
45
+ timers?: "in-process" | "host";
46
+ /**
47
+ * Model executors. Each call is recorded by its `callKey`. They run in the
48
+ * uninterrupted run only: after a crash, a call it made gets its recorded
49
+ * answer, so a fake may answer by call order.
50
+ */
51
+ executors?: Partial<AgentRequestExecutors>;
52
+ /** Actor sources, as `createAgentRuntime`'s `actors`. */
53
+ actors?: Record<string, AnyActorLogic>;
54
+ /**
55
+ * A fresh, empty store for one run: the baseline, or one crash and its
56
+ * resume. Default: an in-memory store. Pass your own adapter to check that
57
+ * an entry it acknowledged is read back after the crash.
58
+ */
59
+ store?: () => AgentEventLogStore;
60
+ /** Called before the baseline and before each crashed run, to reset fakes the executors or actors keep. Not called before the resume: like a real dependency, a fake keeps what the crashed run did to it. */
61
+ reset?: () => void;
62
+ /** Other runtime options (`maxModelCalls`, `verification`, …), shared by every run. */
63
+ runtime?: Omit<AgentRuntimeOptions<TMachine>, "executors" | "actors" | "store" | "threadId" | "signal" | "timers" | "abortWith">;
64
+ /**
65
+ * Milliseconds one run (the baseline, a crashed run, or its resume) may take.
66
+ * Default 5000. An uninterrupted run that times out throws, so no point
67
+ * runs after it. A crashed run or resume that times out is aborted and
68
+ * starts no more effects, but an effect already running that ignores its
69
+ * abort signal can still finish after the next point's `reset`.
70
+ */
71
+ timeout?: number;
72
+ }
73
+ /**
74
+ * One effect the run started: a model call (keyed by its `callKey` without the
75
+ * execution id, which differs per run) or a plain actor (keyed by its invoke
76
+ * site, as `actor:<site>`).
77
+ */
78
+ interface CrashEffect {
79
+ kind: "model" | "actor";
80
+ key: string;
81
+ }
82
+ /** Where a run was killed. */
83
+ type CrashPoint = {
84
+ /** After the store accepted `entries` entries: the next append never lands. */
85
+ kind: "log";
86
+ entries: number;
87
+ } | {
88
+ /** While `effect` was in flight: it ran, but its result was never recorded. */
89
+ kind: "effect";
90
+ effect: CrashEffect;
91
+ /** The effect's position among the baseline's effects, from 0. */
92
+ index: number;
93
+ /** Which run of `effect.key` it is, from 0: the run dies at that one, whatever order concurrent effects start in. */
94
+ occurrence: number;
95
+ };
96
+ /** What went wrong after a crash. */
97
+ type CrashRecoveryProblem =
98
+ /** An effect whose completion was durable ran again. */
99
+ "reran" |
100
+ /** An effect the uninterrupted run made never ran. */
101
+ "skipped" |
102
+ /** An effect ran that the uninterrupted run never made (a model call under a new key). */
103
+ "unexpected" |
104
+ /** A model call re-executed under its key with a different request. */
105
+ "request-changed" |
106
+ /** The resumed run ended with a different status, output, state, or context. */
107
+ "outcome" |
108
+ /** The final log does not replay to the resumed run's state. */
109
+ "replay" |
110
+ /** A `sendDuring` event the crash lost, which the resume never sent again. */
111
+ "undelivered" |
112
+ /** The crashed run or its resume never settled within `timeout`. */
113
+ "stuck" |
114
+ /** The crashed run, its resume, or the store factory threw. */
115
+ "threw";
116
+ /** One problem at one crash point. */
117
+ interface CrashRecoveryFailure {
118
+ point: CrashPoint;
119
+ problem: CrashRecoveryProblem;
120
+ message: string;
121
+ /** The effect key, for effect problems. */
122
+ key?: string;
123
+ }
124
+ /** What {@link checkCrashRecovery} found. */
125
+ interface CrashRecoveryReport {
126
+ /** True when every crash point was reached and recovered: no failures, nothing unreached. */
127
+ ok: boolean;
128
+ /** The uninterrupted run. */
129
+ baseline: {
130
+ status: AgentRunResult<AnyStateMachine>["status"];
131
+ output?: unknown;
132
+ /** Entries in its log. */
133
+ entries: number;
134
+ /** Effects it started, in start order. */
135
+ effects: CrashEffect[];
136
+ };
137
+ /** Every point a run was killed at, in order. */
138
+ points: CrashPoint[];
139
+ /**
140
+ * Points no run died at, with why: the crashed run never started that
141
+ * effect, or one write took the log past that length. Their resumes were
142
+ * not checked.
143
+ */
144
+ unreached: Array<{
145
+ point: CrashPoint;
146
+ reason: string;
147
+ }>;
148
+ failures: CrashRecoveryFailure[];
149
+ }
150
+ /**
151
+ * Runs `machine` once uninterrupted, then once per crash point: killed after
152
+ * each log append and while each effect is in flight, then resumed from the
153
+ * store's log by a fresh runtime. Each resumed run is checked against the
154
+ * uninterrupted one:
155
+ *
156
+ * - An effect whose completion was durable before the crash never runs again.
157
+ * Only an effect in flight at the crash may (execution is at-least-once).
158
+ * - Every effect of the uninterrupted run runs, and no other: a re-executed
159
+ * model call keeps its `callKey` and its request.
160
+ * - The run ends with the same status, output, state value, and context.
161
+ * - The resumed log replays to that state.
162
+ *
163
+ * Model calls the uninterrupted run made are answered from its recording.
164
+ * Plain actors run live, so they must give the same result however many times
165
+ * they run (pass `reset` for fakes that keep state).
166
+ */
167
+ export declare function checkCrashRecovery<TMachine extends AnyStateMachine>(machine: TMachine, options?: CheckCrashRecoveryOptions<TMachine>): Promise<CrashRecoveryReport>;
168
+ //#endregion
6
169
  //#region src/trajectory.d.ts
7
170
  /** An event-shaped trajectory item: anything with a string `type`. */
8
171
  interface TrajectoryEvent {
@@ -1035,4 +1198,4 @@ interface CheckParityReport<TScenario extends CheckParityScenario, TOutput> {
1035
1198
  */
1036
1199
  export declare function checkParity<TScenario extends CheckParityScenario, TEffects extends object, TOutput>(options: CheckParityOptions<TScenario, TEffects, TOutput>): Promise<CheckParityReport<TScenario, TOutput>>;
1037
1200
  //#endregion
1038
- export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AgreementReport, type AgreementRow, type AgreementSummary, type ApprovalRuleProposal, type ApprovalVerdict, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CapProposal, type CapSpec, type CheckParityOptions, type CheckParityOutcome, type CheckParityReport, type CheckParityRow, type CheckParityScenario, type CompareRecordingsOptions, type CompareRunsOptions, type CoverageReport, type CreateRecorderOptions, type Divergence, type EffectDivergence, type EffectDivergenceReason, type EquivalenceReport, type ExplorePathsOptions, type ExploreSnapshot, type FirstDivergenceOptions, type FoldTracesOptions, type GetDecisionRequestsOptions, type HandlerCoverage, type HandlerRef, type JudgeAgreementOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ModelAnswer, type ModelCallMatch, type NormalizeEffect, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type ProposeApprovalRulesOptions, type ProposeCapsOptions, type RecordCallOptions, type RecordClientOptions, type RecordableDecisionModel, type RecordableLanguageModel, type RecordableModel, type RecordedCall, type RecordedEffect, type RecordedError, type RecordedModelCall, type RecordedOutput, type RecordedToolCall, type Recorder, type Recording, RecordingDivergenceError, type RepeatGroup, type RepeatReport, type RepeatResult, type RepeatRun, type RepeatRunsOptions, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateCoverage, type StateStats, type TraceCoverageOptions, type TraceStep, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryEventEnvelope, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, compareRecordings, createRecorder, explorePaths, lintAgentMachine, sameModelCallShape, simulateAgent, textOutput };
1201
+ export { type AgentLintDiagnostic, AgentLintError, type AgentLintSeverity, type AgentPathReport, type AgentPathTerminal, AgentUnknownStateError, type AgreementReport, type AgreementRow, type AgreementSummary, type ApprovalRuleProposal, type ApprovalVerdict, type AssertAgentMachineOptions, type CanReachResult, type CanReachTarget, type CapProposal, type CapSpec, type CheckCrashRecoveryOptions, type CheckParityOptions, type CheckParityOutcome, type CheckParityReport, type CheckParityRow, type CheckParityScenario, type CompareRecordingsOptions, type CompareRunsOptions, type CoverageReport, type CrashEffect, type CrashPoint, type CrashRecoveryFailure, type CrashRecoveryProblem, type CrashRecoveryReport, type CreateRecorderOptions, type Divergence, type EffectDivergence, type EffectDivergenceReason, type EquivalenceReport, type ExplorePathsOptions, type ExploreSnapshot, type FirstDivergenceOptions, type FoldTracesOptions, type GetDecisionRequestsOptions, type HandlerCoverage, type HandlerRef, type JudgeAgreementOptions, type LintAgentMachineOptions, type MatchTrajectoryOptions, type ModelAnswer, type ModelCallMatch, type NormalizeEffect, type ParityLabel, type ParityReport, type ParityResult, type ParityRun, type ProposeApprovalRulesOptions, type ProposeCapsOptions, type RecordCallOptions, type RecordClientOptions, type RecordableDecisionModel, type RecordableLanguageModel, type RecordableModel, type RecordedCall, type RecordedEffect, type RecordedError, type RecordedModelCall, type RecordedOutput, type RecordedToolCall, type Recorder, type Recording, RecordingDivergenceError, type RepeatGroup, type RepeatReport, type RepeatResult, type RepeatRun, type RepeatRunsOptions, type RunSeamOptions, type RunSeamResult, type SeamCall, type SeamRef, type SeamScriptEntry, type SeamSlice, type SeamTurn, type SimulateAgentOptions, type SimulateAgentResult, type SimulationScript, type SimulationTrailEntry, type StateCoverage, type StateStats, type TraceCoverageOptions, type TraceStep, type TracedDecisionRequest, type TrajectoryEvent, type TrajectoryEventEnvelope, type TrajectoryItem, type TrajectoryMatch, type TrajectoryMiss, assertAgentMachine, canReach, compareRecordings, createRecorder, explorePaths, lintAgentMachine, sameModelCallShape, simulateAgent, textOutput };