@parcha/agentrun-dsl 0.1.0-beta.3 → 0.1.0-beta.30

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 (103) hide show
  1. package/README.md +165 -21
  2. package/dist/author-references.d.ts +8 -0
  3. package/dist/author-references.js +8 -0
  4. package/dist/author.d.ts +16 -3
  5. package/dist/author.js +40 -16
  6. package/dist/authoring.js +2 -2
  7. package/dist/cli.js +17 -12
  8. package/dist/code-exec.d.ts +6 -0
  9. package/dist/code-exec.js +126 -0
  10. package/dist/decision-provider.d.ts +157 -0
  11. package/dist/decision-provider.js +230 -0
  12. package/dist/decision-receipts.d.ts +143 -0
  13. package/dist/decision-receipts.js +93 -0
  14. package/dist/dry-run.d.ts +14 -1
  15. package/dist/dry-run.js +58 -15
  16. package/dist/graph.d.ts +169 -0
  17. package/dist/graph.js +433 -0
  18. package/dist/index.d.ts +15 -8
  19. package/dist/index.js +8 -4
  20. package/dist/inspection.d.ts +5 -0
  21. package/dist/inspection.js +16 -3
  22. package/dist/job.d.ts +14 -0
  23. package/dist/job.js +5 -0
  24. package/dist/long-timer.d.ts +7 -0
  25. package/dist/long-timer.js +22 -0
  26. package/dist/observer-snapshot.d.ts +3 -0
  27. package/dist/observer-snapshot.js +46 -0
  28. package/dist/predicates.d.ts +10 -0
  29. package/dist/predicates.js +18 -0
  30. package/dist/recovery/binding.d.ts +10 -0
  31. package/dist/recovery/binding.js +43 -0
  32. package/dist/recovery/call-key.d.ts +13 -0
  33. package/dist/recovery/call-key.js +24 -0
  34. package/dist/recovery/canonical-hash.d.ts +7 -0
  35. package/dist/recovery/canonical-hash.js +22 -0
  36. package/dist/recovery/driver.d.ts +238 -0
  37. package/dist/recovery/driver.js +1337 -0
  38. package/dist/recovery/effect-failure.d.ts +34 -0
  39. package/dist/recovery/effect-failure.js +62 -0
  40. package/dist/recovery/errors.d.ts +31 -0
  41. package/dist/recovery/errors.js +51 -0
  42. package/dist/recovery/execution-path.d.ts +53 -0
  43. package/dist/recovery/execution-path.js +167 -0
  44. package/dist/recovery/file-store.d.ts +7 -0
  45. package/dist/recovery/file-store.js +131 -0
  46. package/dist/recovery/frozen-snapshot.d.ts +274 -0
  47. package/dist/recovery/frozen-snapshot.js +187 -0
  48. package/dist/recovery/handoff-block.d.ts +36 -0
  49. package/dist/recovery/handoff-block.js +148 -0
  50. package/dist/recovery/handoff-digest.d.ts +58 -0
  51. package/dist/recovery/handoff-digest.js +195 -0
  52. package/dist/recovery/handoff-files.d.ts +54 -0
  53. package/dist/recovery/handoff-files.js +162 -0
  54. package/dist/recovery/handoff-receipts.d.ts +42 -0
  55. package/dist/recovery/handoff-receipts.js +53 -0
  56. package/dist/recovery/handoff-redact.d.ts +12 -0
  57. package/dist/recovery/handoff-redact.js +44 -0
  58. package/dist/recovery/handoff.d.ts +44 -0
  59. package/dist/recovery/handoff.js +46 -0
  60. package/dist/recovery/index.d.ts +19 -0
  61. package/dist/recovery/index.js +17 -0
  62. package/dist/recovery/item-state.d.ts +48 -0
  63. package/dist/recovery/item-state.js +89 -0
  64. package/dist/recovery/journal.d.ts +28 -0
  65. package/dist/recovery/journal.js +139 -0
  66. package/dist/recovery/memory-store.d.ts +4 -0
  67. package/dist/recovery/memory-store.js +20 -0
  68. package/dist/recovery/store.d.ts +105 -0
  69. package/dist/recovery/store.js +6 -0
  70. package/dist/recovery/testing/conformance.d.ts +4 -0
  71. package/dist/recovery/testing/conformance.js +268 -0
  72. package/dist/recovery/testing/crash-points.d.ts +18 -0
  73. package/dist/recovery/testing/crash-points.js +43 -0
  74. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  75. package/dist/recovery/testing/crash-sweep.js +146 -0
  76. package/dist/recovery/testing/index.d.ts +3 -0
  77. package/dist/recovery/testing/index.js +4 -0
  78. package/dist/recovery/testing/preload.d.ts +1 -0
  79. package/dist/recovery/testing/preload.js +3 -0
  80. package/dist/recovery/transport-facts.d.ts +23 -0
  81. package/dist/recovery/transport-facts.js +46 -0
  82. package/dist/recovery/with-recovery.d.ts +50 -0
  83. package/dist/recovery/with-recovery.js +142 -0
  84. package/dist/submit-envelope.d.ts +9 -0
  85. package/dist/submit-envelope.js +40 -0
  86. package/dist/system-one.d.ts +40 -1
  87. package/dist/system-one.js +141 -5
  88. package/dist/testing/decision-provider.d.ts +32 -0
  89. package/dist/testing/decision-provider.js +183 -0
  90. package/dist/testing/index.d.ts +1 -0
  91. package/dist/testing/index.js +2 -0
  92. package/dist/vocabulary.d.ts +22 -3
  93. package/dist/vocabulary.js +33 -10
  94. package/dist/workflow-shape.d.ts +7 -0
  95. package/dist/workflow-shape.js +115 -67
  96. package/dist/workflow.d.ts +269 -20
  97. package/dist/workflow.js +1251 -341
  98. package/package.json +25 -2
  99. package/schema/workflow.schema.json +506 -12
  100. package/skills/author/SKILL.md +6 -1
  101. package/skills/author/references/jev-decisions.md +58 -6
  102. package/skills/author/references/language.md +28 -19
  103. package/skills/author/references/sdk-authoring.md +2 -0
