@parcha/agentrun-dsl 0.1.0-beta.11 → 0.1.0-beta.13

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 (61) hide show
  1. package/dist/author.d.ts +9 -2
  2. package/dist/author.js +6 -3
  3. package/dist/decision-receipts.d.ts +98 -0
  4. package/dist/decision-receipts.js +51 -0
  5. package/dist/index.d.ts +5 -3
  6. package/dist/index.js +2 -1
  7. package/dist/recovery/binding.d.ts +10 -0
  8. package/dist/recovery/binding.js +43 -0
  9. package/dist/recovery/call-key.d.ts +13 -0
  10. package/dist/recovery/call-key.js +24 -0
  11. package/dist/recovery/canonical-hash.d.ts +7 -0
  12. package/dist/recovery/canonical-hash.js +22 -0
  13. package/dist/recovery/driver.d.ts +186 -0
  14. package/dist/recovery/driver.js +777 -0
  15. package/dist/recovery/effect-failure.d.ts +34 -0
  16. package/dist/recovery/effect-failure.js +62 -0
  17. package/dist/recovery/errors.d.ts +31 -0
  18. package/dist/recovery/errors.js +51 -0
  19. package/dist/recovery/execution-path.d.ts +45 -0
  20. package/dist/recovery/execution-path.js +153 -0
  21. package/dist/recovery/file-store.d.ts +7 -0
  22. package/dist/recovery/file-store.js +131 -0
  23. package/dist/recovery/frozen-snapshot.d.ts +149 -0
  24. package/dist/recovery/frozen-snapshot.js +136 -0
  25. package/dist/recovery/handoff-block.d.ts +36 -0
  26. package/dist/recovery/handoff-block.js +148 -0
  27. package/dist/recovery/handoff-digest.d.ts +58 -0
  28. package/dist/recovery/handoff-digest.js +195 -0
  29. package/dist/recovery/handoff-files.d.ts +54 -0
  30. package/dist/recovery/handoff-files.js +162 -0
  31. package/dist/recovery/handoff-receipts.d.ts +42 -0
  32. package/dist/recovery/handoff-receipts.js +53 -0
  33. package/dist/recovery/handoff-redact.d.ts +12 -0
  34. package/dist/recovery/handoff-redact.js +44 -0
  35. package/dist/recovery/handoff.d.ts +44 -0
  36. package/dist/recovery/handoff.js +46 -0
  37. package/dist/recovery/index.d.ts +18 -0
  38. package/dist/recovery/index.js +16 -0
  39. package/dist/recovery/journal.d.ts +25 -0
  40. package/dist/recovery/journal.js +127 -0
  41. package/dist/recovery/memory-store.d.ts +4 -0
  42. package/dist/recovery/memory-store.js +20 -0
  43. package/dist/recovery/store.d.ts +81 -0
  44. package/dist/recovery/store.js +6 -0
  45. package/dist/recovery/testing/conformance.d.ts +4 -0
  46. package/dist/recovery/testing/conformance.js +213 -0
  47. package/dist/recovery/testing/crash-points.d.ts +18 -0
  48. package/dist/recovery/testing/crash-points.js +43 -0
  49. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  50. package/dist/recovery/testing/crash-sweep.js +146 -0
  51. package/dist/recovery/testing/index.d.ts +3 -0
  52. package/dist/recovery/testing/index.js +4 -0
  53. package/dist/recovery/testing/preload.d.ts +1 -0
  54. package/dist/recovery/testing/preload.js +3 -0
  55. package/dist/recovery/transport-facts.d.ts +23 -0
  56. package/dist/recovery/transport-facts.js +46 -0
  57. package/dist/recovery/with-recovery.d.ts +44 -0
  58. package/dist/recovery/with-recovery.js +84 -0
  59. package/dist/workflow.d.ts +28 -0
  60. package/dist/workflow.js +247 -87
  61. package/package.json +9 -1
