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

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,183 @@
1
+ // The DecisionProvider conformance suite: what a provider must hold for a decision workflow to rest on it. A provider
2
+ // package registers it in its own tests with a kit that builds the provider over a fake transport.
3
+ import assert from "node:assert/strict";
4
+ import { test } from "node:test";
5
+ import { DecisionProviderError } from "../decision-provider.js";
6
+ import { completeConfidence, validateAnswers } from "../system-one.js";
7
+ const QUESTIONS = {
8
+ holds: { type: "noul", instructions: "Does the statement hold?" },
9
+ pick: { type: "choice", instructions: "Which option fits?", criteria: { first: "the first", second: "the second" } },
10
+ level: { type: "score", instructions: "How strong is it?", criteria: ["weak", "middling", "strong"] },
11
+ };
12
+ const ANSWERS = {
13
+ holds: { type: "noul", noul: 0.8 },
14
+ pick: { type: "choice", choice: "first", probabilities: { first: 0.75, second: 0.25 }, confidence: 0.5 },
15
+ level: { type: "score", score: 1.5, legend: { 0: "weak", 1: "middling", 2: "strong" }, probabilities: { 0: 0, 1: 0.5, 2: 0.5 }, confidence: 0.25 },
16
+ };
17
+ const EVIDENCE = [{ url: "https://example.org/a", title: "A source", excerpts: ["a passage"], scope: "call" }];
18
+ const BASES = ["reported", "estimate", "unknown"];
19
+ /** The smallest PNG: a 1x1 transparent pixel. */
20
+ const PNG = Uint8Array.from(Buffer.from("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "base64"));
21
+ /** Registers the suite as `node:test` tests named under `name`. */
22
+ export function registerDecisionProviderConformance(name, kit) {
23
+ const it = (title, body, options = {}) => test(`${name}: ${title}`, { skip: options.skip ?? false, timeout: 20_000 }, body);
24
+ /** The questions of each type the provider answers, with answers to them. */
25
+ const asked = (provider) => {
26
+ const ids = Object.keys(QUESTIONS).filter((id) => provider.capabilities.types.includes(QUESTIONS[id].type));
27
+ return { questions: Object.fromEntries(ids.map((id) => [id, QUESTIONS[id]])), answers: Object.fromEntries(ids.map((id) => [id, structuredClone(ANSWERS[id])])) };
28
+ };
29
+ const request = (questions, state = { case: "conformance" }) => ({ label: "conformance", kind: "judge", state, questions });
30
+ const ctx = (over = {}) => ({ decisionId: "conformance-decision", signal: over.signal ?? new AbortController().signal, deadlineMs: over.deadlineMs === undefined ? 5_000 : over.deadlineMs });
31
+ /** One decision on a provider whose transport gives `replies`. */
32
+ const decideOn = async (replies, questions, context = ctx()) => {
33
+ const { provider } = kit.build(replies);
34
+ return provider.decide(request(questions ?? asked(provider).questions), context);
35
+ };
36
+ const answerReply = (provider, extra = {}) => ({ kind: "answer", answers: asked(provider).answers, ...extra });
37
+ const probe = () => kit.build([{ kind: "hang" }]).provider;
38
+ /** `promise`, or a failure once `ms` pass: the referenced timer also keeps the process up while a request hangs. */
39
+ const within = (ms, promise) => {
40
+ let timer;
41
+ const late = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`still pending after ${ms} ms`)), ms); });
42
+ return Promise.race([promise, late]).finally(() => clearTimeout(timer));
43
+ };
44
+ const failsWith = (expected) => (error) => {
45
+ assert.ok(error instanceof DecisionProviderError, `a provider fails with a DecisionProviderError, got ${String(error)}`);
46
+ assert.equal(error.code, expected);
47
+ return true;
48
+ };
49
+ it("it answers exactly the questions asked, each in its declared type", async () => {
50
+ const { questions } = asked(probe());
51
+ const outcome = await decideOn([answerReply(probe())]);
52
+ assert.deepEqual(Object.keys(outcome.answers).sort(), Object.keys(questions).sort());
53
+ const { answers } = completeConfidence(questions, outcome.answers);
54
+ validateAnswers(questions, answers);
55
+ });
56
+ it("an answer to a question not asked, or none for one asked, is invalid_response", async () => {
57
+ const { answers } = asked(probe());
58
+ await assert.rejects(decideOn([{ kind: "answer", answers: { ...answers, unasked: { type: "noul", noul: 0.5 } } }]), failsWith("invalid_response"));
59
+ const [first, ...rest] = Object.keys(answers);
60
+ assert.ok(first && rest.length, "the provider answers at least two of noul, choice and score");
61
+ await assert.rejects(decideOn([{ kind: "answer", answers: Object.fromEntries(rest.map((id) => [id, answers[id]])) }]), failsWith("invalid_response"));
62
+ });
63
+ it("a cost it does not know is null, never 0, and cost_basis says how it was reached", async () => {
64
+ const outcome = await decideOn([answerReply(probe())]);
65
+ assert.ok(BASES.includes(outcome.cost_basis), `cost_basis is one of ${BASES.join(", ")}, got ${String(outcome.cost_basis)}`);
66
+ assert.equal(outcome.cost_usd === null, outcome.cost_basis === "unknown", `an unknown cost is null and a known one is not: ${outcome.cost_usd} (${outcome.cost_basis})`);
67
+ if (outcome.cost_usd !== null)
68
+ assert.ok(Number.isFinite(outcome.cost_usd) && outcome.cost_usd >= 0);
69
+ if (outcome.usage !== null)
70
+ assert.ok(Number.isSafeInteger(outcome.usage.input_tokens) && Number.isSafeInteger(outcome.usage.output_tokens));
71
+ });
72
+ it("401 and 403 are auth errors", async () => {
73
+ await assert.rejects(decideOn([{ kind: "status", status: 401 }]), failsWith("auth"));
74
+ await assert.rejects(decideOn([{ kind: "status", status: 403 }]), failsWith("auth"));
75
+ });
76
+ it("422 is invalid_request", async () => {
77
+ await assert.rejects(decideOn([{ kind: "status", status: 422 }]), failsWith("invalid_request"));
78
+ });
79
+ it("429 is rate_limited once its retries are spent", async () => {
80
+ await assert.rejects(decideOn([{ kind: "status", status: 429 }]), failsWith("rate_limited"));
81
+ });
82
+ it("a 5xx is outcome_unknown for a provider that cannot replay, and an http error for one that dedupes", async () => {
83
+ const code = probe().capabilities.replay === "never" ? "outcome_unknown" : "http";
84
+ for (const status of [500, 503])
85
+ await assert.rejects(decideOn([{ kind: "status", status }]), failsWith(code));
86
+ });
87
+ it("a provider that cannot replay never retries a failure after the request was sent", async () => {
88
+ if (probe().capabilities.replay !== "never")
89
+ return;
90
+ for (const reply of [{ kind: "status", status: 500 }, { kind: "status", status: 503 }, { kind: "status", status: 408 }, { kind: "lost" }]) {
91
+ const { provider, calls } = kit.build([reply, answerReply(probe())]);
92
+ await assert.rejects(provider.decide(request(asked(provider).questions), ctx()), failsWith("outcome_unknown"));
93
+ assert.equal(calls(), 1, `${JSON.stringify(reply)} was sent ${calls()} times`);
94
+ }
95
+ });
96
+ it("a malformed body is invalid_response", async () => {
97
+ await assert.rejects(decideOn([{ kind: "malformed" }]), failsWith("invalid_response"));
98
+ });
99
+ it("an abort stops a request in flight as aborted", async () => {
100
+ const controller = new AbortController();
101
+ setTimeout(() => controller.abort(), 20);
102
+ await assert.rejects(within(2_000, decideOn([{ kind: "hang" }], undefined, ctx({ signal: controller.signal, deadlineMs: 10_000 }))), failsWith("aborted"));
103
+ });
104
+ it("a request in flight past its deadline is outcome_unknown for a provider that cannot replay, and timeout for one that dedupes", async () => {
105
+ const code = probe().capabilities.replay === "never" ? "outcome_unknown" : "timeout";
106
+ await assert.rejects(within(3_000, decideOn([{ kind: "hang" }], undefined, ctx({ deadlineMs: 50 }))), failsWith(code));
107
+ });
108
+ it("no key appears in a result or an error", async () => {
109
+ const seen = [JSON.stringify(await decideOn([answerReply(probe(), { evidence: EVIDENCE })]))];
110
+ for (const reply of [{ kind: "status", status: 401 }, { kind: "status", status: 422 }, { kind: "status", status: 429 }, { kind: "status", status: 500 }, { kind: "malformed" }]) {
111
+ try {
112
+ await decideOn([reply]);
113
+ seen.push("no error");
114
+ }
115
+ catch (error) {
116
+ seen.push(String(error), error?.stack ?? "", JSON.stringify(error));
117
+ }
118
+ }
119
+ for (const text of seen)
120
+ assert.ok(!text.includes(kit.canary), "the key appears in what the provider returned or threw");
121
+ });
122
+ it("a request beyond its declared capabilities is refused before anything is sent", async () => {
123
+ const { provider, calls } = kit.build([answerReply(probe())]);
124
+ const { maxQuestions, maxStateBytes, types } = provider.capabilities;
125
+ const over = [];
126
+ if (maxQuestions !== null)
127
+ over.push(request(Object.fromEntries(Array.from({ length: maxQuestions + 1 }, (_, i) => [`q${i}`, { type: "noul", instructions: `Question ${i}?` }]))));
128
+ if (!types.includes("box"))
129
+ over.push(request({ spot: { type: "box", instructions: "Where is it?" } }));
130
+ if (maxStateBytes !== null)
131
+ over.push(request(asked(provider).questions, { text: "x".repeat(maxStateBytes + 1) }));
132
+ if (provider.capabilities.models)
133
+ over.push({ ...request(asked(provider).questions), model: "a-model-it-does-not-declare" });
134
+ for (const each of over)
135
+ await assert.rejects(provider.decide(each, ctx()), failsWith("invalid_request"));
136
+ assert.equal(calls(), 0, "nothing was sent");
137
+ });
138
+ it("a refusal comes back as a refusal", async () => {
139
+ const { answers } = asked(probe());
140
+ const outcome = await decideOn([{ kind: "answer", answers: { ...answers, holds: { type: "refusal" } } }]);
141
+ assert.deepEqual(outcome.answers.holds, { type: "refusal" });
142
+ }, { skip: kit.refuses ? false : "the provider's wire format carries no refusal" });
143
+ it("evidence is a list of sources, and the request id a string or null", async () => {
144
+ const provider = probe();
145
+ const outcome = await decideOn([answerReply(provider, { evidence: EVIDENCE })]);
146
+ assert.ok(Array.isArray(outcome.evidence), "evidence is a list");
147
+ for (const source of outcome.evidence) {
148
+ assert.equal(typeof source.url, "string");
149
+ assert.ok(source.title === null || typeof source.title === "string");
150
+ assert.ok(Array.isArray(source.excerpts) && source.excerpts.every((excerpt) => typeof excerpt === "string"));
151
+ assert.equal(typeof source.scope, "string");
152
+ }
153
+ if (provider.capabilities.evidence === "none")
154
+ assert.equal(outcome.evidence.length, 0, "a provider with no evidence returns none");
155
+ else
156
+ assert.ok(outcome.evidence.length > 0, "a provider with evidence returns the sources it was given");
157
+ assert.ok(outcome.provider_request_id === null || typeof outcome.provider_request_id === "string");
158
+ });
159
+ it("it declares only what the seam can send: noul, choice and score questions, from text, JSON, a URL or an image", async () => {
160
+ // A box question has no node that asks it, and the seam carries no PDF: a provider that declares either cannot be
161
+ // asked for it through judgeFromProvider.
162
+ const { capabilities } = probe();
163
+ for (const type of capabilities.types)
164
+ assert.ok(["noul", "choice", "score"].includes(type), `it declares ${type} questions, which the seam cannot send`);
165
+ for (const input of capabilities.inputs)
166
+ assert.ok(["text", "json", "url", "image"].includes(input), `it declares ${input} input, which the seam cannot carry`);
167
+ });
168
+ it("a provider that takes images answers a request that carries one, named in its state", async () => {
169
+ const { questions, answers } = asked(probe());
170
+ const { provider, calls } = kit.build([{ kind: "answer", answers }]);
171
+ const images = { "<page>": { bytes: PNG, mime: "image/png", ref: "pages/conformance/1.png" } };
172
+ const outcome = await provider.decide({ ...request(questions, { page: "<page>", note: "the page is <page>" }), images }, ctx());
173
+ assert.deepEqual(Object.keys(outcome.answers).sort(), Object.keys(questions).sort());
174
+ assert.equal(calls(), 1);
175
+ }, { skip: kit.build([{ kind: "hang" }]).provider.capabilities.inputs.includes("image") ? false : "the provider takes no image input" });
176
+ it("needs names environment variables, never their values", async () => {
177
+ const { needs } = probe();
178
+ for (const variable of needs) {
179
+ assert.match(variable, /^[A-Z][A-Z0-9_]*$/);
180
+ assert.ok(!variable.includes(kit.canary));
181
+ }
182
+ });
183
+ }
@@ -0,0 +1 @@
1
+ export { registerDecisionProviderConformance, type DecisionProviderKit, type KitReply } from "./decision-provider.js";
@@ -0,0 +1,2 @@
1
+ // Test kits a host or provider package registers in its own tests.
2
+ export { registerDecisionProviderConformance } from "./decision-provider.js";
@@ -2,30 +2,49 @@ export declare const WORKFLOW_NODE_KINDS: readonly ["chain", "code", "agent", "d
2
2
  export type WorkflowNodeKind = typeof WORKFLOW_NODE_KINDS[number];
3
3
  /** Generative kinds: one adapter session each, answering against a schema. */
4
4
  export declare const GENERATIVE_NODE_KINDS: readonly ["agent", "decide", "extract", "report"];
5
+ /** What a decision node or an `ask` predicate may say about its provider: which one, a pinned model, the evidence it
6
+ * needs, its own time bound, and the images it sends (token -> image reference). */
7
+ export declare const DECISION_NODE_FIELDS: readonly ["provider", "model", "evidence", "timeoutMs", "images"];
8
+ /** The longest a decision node may give its provider, in milliseconds. A node only ever shortens its provider's own deadline. */
9
+ export declare const DECISION_TIMEOUT_MAX_MS = 120000;
5
10
  /** Typed-question kinds: one judge request each, no tools and no session. */
6
11
  export declare const JUDGMENT_NODE_KINDS: readonly ["judge", "pick", "sift", "route"];
7
12
  /** The fields each node kind accepts. Any other key is an authoring error. */
8
13
  export declare const NODE_FIELDS: {
9
14
  readonly [Kind in WorkflowNodeKind]: readonly string[];
10
15
  };
16
+ /** Fields every node kind accepts in addition to its own. `metadata` is the host's: an optional object of
17
+ * host markers the engine admits, carries and hashes with the document, and never reads. */
18
+ export declare const HOST_NODE_FIELDS: readonly ["metadata"];
11
19
  /** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
12
20
  export declare const IGNORED_NODE_FIELDS: {
13
21
  readonly [Kind in WorkflowNodeKind]?: readonly string[];
14
22
  };
15
- /** Predicates that read a state value. `poll` accepts only these. */
16
- export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
23
+ /** Predicates that read a state value. `poll` accepts only these, and `not` holds only one of these. */
24
+ export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not"];
17
25
  /** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
18
- export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "ask"];
26
+ export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not", "ask"];
19
27
  export type WorkflowPredicateName = typeof WORKFLOW_PREDICATES[number];
20
28
  /** The fields each predicate takes. */
21
29
  export declare const PREDICATE_FIELDS: {
22
30
  readonly [Name in WorkflowPredicateName]: readonly string[];
23
31
  };
32
+ /** The JSON types `field_type` names. A number is a finite one: NaN and the infinities are no JSON value. */
33
+ export declare const FIELD_TYPES: readonly ["number", "string", "boolean", "array", "object", "null"];
34
+ export type FieldType = typeof FIELD_TYPES[number];
24
35
  export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
25
36
  /** There is no "off": every generative node thinks. */
26
37
  export declare const THINKING_LEVELS: readonly ["low", "medium", "high"];
27
38
  export declare const MODEL_TIERS: readonly ["fast", "default", "strong"];
39
+ /** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
40
+ * the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
41
+ export declare const AGENT_CONTEXTS: readonly ["fresh", "fork"];
28
42
  export declare const CALL_TRANSPORTS: readonly ["tool", "executor", "shell"];
29
43
  export declare const CALL_RETRY_CLASSES: readonly ["timeout", "http_5xx", "http_429", "connection", "exit"];
44
+ /** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
45
+ * `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
46
+ * effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
47
+ * that types a failure itself names the code. */
48
+ export declare const EFFECT_FAILURE_CODES: readonly ["effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing", "effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport"];
30
49
  /** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
31
50
  export declare const PROSE_ARTIFACT_TYPES: readonly ["markdown", "report"];
@@ -6,6 +6,11 @@ export const WORKFLOW_NODE_KINDS = [
6
6
  ];
7
7
  /** Generative kinds: one adapter session each, answering against a schema. */
8
8
  export const GENERATIVE_NODE_KINDS = ["agent", "decide", "extract", "report"];
9
+ /** What a decision node or an `ask` predicate may say about its provider: which one, a pinned model, the evidence it
10
+ * needs, its own time bound, and the images it sends (token -> image reference). */
11
+ export const DECISION_NODE_FIELDS = ["provider", "model", "evidence", "timeoutMs", "images"];
12
+ /** The longest a decision node may give its provider, in milliseconds. A node only ever shortens its provider's own deadline. */
13
+ export const DECISION_TIMEOUT_MAX_MS = 120_000;
9
14
  /** Typed-question kinds: one judge request each, no tools and no session. */
10
15
  export const JUDGMENT_NODE_KINDS = ["judge", "pick", "sift", "route"];
11
16
  const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"];
@@ -13,29 +18,32 @@ const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection
13
18
  export const NODE_FIELDS = {
14
19
  chain: ["node", "steps"],
15
20
  code: ["node", "label", "code", "as"],
16
- agent: GENERATIVE_FIELDS,
21
+ agent: [...GENERATIVE_FIELDS, "budget_usd", "max_turns", "context"],
17
22
  decide: GENERATIVE_FIELDS,
18
23
  extract: GENERATIVE_FIELDS,
19
24
  report: ["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
20
25
  artifact: ["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
21
- map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"],
26
+ map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency", "onItemFailure", "failedAs"],
22
27
  parallel: ["node", "label", "branches"],
23
- loop: ["node", "label", "body", "until", "maxIters"],
28
+ loop: ["node", "label", "body", "until", "maxIters", "expect_iters"],
24
29
  escalate: ["node", "label", "when", "kind", "stage", "summary"],
25
30
  call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires"],
26
31
  workflow: ["node", "label", "workflow", "input", "out", "as"],
27
- judge: ["node", "label", "state", "out", "as", "requires"],
28
- pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"],
29
- sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"],
30
- route: ["node", "label", "state", "instructions", "branches", "unsure", "as", "requires"],
32
+ judge: ["node", "label", "state", "out", "as", "requires", ...DECISION_NODE_FIELDS],
33
+ pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires", ...DECISION_NODE_FIELDS],
34
+ sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires", ...DECISION_NODE_FIELDS],
35
+ route: ["node", "label", "state", "instructions", "branches", "unsure", "valuePath", "otherwise", "as", "requires", ...DECISION_NODE_FIELDS],
31
36
  };
37
+ /** Fields every node kind accepts in addition to its own. `metadata` is the host's: an optional object of
38
+ * host markers the engine admits, carries and hashes with the document, and never reads. */
39
+ export const HOST_NODE_FIELDS = ["metadata"];
32
40
  /** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
33
41
  export const IGNORED_NODE_FIELDS = {
34
42
  agent: ["budget"],
35
43
  decide: ["samples", "voteField"],
36
44
  };
37
- /** Predicates that read a state value. `poll` accepts only these. */
38
- export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
45
+ /** Predicates that read a state value. `poll` accepts only these, and `not` holds only one of these. */
46
+ export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not"];
39
47
  /** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
40
48
  export const WORKFLOW_PREDICATES = [...MECHANICAL_PREDICATES, "ask"];
41
49
  /** The fields each predicate takes. */
@@ -48,13 +56,28 @@ export const PREDICATE_FIELDS = {
48
56
  lt: ["path", "n"],
49
57
  empty: ["path"],
50
58
  no_new_items: ["key"],
51
- ask: ["instructions", "state", "criteria", "gte"],
59
+ field_type: ["path", "type"],
60
+ not: ["of"],
61
+ ask: ["instructions", "state", "criteria", "gte", ...DECISION_NODE_FIELDS],
52
62
  };
63
+ /** The JSON types `field_type` names. A number is a finite one: NaN and the infinities are no JSON value. */
64
+ export const FIELD_TYPES = ["number", "string", "boolean", "array", "object", "null"];
53
65
  export const EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
54
66
  /** There is no "off": every generative node thinks. */
55
67
  export const THINKING_LEVELS = ["low", "medium", "high"];
56
68
  export const MODEL_TIERS = ["fast", "default", "strong"];
69
+ /** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
70
+ * the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
71
+ export const AGENT_CONTEXTS = ["fresh", "fork"];
57
72
  export const CALL_TRANSPORTS = ["tool", "executor", "shell"];
58
73
  export const CALL_RETRY_CLASSES = ["timeout", "http_5xx", "http_429", "connection", "exit"];
74
+ /** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
75
+ * `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
76
+ * effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
77
+ * that types a failure itself names the code. */
78
+ export const EFFECT_FAILURE_CODES = [
79
+ "effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing",
80
+ "effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport",
81
+ ];
59
82
  /** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
60
83
  export const PROSE_ARTIFACT_TYPES = ["markdown", "report"];
@@ -1 +1,8 @@
1
+ /** A shape problem: its message, and a JSON Pointer to the value it is about (to the nearest value the document has, when
2
+ * the one the rule names is missing). */
3
+ export type ShapeIssue = {
4
+ path: string;
5
+ message: string;
6
+ };
1
7
  export declare function workflowShapeErrors(value: unknown, complete?: boolean): string[];
8
+ export declare function workflowShapeIssues(value: unknown, complete?: boolean): ShapeIssue[];
@@ -8,11 +8,36 @@ const isRecord = (value) => value !== null && typeof value === "object" && !Arra
8
8
  // Select the declared discriminator's schema, checking nested nodes separately so
9
9
  // their own discriminators also get useful errors. Never evaluate authored code.
10
10
  const diagnosticDefinitions = { ...documentSchema.definitions, WorkflowNode: {}, Workflow: {} };
11
- const nodeSchemas = new Map(documentSchema.definitions.WorkflowNode.anyOf.map((schema) => [schema.properties.node.const, schema]));
11
+ // A node kind may have more than one schema (a judged route and a route by value are both "route"): every variant is kept.
12
+ const nodeSchemas = new Map();
13
+ for (const schema of documentSchema.definitions.WorkflowNode.anyOf) {
14
+ const kind = schema.properties.node.const;
15
+ nodeSchemas.set(kind, [...(nodeSchemas.get(kind) ?? []), schema]);
16
+ }
12
17
  const diagnosticValidators = new Map();
13
- for (const schema of [documentSchema.definitions.Workflow, ...nodeSchemas.values()]) {
18
+ for (const schema of [documentSchema.definitions.Workflow, ...[...nodeSchemas.values()].flat()]) {
14
19
  diagnosticValidators.set(schema, Compile({ ...schema, definitions: diagnosticDefinitions }));
15
20
  }
21
+ /** The variant of its kind a node is: the one that accepts it, else the one it has the fewest errors against, so a judged
22
+ * route missing its state is diagnosed as a judged route, not as a route by value missing its valuePath. Nested nodes are
23
+ * opaque to a variant's validator, so the count is of the node's own fields. A tie goes to the variant that comes first in
24
+ * the schema: a bare route is diagnosed as a judged route. */
25
+ const variantOf = (variants, entry) => {
26
+ if (variants.length === 1)
27
+ return variants[0];
28
+ let closest = variants[0], fewest = Infinity;
29
+ for (const variant of variants) {
30
+ const validator = diagnosticValidators.get(variant);
31
+ if (validator.Check(entry))
32
+ return variant;
33
+ const count = [...validator.Errors(entry)].length;
34
+ if (count < fewest) {
35
+ closest = variant;
36
+ fewest = count;
37
+ }
38
+ }
39
+ return closest;
40
+ };
16
41
  const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
17
42
  function discriminatedErrors(value) {
18
43
  const errors = [];
@@ -22,7 +47,7 @@ function discriminatedErrors(value) {
22
47
  const validator = diagnosticValidators.get(schema);
23
48
  if (!validator.Check(entry))
24
49
  for (const error of validator.Errors(entry)) {
25
- errors.push(`workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}`);
50
+ errors.push({ path: `${path}${error.instancePath}`, message: `workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}` });
26
51
  if (errors.length >= 8)
27
52
  return;
28
53
  }
@@ -32,9 +57,9 @@ function discriminatedErrors(value) {
32
57
  if (!schema || typeof schema !== "object" || errors.length >= 8)
33
58
  return;
34
59
  if (schema.$ref === "#/definitions/WorkflowNode") {
35
- const selected = isRecord(entry) && typeof entry.node === "string" ? nodeSchemas.get(entry.node) : undefined;
36
- if (selected)
37
- check(selected, entry, path);
60
+ const variants = isRecord(entry) && typeof entry.node === "string" ? nodeSchemas.get(entry.node) : undefined;
61
+ if (variants)
62
+ check(variantOf(variants, entry), entry, path);
38
63
  return; // Unknown/missing discriminators retain the full validator's fallback.
39
64
  }
40
65
  if (schema.$ref === "#/definitions/Workflow") {
@@ -58,124 +83,147 @@ function discriminatedErrors(value) {
58
83
  check(documentSchema.definitions.Workflow, value, "");
59
84
  return errors;
60
85
  }
86
+ /** The deepest prefix of `path` that names a value in `document`: a rule about a missing key points at its container. */
87
+ function present(document, path) {
88
+ let cursor = document;
89
+ let reached = "";
90
+ for (const raw of path.split("/").slice(1)) {
91
+ const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
92
+ if (cursor === null || typeof cursor !== "object" || !Object.hasOwn(cursor, key))
93
+ break;
94
+ cursor = cursor[key];
95
+ reached += `/${raw}`;
96
+ }
97
+ return reached;
98
+ }
61
99
  export function workflowShapeErrors(value, complete = false) {
100
+ return workflowShapeIssues(value, complete).map(issue => issue.message);
101
+ }
102
+ export function workflowShapeIssues(value, complete = false) {
103
+ const located = (issues) => issues.map(issue => ({ path: present(value, issue.path), message: issue.message }));
62
104
  if (complete) {
63
105
  if (fullValidator.Check(value))
64
106
  return [];
65
107
  const selected = discriminatedErrors(value);
66
108
  if (selected.length)
67
- return selected;
68
- return [...fullValidator.Errors(value)].slice(0, 8).map(error => `workflow${error.instancePath || "/"}: ${error.message}`);
109
+ return located(selected);
110
+ return located([...fullValidator.Errors(value)].slice(0, 8).map(error => ({ path: error.instancePath, message: `workflow${error.instancePath || "/"}: ${error.message}` })));
69
111
  }
112
+ const at = (loc, key) => ({ text: `${loc.text}.${key}`, ptr: `${loc.ptr}/${pointer(key)}` });
113
+ const index = (loc, i) => ({ text: `${loc.text}[${i}]`, ptr: `${loc.ptr}/${i}` });
70
114
  const errors = [];
71
- const fail = (path, expected) => { errors.push(`${path} must be ${expected}`); };
72
- const record = (entry, path) => {
115
+ const fail = (loc, expected) => { errors.push({ path: loc.ptr, message: `${loc.text} must be ${expected}` }); };
116
+ const record = (entry, loc) => {
73
117
  if (isRecord(entry))
74
118
  return true;
75
- fail(path, "an object");
119
+ fail(loc, "an object");
76
120
  return false;
77
121
  };
78
- const strings = (entry, path, keys) => {
122
+ const strings = (entry, loc, keys) => {
79
123
  for (const key of keys)
80
124
  if (entry[key] !== undefined && typeof entry[key] !== "string")
81
- fail(`${path}.${key}`, "a string");
125
+ fail(at(loc, key), "a string");
82
126
  };
83
- const stringList = (entry, path) => {
127
+ const stringList = (entry, loc) => {
84
128
  if (entry === undefined)
85
129
  return;
86
130
  if (!Array.isArray(entry)) {
87
- fail(path, "an array of strings");
131
+ fail(loc, "an array of strings");
88
132
  return;
89
133
  }
90
- entry.forEach((item, index) => { if (typeof item !== "string")
91
- fail(`${path}[${index}]`, "a string"); });
134
+ entry.forEach((item, i) => { if (typeof item !== "string")
135
+ fail(index(loc, i), "a string"); });
92
136
  };
93
137
  // Preserve existing diagnostics for missing, non-finite and out-of-range numbers, and
94
138
  // primitive strings such as poll.deadline_s="soon". Objects can throw during coercion.
95
- const numeric = (entry, path, keys) => {
139
+ const numeric = (entry, loc, keys) => {
96
140
  for (const key of keys) {
97
141
  const item = entry[key];
98
142
  if (item !== null && item !== undefined && !["number", "string", "boolean"].includes(typeof item))
99
- fail(`${path}.${key}`, "a number");
143
+ fail(at(loc, key), "a number");
100
144
  }
101
145
  };
102
- const objectField = (entry, path, key, visit) => {
146
+ const objectField = (entry, loc, key, visit) => {
103
147
  if (entry[key] === undefined)
104
148
  return;
105
- if (record(entry[key], `${path}.${key}`))
106
- visit?.(entry[key], `${path}.${key}`);
149
+ if (record(entry[key], at(loc, key)))
150
+ visit?.(entry[key], at(loc, key));
107
151
  };
108
- const predicate = (entry, path) => {
109
- strings(entry, path, ["predicate", "path", "key", "instructions"]);
110
- numeric(entry, path, ["n", "gte"]);
111
- objectField(entry, path, "state");
112
- objectField(entry, path, "criteria", (criteria, at) => strings(criteria, at, ["true", "false"]));
152
+ const predicate = (entry, loc) => {
153
+ strings(entry, loc, ["predicate", "path", "key", "instructions"]);
154
+ numeric(entry, loc, ["n", "gte"]);
155
+ objectField(entry, loc, "state");
156
+ objectField(entry, loc, "criteria", (criteria, here) => strings(criteria, here, ["true", "false"]));
113
157
  };
114
- const node = (entry, path) => {
158
+ const node = (entry, loc) => {
115
159
  if (entry === undefined)
116
160
  return; // missing bodies already receive semantic diagnostics
117
- if (!record(entry, path))
161
+ if (!record(entry, loc))
118
162
  return;
119
- strings(entry, path, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier"]);
120
- numeric(entry, path, ["maxConcurrency", "maxIters", "deadline_s"]);
163
+ strings(entry, loc, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier", "valuePath", "otherwise", "onItemFailure", "failedAs"]);
164
+ numeric(entry, loc, ["maxConcurrency", "maxIters", "expect_iters", "deadline_s"]);
121
165
  for (const key of ["requires", "tools", "produces"])
122
- stringList(entry[key], `${path}.${key}`);
166
+ stringList(entry[key], at(loc, key));
123
167
  if (entry.sopSection !== undefined && typeof entry.sopSection !== "string")
124
- stringList(entry.sopSection, `${path}.sopSection`);
168
+ stringList(entry.sopSection, at(loc, "sopSection"));
125
169
  for (const key of ["state", "args", "input", "env"])
126
- objectField(entry, path, key);
170
+ objectField(entry, loc, key);
171
+ // Host-owned and opaque: only its container is checked, never its keys or values.
172
+ if (entry.metadata !== undefined && !isRecord(entry.metadata)) {
173
+ errors.push({ path: at(loc, "metadata").ptr, message: `${loc.text} (${typeof entry.label === "string" && entry.label ? entry.label : String(entry.node)}): metadata must be a plain object of host markers` });
174
+ }
127
175
  for (const key of ["until", "when"])
128
- objectField(entry, path, key, predicate);
129
- objectField(entry, path, "verify", (verify, at) => {
130
- strings(verify, at, ["out"]);
131
- numeric(verify, at, ["maxDrives"]);
132
- objectField(verify, at, "state");
133
- objectField(verify, at, "override", (override, here) => numeric(override, here, ["below"]));
176
+ objectField(entry, loc, key, predicate);
177
+ objectField(entry, loc, "verify", (verify, here) => {
178
+ strings(verify, here, ["out"]);
179
+ numeric(verify, here, ["maxDrives"]);
180
+ objectField(verify, here, "state");
181
+ objectField(verify, here, "override", (override, inner) => numeric(override, inner, ["below"]));
134
182
  });
135
- objectField(entry, path, "keep", (keep, at) => { strings(keep, at, ["path"]); numeric(keep, at, ["gte"]); });
136
- objectField(entry, path, "unsure", (unsure, at) => { strings(unsure, at, ["branch"]); numeric(unsure, at, ["gte"]); });
137
- objectField(entry, path, "retry", (retry, at) => {
138
- numeric(retry, at, ["attempts", "backoff_s"]);
139
- stringList(retry.on, `${at}.on`);
183
+ objectField(entry, loc, "keep", (keep, here) => { strings(keep, here, ["path"]); numeric(keep, here, ["gte"]); });
184
+ objectField(entry, loc, "unsure", (unsure, here) => { strings(unsure, here, ["branch"]); numeric(unsure, here, ["gte"]); });
185
+ objectField(entry, loc, "retry", (retry, here) => {
186
+ numeric(retry, here, ["attempts", "backoff_s"]);
187
+ stringList(retry.on, at(here, "on"));
140
188
  });
141
- objectField(entry, path, "poll", (poll, at) => {
142
- numeric(poll, at, ["interval_s", "deadline_s"]);
189
+ objectField(entry, loc, "poll", (poll, here) => {
190
+ numeric(poll, here, ["interval_s", "deadline_s"]);
143
191
  for (const key of ["until", "fail_when"])
144
- objectField(poll, at, key, predicate);
192
+ objectField(poll, here, key, predicate);
145
193
  });
146
194
  if (entry.node === "chain" || entry.node === "parallel") {
147
195
  const key = entry.node === "chain" ? "steps" : "branches";
148
196
  if (entry[key] !== undefined) {
149
197
  if (!Array.isArray(entry[key]))
150
- fail(`${path}.${key}`, "an array of nodes");
198
+ fail(at(loc, key), "an array of nodes");
151
199
  else
152
- entry[key].forEach((child, index) => node(child, `${path}.${key}[${index}]`));
200
+ entry[key].forEach((child, i) => node(child, index(at(loc, key), i)));
153
201
  }
154
202
  }
155
203
  if (entry.node === "map" || entry.node === "loop")
156
- node(entry.body, `${path}.body`);
204
+ node(entry.body, at(loc, "body"));
157
205
  if (entry.node === "route")
158
- objectField(entry, path, "branches", (branches, at) => {
206
+ objectField(entry, loc, "branches", (branches, here) => {
159
207
  for (const [name, branch] of Object.entries(branches))
160
- if (record(branch, `${at}.${name}`)) {
161
- strings(branch, `${at}.${name}`, ["criteria"]);
162
- node(branch.body, `${at}.${name}.body`);
208
+ if (record(branch, at(here, name))) {
209
+ strings(branch, at(here, name), ["criteria"]);
210
+ node(branch.body, at(at(here, name), "body"));
163
211
  }
164
212
  });
165
213
  if (entry.node === "workflow")
166
- workflow(entry.workflow, `${path}.workflow`);
214
+ workflow(entry.workflow, at(loc, "workflow"));
167
215
  };
168
- const workflow = (entry, path) => {
169
- if (!record(entry, path))
216
+ const workflow = (entry, loc) => {
217
+ if (!record(entry, loc))
170
218
  return;
171
- strings(entry, path, ["name"]);
172
- record(entry.schemas, `${path}.schemas`);
173
- objectField(entry, path, "input", (input, at) => strings(input, at, ["schemaId"]));
174
- if (record(entry.output, `${path}.output`))
175
- strings(entry.output, `${path}.output`, ["schemaId", "path"]);
176
- if (record(entry.root, `${path}.root`))
177
- node(entry.root, `${path}.root`);
219
+ strings(entry, loc, ["name"]);
220
+ record(entry.schemas, at(loc, "schemas"));
221
+ objectField(entry, loc, "input", (input, here) => strings(input, here, ["schemaId"]));
222
+ if (record(entry.output, at(loc, "output")))
223
+ strings(entry.output, at(loc, "output"), ["schemaId", "path"]);
224
+ if (record(entry.root, at(loc, "root")))
225
+ node(entry.root, at(loc, "root"));
178
226
  };
179
- workflow(value, "workflow");
180
- return errors.slice(0, 8);
227
+ workflow(value, { text: "workflow", ptr: "" });
228
+ return located(errors.slice(0, 8));
181
229
  }