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

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 +107 -17
  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 +1007 -332
  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
package/dist/authoring.js CHANGED
@@ -57,7 +57,7 @@ export function defineWorkflow(definition) {
57
57
  });
58
58
  const result = validateWorkflow(document);
59
59
  if (!result.ok)
60
- throw new WorkflowInvalidError(document.name, result.errors);
60
+ throw new WorkflowInvalidError(document.name, result.errors, result.issues);
61
61
  const inputSchema = resolveSchemaForWorkflow(document, document.schemas[definition.input]);
62
62
  if (!objectContract(inputSchema)) {
63
63
  throw new WorkflowSchemaConversionError(definition.input, new Error("workflow input must be constrained to JSON objects; declare type: object or object-only schema alternatives"));
package/dist/cli.js CHANGED
@@ -12,7 +12,7 @@ const help = `AgentRun DSL — build, test, and run agent workflows
12
12
  agentrun example [file.json] Write the demo workflow (never overwrite)
13
13
  agentrun inspect workflow.json [--json] Show structure without executing code
14
14
  agentrun validate workflow.json [input.json] --trusted
15
- agentrun dry-run workflow.json [input.json] --trusted
15
+ agentrun dry-run workflow.json [input.json] --trusted [--strict]
16
16
  agentrun run workflow.json input.json --trusted
17
17
 
18
18
  demo runs the real interpreter with scripted judgments, without a key or network.
@@ -22,6 +22,8 @@ during validation and running. Only use workflows you trust; this is not a sandb
22
22
  validate checks a supplied input against the workflow's input contract.
23
23
  dry-run uses supplied input, or synthesizes it from the declared input schema.
24
24
  Without an input schema, dry-run starts with an empty input object.
25
+ dry-run exits 1 when a check fails. A check that could not run (status not_run, the
26
+ reasons under skipped) exits 0 unless --strict is given, which makes it exit 3.
25
27
  `;
26
28
  async function main(args) {
27
29
  const [command] = args;
@@ -86,14 +88,15 @@ async function main(args) {
86
88
  throw new Error(`Unknown command "${command}". Use agentrun --help.`);
87
89
  if (!args.includes("--trusted"))
88
90
  throw new Error("Pass --trusted only after reviewing the workflow. Authored JavaScript may execute, including during validation.");
89
- const positional = args.slice(1).filter(arg => arg !== "--trusted");
91
+ const strict = command === "dry-run" && args.includes("--strict");
92
+ const positional = args.slice(1).filter(arg => arg !== "--trusted" && !(strict && arg === "--strict"));
90
93
  const unknown = positional.find(arg => arg.startsWith("--"));
91
94
  if (unknown)
92
95
  throw new Error(`Unknown option "${unknown}". Use agentrun --help.`);
93
96
  if (!positional[0])
94
97
  throw new Error("Provide a workflow JSON file.");
95
98
  if (positional.length > 2)
96
- throw new Error(`Usage: agentrun ${command} workflow.json ${command === "run" ? "input.json" : "[input.json]"} --trusted`);
99
+ throw new Error(`Usage: agentrun ${command} workflow.json ${command === "run" ? "input.json" : "[input.json]"} --trusted${command === "dry-run" ? " [--strict]" : ""}`);
97
100
  if (command === "run" && !positional[1])
98
101
  throw new Error("Provide an input JSON file.");
99
102
  const workflow = JSON.parse(await readFile(resolve(positional[0]), "utf8"));
@@ -121,6 +124,8 @@ async function main(args) {
121
124
  console.log(JSON.stringify(result, null, 2));
122
125
  if (!result.ok)
123
126
  process.exitCode = 1;
127
+ else if (strict && result.status === "not_run")
128
+ process.exitCode = 3;
124
129
  }
125
130
  else {
126
131
  const result = await runWorkflow(workflow, input, {});
@@ -1,3 +1,9 @@
1
+ /** The denied globals a transform's source names, in DENIED_GLOBALS order: a lexical scan of the source
2
+ * that skips comments, string and template text and regular-expression literals, and ignores a name
3
+ * read as a property (after `.` or `?.`). A name used as an object key or a local binding is still
4
+ * named: the lint refuses rather than guesses. It is a lint for untrusted authors, never a boundary:
5
+ * a host that runs such code isolates it (deps.runCode). */
6
+ export declare function deniedGlobalReferences(src: string): string[];
1
7
  /** Parse the same expression as trusted execution, without evaluating it or calling its body.
2
8
  * Syntax validity does not prove that the expression produces a function or a valid patch. */
3
9
  export declare function compileTransformSyntax(src: string): void;
package/dist/code-exec.js CHANGED
@@ -10,6 +10,132 @@ const DENIED_GLOBALS = [
10
10
  "fetch", "XMLHttpRequest", "Function", "Buffer",
11
11
  "setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Promise", "Date",
12
12
  ];
13
+ /** Words after which a `/` starts a regular expression rather than a division. */
14
+ const REGEX_AFTER_WORDS = new Set(["return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw", "case", "do", "else", "yield", "await"]);
15
+ const IDENTIFIER_START = /[A-Za-z_$\u0080-\uffff]/;
16
+ const IDENTIFIER_PART = /[A-Za-z0-9_$\u0080-\uffff]/;
17
+ /** The denied globals a transform's source names, in DENIED_GLOBALS order: a lexical scan of the source
18
+ * that skips comments, string and template text and regular-expression literals, and ignores a name
19
+ * read as a property (after `.` or `?.`). A name used as an object key or a local binding is still
20
+ * named: the lint refuses rather than guesses. It is a lint for untrusted authors, never a boundary:
21
+ * a host that runs such code isolates it (deps.runCode). */
22
+ export function deniedGlobalReferences(src) {
23
+ const denied = new Set(DENIED_GLOBALS);
24
+ const found = new Set();
25
+ const braces = [];
26
+ const n = typeof src === "string" ? src.length : 0;
27
+ let i = 0;
28
+ // The previous significant token: a word, a value (literal, closing bracket), or punctuation.
29
+ let prev = null;
30
+ /** Template text from i: true when it stopped at `${` (code follows), false at its closing backtick. */
31
+ const templateText = () => {
32
+ while (i < n) {
33
+ if (src[i] === "\\") {
34
+ i += 2;
35
+ continue;
36
+ }
37
+ if (src[i] === "`") {
38
+ i += 1;
39
+ return false;
40
+ }
41
+ if (src[i] === "$" && src[i + 1] === "{") {
42
+ i += 2;
43
+ braces.push("template");
44
+ return true;
45
+ }
46
+ i += 1;
47
+ }
48
+ return false;
49
+ };
50
+ while (i < n) {
51
+ const c = src[i];
52
+ if (/\s/.test(c)) {
53
+ i += 1;
54
+ continue;
55
+ }
56
+ if (c === "/" && src[i + 1] === "/") {
57
+ const end = src.indexOf("\n", i);
58
+ i = end < 0 ? n : end;
59
+ continue;
60
+ }
61
+ if (c === "/" && src[i + 1] === "*") {
62
+ const end = src.indexOf("*/", i + 2);
63
+ i = end < 0 ? n : end + 2;
64
+ continue;
65
+ }
66
+ if (c === "'" || c === '"') {
67
+ i += 1;
68
+ while (i < n && src[i] !== c)
69
+ i += src[i] === "\\" ? 2 : 1;
70
+ i += 1;
71
+ prev = { kind: "value", text: c };
72
+ continue;
73
+ }
74
+ if (c === "`" || (c === "}" && braces[braces.length - 1] === "template")) {
75
+ if (c === "}")
76
+ braces.pop();
77
+ i += 1;
78
+ prev = templateText() ? null : { kind: "value", text: "`" };
79
+ continue;
80
+ }
81
+ if (c === "/") {
82
+ const regex = prev === null || (prev.kind === "punct" && !")]}".includes(prev.text)) || (prev.kind === "word" && REGEX_AFTER_WORDS.has(prev.text));
83
+ if (regex) {
84
+ i += 1;
85
+ let inClass = false;
86
+ while (i < n && (inClass || src[i] !== "/")) {
87
+ if (src[i] === "\\") {
88
+ i += 2;
89
+ continue;
90
+ }
91
+ if (src[i] === "[")
92
+ inClass = true;
93
+ else if (src[i] === "]")
94
+ inClass = false;
95
+ i += 1;
96
+ }
97
+ i += 1;
98
+ while (i < n && IDENTIFIER_PART.test(src[i]))
99
+ i += 1;
100
+ prev = { kind: "value", text: "/" };
101
+ continue;
102
+ }
103
+ }
104
+ if (IDENTIFIER_START.test(c)) {
105
+ const start = i;
106
+ while (i < n && IDENTIFIER_PART.test(src[i]))
107
+ i += 1;
108
+ const word = src.slice(start, i);
109
+ if (denied.has(word) && !(prev?.kind === "punct" && prev.text === "."))
110
+ found.add(word);
111
+ prev = { kind: "word", text: word };
112
+ continue;
113
+ }
114
+ if (/[0-9]/.test(c)) {
115
+ while (i < n && IDENTIFIER_PART.test(src[i]))
116
+ i += 1;
117
+ prev = { kind: "value", text: "0" };
118
+ continue;
119
+ }
120
+ if (c === "." && src.startsWith("...", i)) {
121
+ i += 3;
122
+ prev = { kind: "punct", text: "..." };
123
+ continue;
124
+ }
125
+ if (c === "?" && src[i + 1] === "." && !/[0-9]/.test(src[i + 2] ?? "")) {
126
+ i += 2;
127
+ prev = { kind: "punct", text: "." };
128
+ continue;
129
+ }
130
+ if (c === "{")
131
+ braces.push("brace");
132
+ if (c === "}")
133
+ braces.pop();
134
+ i += 1;
135
+ prev = c === ")" || c === "]" || c === "}" ? { kind: "value", text: c } : { kind: "punct", text: c };
136
+ }
137
+ return DENIED_GLOBALS.filter((name) => found.has(name));
138
+ }
13
139
  function createTransformFactory(src) {
14
140
  if (typeof src !== "string" || !src.trim())
15
141
  throw new Error("code transform source must be a non-empty string");
@@ -0,0 +1,98 @@
1
+ import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
2
+ export declare const DECISION_RECEIPT_VERSION = 1;
3
+ /** The typed questions the interpreter asks: the five question nodes and predicates, and a generative
4
+ * node's `verify` clause. */
5
+ export type DecisionKind = "judge" | "pick" | "sift" | "route" | "ask" | "verify";
6
+ /** How answers become the action, with every threshold applied. */
7
+ export type DecisionRule =
8
+ /** judge: each question's decoded value (a choice, a yes/no at 0.5, a rounded score). */
9
+ {
10
+ kind: "judge";
11
+ }
12
+ /** pick: the chosen option names an item by its position, or none. */
13
+ | {
14
+ kind: "pick";
15
+ options: string[];
16
+ none: string | null;
17
+ }
18
+ /** route: the chosen branch, or the unsure branch when the choice's confidence is below `gte`. */
19
+ | {
20
+ kind: "route";
21
+ unsure: {
22
+ gte: number;
23
+ branch: string;
24
+ } | null;
25
+ }
26
+ /** sift: an item of this request is kept when its `keep` measure meets `gte`; every item without a keep
27
+ * rule. `items` counts this request's items; the action names them by their position in the request. */
28
+ | {
29
+ kind: "sift";
30
+ items: number;
31
+ ids: string[];
32
+ keep: {
33
+ id: string;
34
+ measure: "confidence" | "value";
35
+ gte: number;
36
+ } | null;
37
+ }
38
+ /** ask: the predicate holds when the yes-probability meets `gte`. */
39
+ | {
40
+ kind: "ask";
41
+ gte: number;
42
+ }
43
+ /** verify: a yes/no question fails when its yes-probability is below its threshold (null: not judged).
44
+ * A failed question the submission holds is doubted; a failed one it lacks is unmet. */
45
+ | {
46
+ kind: "verify";
47
+ thresholds: Record<string, number | null>;
48
+ present: string[];
49
+ };
50
+ export type DecisionReceipt = {
51
+ v: typeof DECISION_RECEIPT_VERSION;
52
+ /** The request's identity: where it sits in the run (execution path, kind, position among its node's
53
+ * requests) and what it asked (questions and state). The same request asked again has the same id. */
54
+ id: string;
55
+ /** When the receipt was made, ISO 8601. */
56
+ at: string;
57
+ /** The label the request carried, a child workflow's prefix included. */
58
+ node: string;
59
+ kind: DecisionKind;
60
+ /** The map item the request ran for, by index; null outside a map. */
61
+ item: number | null;
62
+ execution_path: string;
63
+ /** This request among the requests its node makes at this path. A sift over the host's limits sends
64
+ * `count` requests, and `items` lists the positions in the sifted list this one covers, in the order it
65
+ * asked about them. A verify clause's nth review has index n - 1 and `count` is the most it may ask.
66
+ * Every other kind asks once. */
67
+ request: {
68
+ index: number;
69
+ count: number;
70
+ items?: number[];
71
+ };
72
+ /** `answered`: the answers came back and decided `action`. `failed`: the judge rejected, or its answers
73
+ * were refused. `cancelled`: the request's signal was aborted before it settled, so whether it was
74
+ * served is not known. */
75
+ status: "answered" | "failed" | "cancelled";
76
+ /** SHA-256 of the canonical JSON of the state the judge was given. */
77
+ state_sha256: string;
78
+ questions: Record<string, SystemOneQuestion>;
79
+ /** What came back, as it came back; empty when nothing did. */
80
+ answers: Record<string, SystemOneAnswer>;
81
+ /** Null unless `status` is `answered`. */
82
+ rule: DecisionRule | null;
83
+ /** What the answers decide under `rule`; null unless `status` is `answered`. */
84
+ action: unknown;
85
+ model: string | null;
86
+ usage: {
87
+ input_tokens: number;
88
+ output_tokens: number;
89
+ } | null;
90
+ cost_usd: number | null;
91
+ request_sha256: string | null;
92
+ /** Wall time of the judge call, in milliseconds. */
93
+ latency_ms: number;
94
+ error?: string;
95
+ };
96
+ /** The action a receipt's answers and rule determine, recomputed without a model call: for an answered
97
+ * receipt it equals `receipt.action`. Null for a receipt that decided nothing. */
98
+ export declare function rederiveDecision(receipt: Pick<DecisionReceipt, "rule" | "answers" | "questions">): unknown;
@@ -0,0 +1,51 @@
1
+ // Decision receipts: one record per typed-question request, holding what was asked, what came back, the
2
+ // rule that turns those answers into an action (its thresholds included) and the action itself. A receipt
3
+ // alone explains a decision: `rederiveDecision` recomputes the action from it without a model call.
4
+ import { answerConfidence, answersToValue } from "./system-one.js";
5
+ export const DECISION_RECEIPT_VERSION = 1;
6
+ /** The action a receipt's answers and rule determine, recomputed without a model call: for an answered
7
+ * receipt it equals `receipt.action`. Null for a receipt that decided nothing. */
8
+ export function rederiveDecision(receipt) {
9
+ const rule = receipt.rule;
10
+ const answers = receipt.answers;
11
+ if (!rule)
12
+ return null;
13
+ switch (rule.kind) {
14
+ case "judge": return answersToValue(receipt.answers, receipt.questions);
15
+ case "pick": {
16
+ const choice = answers.pick?.choice;
17
+ const none = rule.none !== null && choice === rule.none;
18
+ return { index: none ? null : rule.options.indexOf(choice), none };
19
+ }
20
+ case "route": {
21
+ const branch = answers.branch?.choice;
22
+ const unsure = Boolean(rule.unsure && answers.branch.confidence < rule.unsure.gte);
23
+ return { branch, taken: unsure ? rule.unsure.branch : branch, unsure };
24
+ }
25
+ case "sift": {
26
+ const kept = [];
27
+ for (let i = 0; i < rule.items; i += 1) {
28
+ if (!rule.keep) {
29
+ kept.push(i);
30
+ continue;
31
+ }
32
+ const answer = answers[`${i}.${rule.keep.id}`];
33
+ const measure = !answer ? NaN : rule.keep.measure === "confidence" ? answerConfidence(answer) : answer.type === "noul" ? answer.noul : answer.type === "score" ? answer.score : NaN;
34
+ if (Number.isFinite(measure) && measure >= rule.keep.gte)
35
+ kept.push(i);
36
+ }
37
+ return { kept };
38
+ }
39
+ case "ask": return { holds: Number(answers.holds?.noul) >= rule.gte };
40
+ case "verify": {
41
+ const doubted = [];
42
+ const unmet = [];
43
+ for (const [id, threshold] of Object.entries(rule.thresholds)) {
44
+ if (threshold === null || !(Number(answers[id]?.noul) < threshold))
45
+ continue;
46
+ (rule.present.includes(id) ? doubted : unmet).push(id);
47
+ }
48
+ return { accepted: doubted.length === 0 && unmet.length === 0, doubted, unmet };
49
+ }
50
+ }
51
+ }
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
@@ -116,9 +116,9 @@ function unsupportedConstructs(schema, path, found, depth = 0) {
116
116
  return found;
117
117
  }
118
118
  export async function dryRunWorkflow(workflow, opts = {}) {
119
- const valid = validateWorkflow(workflow, opts.input === undefined ? undefined : { input: opts.input });
119
+ const valid = validateWorkflow(workflow, { ...(opts.input === undefined ? {} : { input: opts.input }), ...(opts.runCode ? { executeCode: false } : {}) });
120
120
  if (!valid.ok)
121
- return { ok: false, problems: [new WorkflowInvalidError(String(workflow?.name), valid.errors).message] };
121
+ return { ok: false, status: "failed", problems: [new WorkflowInvalidError(String(workflow?.name), valid.errors, valid.issues).message] };
122
122
  const skipped = [];
123
123
  const scanSchemas = (plan) => {
124
124
  for (const [id, schema] of Object.entries(plan.schemas || {}))
@@ -139,13 +139,13 @@ export async function dryRunWorkflow(workflow, opts = {}) {
139
139
  };
140
140
  scanSchemas(workflow);
141
141
  if (skipped.length)
142
- return { ok: true, skipped };
142
+ return { ok: true, status: "not_run", skipped };
143
143
  let input = opts.input ?? {};
144
144
  if (opts.input === undefined && workflow.input) {
145
145
  const schema = resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.input.schemaId]);
146
146
  const generated = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
147
147
  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."] };
148
+ 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
149
  }
150
150
  input = generated;
151
151
  }
@@ -156,36 +156,62 @@ export async function dryRunWorkflow(workflow, opts = {}) {
156
156
  } };
157
157
  }
158
158
  let currentLabel = "";
159
+ // Every synthetic step counts, and every 64th yields to the event loop, so the host can take a stop meanwhile.
160
+ const maxSteps = opts.maxSteps ?? 10_000;
161
+ let steps = 0;
162
+ // Why the dry run stopped early, kept here: the interpreter may wrap what an adapter throws.
163
+ let stopped;
164
+ const stop = (reason) => { stopped ??= reason; throw new Error(stopped); };
165
+ const step = async () => {
166
+ if (opts.signal?.aborted)
167
+ stop("The dry run was stopped before it finished.");
168
+ steps += 1;
169
+ if (steps > maxSteps)
170
+ 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.`);
171
+ if (steps % 64 === 0) {
172
+ await new Promise((resolve) => setTimeout(resolve, 0));
173
+ if (opts.signal?.aborted)
174
+ stop("The dry run was stopped before it finished.");
175
+ }
176
+ };
177
+ const runCode = opts.runCode;
159
178
  try {
160
179
  const result = await runWorkflow(workflow, input, {
161
180
  sop: opts.sop,
181
+ ...(runCode ? { runCode: async (...args) => { await step(); return runCode(...args); } } : {}),
162
182
  onEvent: (event) => { if (typeof event.label === "string")
163
183
  currentLabel = event.label; },
164
184
  runNode: async ({ schema, review }) => {
185
+ await step();
165
186
  const candidate = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
166
187
  if (review)
167
188
  await review(candidate);
168
189
  return candidate;
169
190
  },
170
- runJudge: async ({ questions }) => ({ answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "" }),
191
+ runJudge: async ({ questions }) => { await step(); return { answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "" }; },
171
192
  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 ?? {}),
193
+ runEffect: async ({ node, schema }) => {
194
+ await step();
195
+ return node.via === "shell"
196
+ ? { code: 0, stdout: "{}", stderr: "", truncated: false }
197
+ : synthesizeInstance(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {});
198
+ },
175
199
  });
176
200
  if (result.status === "escalated") {
177
201
  // 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`] };
202
+ return { ok: true, status: "not_run", skipped: [`escalated:${result.escalation.kind}@${result.escalation.stage} on synthetic values`] };
179
203
  }