@@ -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
+ }
@@ -0,0 +1,44 @@
1
+ import type { WorkflowDeps } from "../workflow.js";
2
+ import type { openRecovery, RecoveryEffectParams } from "./driver.js";
3
+ /** A recovery driver, as `openRecovery` returns it. */
4
+ export type RecoveryDriver = Awaited<ReturnType<typeof openRecovery>>;
5
+ /** The attempt of an LLM step a node runner is asked to run, as the driver admitted it. One attempt is one session:
6
+ * a runner that keeps what an attempt delivered keys it by `sessionId`. */
7
+ export type RecoveryStep = {
8
+ sessionId: string;
9
+ attempt: number;
10
+ earlierSessionIds: readonly string[];
11
+ };
12
+ /** What a host's node runner receives under the driver: the interpreter's parameters, and the attempt it runs. A
13
+ * runner marks a failure no second attempt should follow (one that ended on a bound of its own) with `final: true`
14
+ * on what it throws. */
15
+ export type RecoveryNodeParams = Parameters<NonNullable<WorkflowDeps["runNode"]>>[0] & {
16
+ step?: RecoveryStep;
17
+ };
18
+ /** The host's adapters as `withRecovery` takes them: the interpreter's, with the two that learn more under the driver. */
19
+ export type RecoveryAdapters = Omit<WorkflowDeps, "runEffect" | "runNode"> & {
20
+ runEffect?: (params: RecoveryEffectParams) => Promise<unknown>;
21
+ runNode?: (params: RecoveryNodeParams) => Promise<unknown>;
22
+ };
23
+ export type WithRecoveryOptions = {
24
+ /** The node runner keeps what each attempt delivered: asked again for a `sessionId` whose record it holds, it
25
+ * returns that record without running anything. A step found delivered is then asked of it again as the same
26
+ * attempt, and nothing is spent. Absent, such a step has spent its attempt.
27
+ * A record the interpreter refuses is therefore returned, and refused, again at every later open: the step neither
28
+ * advances nor spends, and the run fails the same way each time until the host ends it (an escalation, a new run). */
29
+ durableNodes?: boolean;
30
+ };
31
+ /** The dependencies to run a workflow with under `driver`. The interpreter's `recovery` hooks cover nodes; three
32
+ * things they have no slot for are applied to the host's adapters here:
33
+ * - `runEffect`: each effect is admitted before it is dispatched, a completed one is answered from its receipt, and
34
+ * one admitted and never completed is refused;
35
+ * - `runJudge`: a route's answer is committed as its decision before any branch step runs, and a resume inside the
36
+ * branch follows it without asking again; every answer's spend is committed with the driver's state;
37
+ * - `runNode`: an LLM step's record is committed before the step runs, with two attempts, each handed to the
38
+ * runner as its `step`. A failed attempt is followed at once by the second, unless the runner marked the
39
+ * failure final; a step that spent both is refused at every later open. A process that dies inside a step spends
40
+ * no attempt. A step that delivered a submission and whose node never committed (the interpreter refused it, or
41
+ * the process died first) is answered again from the runner's own record under `durableNodes`, and has spent its
42
+ * attempt otherwise.
43
+ * The run stops through the driver's signal, together with the host's own. */
44
+ export declare function withRecovery(driver: RecoveryDriver, deps: RecoveryAdapters, options?: WithRecoveryOptions): WorkflowDeps;
@@ -0,0 +1,84 @@
1
+ import { validateAnswers } from "../system-one.js";
2
+ /** The dependencies to run a workflow with under `driver`. The interpreter's `recovery` hooks cover nodes; three
3
+ * things they have no slot for are applied to the host's adapters here:
4
+ * - `runEffect`: each effect is admitted before it is dispatched, a completed one is answered from its receipt, and
5
+ * one admitted and never completed is refused;
6
+ * - `runJudge`: a route's answer is committed as its decision before any branch step runs, and a resume inside the
7
+ * branch follows it without asking again; every answer's spend is committed with the driver's state;
8
+ * - `runNode`: an LLM step's record is committed before the step runs, with two attempts, each handed to the
9
+ * runner as its `step`. A failed attempt is followed at once by the second, unless the runner marked the
10
+ * failure final; a step that spent both is refused at every later open. A process that dies inside a step spends
11
+ * no attempt. A step that delivered a submission and whose node never committed (the interpreter refused it, or
12
+ * the process died first) is answered again from the runner's own record under `durableNodes`, and has spent its
13
+ * attempt otherwise.
14
+ * The run stops through the driver's signal, together with the host's own. */
15
+ export function withRecovery(driver, deps, options = {}) {
16
+ const { runEffect, runJudge, runNode } = deps;
17
+ return {
18
+ ...deps,
19
+ recovery: driver.recovery,
20
+ signal: deps.signal ? AbortSignal.any([deps.signal, driver.signal]) : driver.signal,
21
+ runEffect: runEffect && driver.wrapEffect(runEffect),
22
+ runJudge: runJudge && (async (params) => {
23
+ const decided = params.kind === "route" ? driver.routeDecision(params.executionPath) : undefined;
24
+ if (decided)
25
+ return decided.result;
26
+ const result = await runJudge(params);
27
+ const cost = typeof result.cost_usd === "number" && Number.isFinite(result.cost_usd) ? result.cost_usd : null;
28
+ // An answer the interpreter would refuse is spent at its price and is never a decision: the question is
29
+ // asked again by the next process.
30
+ try {
31
+ validateAnswers(params.questions, result.answers);
32
+ }
33
+ catch (error) {
34
+ driver.recordQuestionSpend(cost);
35
+ throw error;
36
+ }
37
+ driver.recordQuestionSpend(cost, params.kind === "route" ? { executionPath: params.executionPath, label: params.label, result: result, receipts: null } : undefined);
38
+ // The decision is durable before the interpreter acts on the answer, and a stop taken meanwhile ends the run here.
39
+ await driver.flush();
40
+ driver.checkStop();
41
+ return result;
42
+ }),
43
+ runNode: runNode && (async (params) => {
44
+ const admit = () => driver.stepSession(params.executionPath, params.label, { attemptsAllowed: 2 });
45
+ let admission = admit();
46
+ for (;;) {
47
+ // An attempt that delivered a submission is asked for again only when its node never committed. A runner that
48
+ // keeps what it delivered answers it again below, as the same attempt; with any other runner it is spent.
49
+ if (admission.status === "submitted" && !options.durableNodes) {
50
+ driver.stepAttemptFailed(params.executionPath);
51
+ admission = admit();
52
+ }
53
+ if (admission.status === "failed")
54
+ throw new Error(`${params.label} failed after ${admission.attemptsAllowed} attempts`);
55
+ // The step's record is durable before the attempt runs. A stop or a caller's cancellation that landed
56
+ // meanwhile ends the step here: the runner is not called, and no attempt is spent. A pause waiting for an
57
+ // effect in flight holds the step here until it is taken.
58
+ await driver.flush();
59
+ await driver.seam();
60
+ if (params.signal?.aborted)
61
+ throw params.signal.reason;
62
+ try {
63
+ const submission = await runNode({ ...params, step: { sessionId: admission.sessionId, attempt: admission.attempt, earlierSessionIds: admission.earlierSessionIds } });
64
+ driver.stepSubmitted(params.executionPath);
65
+ return submission;
66
+ }
67
+ catch (error) {
68
+ // A stop the driver took, or a sibling's failure, ends the step where it is: no attempt is spent.
69
+ if (driver.signal.aborted || params.signal?.aborted)
70
+ throw error;
71
+ // A failure the runner marked final (an attempt that ended on a bound of its own) gets no second attempt: it
72
+ // would spend the same again.
73
+ const final = error?.final === true;
74
+ driver.stepAttemptFailed(params.executionPath, final);
75
+ if (final)
76
+ throw error;
77
+ admission = admit();
78
+ if (admission.status !== "running")
79
+ throw error;
80
+ }
81
+ }
82
+ }),
83
+ };
84
+ }
@@ -1,6 +1,7 @@
1
1
  import { type AcceptPredicate } from "./predicates.js";