@@ -0,0 +1,230 @@
1
+ // The seam for decision models: a DecisionProvider answers typed questions (noul, choice, score, box) about a state, fast
2
+ // and without an agent harness, and judgeFromProvider makes one the interpreter's runJudge. Jev is one provider and a
3
+ // third-party API another; each passes the conformance suite in `@parcha/agentrun-dsl/testing`.
4
+ import { createHash } from "node:crypto";
5
+ import { completeConfidence, validateAnswers } from "./system-one.js";
6
+ /** A PNG's or JPEG's width and height in pixels, read from its header (PNG's IHDR, a JPEG's first frame marker); null
7
+ * when the bytes are neither or the header is cut short. A provider with a size cap checks it before a paid call. */
8
+ export function imageDimensions(bytes) {
9
+ const u16 = (at) => (bytes[at] << 8) | bytes[at + 1];
10
+ const u32 = (at) => ((bytes[at] << 24) >>> 0) + (bytes[at + 1] << 16) + (bytes[at + 2] << 8) + bytes[at + 3];
11
+ if (bytes.length >= 24 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[12] === 0x49 && bytes[13] === 0x48 && bytes[14] === 0x44 && bytes[15] === 0x52) {
12
+ return { width: u32(16), height: u32(20) };
13
+ }
14
+ if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8)
15
+ return null;
16
+ for (let at = 2; at + 3 < bytes.length;) {
17
+ if (bytes[at] !== 0xff)
18
+ return null;
19
+ const marker = bytes[at + 1];
20
+ if (marker === 0xff) {
21
+ at++;
22
+ continue;
23
+ }
24
+ if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
25
+ at += 2;
26
+ continue;
27
+ }
28
+ // A start-of-frame marker (C0-CF but DHT C4, JPG C8 and DAC CC) holds precision, height, width.
29
+ if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc)
30
+ return at + 8 < bytes.length ? { width: u16(at + 7), height: u16(at + 5) } : null;
31
+ if (marker === 0xd9 || marker === 0xda)
32
+ return null;
33
+ at += 2 + u16(at + 2);
34
+ }
35
+ return null;
36
+ }
37
+ /** A provider's failure. Its message names what failed, never a key, a header, a request or response body. */
38
+ export class DecisionProviderError extends Error {
39
+ code;
40
+ status;
41
+ attempts;
42
+ /** The provider's own reference for the failure, when it gives one. */
43
+ refId;
44
+ /** What a request that was or may have been billed is booked at (`outcome_unknown`, `invalid_response`), with how it was
45
+ * reached; null when unknown. */
46
+ costUsd;
47
+ costBasis;
48
+ /** True when the provider knows the request was never sent (a check before it, cut by the deadline or a cancel):
49
+ * judgeFromProviders keeps its code under a node's timeoutMs, where any other cut is taken for a request that may
50
+ * have been billed. Absent when it may have been sent; `attempts` alone never says so. */
51
+ unsent;
52
+ constructor(code, message, details = {}) {
53
+ super(message, details.cause !== undefined ? { cause: details.cause } : undefined);
54
+ this.code = code;
55
+ this.name = "DecisionProviderError";
56
+ this.attempts = details.attempts ?? 0;
57
+ if (details.status !== undefined)
58
+ this.status = details.status;
59
+ if (details.refId !== undefined)
60
+ this.refId = details.refId;
61
+ if (details.costUsd !== undefined)
62
+ this.costUsd = details.costUsd;
63
+ if (details.costBasis !== undefined)
64
+ this.costBasis = details.costBasis;
65
+ if (details.unsent === true)
66
+ this.unsent = true;
67
+ }
68
+ }
69
+ /** What a provider's error books for its request: one sent whose outcome was lost (`outcome_unknown`), or one answered
70
+ * with what the seam or the provider rejects (`invalid_response`), was or may have been paid for, and is booked at the
71
+ * cost the error carries, null when that is unknown (never 0). Undefined for an error that books nothing. */
72
+ export function chargedCost(error) {
73
+ if (!(error instanceof DecisionProviderError) || (error.code !== "outcome_unknown" && error.code !== "invalid_response"))
74
+ return undefined;
75
+ return typeof error.costUsd === "number" && Number.isFinite(error.costUsd) ? error.costUsd : null;
76
+ }
77
+ /** Refuses, as invalid_request, a request beyond what `capabilities` declares: a question type it does not answer, more
78
+ * questions than it takes, a larger state, or a model it does not serve. A provider calls it before it sends anything. */
79
+ export function checkCapabilities(capabilities, request) {
80
+ if (request.model !== undefined && capabilities.models && !capabilities.models.includes(request.model))
81
+ throw new DecisionProviderError("invalid_request", `The provider does not answer with the model "${request.model}".`);
82
+ const types = Object.values(request.questions).map((question) => question?.type);
83
+ const unknown = types.filter((type) => !capabilities.types.includes(type));
84
+ if (unknown.length)
85
+ throw new DecisionProviderError("invalid_request", `The provider does not answer ${[...new Set(unknown)].map(String).join(", ")} questions.`);
86
+ if (capabilities.maxQuestions !== null && types.length > capabilities.maxQuestions)
87
+ throw new DecisionProviderError("invalid_request", `${types.length} questions exceed the ${capabilities.maxQuestions} one request may hold.`);
88
+ if (capabilities.maxStateBytes !== null) {
89
+ const bytes = Buffer.byteLength(JSON.stringify(request.state ?? null) ?? "null", "utf8");
90
+ if (bytes > capabilities.maxStateBytes)
91
+ throw new DecisionProviderError("invalid_request", `A state of ${bytes} bytes exceeds the ${capabilities.maxStateBytes} one request may hold.`);
92
+ }
93
+ }
94
+ /** `promise`, or `signal`'s reason once it aborts first: a loader that does not watch its signal is cut all the same. */
95
+ function untilAborted(promise, signal) {
96
+ if (signal.aborted) {
97
+ promise.catch(() => { });
98
+ return Promise.reject(signal.reason);
99
+ }
100
+ return new Promise((resolve, reject) => {
101
+ const stop = () => reject(signal.reason);
102
+ signal.addEventListener("abort", stop, { once: true });
103
+ promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop));
104
+ });
105
+ }
106
+ /** Requests cut while their images loaded: nothing was sent, so judgeFromProviders never takes one for a request that
107
+ * may have been billed. */
108
+ const cutBeforeSending = new WeakSet();
109
+ /** Loads a request's images through the host's `loadImage`, before anything is sent: a provider that takes no image input,
110
+ * a host that cannot load one, or an image that cannot be read is refused, and no request is made. */
111
+ async function loadImages(provider, images, loadImage, signal) {
112
+ if (!provider.capabilities.inputs.includes("image"))
113
+ throw new DecisionProviderError("invalid_request", `The provider ${provider.id} takes no image input, and the request carries ${Object.keys(images).length}.`);
114
+ if (!loadImage)
115
+ throw new DecisionProviderError("configuration", "The request carries images, and this host has no loadImage to read them.");
116
+ const loaded = Object.create(null);
117
+ const digests = [];
118
+ for (const [token, ref] of Object.entries(images)) {
119
+ let image;
120
+ try {
121
+ image = await untilAborted(loadImage(ref, { signal }), signal);
122
+ }
123
+ catch (error) {
124
+ throw new DecisionProviderError("invalid_request", `The image ${token} (${ref}) could not be read: ${String(error?.message ?? error).slice(0, 200)}`);
125
+ }
126
+ if (!(image?.bytes instanceof Uint8Array) || !image.bytes.byteLength || typeof image.mime !== "string")
127
+ throw new DecisionProviderError("invalid_request", `The image ${token} (${ref}) read as no image bytes.`);
128
+ loaded[token] = { bytes: image.bytes, mime: image.mime, ref };
129
+ digests.push({ token, ref, sha256: createHash("sha256").update(image.bytes).digest("hex"), mime: image.mime, bytes: image.bytes.byteLength });
130
+ }
131
+ return { loaded: { ...loaded }, digests };
132
+ }
133
+ /** The interpreter's runJudge, answered by `provider`: the request goes to it with the decision's id, its signal and
134
+ * `deadlineMs`, and with the images it names, loaded through `loadImage` within that deadline (the provider gets what is
135
+ * left of it; a load the deadline cuts is `timeout`, one the signal cuts `aborted`, and neither was sent); a choice or
136
+ * score without a confidence gets one derived, and the result names each one's source and each image's digest. The
137
+ * answers are validated against the questions, and ones that do not match them are invalid_response. */
138
+ export function judgeFromProvider(provider, options = {}) {
139
+ return async (params) => {
140
+ const request = { label: params.label, kind: params.kind, state: params.state, questions: params.questions, ...(params.item ? { item: params.item } : {}), ...(params.executionPath !== undefined ? { executionPath: params.executionPath } : {}), ...(params.model !== undefined ? { model: params.model } : {}) };
141
+ checkCapabilities(provider.capabilities, request);
142
+ let digests;
143
+ const signal = params.signal ?? new AbortController().signal;
144
+ let deadlineMs = options.deadlineMs ?? null;
145
+ if (params.images && Object.keys(params.images).length) {
146
+ // The deadline counts from before the images load, and loading is cut by it as by the run's signal.
147
+ const started = Date.now();
148
+ const loading = deadlineMs !== null ? AbortSignal.any([signal, AbortSignal.timeout(deadlineMs)]) : signal;
149
+ const cutWith = (reason) => {
150
+ const timedOut = reason?.name === "TimeoutError";
151
+ const cut = new DecisionProviderError(timedOut ? "timeout" : "aborted", `${provider.id}: ${timedOut ? "the deadline passed" : "the request was cancelled"} while its images loaded; nothing was sent`, { cause: reason });
152
+ cutBeforeSending.add(cut);
153
+ return cut;
154
+ };
155
+ let images;
156
+ try {
157
+ images = await loadImages(provider, params.images, options.loadImage, loading);
158
+ }
159
+ catch (error) {
160
+ if (!loading.aborted)
161
+ throw error;
162
+ throw cutWith(loading.reason);
163
+ }
164
+ // A load can end past the deadline before its timer fires (a loader's synchronous work, or hashing the last image,
165
+ // holds the thread): it is cut here, before anything is sent, and the provider gets only time that is left.
166
+ const elapsed = Date.now() - started;
167
+ if (loading.aborted)
168
+ throw cutWith(loading.reason);
169
+ if (deadlineMs !== null && elapsed >= deadlineMs)
170
+ throw cutWith(new DOMException("The decision's deadline passed while its images loaded", "TimeoutError"));
171
+ request.images = images.loaded;
172
+ digests = images.digests;
173
+ if (deadlineMs !== null)
174
+ deadlineMs -= elapsed;
175
+ }
176
+ const outcome = await provider.decide(request, { decisionId: params.decisionId ?? "", signal, deadlineMs });
177
+ const { answers, confidence_source } = completeConfidence(params.questions, (outcome.answers ?? {}));
178
+ try {
179
+ validateAnswers(params.questions, answers);
180
+ }
181
+ catch (error) {
182
+ // The provider answered, so the request was paid for: the rejection carries its cost, or null when it reported none.
183
+ const cost = typeof outcome.cost_usd === "number" && Number.isFinite(outcome.cost_usd) ? outcome.cost_usd : null;
184
+ throw new DecisionProviderError("invalid_response", `${provider.id} answered with ${error.message.replace(/^System One /, "")}`, { costUsd: cost, costBasis: cost === null ? "unknown" : outcome.cost_basis });
185
+ }
186
+ const result = {
187
+ answers, model: outcome.model, usage: outcome.usage, cost_usd: outcome.cost_usd, cost_basis: outcome.cost_basis,
188
+ evidence: outcome.evidence, provider_request_id: outcome.provider_request_id, confidence_source,
189
+ ...(digests ? { images: digests } : {}),
190
+ };
191
+ return result;
192
+ };
193
+ }
194
+ /** The interpreter's runJudge over a host's providers: each request goes to the provider its node names, or to
195
+ * `default`, with the node's pinned model, within the shorter of the node's `timeoutMs` and the provider's own
196
+ * `deadlineMs`: a node only ever shortens it. The node's bound is kept here: when it passes, the call is cut, and a cut
197
+ * call may already have been sent and billed, so it is `outcome_unknown` (the decision escalates as interrupted), never
198
+ * asked again. A call cut while its images load was not sent, and stays `timeout`. The result names the provider that
199
+ * answered. */
200
+ export function judgeFromProviders(options) {
201
+ return async (params) => {
202
+ const id = params.provider ?? options.default;
203
+ const provider = Object.hasOwn(options.providers, id) ? options.providers[id] : undefined;
204
+ if (!provider)
205
+ throw new DecisionProviderError("configuration", `No decision provider "${id}" on this host.`);
206
+ const own = options.deadlineMs ?? null;
207
+ const node = params.timeoutMs ?? null;
208
+ const shorter = node !== null && (own === null || node < own);
209
+ const deadlineMs = shorter ? node : own;
210
+ const cut = new AbortController();
211
+ const timer = shorter ? setTimeout(() => cut.abort(new DOMException("The decision node's timeoutMs passed", "TimeoutError")), node) : undefined;
212
+ const signal = params.signal ? AbortSignal.any([params.signal, cut.signal]) : cut.signal;
213
+ try {
214
+ const result = await judgeFromProvider(provider, { deadlineMs, ...(options.loadImage ? { loadImage: options.loadImage } : {}) })({ ...params, signal });
215
+ return { ...result, provider: id };
216
+ }
217
+ catch (error) {
218
+ if (cut.signal.aborted && error instanceof DecisionProviderError && !cutBeforeSending.has(error) && error.unsent !== true && (error.code === "aborted" || error.code === "timeout")) {
219
+ throw new DecisionProviderError("outcome_unknown", `${id}: cut by the node's timeoutMs (${node} ms) after it may have been sent`, {
220
+ attempts: error.attempts, ...(error.costUsd !== undefined ? { costUsd: error.costUsd } : {}), ...(error.costBasis !== undefined ? { costBasis: error.costBasis } : {}), cause: error
221
+ });
222
+ }
223
+ throw error;
224
+ }
225
+ finally {
226
+ if (timer !== undefined)
227
+ clearTimeout(timer);
228
+ }
229
+ };
230
+ }
@@ -0,0 +1,143 @@
1
+ import type { CostBasis, DecisionEvidence } from "./decision-provider.js";
2
+ import { type ConfidenceSource, type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
3
+ export declare const DECISION_RECEIPT_VERSION = 1;
4
+ /** The escalation kind of a decision its provider refused: the run ends `escalated` at stage "decision", for a person. */
5
+ export declare const DECISION_REFUSED = "decision_refused";
6
+ /** The escalation kind of a run whose decision was asked by an earlier process and never answered there: it is routed to
7
+ * review instead of being asked, and paid for, again. Its stage is `decision`. */
8
+ export declare const DECISION_INTERRUPTED = "decision_interrupted";
9
+ /** The most of the state a receipt keeps, as UTF-8 JSON bytes: a larger state is kept as the first this many bytes of its
10
+ * JSON text, with `state_truncated: true`. */
11
+ export declare const DECISION_STATE_MAX_BYTES: number;
12
+ /** The most of a request's error a receipt keeps, in characters; a longer one is kept to it with `error_truncated`. */
13
+ export declare const DECISION_ERROR_MAX: number;
14
+ /** An image a request carried, as its receipt names it: the token the request used, the reference the host loaded, and
15
+ * the image's SHA-256, type and size (never the bytes). The digest fields are null when the image was never loaded (a
16
+ * request that failed before its images were read). */
17
+ export type DecisionImageDigest = {
18
+ token: string;
19
+ ref: string;
20
+ sha256: string | null;
21
+ mime: string | null;
22
+ bytes: number | null;
23
+ };
24
+ /** The typed questions the interpreter asks: the five question nodes and predicates, and a generative
25
+ * node's `verify` clause. */
26
+ export type DecisionKind = "judge" | "pick" | "sift" | "route" | "ask" | "verify";
27
+ /** How answers become the action, with every threshold applied. */
28
+ export type DecisionRule =
29
+ /** judge: each question's decoded value (a choice, a yes/no at 0.5, a rounded score). */
30
+ {
31
+ kind: "judge";
32
+ }
33
+ /** pick: the chosen option names an item by its position, or none. */
34
+ | {
35
+ kind: "pick";
36
+ options: string[];
37
+ none: string | null;
38
+ }
39
+ /** route: the chosen branch, or the unsure branch when the choice's confidence is below `gte`. The chosen
40
+ * branch names one of `branches`; `unsure`, when set, judges its confidence against `gte`. `branches` is
41
+ * absent on a rule recorded before it was added, and such a rule skips the branch-membership check. */
42
+ | {
43
+ kind: "route";
44
+ branches?: string[];
45
+ unsure: {
46
+ gte: number;
47
+ branch: string;
48
+ } | null;
49
+ }
50
+ /** sift: an item of this request is kept when its `keep` measure meets `gte`; every item without a keep
51
+ * rule. `items` counts this request's items; the action names them by their position in the request. */
52
+ | {
53
+ kind: "sift";
54
+ items: number;
55
+ ids: string[];
56
+ keep: {
57
+ id: string;
58
+ measure: "confidence" | "value";
59
+ gte: number;
60
+ } | null;
61
+ }
62
+ /** ask: the predicate holds when the yes-probability meets `gte`. */
63
+ | {
64
+ kind: "ask";
65
+ gte: number;
66
+ }
67
+ /** verify: a yes/no question fails when its yes-probability is below its threshold (null: not judged).
68
+ * A failed question the submission holds is doubted; a failed one it lacks is unmet. */
69
+ | {
70
+ kind: "verify";
71
+ thresholds: Record<string, number | null>;
72
+ present: string[];
73
+ };
74
+ export type DecisionReceipt = {
75
+ v: typeof DECISION_RECEIPT_VERSION;
76
+ /** The request's identity: where it sits in the run (execution path, kind, position among its node's
77
+ * requests) and what it asked (questions and state). The same request asked again has the same id. */
78
+ id: string;
79
+ /** When the receipt was made, ISO 8601. */
80
+ at: string;
81
+ /** The label the request carried, a child workflow's prefix included. */
82
+ node: string;
83
+ kind: DecisionKind;
84
+ /** The map item the request ran for, by index; null outside a map. */
85
+ item: number | null;
86
+ execution_path: string;
87
+ /** This request among the requests its node makes at this path. A sift over the host's limits sends
88
+ * `count` requests, and `items` lists the positions in the sifted list this one covers, in the order it
89
+ * asked about them. A verify clause's nth review has index n - 1 and `count` is the most it may ask.
90
+ * Every other kind asks once. */
91
+ request: {
92
+ index: number;
93
+ count: number;
94
+ items?: number[];
95
+ };
96
+ /** `answered`: the answers came back and decided `action`. `failed`: the judge rejected, or its answers
97
+ * were refused. `cancelled`: the request's signal was aborted before it settled, so whether it was
98
+ * served is not known. */
99
+ status: "answered" | "failed" | "cancelled";
100
+ /** SHA-256 of the canonical JSON of the state the judge was given. */
101
+ state_sha256: string;
102
+ questions: Record<string, SystemOneQuestion>;
103
+ /** What came back, as it came back; empty when nothing did. */
104
+ answers: Record<string, SystemOneAnswer>;
105
+ /** Null unless `status` is `answered`. */
106
+ rule: DecisionRule | null;
107
+ /** What the answers decide under `rule`; null unless `status` is `answered`. */
108
+ action: unknown;
109
+ model: string | null;
110
+ usage: {
111
+ input_tokens: number;
112
+ output_tokens: number;
113
+ } | null;
114
+ cost_usd: number | null;
115
+ request_sha256: string | null;
116
+ /** Wall time of the judge call, in milliseconds. */
117
+ latency_ms: number;
118
+ /** The questions whose answer came back as a refusal, when any did. A refusal decodes to no value: the request is
119
+ * `failed` and the run escalates (DECISION_REFUSED), except a route with an `unsure` branch, which takes that branch. */
120
+ refused?: string[];
121
+ /** For each choice and score answer, whether its confidence is the provider's own or was derived from its
122
+ * probabilities; present when the judge said. */
123
+ confidence_source?: Record<string, ConfidenceSource>;
124
+ /** The provider that answered, when the host's judge names it or the node pins it. */
125
+ provider?: string;
126
+ /** The sources the provider grounded its answers in, unless the node said `evidence: "off"`; absent when it gave none. */
127
+ evidence?: DecisionEvidence[];
128
+ /** How `cost_usd` was reached (reported by the provider, estimated by the host, unknown), when the judge said. */
129
+ cost_basis?: CostBasis;
130
+ /** The images the request carried, by digest; absent when it carried none. */
131
+ images?: DecisionImageDigest[];
132
+ /** The state the judge saw: the value itself, or, past `DECISION_STATE_MAX_BYTES` of JSON, the first that many bytes of
133
+ * its JSON text (a string) with `state_truncated: true`. Absent on a receipt recorded before it was kept. */
134
+ state?: unknown;
135
+ state_truncated?: boolean;
136
+ /** The request's error, whole up to `DECISION_ERROR_MAX` characters: a host redacts it before it cuts it for a person.
137
+ * A longer one is kept to that many with `error_truncated: true`; one recorded before was cut at 2000. */
138
+ error?: string;
139
+ error_truncated?: boolean;
140
+ };
141
+ /** The action a receipt's answers and rule determine, recomputed without a model call: for an answered
142
+ * receipt it equals `receipt.action`. Null for a receipt that decided nothing. */
143
+ export declare function rederiveDecision(receipt: Pick<DecisionReceipt, "rule" | "answers" | "questions">): unknown;
@@ -0,0 +1,93 @@
1
+ import { answerConfidence, answersToValue } from "./system-one.js";
2
+ export const DECISION_RECEIPT_VERSION = 1;
3
+ /** The escalation kind of a decision its provider refused: the run ends `escalated` at stage "decision", for a person. */
4
+ export const DECISION_REFUSED = "decision_refused";
5
+ /** The escalation kind of a run whose decision was asked by an earlier process and never answered there: it is routed to
6
+ * review instead of being asked, and paid for, again. Its stage is `decision`. */
7
+ export const DECISION_INTERRUPTED = "decision_interrupted";
8
+ /** The most of the state a receipt keeps, as UTF-8 JSON bytes: a larger state is kept as the first this many bytes of its
9
+ * JSON text, with `state_truncated: true`. */
10
+ export const DECISION_STATE_MAX_BYTES = 64 * 1024;
11
+ /** The most of a request's error a receipt keeps, in characters; a longer one is kept to it with `error_truncated`. */
12
+ export const DECISION_ERROR_MAX = 64 * 1024;
13
+ /** The action a receipt's answers and rule determine, recomputed without a model call: for an answered
14
+ * receipt it equals `receipt.action`. Null for a receipt that decided nothing. */
15
+ export function rederiveDecision(receipt) {
16
+ const rule = receipt.rule;
17
+ const answers = receipt.answers;
18
+ if (!rule)
19
+ return null;
20
+ switch (rule.kind) {
21
+ case "judge": return answersToValue(receipt.answers, receipt.questions);
22
+ case "pick": {
23
+ // An answered pick carries its pick answer; a receipt without one decided nothing.
24
+ const answer = answers.pick;
25
+ if (!answer || typeof answer !== "object")
26
+ return null;
27
+ const choice = answer.choice;
28
+ // The choice must be a string that names an option, or the none option. Anything else (no string
29
+ // choice, or a choice in neither set) is a malformed answer, never a fail-open {index: -1}.
30
+ if (typeof choice !== "string")
31
+ return null;
32
+ const none = rule.none !== null && choice === rule.none;
33
+ if (!none && !rule.options.includes(choice))
34
+ return null;
35
+ return { index: none ? null : rule.options.indexOf(choice), none };
36
+ }
37
+ case "route": {
38
+ // An answered route carries its branch answer; a receipt without one decided nothing.
39
+ const answer = answers.branch;
40
+ if (!answer || typeof answer !== "object")
41
+ return null;
42
+ // A refused route has no branch of its own: it took the unsure branch, and without one it decided nothing.
43
+ if (answer.type === "refusal")
44
+ return rule.unsure ? { branch: null, taken: rule.unsure.branch, unsure: true, refused: true } : null;
45
+ const branch = answer.choice;
46
+ // The chosen branch must be a string; when the rule carries `branches` (recorded since this check was
47
+ // added) it must name one of them. A rule recorded before `branches` skips the membership check, so an
48
+ // older route receipt re-derives as it did before, never throwing on a missing field.
49
+ if (typeof branch !== "string" || (rule.branches && !rule.branches.includes(branch)))
50
+ return null;
51
+ // When unsure is set, judging SURE/UNSURE needs a finite numeric confidence. A missing or non-numeric
52
+ // confidence must not compare false and re-derive as SURE (a fail-open onto the chosen branch).
53
+ if (rule.unsure && !(typeof answer.confidence === "number" && Number.isFinite(answer.confidence)))
54
+ return null;
55
+ const unsure = Boolean(rule.unsure && answer.confidence < rule.unsure.gte);
56
+ return { branch, taken: unsure ? rule.unsure.branch : branch, unsure };
57
+ }
58
+ case "sift": {
59
+ const kept = [];
60
+ for (let i = 0; i < rule.items; i += 1) {
61
+ if (!rule.keep) {
62
+ kept.push(i);
63
+ continue;
64
+ }
65
+ const answer = answers[`${i}.${rule.keep.id}`];
66
+ const measure = !answer ? NaN : rule.keep.measure === "confidence" ? answerConfidence(answer) : answer.type === "noul" ? answer.noul : answer.type === "score" ? answer.score : NaN;
67
+ if (Number.isFinite(measure) && measure >= rule.keep.gte)
68
+ kept.push(i);
69
+ }
70
+ return { kept };
71
+ }
72
+ case "ask": return { holds: Number(answers.holds?.noul) >= rule.gte };
73
+ case "verify": {
74
+ const doubted = [];
75
+ const unmet = [];
76
+ for (const [id, threshold] of Object.entries(rule.thresholds)) {
77
+ if (threshold === null)
78
+ continue;
79
+ // A field with a threshold needs its yes/no answer; a receipt missing one, or holding another shape, decided
80
+ // nothing (null), never a fail-open "accepted".
81
+ const answer = answers[id];
82
+ // The answer must be a noul with a finite numeric probability. A noul-typed answer whose noul is
83
+ // absent or not a finite number would compare NaN < threshold (false), reading as supported: a
84
+ // fail-open one level down. It decided nothing.
85
+ if (answer?.type !== "noul" || typeof answer.noul !== "number" || !Number.isFinite(answer.noul))
86
+ return null;
87
+ if (answer.noul < threshold)
88
+ (rule.present.includes(id) ? doubted : unmet).push(id);
89
+ }
90
+ return { accepted: doubted.length === 0 && unmet.length === 0, doubted, unmet };
91
+ }
92
+ }
93
+ }
package/dist/dry-run.d.ts CHANGED
@@ -1,9 +1,13 @@
1
- import { type Workflow } from "./workflow.js";
1
+ import { type Workflow, type WorkflowDeps } from "./workflow.js";
2
+ /** `ok` keeps its meaning: false only when a check failed. `status` says whether every check ran: `passed`, `not_run`
3
+ * (a check stood down; `skipped` says which and why, so this is not proof the graph was exercised) or `failed`. */
2
4
  export type DryRunResult = {
3
5
  ok: true;
6
+ status: "passed" | "not_run";
4
7
  skipped?: string[];
5
8
  } | {
6
9
  ok: false;
10
+ status: "failed";
7
11
  problems: string[];
8
12
  stage?: string;
9
13
  };
@@ -15,5 +19,14 @@ export type DryRunOptions = {
15
19
  references_parsed?: Record<string, unknown>;
16
20
  };
17
21
  input?: Record<string, unknown>;
22
+ /** The host's executor for `code` nodes (WorkflowDeps.runCode). Present, the dry run validates
23
+ * with executeCode:false and hands every code node to it, so no code body runs in this process. */
24
+ runCode?: WorkflowDeps["runCode"];
25
+ /** Ends the dry run: it stops at its next step, as not run. */
26
+ signal?: AbortSignal;
27
+ /** The most synthetic steps (an agent's or a judge's answer, an effect, a code node the host runs) before the dry run
28
+ * stops, as not run: synthetic answers can keep a loop going to its bound, and a map over a long list. 10,000 by
29
+ * default. */
30
+ maxSteps?: number;
18
31
  };