180
- return { ok: true };
204
+ return { ok: true, status: "passed" };
181
205
  }
182
206
  catch (error) {
207
+ if (stopped)
208
+ return { ok: true, status: "not_run", skipped: [stopped] };
183
209
  if (error instanceof WorkflowOutputInvalidError) {
184
- return { ok: false, problems: error.problems, stage: error.stage };
210
+ return { ok: false, status: "failed", problems: error.problems, stage: error.stage };
185
211
  }
186
212
  if (error instanceof WorkflowInputInvalidError)
187
- return { ok: false, problems: [error.message] };
213
+ return { ok: false, status: "failed", problems: [error.message] };
188
214
  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 };
215
+ return { ok: false, status: "failed", problems: [`deterministic path threw over schema-conforming inputs${currentLabel ? ` (at "${currentLabel}")` : ""}: ${message.slice(0, 1200)}`], stage: currentLabel || undefined };
190
216
  }
191
217
  }
@@ -0,0 +1,83 @@
1
+ /** One node of the workflow as written. `path` is a JSON Pointer (RFC 6901) into the document: `/root` is the root,
2
+ * `/root/steps/1` a chain's second step, `/root/branches/<name>/body` a route's branch, `/root/body` a map's or a
3
+ * loop's body, `/root/workflow/root` a child workflow's root: the pointers `inspectWorkflow` and a validation issue
4
+ * use for the same node. `label` is the node's label, or its kind when it has none. `via` is a `call` node's transport. */
5
+ export type GraphNode = {
6
+ path: string;
7
+ kind: string;
8
+ label: string;
9
+ via?: string;
10
+ };
11
+ /** How control reaches `to` from `from`.
12
+ * - `next`: a chain enters its first step and each step is followed by the next; a loop enters its body, which runs again
13
+ * until the loop ends.
14
+ * - `branch`: a parallel node starts each of its branches.
15
+ * - `route`: a route node takes one of its branches (the branch's name is the last pointer segment before `/body`).
16
+ * - `item`: a map runs its body once for each item.
17
+ * - `child`: a workflow node runs the child workflow's root. */
18
+ export type GraphEdgeKind = "next" | "branch" | "route" | "item" | "child";
19
+ export type GraphEdge = {
20
+ from: string;
21
+ to: string;
22
+ kind: GraphEdgeKind;
23
+ };
24
+ export type WorkflowGraph = {
25
+ nodes: GraphNode[];
26
+ edges: GraphEdge[];
27
+ };
28
+ /** The graph of `workflow`, computed from its JSON alone: nodes in document order (a node, then its descendants), and the
29
+ * edges between them. A value that is not a workflow, or a node the walk does not know, adds nothing and never throws:
30
+ * validation is `validateWorkflow`'s. */
31
+ export declare function workflowGraph(workflow: unknown): WorkflowGraph;
32
+ /** What a run has done at a node. A node inside a map's or a loop's body stands for every item or iteration, and the record names
33
+ * only those that started, so it is `done` only once the map or loop is: until then it is `working`, and a done node never
34
+ * goes back. A container (chain, parallel, map, loop, route, workflow) is `working` while some of
35
+ * its descendants are, or some are done and it is not; a node a run never reached, a branch a route did not take among
36
+ * them, is `not-run`. */
37
+ export type NodeState = "done" | "working" | "failed" | "not-run";
38
+ type Frame = {
39
+ done?: unknown;
40
+ steps?: unknown;
41
+ inputs?: unknown;
42
+ partial?: unknown;
43
+ };
44
+ /** The part of an `agentrun.items` value the status reads: the map item's `status` and its frame. */
45
+ export type ItemRecordLike = {
46
+ map?: unknown;
47
+ index?: unknown;
48
+ status?: unknown;
49
+ frame?: Frame;
50
+ };
51
+ /** What `nodeStatus` reads: a driver frame (the `pin` of a frozen snapshot: `done`, `steps`, `inputs`), a frozen snapshot
52
+ * (its `pin`), or the map items' records, alone or together with the driver's record (`{ pin, items }`). */
53
+ export type StatusSource = Frame | {
54
+ pin: Frame;
55
+ items?: readonly ItemRecordLike[];
56
+ } | readonly ItemRecordLike[];
57
+ /** `item`: the source is one map item's (or loop iteration's) record, read on its own, and this is its execution path
58
+ * (`<map path>/items/<index>`, `<loop path>/iterations/<index>`). That item is then the instance, not one of many: its body is done
59
+ * when the item is, whether or not the map is. A map or loop inside the item still stands for all of its own items. */
60
+ export type StatusOptions = {
61
+ item?: string;
62
+ };
63
+ /** For every node of `graph`, the state the record shows. `source` is what the driver kept: its frame and, in the keyed
64
+ * layout, the records of the map items (a run's whole story is the frame and the items together). A source that is not
65
+ * one of those shows no node run. */
66
+ export declare function nodeStatus(graph: WorkflowGraph, source: StatusSource, options?: StatusOptions): Record<string, NodeState>;
67
+ /** Where an execution path is in the graph: the node it ran at (`path`, a node of the graph) and the map items and loop
68
+ * iterations it ran in, outermost first. */
69
+ export type GraphNodeAt = {
70
+ path: string;
71
+ at: {
72
+ kind: "item" | "iteration";
73
+ index: number;
74
+ }[];
75
+ };
76
+ /** The graph node an execution path ran at. An execution path is the node's JSON Pointer with two runtime segments added:
77
+ * a map's item (`items/<i>` before the map's `body`) and a loop's iteration (`iterations/<i>` before the loop's `body`); the
78
+ * graph has `/body` for both, and the indexes are returned in `at`. The path is read by walking the graph from `/root`, by
79
+ * each node's kind, never by matching its text, so a route branch named `items` or `iterations` is a branch. Undefined for
80
+ * a path the graph does not have, or one that is not an execution path (a map's `body` without an item, an item without
81
+ * its `body`). */
82
+ export declare function graphNodeOf(graph: WorkflowGraph, executionPath: string): GraphNodeAt | undefined;
83
+ export {};