@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.20

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 (102) hide show
  1. package/README.md +46 -16
  2. package/dist/author.d.ts +96 -0
  3. package/dist/author.js +320 -0
  4. package/dist/authoring.js +1 -1
  5. package/dist/cli.js +8 -3
  6. package/dist/code-exec.d.ts +6 -0
  7. package/dist/code-exec.js +126 -0
  8. package/dist/decision-receipts.d.ts +98 -0
  9. package/dist/decision-receipts.js +51 -0
  10. package/dist/dry-run.d.ts +14 -1
  11. package/dist/dry-run.js +39 -13
  12. package/dist/graph.d.ts +83 -0
  13. package/dist/graph.js +231 -0
  14. package/dist/index.d.ts +12 -4
  15. package/dist/index.js +6 -2
  16. package/dist/inspection.js +2 -2
  17. package/dist/job.d.ts +14 -0
  18. package/dist/job.js +5 -0
  19. package/dist/long-timer.d.ts +7 -0
  20. package/dist/long-timer.js +22 -0
  21. package/dist/observer-snapshot.d.ts +3 -0
  22. package/dist/observer-snapshot.js +46 -0
  23. package/dist/predicates.d.ts +4 -0
  24. package/dist/predicates.js +19 -2
  25. package/dist/recovery/binding.d.ts +10 -0
  26. package/dist/recovery/binding.js +43 -0
  27. package/dist/recovery/call-key.d.ts +13 -0
  28. package/dist/recovery/call-key.js +24 -0
  29. package/dist/recovery/canonical-hash.d.ts +7 -0
  30. package/dist/recovery/canonical-hash.js +22 -0
  31. package/dist/recovery/driver.d.ts +208 -0
  32. package/dist/recovery/driver.js +1222 -0
  33. package/dist/recovery/effect-failure.d.ts +34 -0
  34. package/dist/recovery/effect-failure.js +62 -0
  35. package/dist/recovery/errors.d.ts +31 -0
  36. package/dist/recovery/errors.js +51 -0
  37. package/dist/recovery/execution-path.d.ts +53 -0
  38. package/dist/recovery/execution-path.js +167 -0
  39. package/dist/recovery/file-store.d.ts +7 -0
  40. package/dist/recovery/file-store.js +131 -0
  41. package/dist/recovery/frozen-snapshot.d.ts +244 -0
  42. package/dist/recovery/frozen-snapshot.js +171 -0
  43. package/dist/recovery/handoff-block.d.ts +36 -0
  44. package/dist/recovery/handoff-block.js +148 -0
  45. package/dist/recovery/handoff-digest.d.ts +58 -0
  46. package/dist/recovery/handoff-digest.js +195 -0
  47. package/dist/recovery/handoff-files.d.ts +54 -0
  48. package/dist/recovery/handoff-files.js +162 -0
  49. package/dist/recovery/handoff-receipts.d.ts +42 -0
  50. package/dist/recovery/handoff-receipts.js +53 -0
  51. package/dist/recovery/handoff-redact.d.ts +12 -0
  52. package/dist/recovery/handoff-redact.js +44 -0
  53. package/dist/recovery/handoff.d.ts +44 -0
  54. package/dist/recovery/handoff.js +46 -0
  55. package/dist/recovery/index.d.ts +18 -0
  56. package/dist/recovery/index.js +16 -0
  57. package/dist/recovery/item-state.d.ts +48 -0
  58. package/dist/recovery/item-state.js +89 -0
  59. package/dist/recovery/journal.d.ts +28 -0
  60. package/dist/recovery/journal.js +139 -0
  61. package/dist/recovery/memory-store.d.ts +4 -0
  62. package/dist/recovery/memory-store.js +20 -0
  63. package/dist/recovery/store.d.ts +105 -0
  64. package/dist/recovery/store.js +6 -0
  65. package/dist/recovery/testing/conformance.d.ts +4 -0
  66. package/dist/recovery/testing/conformance.js +268 -0
  67. package/dist/recovery/testing/crash-points.d.ts +18 -0
  68. package/dist/recovery/testing/crash-points.js +43 -0
  69. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  70. package/dist/recovery/testing/crash-sweep.js +146 -0
  71. package/dist/recovery/testing/index.d.ts +3 -0
  72. package/dist/recovery/testing/index.js +4 -0
  73. package/dist/recovery/testing/preload.d.ts +1 -0
  74. package/dist/recovery/testing/preload.js +3 -0
  75. package/dist/recovery/transport-facts.d.ts +23 -0
  76. package/dist/recovery/transport-facts.js +46 -0
  77. package/dist/recovery/with-recovery.d.ts +44 -0
  78. package/dist/recovery/with-recovery.js +87 -0
  79. package/dist/system-one.d.ts +17 -1
  80. package/dist/system-one.js +62 -5
  81. package/dist/vocabulary.d.ts +42 -0
  82. package/dist/vocabulary.js +74 -0
  83. package/dist/workflow-shape.d.ts +7 -0
  84. package/dist/workflow-shape.js +85 -62
  85. package/dist/workflow.d.ts +187 -16
  86. package/dist/workflow.js +967 -324
  87. package/package.json +18 -2
  88. package/schema/workflow.schema.json +251 -15
  89. package/skills/author/SKILL.md +122 -0
  90. package/skills/author/examples/evidence-gate.input.json +6 -0
  91. package/skills/author/examples/evidence-gate.json +125 -0
  92. package/skills/author/examples/read-file.input.json +1 -0
  93. package/skills/author/examples/read-file.json +44 -0
  94. package/skills/author/examples/read-source-decision.input.json +4 -0
  95. package/skills/author/examples/read-source-decision.json +37 -0
  96. package/skills/author/examples/release-note.txt +10 -0
  97. package/skills/author/examples/review-release-notes.input.json +6 -0
  98. package/skills/author/examples/review-release-notes.json +123 -0
  99. package/skills/author/references/jev-decisions.md +125 -0
  100. package/skills/author/references/language.md +118 -0
  101. package/skills/author/references/sdk-authoring.md +11 -0
  102. package/skills/author/references/workflow-format.md +137 -0