19
32
  export declare function dryRunWorkflow(workflow: Workflow, opts?: DryRunOptions): Promise<DryRunResult>;
package/dist/dry-run.js CHANGED
@@ -2,6 +2,17 @@ import { Compile } from "typebox/compile";
2
2
  import { runWorkflow, validateWorkflow, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError } from "./workflow.js";
3
3
  import { resolveSchemaForWorkflow } from "./schema-references.js";
4
4
  import { synthesizeAnswers } from "./system-one.js";
5
+ /** A provider for every id the workflow names, and a default: the dry run answers each decision itself, so a node's
6
+ * provider and timeoutMs hold it to no host's providers. */
7
+ function syntheticProviders(workflow) {
8
+ const ids = new Set(["dry-run"]);
9
+ JSON.stringify(workflow, (key, value) => { if (key === "provider" && typeof value === "string")
10
+ ids.add(value); return value; });
11
+ const capabilities = { types: ["noul", "choice", "score", "box"], inputs: ["text", "json", "image", "pdf", "url"], evidence: "citations",
12
+ probability: "none", grounding: false, replay: "deduped", maxQuestions: null, maxStateBytes: null };
13
+ const provider = (id) => ({ id, needs: [], capabilities, decide: async () => { throw new Error("A dry run answers its decisions itself."); } });
14
+ return { providers: Object.fromEntries([...ids].map((id) => [id, provider(id)])), default: "dry-run" };
15
+ }
5
16
  export function synthesizeInstance(schema, definitions = {}, depth = 0) {
6
17
  if (depth > 12 || !schema || typeof schema !== "object")
7
18
  return null;
@@ -116,9 +127,9 @@ function unsupportedConstructs(schema, path, found, depth = 0) {
116
127
  return found;
117
128
  }
118
129
  export async function dryRunWorkflow(workflow, opts = {}) {
119
- const valid = validateWorkflow(workflow, opts.input === undefined ? undefined : { input: opts.input });
130
+ const valid = validateWorkflow(workflow, { ...(opts.input === undefined ? {} : { input: opts.input }), ...(opts.runCode ? { executeCode: false } : {}) });
120
131
  if (!valid.ok)
121
- return { ok: false, problems: [new WorkflowInvalidError(String(workflow?.name), valid.errors).message] };
132
+ return { ok: false, status: "failed", problems: [new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues).message] };
122
133
  const skipped = [];
123
134
  const scanSchemas = (plan) => {
124
135
  for (const [id, schema] of Object.entries(plan.schemas || {}))
@@ -139,53 +150,85 @@ export async function dryRunWorkflow(workflow, opts = {}) {
139
150
  };
140
151
  scanSchemas(workflow);
141
152
  if (skipped.length)
142
- return { ok: true, skipped };
153
+ return { ok: true, status: "not_run", skipped };
143
154
  let input = opts.input ?? {};
144
155
  if (opts.input === undefined && workflow.input) {
145
156
  const schema = resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]);
146
157
  const generated = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
147
158
  if (!generated || typeof generated !== "object" || Array.isArray(generated) || !Compile(schema).Check(generated)) {
148
- return { ok: true, skipped: ["Could not synthesize a valid input object. Supply input explicitly to dryRunWorkflow or the dry-run CLI."] };
159
+ return { ok: true, status: "not_run", skipped: ["Could not synthesize a valid input object. Supply input explicitly to dryRunWorkflow or the dry-run CLI."] };
149
160
  }
150
161
  input = generated;
151
162
  }