2
2
  import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
3
3
  import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
4
+ import { type DecisionReceipt } from "./decision-receipts.js";
4
5
  export { resolveSchemaForWorkflow } from "./schema-references.js";
5
6
  /** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
6
7
  * or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
@@ -497,6 +498,9 @@ export type WorkflowDeps = {
497
498
  signal?: AbortSignal;
498
499
  state: unknown;
499
500
  questions: Record<string, SystemOneQuestion>;
501
+ /** The id of this request's decision receipt (`DecisionReceipt.id`): the same request asked again
502
+ * carries the same id. */
503
+ decisionId?: string;
500
504
  }) => Promise<{
501
505
  answers: Record<string, SystemOneAnswer>;
502
506
  model?: string | null;
@@ -507,6 +511,12 @@ export type WorkflowDeps = {
507
511
  cost_usd?: number | null;
508
512
  request_sha256?: string;
509
513
  }>;
514
+ /** Records one typed-question request and what its answers decide. It is awaited before the answers
515
+ * reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
516
+ * rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
517
+ * recorded too, before its failure is thrown. A decision answered from `recovery.decision` was
518
+ * recorded by the run that asked it and is not recorded again. */
519
+ recordDecision?: (receipt: DecisionReceipt, exchange: DecisionExchange) => Promise<void>;
510
520
  syntheticEffects?: boolean;
511
521
  checkpoint?: (state: Record<string, unknown>, label: string, executionPath?: string) => Promise<void>;
512
522
  /** Critical recovery stores stop execution on write failure; omitted retains legacy best effort. */
@@ -519,6 +529,10 @@ export type WorkflowDeps = {
519
529
  pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
520
530
  wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
521
531
  fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
532
+ /** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
533
+ * the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
534
+ * other receipt, or none, means the request is asked. */
535
+ decision?: (id: string) => Promise<DecisionReceipt | undefined>;
522
536
  };
523
537
  /** A completed-effect memo keyed by the call's idempotency key. A hit skips the effect and
524
538
  * reuses its result; polled calls are never memoized (their result is a moment in time). */
@@ -543,6 +557,14 @@ export type WorkflowEvent = {
543
557
  detail?: unknown;
544
558
  executionPath?: string;
545
559
  };
560
+ type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
561
+ type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
562
+ /** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
563
+ * and, when the judge returned, the very object it returned, so a host reads back what it put there. */
564
+ export type DecisionExchange = {
565
+ request: JudgeRequest;
566
+ result?: JudgeResult;
567
+ };
546
568
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
547
569
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
548
570
  /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
@@ -661,6 +683,12 @@ export declare class WorkflowStateError extends Error {
661
683
  export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
662
684
  export declare const submissionSchemaForNode: typeof stageSchemaForNode;
663
685
  export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
686
+ /** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
687
+ export declare class WorkflowDecisionRecordError extends Error {
688
+ readonly label: string;
689
+ readonly decisionId: string;
690
+ constructor(label: string, decisionId: string, cause: unknown);
691
+ }
664
692
  /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
665
693
  export declare const HOST_STATE_KEY = "$host";
666
694
  export declare class WorkflowVerificationError extends Error {