@@ -0,0 +1,268 @@
1
+ // The store conformance suite: what a RecoveryStore must hold for the driver's rules to rest on it. A store that
2
+ // passes carries them; a host that writes its own store registers this suite in its own tests.
3
+ import assert from "node:assert/strict";
4
+ import { test } from "node:test";
5
+ import { RecoveryError } from "../errors.js";
6
+ const BOUND = { binding: "binding-1", inputs: { workflow: "digest-a", "config.question": "digest-b" } };
7
+ const refused = (pattern) => (error) => {
8
+ assert.ok(error instanceof RecoveryError, `a store refuses with a RecoveryError, got ${String(error)}`);
9
+ if (pattern)
10
+ assert.match(error.message, pattern);
11
+ return true;
12
+ };
13
+ /** Registers the suite as `node:test` tests named under `name`. `create` returns a new, empty store on every call;
14
+ * the suite opens one store several times, as the successive processes of one run would. */
15
+ export function registerStoreConformance(name, create) {
16
+ const it = (title, body) => test(`${name}: ${title}`, async () => body(await create()));
17
+ it("a new journal is unbound and empty, and its first open is generation 1", async (store) => {
18
+ const journal = await store.open(BOUND);
19
+ assert.deepEqual([journal.existing, journal.generation, journal.state, journal.revision], [false, 1, null, 0]);
20
+ assert.deepEqual([journal.effects(), journal.notes(), journal.effect("absent")], [[], [], undefined]);
21
+ await journal.close();
22
+ });
23
+ it("every write is one commit: the revision advances by one, and the next open reads what was committed", async (store) => {
24
+ const first = await store.open(BOUND);
25
+ assert.equal(await first.save({ step: 1 }), 1);
26
+ assert.equal(await first.save((revision) => ({ step: 2, at: revision }), { kind: "escalation", detail: { why: "gate" } }), 2);
27
+ assert.equal(await first.note("inherited", { level: "full" }), 3);
28
+ assert.equal(first.revision, 3);
29
+ assert.deepEqual(first.notes().map((note) => [note.revision, note.kind, note.detail]), [[2, "escalation", { why: "gate" }], [3, "inherited", { level: "full" }]]);
30
+ await first.close();
31
+ const second = await store.open(BOUND);
32
+ assert.deepEqual([second.existing, second.generation, second.revision], [true, 2, 3]);
33
+ assert.deepEqual(second.state, { step: 2, at: 2 });
34
+ assert.deepEqual(second.notes().map((note) => [note.revision, note.kind, note.detail]), [[2, "escalation", { why: "gate" }], [3, "inherited", { level: "full" }]]);
35
+ assert.ok(second.notes().every((note) => !Number.isNaN(Date.parse(note.at))));
36
+ await second.close();
37
+ });
38
+ it("commits asked for together land one at a time, in the order they were asked for", async (store) => {
39
+ const journal = await store.open(BOUND);
40
+ const revisions = await Promise.all([journal.save({ n: 1 }), journal.save({ n: 2 }), journal.note("handoff", {}), journal.save({ n: 3 })]);
41
+ assert.deepEqual(revisions, [1, 2, 3, 4]);
42
+ await journal.close();
43
+ const next = await store.open(BOUND);
44
+ assert.deepEqual([next.state, next.revision], [{ n: 3 }, 4]);
45
+ await next.close();
46
+ });
47
+ it("admit commits the effect with the state that admits it; an id already admitted is returned as it stands and writes nothing", async (store) => {
48
+ const first = await store.open(BOUND);
49
+ assert.equal(await first.admit("e1", "lookup", "args-1", { admitted: ["e1"] }, "run-1"), "new");
50
+ assert.equal(first.revision, 1);
51
+ const held = { id: "e1", name: "lookup", argsHash: "args-1", status: "unknown", session: "run-1", result: null };
52
+ assert.deepEqual(await first.admit("e1", "other", "args-2", { admitted: [] }), held);
53
+ assert.equal(first.revision, 1);
54
+ await first.close();
55
+ const second = await store.open(BOUND);
56
+ assert.deepEqual(second.state, { admitted: ["e1"] });
57
+ assert.deepEqual(second.effects(), [held]);
58
+ assert.deepEqual(second.effect("e1"), held);
59
+ await second.close();
60
+ });
61
+ it("admit keeps the external call it is given with the effect, through its completion, at every later open; an effect admitted without one has none", async (store) => {
62
+ const intent = { tool: "registry_lookup", argsHash: "intent-1" };
63
+ const first = await store.open(BOUND);
64
+ assert.equal(await first.admit("e1", "lookup", "args-1", {}, "run-1", intent), "new");
65
+ assert.equal(await first.admit("e2", "render", "args-2", {}, "run-1"), "new");
66
+ const admitted = { id: "e1", name: "lookup", argsHash: "args-1", status: "unknown", session: "run-1", result: null, intent };
67
+ const plain = { id: "e2", name: "render", argsHash: "args-2", status: "unknown", session: "run-1", result: null };
68
+ assert.deepEqual([first.effect("e1"), first.effect("e2")], [admitted, plain]);
69
+ await first.close();
70
+ const second = await store.open(BOUND);
71
+ assert.deepEqual(second.effects(), [admitted, plain]);
72
+ await second.complete("e1", { value: 1 }, {});
73
+ await second.close();
74
+ const third = await store.open(BOUND);
75
+ assert.deepEqual(third.effects(), [{ ...admitted, status: "completed", result: { value: 1 } }, plain]);
76
+ assert.equal(Object.hasOwn(third.effect("e2"), "intent"), false);
77
+ await third.close();
78
+ });
79
+ it("admit keeps the arguments it is given with the effect, through its completion, at every later open; an effect admitted without them has none", async (store) => {
80
+ const args = { id: 7, nested: { list: [1, 2] } };
81
+ const first = await store.open(BOUND);
82
+ assert.equal(await first.admit("e1", "lookup", "args-1", {}, "run-1", undefined, args), "new");
83
+ assert.equal(await first.admit("e2", "render", "args-2", {}, "run-1", undefined, null), "new");
84
+ assert.equal(await first.admit("e3", "plain", "args-3", {}, "run-1"), "new");
85
+ const kept = { id: "e1", name: "lookup", argsHash: "args-1", status: "unknown", session: "run-1", result: null, args };
86
+ const empty = { id: "e2", name: "render", argsHash: "args-2", status: "unknown", session: "run-1", result: null, args: null };
87
+ const plain = { id: "e3", name: "plain", argsHash: "args-3", status: "unknown", session: "run-1", result: null };
88
+ assert.deepEqual(first.effects(), [kept, empty, plain]);
89
+ await first.close();
90
+ const second = await store.open(BOUND);
91
+ assert.deepEqual(second.effects(), [kept, empty, plain]);
92
+ await second.complete("e1", { value: 1 }, {});
93
+ await second.close();
94
+ const third = await store.open(BOUND);
95
+ assert.deepEqual(third.effects(), [{ ...kept, status: "completed", result: { value: 1 } }, empty, plain]);
96
+ assert.equal(Object.hasOwn(third.effect("e3"), "args"), false);
97
+ await third.close();
98
+ });
99
+ it("called keeps the outside calls with the effect: effects() carries them, replaced by each list given, through completion and at every later open", async (store) => {
100
+ const first = await store.open(BOUND);
101
+ await first.admit("e1", "lookup", "args-1", {});
102
+ await first.admit("e2", "render", "args-2", {});
103
+ await first.called("e1", [{ outcome: "applied" }]);
104
+ assert.deepEqual(first.effect("e1").calls, [{ outcome: "applied" }]);
105
+ await first.called("e1", [{ outcome: "applied" }, { outcome: "applied", again: true }]);
106
+ assert.equal(Object.hasOwn(first.effect("e2"), "calls"), false);
107
+ await first.close();
108
+ const second = await store.open(BOUND);
109
+ assert.deepEqual(second.effect("e1").calls, [{ outcome: "applied" }, { outcome: "applied", again: true }]);
110
+ await second.complete("e1", { value: 1 }, {});
111
+ assert.deepEqual(second.effect("e1").calls, [{ outcome: "applied" }, { outcome: "applied", again: true }]);
112
+ await second.close();
113
+ const third = await store.open(BOUND);
114
+ assert.deepEqual(third.effects().map((effect) => [effect.id, effect.status, effect.calls]), [["e1", "completed", [{ outcome: "applied" }, { outcome: "applied", again: true }]], ["e2", "unknown", undefined]]);
115
+ await third.close();
116
+ });
117
+ it("an effect admitted and never completed is unknown at every later open", async (store) => {
118
+ const first = await store.open(BOUND);
119
+ await first.admit("e1", "lookup", "args-1", {});
120
+ await first.called("e1", [{ tool: "lookup", ok: false }]);
121
+ await first.close();
122
+ for (const generation of [2, 3]) {
123
+ const later = await store.open(BOUND);
124
+ assert.deepEqual([later.generation, later.effect("e1")?.status, later.effect("e1")?.result, later.effect("e1")?.session], [generation, "unknown", null, null]);
125
+ await later.close();
126
+ }
127
+ });
128
+ it("complete stores the result with the state that follows, once, and never without an admission", async (store) => {
129
+ const first = await store.open(BOUND);
130
+ await first.admit("e1", "lookup", "args-1", { phase: "admitted" });
131
+ await assert.rejects(first.complete("e0", { value: 1 }, {}), refused());
132
+ await first.complete("e1", { value: 7, files: {} }, { phase: "completed" });
133
+ await assert.rejects(first.complete("e1", { value: 8 }, { phase: "twice" }), refused());
134
+ assert.deepEqual([first.effect("e1")?.status, first.effect("e1")?.result], ["completed", { value: 7, files: {} }]);
135
+ await first.close();
136
+ const second = await store.open(BOUND);
137
+ assert.deepEqual([second.state, second.effect("e1")?.status, second.effect("e1")?.result], [{ phase: "completed" }, "completed", { value: 7, files: {} }]);
138
+ await second.close();
139
+ });
140
+ it("an effect completed with no state keeps the state the open found: a reconciliation", async (store) => {
141
+ const first = await store.open(BOUND);
142
+ await first.admit("e1", "lookup", "args-1", { phase: "admitted" });
143
+ await first.close();
144
+ const operator = await store.open(BOUND);
145
+ await operator.complete("e1", { value: 7 });
146
+ await operator.close();
147
+ const third = await store.open(BOUND);
148
+ assert.deepEqual([third.state, third.effect("e1")?.status, third.effect("e1")?.result], [{ phase: "admitted" }, "completed", { value: 7 }]);
149
+ await third.close();
150
+ });
151
+ it("calls are kept only for an admitted effect, and keeping them completes nothing", async (store) => {
152
+ const journal = await store.open(BOUND);
153
+ await assert.rejects(journal.called("e1", []), refused());
154
+ await journal.admit("e1", "lookup", "args-1", {});
155
+ await journal.called("e1", [{ tool: "lookup" }]);
156
+ assert.deepEqual([journal.revision, journal.effect("e1")?.status], [2, "unknown"]);
157
+ await journal.close();
158
+ });
159
+ it("a journal has one owner: a second open of a live journal is refused, and closing lets the next one in", async (store) => {
160
+ const owner = await store.open(BOUND);
161
+ await owner.save({ by: "owner" });
162
+ await assert.rejects(store.open(BOUND), refused());
163
+ await owner.save({ by: "owner", still: true });
164
+ await owner.close();
165
+ await owner.close();
166
+ const next = await store.open(BOUND);
167
+ assert.deepEqual([next.generation, next.state], [2, { by: "owner", still: true }]);
168
+ await next.close();
169
+ });
170
+ it("a closed journal commits nothing", async (store) => {
171
+ const first = await store.open(BOUND);
172
+ await first.save({ kept: true });
173
+ await first.close();
174
+ await assert.rejects(first.save({ kept: false }), refused());
175
+ await assert.rejects(first.admit("e1", "lookup", "args-1", {}), refused());
176
+ const second = await store.open(BOUND);
177
+ assert.deepEqual([second.state, second.revision, second.effects()], [{ kept: true }, 1, []]);
178
+ await second.close();
179
+ });
180
+ it("a binding that differs is refused naming the inputs that moved; the journal stays as it was", async (store) => {
181
+ const first = await store.open(BOUND);
182
+ await first.save({ kept: true });
183
+ await first.close();
184
+ const moved = { binding: "binding-2", inputs: { workflow: "digest-a", "config.question": "digest-c", cwd: "digest-d" } };
185
+ await assert.rejects(store.open(moved), (error) => {
186
+ refused(/^Run store binding mismatch: config\.question, cwd \(new\) changed since the run was bound$/)(error);
187
+ assert.deepEqual([error.code, error.moved], ["RUN_STORE_BINDING_MISMATCH", ["config.question", "cwd"]]);
188
+ return true;
189
+ });
190
+ await assert.rejects(store.open({ binding: "binding-2" }), refused(/^Run store binding mismatch: the opener named no input digests, so the input that moved cannot be named$/));
191
+ const again = await store.open(BOUND);
192
+ assert.deepEqual([again.existing, again.generation, again.state], [true, 2, { kept: true }]);
193
+ await again.close();
194
+ });
195
+ it("values are stored as plain JSON, and a write that cannot be stored writes nothing at all", async (store) => {
196
+ const first = await store.open(BOUND);
197
+ await first.save({ kept: 1, dropped: undefined, nested: [undefined, { at: new Date(0) }] });
198
+ await assert.rejects(first.save({ bad: Number.NaN }), refused());
199
+ await assert.rejects(first.admit("e1", "lookup", "args-1", { bad: Number.POSITIVE_INFINITY }), refused());
200
+ assert.deepEqual([first.revision, first.effects()], [1, []]);
201
+ assert.equal(await first.save(undefined), 2);
202
+ await first.close();
203
+ const second = await store.open(BOUND);
204
+ assert.deepEqual([second.state, second.revision, second.effects()], [null, 2, []]);
205
+ await second.close();
206
+ const third = await store.open(BOUND);
207
+ await third.save({ kept: 1, dropped: undefined, nested: [undefined, { at: new Date(0) }] });
208
+ await third.close();
209
+ const fourth = await store.open(BOUND);
210
+ assert.deepEqual(fourth.state, { kept: 1, nested: [null, { at: "1970-01-01T00:00:00.000Z" }] });
211
+ await fourth.close();
212
+ });
213
+ // Parts: a store that keeps them declares it with both reads, `items` and `stateOf`; a store with neither keeps the
214
+ // driver's whole state in one record, and these cases hold for it trivially.
215
+ const keeps = (journal) => {
216
+ assert.equal(typeof journal.items === "function", typeof journal.stateOf === "function", "a store declares both items and stateOf, or neither");
217
+ return typeof journal.items === "function";
218
+ };
219
+ const ITEM = "/root/steps/0/items/0";
220
+ it("parts are kept beside the state, in the same commit: an item's record replaced whole at each write, a state written once", async (store) => {
221
+ const first = await store.open(BOUND);
222
+ if (!keeps(first)) {
223
+ await first.close();
224
+ return;
225
+ }
226
+ assert.equal(await first.save({ n: 1 }, undefined, (revision) => ({ items: { [ITEM]: { effects: [], status: "running", revision } }, states: { "sha-a": { a: 1 } } })), 1);
227
+ assert.equal(await first.save({ n: 2 }, undefined, (revision) => ({ items: { [ITEM]: { effects: [], revision } }, states: { "sha-a": { a: "rewritten" }, "sha-b": { b: 2 } } })), 2);
228
+ await first.close();
229
+ const second = await store.open(BOUND);
230
+ assert.deepEqual(await second.items([ITEM, "/root/steps/0/items/1"]), [{ effects: [], revision: 2 }, undefined]);
231
+ assert.deepEqual([await second.stateOf("sha-a"), await second.stateOf("sha-b")], [{ a: 1 }, { b: 2 }]);
232
+ assert.deepEqual(second.state, { n: 2 });
233
+ await second.close();
234
+ });
235
+ it("an effect admitted with an owner is listed by the owner's record, and by effects() once that record is read", async (store) => {
236
+ const first = await store.open(BOUND);
237
+ if (!keeps(first)) {
238
+ await first.close();
239
+ return;
240
+ }
241
+ const owned = (ids) => () => ({ items: { [ITEM]: { effects: ids } } });
242
+ assert.equal(await first.admit("e1", "lookup", "args-1", { n: 1 }, "run-1", undefined, { id: 1 }, owned(["e1"]), ITEM), "new");
243
+ assert.equal(await first.admit("e2", "lookup", "args-2", { n: 2 }, "run-1", undefined, undefined, owned(["e1", "e2"]), ITEM), "new");
244
+ await first.complete("e1", { value: 1 }, { n: 3 }, owned(["e1", "e2"]));
245
+ await first.close();
246
+ const second = await store.open(BOUND);
247
+ const [record] = await second.items([ITEM]);
248
+ assert.deepEqual(record?.effects, ["e1", "e2"]);
249
+ assert.deepEqual(second.effects().map((effect) => [effect.id, effect.status, effect.result]).sort(), [["e1", "completed", { value: 1 }], ["e2", "unknown", null]]);
250
+ assert.deepEqual(second.effect("e1")?.args, { id: 1 });
251
+ assert.deepEqual(second.state, { n: 3 });
252
+ await second.close();
253
+ });
254
+ it("a write whose parts cannot be stored writes nothing at all, its state included", async (store) => {
255
+ const first = await store.open(BOUND);
256
+ if (!keeps(first)) {
257
+ await first.close();
258
+ return;
259
+ }
260
+ await first.save({ kept: 1 });
261
+ await assert.rejects(first.save({ kept: 2 }, undefined, () => ({ items: { [ITEM]: { effects: [], bad: Number.POSITIVE_INFINITY } } })), refused());
262
+ assert.equal(first.revision, 1);
263
+ await first.close();
264
+ const second = await store.open(BOUND);
265
+ assert.deepEqual([second.state, second.revision, await second.items([ITEM])], [{ kept: 1 }, 1, [undefined]]);
266
+ await second.close();
267
+ });
268
+ }
@@ -0,0 +1,18 @@
1
+ export declare const CRASH_POINTS: readonly ["admit", "dispatch", "settle", "commit", "session", "request", "submit"];
2
+ export type CrashPoint = (typeof CRASH_POINTS)[number];
3
+ /** The environment variable that carries the plan to the child, as JSON. */
4
+ export declare const CRASH_PLAN_ENV = "AGENTRUN_CRASH_PLAN";
5
+ export type CrashPlan = {
6
+ mode: "census";
7
+ file: string;
8
+ } | {
9
+ mode: "kill";
10
+ point: CrashPoint;
11
+ nth: number;
12
+ };
13
+ /** Cross `point`. Without a plan it does nothing; in a census it records the crossing; in a kill plan the nth crossing
14
+ * of the planned point ends this process with SIGKILL, and never returns. */
15
+ export declare function crossing(point: CrashPoint): Promise<void>;
16
+ /** Make `crossing` reachable as `globalThis[Symbol.for("agentrun.crash.crossing")]`, for a child whose code does not
17
+ * import this module. */
18
+ export declare function installCrossing(): void;
@@ -0,0 +1,43 @@
1
+ // The child side of a crash sweep: a process that crosses named points of a run, and either counts the crossings (the
2
+ // census) or kills itself at one of them. A point is crossed just before the step it names:
3
+ // admit before an effect is admitted: nothing of it is durable
4
+ // dispatch after the admission is durable, before the call goes out
5
+ // settle after the call returned, before its result is committed
6
+ // commit before the node that ran is committed
7
+ // session before an agent step's conversation is created
8
+ // request while a model request is in flight
9
+ // submit while the step's submission is being taken
10
+ import { appendFileSync } from "node:fs";
11
+ export const CRASH_POINTS = ["admit", "dispatch", "settle", "commit", "session", "request", "submit"];
12
+ /** The environment variable that carries the plan to the child, as JSON. */
13
+ export const CRASH_PLAN_ENV = "AGENTRUN_CRASH_PLAN";
14
+ const SLOT = Symbol.for("agentrun.crash.crossing");
15
+ function planOf(env) {
16
+ const text = env[CRASH_PLAN_ENV];
17
+ return text ? JSON.parse(text) : undefined;
18
+ }
19
+ const crossed = new Map();
20
+ /** Cross `point`. Without a plan it does nothing; in a census it records the crossing; in a kill plan the nth crossing
21
+ * of the planned point ends this process with SIGKILL, and never returns. */
22
+ export async function crossing(point) {
23
+ const plan = planOf(process.env);
24
+ if (!plan)
25
+ return;
26
+ if (plan.mode === "census") {
27
+ appendFileSync(plan.file, `${point}\n`);
28
+ return;
29
+ }
30
+ if (plan.point !== point)
31
+ return;
32
+ const nth = (crossed.get(point) ?? 0) + 1;
33
+ crossed.set(point, nth);
34
+ if (nth !== plan.nth)
35
+ return;
36
+ process.kill(process.pid, "SIGKILL");
37
+ await new Promise(() => { });
38
+ }
39
+ /** Make `crossing` reachable as `globalThis[Symbol.for("agentrun.crash.crossing")]`, for a child whose code does not
40
+ * import this module. */
41
+ export function installCrossing() {
42
+ globalThis[SLOT] = crossing;
43
+ }
@@ -0,0 +1,65 @@
1
+ import { type CrashPoint } from "./crash-points.js";
2
+ /** What a child reports: how it ended (an exit code, or the signal that killed it), the JSON lines it printed, and
3
+ * what it wrote to stderr. By convention a child that ends its run prints `{"outcome": ...}` and exits 0. */
4
+ export type ChildRun = {
5
+ exit: number | string | null;
6
+ rows: Array<Record<string, unknown>>;
7
+ stderr: string;
8
+ timedOut?: boolean;
9
+ };
10
+ /** The header a child's calls carry, and the environment variable that holds its value. */
11
+ export declare const COUNT_TOKEN_HEADER = "x-agentrun-count-token";
12
+ export declare const COUNT_TOKEN_ENV = "COUNT_TOKEN";
13
+ /** The requests a counting server has seen, by path: only those that carry its token, since anything else on this
14
+ * machine may reach a port this server holds. */
15
+ export type CountingServer = {
16
+ url: string;
17
+ token: string;
18
+ counts: Record<string, number>;
19
+ close(): Promise<void>;
20
+ };
21
+ /** A server for the calls a child's effects make, counted by path. A request counts when it carries the server's token
22
+ * in the `x-agentrun-count-token` header. `POST /effect/<id>` answers `{ ok: true, id }`; any other path answers
23
+ * `{ ok: true }`. */
24
+ export declare function countingServer(): Promise<CountingServer>;
25
+ export type SweepCase = {
26
+ point: CrashPoint;
27
+ nth: number;
28
+ /** The process that was killed. */
29
+ killed: ChildRun;
30
+ /** The process that resumed the run, then one more that opened it after it ended. */
31
+ resumed: ChildRun;
32
+ reopened: ChildRun;
33
+ /** The counting server's counts after each process: killed, resumed, reopened. */
34
+ counts: Array<Record<string, number>>;
35
+ violations: string[];
36
+ };
37
+ export type SweepOptions = {
38
+ /** The child script. It is run as `node` with the preload module loaded, then `<child> <start|resume> <directory>` in a run directory
39
+ * that holds the run, with `COUNT_URL` set to the counting server, `COUNT_TOKEN` to the token its calls carry, and the crash plan in `AGENTRUN_CRASH_PLAN`.
40
+ * `start` begins the run and `resume` opens one a process left, and both print their outcome. */
41
+ child: string;
42
+ /** Extra environment for every child (a planted fault, a fixture's knobs). */
43
+ env?: Record<string, string>;
44
+ /** Points to sweep; default every point the census crossed. */
45
+ points?: readonly CrashPoint[];
46
+ /** 1 resumes in the run's own directory; 2 resumes in a copy of it, as a second machine would that was handed the
47
+ * run's files. */
48
+ machines?: 1 | 2;
49
+ /** What the sweep checks beyond the at-most-once rule: the reasons this case is wrong, if it is. `census` is the
50
+ * uncut run. */
51
+ expect?(found: SweepCase, census: ChildRun): string[];
52
+ /** A directory for the run directories; default the system's temporary directory. */
53
+ directory?: string;
54
+ /** Most milliseconds a child may run; one that is still running then is killed, and the case reports it. Default 60 000. */
55
+ timeoutMs?: number;
56
+ };
57
+ export type SweepResult = {
58
+ census: ChildRun;
59
+ crossings: Record<string, number>;
60
+ cases: SweepCase[];
61
+ violations: string[];
62
+ };
63
+ /** Run the sweep. The census runs the workflow once with nothing killed; every crossing it counted is then cut in a
64
+ * fresh run, resumed by a later process, and opened once more after the run ended, which changes nothing. */
65
+ export declare function crashSweep(options: SweepOptions): Promise<SweepResult>;
@@ -0,0 +1,146 @@
1
+ // The census-then-kill sweep. A child runs the workflow once with the crossings counted (the census); then, for every
2
+ // crossing of every point, a fresh run is killed there and a later process resumes it. The calls the child makes go to a
3
+ // counting server in this process, outside every killed one, so what was dispatched is read from the one place a kill
4
+ // cannot reach. The sweep holds the at-most-once rule: no effect is dispatched twice, whichever crossing was cut.
5
+ import { spawn } from "node:child_process";
6
+ import { randomUUID } from "node:crypto";
7
+ import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
8
+ import http from "node:http";
9
+ import { tmpdir } from "node:os";
10
+ import { join } from "node:path";
11
+ import { fileURLToPath } from "node:url";
12
+ import { CRASH_PLAN_ENV, CRASH_POINTS } from "./crash-points.js";
13
+ const LOOPBACK = "127.0.0.1";
14
+ /** The header a child's calls carry, and the environment variable that holds its value. */
15
+ export const COUNT_TOKEN_HEADER = "x-agentrun-count-token";
16
+ export const COUNT_TOKEN_ENV = "COUNT_TOKEN";
17
+ /** A server for the calls a child's effects make, counted by path. A request counts when it carries the server's token
18
+ * in the `x-agentrun-count-token` header. `POST /effect/<id>` answers `{ ok: true, id }`; any other path answers
19
+ * `{ ok: true }`. */
20
+ export async function countingServer() {
21
+ const counts = {};
22
+ const token = randomUUID();
23
+ const server = http.createServer((request, response) => {
24
+ request.resume();
25
+ if (request.headers[COUNT_TOKEN_HEADER] === token)
26
+ counts[request.url ?? "/"] = (counts[request.url ?? "/"] ?? 0) + 1;
27
+ response.setHeader("content-type", "application/json");
28
+ response.end(JSON.stringify({ ok: true, id: request.url?.startsWith("/effect/") ? request.url.slice("/effect/".length) : undefined }));
29
+ });
30
+ await new Promise((resolve) => server.listen(0, LOOPBACK, resolve));
31
+ const address = server.address();
32
+ return { url: `http://${LOOPBACK}:${address.port}`, token, counts, close: () => new Promise((resolve) => { server.close(() => resolve()); server.closeAllConnections(); }) };
33
+ }
34
+ const PRELOAD = fileURLToPath(new URL("./preload.js", import.meta.url));
35
+ function runChild(options, server, mode, directory, plan) {
36
+ return new Promise((resolve) => {
37
+ const env = { ...process.env, ...options.env, COUNT_URL: server.url, [COUNT_TOKEN_ENV]: server.token };
38
+ delete env.NODE_TEST_CONTEXT;
39
+ delete env[CRASH_PLAN_ENV];
40
+ if (plan)
41
+ env[CRASH_PLAN_ENV] = JSON.stringify(plan);
42
+ const child = spawn(process.execPath, [`--import=${PRELOAD}`, options.child, mode, directory], { env, stdio: ["ignore", "pipe", "pipe"] });
43
+ let out = "";
44
+ let err = "";
45
+ let timedOut = false;
46
+ const deadline = setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, options.timeoutMs ?? 60_000);
47
+ child.stdout.on("data", (chunk) => { out += chunk; });
48
+ child.stderr.on("data", (chunk) => { err += chunk; });
49
+ child.on("close", (code, signal) => {
50
+ clearTimeout(deadline);
51
+ resolve({
52
+ exit: signal ?? code,
53
+ rows: out.split("\n").filter(Boolean).flatMap((line) => { try {
54
+ return [JSON.parse(line)];
55
+ }
56
+ catch {
57
+ return [];
58
+ } }),
59
+ stderr: err.trim(),
60
+ ...(timedOut ? { timedOut } : {}),
61
+ });
62
+ });
63
+ });
64
+ }
65
+ /** Why a child that was meant to end its run did not: it ran past its deadline, exited non-zero or printed no outcome. */
66
+ const didNotEnd = (run, what, timeoutMs) => {
67
+ if (run.timedOut)
68
+ return `${what} was still running after ${timeoutMs} ms and was killed`;
69
+ if (run.exit !== 0 || outcomeOf(run) === undefined)
70
+ return `${what} did not end its run: exit ${run.exit}${run.stderr ? `, ${run.stderr.slice(0, 200)}` : ""}`;
71
+ return undefined;
72
+ };
73
+ const outcomeOf = (run) => run.rows.find((row) => row.outcome !== undefined)?.outcome;
74
+ /** The effects dispatched more than once, as the reasons the rule failed. */
75
+ const doubled = (counts) => Object.entries(counts).filter(([path, count]) => path.startsWith("/effect/") && count > 1).map(([path, count]) => `${path} was dispatched ${count} times`);
76
+ /** Run the sweep. The census runs the workflow once with nothing killed; every crossing it counted is then cut in a
77
+ * fresh run, resumed by a later process, and opened once more after the run ended, which changes nothing. */
78
+ export async function crashSweep(options) {
79
+ const server = await countingServer();
80
+ const timeoutMs = options.timeoutMs ?? 60_000;
81
+ let base = "";
82
+ const fresh = (name) => { const directory = join(base, name); mkdirSync(directory); return directory; };
83
+ try {
84
+ base = mkdtempSync(join(options.directory ?? tmpdir(), "agentrun-crash-"));
85
+ const clear = () => { for (const key of Object.keys(server.counts))
86
+ delete server.counts[key]; };
87
+ const census = await (async () => {
88
+ const directory = fresh("census");
89
+ const file = join(base, "census.log");
90
+ writeFileSync(file, "");
91
+ return runChild(options, server, "start", directory, { mode: "census", file });
92
+ })();
93
+ const crossings = {};
94
+ for (const point of readFileSync(join(base, "census.log"), "utf8").split("\n").filter(Boolean))
95
+ crossings[point] = (crossings[point] ?? 0) + 1;
96
+ const violations = [];
97
+ const censusFailure = didNotEnd(census, "the census run", timeoutMs);
98
+ if (censusFailure)
99
+ violations.push(censusFailure);
100
+ violations.push(...doubled(server.counts).map((reason) => `census: ${reason}`));
101
+ const cases = [];
102
+ for (const point of options.points ?? CRASH_POINTS.filter((candidate) => crossings[candidate])) {
103
+ for (let nth = 1; nth <= (crossings[point] ?? 0); nth += 1) {
104
+ clear();
105
+ const name = `${point}-${nth}`;
106
+ const one = fresh(`${name}-a`);
107
+ const killed = await runChild(options, server, "start", one, { mode: "kill", point, nth });
108
+ const afterKilled = { ...server.counts };
109
+ let there = one;
110
+ if (options.machines === 2) {
111
+ there = join(base, `${name}-b`);
112
+ cpSync(one, there, { recursive: true });
113
+ }
114
+ const resumed = await runChild(options, server, "resume", there, undefined);
115
+ const afterResumed = { ...server.counts };
116
+ const reopened = await runChild(options, server, "resume", there, undefined);
117
+ const found = { point, nth, killed, resumed, reopened, counts: [afterKilled, afterResumed, { ...server.counts }], violations: [] };
118
+ if (killed.timedOut)
119
+ found.violations.push(`the process cut at ${name} was still running after ${timeoutMs} ms and was killed`);
120
+ else if (killed.exit !== "SIGKILL")
121
+ found.violations.push(`the kill at ${name} did not land: exit ${killed.exit}`);
122
+ const resumeFailure = didNotEnd(resumed, `the resume after ${name}`, timeoutMs);
123
+ if (resumeFailure)
124
+ found.violations.push(resumeFailure);
125
+ const reopenFailure = didNotEnd(reopened, `a later open after ${name}`, timeoutMs);
126
+ if (reopenFailure)
127
+ found.violations.push(reopenFailure);
128
+ found.violations.push(...doubled(server.counts));
129
+ if (JSON.stringify(outcomeOf(reopened)) !== JSON.stringify(outcomeOf(resumed)))
130
+ found.violations.push(`a later open after ${name} changed the run's outcome`);
131
+ const made = Object.keys(server.counts).filter((path) => server.counts[path] !== (afterResumed[path] ?? 0));
132
+ if (made.length)
133
+ found.violations.push(`a later open after ${name} made calls: ${made.join(", ")}`);
134
+ found.violations.push(...(options.expect?.(found, census) ?? []));
135
+ cases.push(found);
136
+ violations.push(...found.violations.map((reason) => `${name}: ${reason}`));
137
+ }
138
+ }
139
+ return { census, crossings, cases, violations };
140
+ }
141
+ finally {
142
+ await server.close();
143
+ if (base)
144
+ rmSync(base, { recursive: true, force: true });
145
+ }
146
+ }
@@ -0,0 +1,3 @@
1
+ export { registerStoreConformance } from "./conformance.js";
2
+ export { CRASH_PLAN_ENV, CRASH_POINTS, crossing, installCrossing, type CrashPlan, type CrashPoint } from "./crash-points.js";
3
+ export { COUNT_TOKEN_ENV, COUNT_TOKEN_HEADER, countingServer, crashSweep, type ChildRun, type CountingServer, type SweepCase, type SweepOptions, type SweepResult } from "./crash-sweep.js";
@@ -0,0 +1,4 @@
1
+ // Test support for recovery stores and the hosts that use them. No runtime entry point of this package imports it.
2
+ export { registerStoreConformance } from "./conformance.js";
3
+ export { CRASH_PLAN_ENV, CRASH_POINTS, crossing, installCrossing } from "./crash-points.js";
4
+ export { COUNT_TOKEN_ENV, COUNT_TOKEN_HEADER, countingServer, crashSweep } from "./crash-sweep.js";
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,3 @@
1
+ // Loaded in a child with `node --import`: installs the crossing function before the child's own code runs.
2
+ import { installCrossing } from "./crash-points.js";
3
+ installCrossing();
@@ -0,0 +1,23 @@
1
+ import type { CallRetryClass } from "../workflow.js";
2
+ export type TransportFact = {
3
+ /** The HTTP status the response carried, when one arrived. */
4
+ status?: number;
5
+ /** The thrown error's class name: TimeoutError (a deadline), AbortError, TypeError. */
6
+ errorName?: string;
7
+ /** The Node or undici system code on the error or its cause chain (ECONNRESET, UND_ERR_SOCKET, ENOTFOUND). */
8
+ causeCode?: string;
9
+ /** The provider's error object `type`, when a throw site attached it. */
10
+ providerType?: string;
11
+ /** The provider's error object `code`, from the same place. */
12
+ providerCode?: string;
13
+ /** Which deadline cut a silent stream: no response headers, or no bytes mid-body. */
14
+ idle?: "headers" | "body";
15
+ };
16
+ /** The typed facts an error carries: a `transport` record a throw site attached, else its class
17
+ * name, its string `code` (a system code) and a numeric `status`, walking the cause chain; the
18
+ * first value found for each field wins. Message text is never read. */
19
+ export declare function transportFactOf(error: unknown): TransportFact;
20
+ /** The retry class a failed effect earns from its typed facts, or null: only a failure transient
21
+ * by nature (a deadline, a 408 or 429, a 5xx, a dropped or refused connection) earns one. The
22
+ * classes are the workflow's call retry classes. */
23
+ export declare function effectRetryClass(fact: TransportFact): CallRetryClass | null;
@@ -0,0 +1,46 @@
1
+ // What a request's transport knew when it failed, and the retry class an effect earns from it.
2
+ //
3
+ // A failure is classified from typed fields the error carries (the HTTP status, the thrown error's
4
+ // class name, the system code on it or its cause, which deadline cut a silent stream), never from
5
+ // the text of an error message.
6
+ // ---- reading typed fields off a thrown error ----------------------------------------------------
7
+ const asCode = (value) => (typeof value === "string" && value ? value : undefined);
8
+ /** The typed facts an error carries: a `transport` record a throw site attached, else its class
9
+ * name, its string `code` (a system code) and a numeric `status`, walking the cause chain; the
10
+ * first value found for each field wins. Message text is never read. */
11
+ export function transportFactOf(error) {
12
+ const out = {};
13
+ let current = error;
14
+ for (let depth = 0; current && typeof current === "object" && depth < 6; depth += 1, current = current.cause) {
15
+ const attached = current.transport;
16
+ if (attached && typeof attached === "object") {
17
+ for (const [key, value] of Object.entries(attached))
18
+ if (value !== undefined && out[key] === undefined)
19
+ out[key] = value;
20
+ }
21
+ if (out.errorName === undefined && typeof current.name === "string" && current.name !== "Error")
22
+ out.errorName = current.name;
23
+ if (out.causeCode === undefined && asCode(current.code))
24
+ out.causeCode = asCode(current.code);
25
+ if (out.status === undefined && Number.isInteger(current.status))
26
+ out.status = current.status;
27
+ }
28
+ return out;
29
+ }
30
+ // ---- effects (tool calls) -------------------------------------------------------------------------
31
+ const TIMEOUT_CAUSES = new Set(["ETIMEDOUT", "UND_ERR_CONNECT_TIMEOUT", "UND_ERR_HEADERS_TIMEOUT", "UND_ERR_BODY_TIMEOUT"]);
32
+ const CONNECTION_CAUSES = new Set(["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "EPIPE", "ECONNABORTED", "UND_ERR_SOCKET", "UND_ERR_CLOSED"]);
33
+ /** The retry class a failed effect earns from its typed facts, or null: only a failure transient
34
+ * by nature (a deadline, a 408 or 429, a 5xx, a dropped or refused connection) earns one. The
35
+ * classes are the workflow's call retry classes. */
36
+ export function effectRetryClass(fact) {
37
+ if (fact.errorName === "TimeoutError" || fact.idle || fact.status === 408 || (fact.causeCode && TIMEOUT_CAUSES.has(fact.causeCode)))
38
+ return "timeout";
39
+ if (fact.status === 429)
40
+ return "http_429";
41
+ if (fact.status !== undefined && fact.status >= 500 && fact.status <= 599)
42
+ return "http_5xx";
43
+ if (fact.causeCode && CONNECTION_CAUSES.has(fact.causeCode))
44
+ return "connection";
45
+ return null;
46
+ }