152
163
  if (opts.probeContext && !Object.prototype.hasOwnProperty.call(input, "context")) {
153
164
  input = { ...input, context: {
154
- references: opts.probeContext?.references ?? {},
155
- references_parsed: opts.probeContext?.references_parsed ?? {},
165
+ references: opts.probeContext.references ?? {},
166
+ references_parsed: opts.probeContext.references_parsed ?? {},
156
167
  } };
157
168
  }
158
169
  let currentLabel = "";
170
+ // Every synthetic step counts, and every 64th yields to the event loop, so the host can take a stop meanwhile.
171
+ const maxSteps = opts.maxSteps ?? 10_000;
172
+ let steps = 0;
173
+ // Why the dry run stopped early, kept here: the interpreter may wrap what an adapter throws.
174
+ let stopped;
175
+ const stop = (reason) => { stopped ??= reason; throw new Error(stopped); };
176
+ const step = async () => {
177
+ if (opts.signal?.aborted)
178
+ stop("The dry run was stopped before it finished.");
179
+ steps += 1;
180
+ if (steps > maxSteps)
181
+ stop(`The dry run stopped after ${maxSteps} synthetic steps: on synthetic values the workflow's loops or maps go on further. Supply input, or lower a loop's maxIters.`);
182
+ if (steps % 64 === 0) {
183
+ await new Promise((resolve) => setTimeout(resolve, 0));
184
+ if (opts.signal?.aborted)
185
+ stop("The dry run was stopped before it finished.");
186
+ }
187
+ };
188
+ const runCode = opts.runCode;
159
189
  try {
160
190
  const result = await runWorkflow(workflow, input, {
161
191
  sop: opts.sop,
192
+ ...(runCode ? { runCode: async (...args) => { await step(); return runCode(...args); } } : {}),
162
193
  onEvent: (event) => { if (typeof event.label === "string")
163
194
  currentLabel = event.label; },
164
195
  runNode: async ({ schema, review }) => {
196
+ await step();
165
197
  const candidate = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
166
198
  if (review)
167
199
  await review(candidate);
168
200
  return candidate;
169
201
  },
170
- runJudge: async ({ questions }) => ({ answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "" }),
202
+ // A node that requires evidence gets a placeholder, as a provider that gives evidence would answer it.
203
+ runJudge: async ({ questions, evidence }) => {
204
+ await step();
205
+ return { answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "",
206
+ ...(evidence === "required" ? { evidence: [{ url: "https://example.invalid/dry-run", title: null, excerpts: [], scope: "dry_run" }] } : {}) };
207
+ },
171
208
  syntheticEffects: true,
172
- runEffect: async ({ node, schema }) => node.via === "shell"
173
- ? { code: 0, stdout: "{}", stderr: "", truncated: false }
174
- : synthesizeInstance(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {}),
209
+ decisionProviders: syntheticProviders(workflow),
210
+ runEffect: async ({ node, schema }) => {
211
+ await step();
212
+ return node.via === "shell"
213
+ ? { code: 0, stdout: "{}", stderr: "", truncated: false }
214
+ : synthesizeInstance(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {});
215
+ },
175
216
  });
176
217
  if (result.status === "escalated") {
177
218
  // Synthetic values tripping an escalate predicate proves nothing about real cases.
178
- return { ok: true, skipped: [`escalated:${result.escalation.kind}@${result.escalation.stage} on synthetic values`] };
219
+ return { ok: true, status: "not_run", skipped: [`escalated:${result.escalation.kind}@${result.escalation.stage} on synthetic values`] };
179
220
  }
180
- return { ok: true };
221
+ return { ok: true, status: "passed" };
181
222
  }
182
223
  catch (error) {
224
+ if (stopped)
225
+ return { ok: true, status: "not_run", skipped: [stopped] };
183
226
  if (error instanceof WorkflowOutputInvalidError) {
184
- return { ok: false, problems: error.problems, stage: error.stage };
227
+ return { ok: false, status: "failed", problems: error.problems, stage: error.stage };
185
228
  }
186
229
  if (error instanceof WorkflowInputInvalidError)
187
- return { ok: false, problems: [error.message] };
230
+ return { ok: false, status: "failed", problems: [error.message] };
188
231
  const message = error instanceof Error ? error.message : String(error);
189
- return { ok: false, problems: [`deterministic path threw over schema-conforming inputs${currentLabel ? ` (at "${currentLabel}")` : ""}: ${message.slice(0, 1200)}`], stage: currentLabel || undefined };
232
+ return { ok: false, status: "failed", problems: [`deterministic path threw over schema-conforming inputs${currentLabel ? ` (at "${currentLabel}")` : ""}: ${message.slice(0, 1200)}`], stage: currentLabel || undefined };
190
233
  }
191
234
  }