@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
@@ -1,10 +1,15 @@
1
1
  import { type AcceptPredicate } from "./predicates.js";
2
- import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
2
+ import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
3
+ import { type ConfidenceSource, type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
4
+ import { type CostBasis, type DecisionEvidence, type DecisionProvider } from "./decision-provider.js";
5
+ import { type DecisionImageDigest, type DecisionReceipt } from "./decision-receipts.js";
3
6
  export { resolveSchemaForWorkflow } from "./schema-references.js";
4
7
  /** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
5
8
  * or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
6
9
  * decision is on the edge. */
7
10
  export type ModelTier = "fast" | "default" | "strong";
11
+ /** An `agent` node's context (`AGENT_CONTEXTS`). */
12
+ export type AgentContext = "fresh" | "fork";
8
13
  export type VerifyClause = {
9
14
  out: string;
10
15
  state?: Record<string, unknown>;
@@ -13,6 +18,12 @@ export type VerifyClause = {
13
18
  below: number;
14
19
  };
15
20
  };
21
+ /** What a decision node asks of its provider's evidence: none, whatever it gives, or some (a provider that gives none is refused before the run). */
22
+ export type DecisionEvidenceMode = "off" | "if_supported" | "required";
23
+ /** The images a decision node sends with its request: each key is a token (such as `"<page1>"`) that appears literally in
24
+ * the node's `state` or in a question's text, and each value is a reference to the image, written as a `state` value is
25
+ * (`"{item.pages.0.image}"`, or a literal path), that resolves to a string the host loads (a run-relative file path). */
26
+ export type DecisionImages = Record<string, string>;
16
27
  export type AskPredicate = {
17
28
  predicate: "ask";
18
29
  instructions: string;
@@ -22,20 +33,32 @@ export type AskPredicate = {
22
33
  false?: string;
23
34
  };
24
35
  gte?: number;
36
+ provider?: string;
37
+ model?: string;
38
+ evidence?: DecisionEvidenceMode;
39
+ timeoutMs?: number;
40
+ images?: DecisionImages;
25
41
  };
26
42
  export type MechanicalPredicate = AcceptPredicate;
27
43
  export type Predicate = MechanicalPredicate | AskPredicate;
28
44
  export type WorkflowEffort = "minimal" | "low" | "medium" | "high";
29
45
  /** The author's thinking dial. There is deliberately no "off": thinking is never off. */
30
46
  export type WorkflowThinking = "low" | "medium" | "high";
47
+ /** Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the
48
+ * document and never reads it; it never reaches state, events, prompts or effect identities. */
49
+ export type NodeMetadata = {
50
+ [key: string]: unknown;
51
+ };
31
52
  export type WorkflowNode = {
32
53
  node: "chain";
33
54
  steps: WorkflowNode[];
55
+ metadata?: NodeMetadata;
34
56
  } | {
35
57
  node: "code";
36
58
  label: string;
37
59
  code: string;
38
60
  as?: string;
61
+ metadata?: NodeMetadata;
39
62
  } | {
40
63
  node: "agent";
41
64
  label: string;
@@ -50,6 +73,13 @@ export type WorkflowNode = {
50
73
  thinking?: WorkflowThinking;
51
74
  verify?: VerifyClause;
52
75
  tier?: ModelTier;
76
+ /** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
77
+ budget_usd?: number;
78
+ /** The most turns the node asks its host for, per attempt. The host applies it within its own cap; the engine
79
+ * enforces nothing. @minimum 1 @TJS-type integer */
80
+ max_turns?: number;
81
+ context?: AgentContext;
82
+ metadata?: NodeMetadata;
53
83
  } | {
54
84
  node: "decide";
55
85
  label: string;
@@ -64,6 +94,7 @@ export type WorkflowNode = {
64
94
  thinking?: WorkflowThinking;
65
95
  verify?: VerifyClause;
66
96
  tier?: ModelTier;
97
+ metadata?: NodeMetadata;
67
98
  } | {
68
99
  node: "extract";
69
100
  label: string;
@@ -78,6 +109,7 @@ export type WorkflowNode = {
78
109
  thinking?: WorkflowThinking;
79
110
  verify?: VerifyClause;
80
111
  tier?: ModelTier;
112
+ metadata?: NodeMetadata;
81
113
  } | {
82
114
  node: "report";
83
115
  label: string;
@@ -88,6 +120,7 @@ export type WorkflowNode = {
88
120
  tools?: string[];
89
121
  effort?: WorkflowEffort;
90
122
  thinking?: WorkflowThinking;
123
+ metadata?: NodeMetadata;
91
124
  } | ArtifactNode | {
92
125
  node: "map";
93
126
  label: string;
@@ -96,16 +129,26 @@ export type WorkflowNode = {
96
129
  as: string;
97
130
  resultPath?: string;
98
131
  maxConcurrency?: number;
132
+ /** What an item's failure does: `stop` (the default) stops the map and the run; `collect` ends the item as a row
133
+ * of `failedAs` when its failure is an item failure (`isItemFailure`), and the other items finish. */
134
+ onItemFailure?: "stop" | "collect";
135
+ /** With `onItemFailure: "collect"`, the state key the map writes its failed items under, one row each in item order:
136
+ * `{ item_index, label, code, message }`. `as` stays aligned with the items, `null` in a failed item's slot. */
137
+ failedAs?: string;
138
+ metadata?: NodeMetadata;
99
139
  } | {
100
140
  node: "parallel";
101
141
  label: string;
102
142
  branches: WorkflowNode[];
143
+ metadata?: NodeMetadata;
103
144
  } | {
104
145
  node: "loop";
105
146
  label: string;
106
147
  body: WorkflowNode;
107
148
  until: Predicate;
108
149
  maxIters: number;
150
+ expect_iters?: number;
151
+ metadata?: NodeMetadata;
109
152
  } | {
110
153
  node: "escalate";
111
154
  label: string;
@@ -113,6 +156,7 @@ export type WorkflowNode = {
113
156
  kind: string;
114
157
  stage: string;
115
158
  summary: string;
159
+ metadata?: NodeMetadata;
116
160
  } | JudgeNode | PickNode | SiftNode | RouteNode | CallNode | WorkflowInvocation;
117
161
  /** A judgment as typed questions. `state` is what the questions see, interpolated by value from the
118
162
  * workflow state (a whole-string placeholder keeps its type); `out` is a flat schema of enums,
@@ -125,6 +169,12 @@ export type JudgeNode = {
125
169
  out: string;
126
170
  as: string;
127
171
  requires?: string[];
172
+ provider?: string;
173
+ model?: string;
174
+ evidence?: DecisionEvidenceMode;
175
+ timeoutMs?: number;
176
+ images?: DecisionImages;
177
+ metadata?: NodeMetadata;
128
178
  };
129
179
  /** One choice whose options are the items of a list. `describe` renders each item as its option
130
180
  * text (`{item.field}`); `allowNone` adds a none-of-these option. The result at `as` is
@@ -140,6 +190,12 @@ export type PickNode = {
140
190
  allowNone?: boolean;
141
191
  as: string;
142
192
  requires?: string[];
193
+ provider?: string;
194
+ model?: string;
195
+ evidence?: DecisionEvidenceMode;
196
+ timeoutMs?: number;
197
+ images?: DecisionImages;
198
+ metadata?: NodeMetadata;
143
199
  };
144
200
  /** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
145
201
  * questions are prefixed `i.`; every answer lands in `as.answers[i]` and `as.values[i]`. `keep`
@@ -158,11 +214,20 @@ export type SiftNode = {
158
214
  gte?: number;
159
215
  };
160
216
  requires?: string[];
217
+ provider?: string;
218
+ model?: string;
219
+ evidence?: DecisionEvidenceMode;
220
+ timeoutMs?: number;
221
+ images?: DecisionImages;
222
+ metadata?: NodeMetadata;
161
223
  };
162
- /** A choice among subgraphs. The options are the branch names, their criteria the branch
224
+ /** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
225
+ * already holds the choice as a string at `valuePath` and no model is asked. */
226
+ export type RouteNode = RouteByJudgmentNode | RouteByValueNode;
227
+ /** A choice among subgraphs that Jev makes. The options are the branch names, their criteria the branch
163
228
  * descriptions; the chosen branch runs on the state. `as` (optional) records the choice and its
164
229
  * distribution; `unsure` names the branch taken when confidence is below `gte`. */
165
- export type RouteNode = {
230
+ export type RouteByJudgmentNode = {
166
231
  node: "route";
167
232
  label: string;
168
233
  state: Record<string, unknown>;
@@ -177,9 +242,38 @@ export type RouteNode = {
177
242
  branch: string;
178
243
  gte: number;
179
244
  };
245
+ valuePath?: never;
246
+ otherwise?: never;
180
247
  as?: string;
181
248
  requires?: string[];
249
+ provider?: string;
250
+ model?: string;
251
+ evidence?: DecisionEvidenceMode;
252
+ timeoutMs?: number;
253
+ images?: DecisionImages;
254
+ metadata?: NodeMetadata;
182
255
  };
256
+ /** A route by a value already in state: the string at `valuePath` names the branch. A missing value or
257
+ * an unknown name takes `otherwise` when declared and fails before any branch otherwise; a value that is
258
+ * not a string always fails. `as` records `{value, taken, fallback}`. */
259
+ export type RouteByValueNode = {
260
+ node: "route";
261
+ label: string;
262
+ valuePath: string;
263
+ branches: {
264
+ [branch: string]: {
265
+ body: WorkflowNode;
266
+ };
267
+ };
268
+ otherwise?: string;
269
+ state?: never;
270
+ instructions?: never;
271
+ unsure?: never;
272
+ as?: string;
273
+ requires?: string[];
274
+ metadata?: NodeMetadata;
275
+ };
276
+ export declare const routesByValue: (node: RouteNode) => node is RouteByValueNode;
183
277
  /** A child workflow invoked as one step of its parent. The child is embedded whole, so the parent
184
278
  * digest covers every child byte; `input` is interpolated by value and is the child's ENTIRE initial
185
279
  * state (no parent state leaks in); the child's validated output is checked against the parent's
@@ -192,10 +286,13 @@ export type WorkflowInvocation = {
192
286
  input: Record<string, unknown>;
193
287
  out: string;
194
288
  as: string;
289
+ metadata?: NodeMetadata;
195
290
  };
196
291
  /** `exit` is a shell command that ended with a non-zero status: retried only when the author
197
292
  * declared retry, since re-running a command is the author's call. */
198
293
  export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
294
+ /** A failed effect's closed code (EFFECT_FAILURE_CODES). */
295
+ export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
199
296
  /** The workflow's terminal deliverable. Types "markdown" and "report" use the report
200
297
  * writer; other non-empty types name a workspace file produced by an earlier call.
201
298
  * File existence and delivery are the host's responsibility. */
@@ -214,6 +311,7 @@ export type ArtifactNode = {
214
311
  effort?: WorkflowEffort;
215
312
  thinking?: WorkflowThinking;
216
313
  requires?: string[];
314
+ metadata?: NodeMetadata;
217
315
  };
218
316
  export type ArtifactState = {
219
317
  path: string;
@@ -263,19 +361,24 @@ export type CallNode = {
263
361
  produces?: string[];
264
362
  /** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
265
363
  deadline_s: number;
364
+ /** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
266
365
  retry?: {
267
366
  attempts: number;
268
367
  backoff_s?: number;
269
- on?: CallRetryClass[];
368
+ on?: (CallRetryClass | EffectFailureCode)[];
270
369
  };
271
370
  /** Repeat the call until its result settles (a queued job, an eventually consistent read). */
272
371
  poll?: PollClause;
273
372
  requires?: string[];
373
+ metadata?: NodeMetadata;
274
374
  };
275
375
  export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
276
376
  export type LlmNode = Extract<WorkflowNode, {
277
377
  node: "agent" | "decide" | "extract" | "report";
278
378
  }>;
379
+ export type CodeNode = Extract<WorkflowNode, {
380
+ node: "code";
381
+ }>;
279
382
  export declare const REPORT_SCHEMA: Record<string, unknown>;
280
383
  export type Workflow = {
281
384
  v: 2;
@@ -366,6 +469,10 @@ export type HostPolicy = {
366
469
  };
367
470
  export type WorkflowDeps = {
368
471
  maxQuestionsPerRequest?: number;
472
+ /** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
473
+ * measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
474
+ * requests. Absent = no byte limit. */
475
+ maxStateBytesPerRequest?: number;
369
476
  /** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
370
477
  hostPolicy?: HostPolicy;
371
478
  runNode?: (params: {
@@ -390,6 +497,15 @@ export type WorkflowDeps = {
390
497
  message: string;
391
498
  }>;
392
499
  tier?: ModelTier;
500
+ /** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
501
+ * No runner stops a run on money. A host may cap it by what it has left. */
502
+ budgetUsd?: number;
503
+ /** An `agent` node's `max_turns`: the most turns it asks for, per attempt. The host applies it within its own cap
504
+ * and refuses a node that asks for more; the engine enforces nothing. */
505
+ maxTurns?: number;
506
+ /** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
507
+ * a host that has none to fork refuses it. */
508
+ context?: AgentContext;
393
509
  }) => Promise<unknown>;
394
510
  runEffect?: (params: {
395
511
  node: CallNode;
@@ -399,9 +515,32 @@ export type WorkflowDeps = {
399
515
  attempt: number;
400
516
  idempotencyKey: string;
401
517
  signal: AbortSignal;
518
+ /** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
519
+ * interpreter armed its deadline timer, so the host measures its own kill and duration against
520
+ * the instant the timer fires. Absent when the call has no deadline. */
521
+ deadlineAt?: number;
402
522
  item?: MapItem;
403
523
  executionPath?: string;
404
524
  }) => Promise<unknown>;
525
+ /** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
526
+ * the context the transform would receive and uses what it resolves to as the transform's result
527
+ * (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
528
+ * Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
529
+ * which is not a sandbox: a host that runs code from an untrusted author supplies this. */
530
+ runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
531
+ sop: string;
532
+ label: string;
533
+ executionPath: string;
534
+ item?: MapItem;
535
+ signal?: AbortSignal;
536
+ }) => Promise<unknown>;
537
+ /** The host's decision providers by id, and the one a node that names none gets. A run checks every decision node
538
+ * against them before any node runs: a provider the host lacks, evidence it cannot give, a model it does not serve, a
539
+ * question type it does not answer. Without them, a node that names a provider or sets timeoutMs is refused. */
540
+ decisionProviders?: {
541
+ providers: Readonly<Record<string, DecisionProvider>>;
542
+ default: string;
543
+ };
405
544
  runJudge?: (params: {
406
545
  label: string;
407
546
  kind: "judge" | "pick" | "sift" | "route" | "ask";
@@ -410,6 +549,20 @@ export type WorkflowDeps = {
410
549
  signal?: AbortSignal;
411
550
  state: unknown;
412
551
  questions: Record<string, SystemOneQuestion>;
552
+ /** The id of this request's decision receipt (`DecisionReceipt.id`): the same request asked again
553
+ * carries the same id. */
554
+ decisionId?: string;
555
+ /** The node's provider, by id; absent, the host's default answers. */
556
+ provider?: string;
557
+ /** The model the node pins, when it pins one. */
558
+ model?: string;
559
+ /** What the node asks of the provider's evidence. */
560
+ evidence?: DecisionEvidenceMode;
561
+ /** The node's own time bound, in milliseconds: it only ever shortens the provider's deadline. */
562
+ timeoutMs?: number;
563
+ /** The images the node sends, token -> resolved image reference (a run-relative path). The host loads them
564
+ * (`judgeFromProvider`'s `loadImage`); each token appears literally in `state` or a question's text. */
565
+ images?: Record<string, string>;
413
566
  }) => Promise<{
414
567
  answers: Record<string, SystemOneAnswer>;
415
568
  model?: string | null;
@@ -419,7 +572,25 @@ export type WorkflowDeps = {
419
572
  } | null;
420
573
  cost_usd?: number | null;
421
574
  request_sha256?: string;
575
+ /** Whether each choice and score answer's confidence is the provider's own or derived from its probabilities. */
576
+ confidence_source?: Record<string, ConfidenceSource>;
577
+ /** The sources the provider grounded its answers in (a DecisionProvider's, through judgeFromProvider). */
578
+ evidence?: DecisionEvidence[];
579
+ /** The provider's own id for the request, when it gives one. */
580
+ provider_request_id?: string | null;
581
+ /** How `cost_usd` was reached: reported by the provider, estimated by the host, or unknown (null). */
582
+ cost_basis?: CostBasis;
583
+ /** The provider that answered, by id. */
584
+ provider?: string;
585
+ /** The images the request carried, by digest (never the bytes), as the host loaded them. */
586
+ images?: DecisionImageDigest[];
422
587
  }>;
588
+ /** Records one typed-question request and what its answers decide. It is awaited before the answers
589
+ * reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
590
+ * rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
591
+ * recorded too, before its failure is thrown. A decision answered from `recovery.decision` was
592
+ * recorded by the run that asked it and is not recorded again. */
593
+ recordDecision?: (receipt: DecisionReceipt, exchange: DecisionExchange) => Promise<void>;
423
594
  syntheticEffects?: boolean;
424
595
  checkpoint?: (state: Record<string, unknown>, label: string, executionPath?: string) => Promise<void>;
425
596
  /** Critical recovery stores stop execution on write failure; omitted retains legacy best effort. */
@@ -432,6 +603,17 @@ export type WorkflowDeps = {
432
603
  pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
433
604
  wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
434
605
  fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
606
+ /** A map with `onItemFailure: "collect"` commits an item that ended on its failure here, at the item's body path,
607
+ * once, before the map goes on; `node` is the map. A store without both hooks cannot hold such a map: it is refused
608
+ * before any step runs. */
609
+ failItem?: (node: WorkflowNode, failure: MapItemFailure, executionPath?: string) => Promise<void>;
610
+ /** The failure an earlier process committed for the item whose body path this is, if any: the item ends on it again,
611
+ * and its body never runs again. */
612
+ itemFailure?: (node: WorkflowNode, executionPath?: string) => Promise<MapItemFailure | undefined>;
613
+ /** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
614
+ * the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
615
+ * other receipt, or none, means the request is asked. */
616
+ decision?: (id: string) => Promise<DecisionReceipt | undefined>;
435
617
  };
436
618
  /** A completed-effect memo keyed by the call's idempotency key. A hit skips the effect and
437
619
  * reuses its result; polled calls are never memoized (their result is a moment in time). */
@@ -444,18 +626,39 @@ export type WorkflowDeps = {
444
626
  signal?: AbortSignal;
445
627
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
446
628
  * Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
447
- onEvent?: (event: {
448
- type: string;
449
- label: string;
450
- detail?: unknown;
451
- executionPath?: string;
452
- }) => void;
629
+ onEvent?: (event: WorkflowEvent) => void;
630
+ /** Trusted host boundary: return a detached snapshot without mutating the input.
631
+ * Runs before generic copying; undefined or thrown errors omit the event.
632
+ * Required trace validation cancels through the host signal, preserving execution cleanup. */
633
+ prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
634
+ };
635
+ export type WorkflowEvent = {
636
+ type: string;
637
+ label: string;
638
+ detail?: unknown;
639
+ executionPath?: string;
640
+ };
641
+ type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
642
+ type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
643
+ /** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
644
+ * and, when the judge returned, the very object it returned, so a host reads back what it put there. */
645
+ export type DecisionExchange = {
646
+ request: JudgeRequest;
647
+ result?: JudgeResult;
453
648
  };
454
649
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
455
650
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
651
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
652
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
456
653
  export declare class EffectFailure extends Error {
457
654
  readonly retryClass: CallRetryClass | null;
458
- constructor(message: string, retryClass?: CallRetryClass | null);
655
+ readonly code: EffectFailureCode | null;
656
+ readonly detail?: Record<string, unknown>;
657
+ constructor(message: string, retryClass?: CallRetryClass | null, options?: {
658
+ code?: EffectFailureCode | null;
659
+ detail?: Record<string, unknown>;
660
+ cause?: unknown;
661
+ });
459
662
  }
460
663
  export declare function parseCsvRows(text: string): string[][];
461
664
  export declare function buildReferenceContext(files: Record<string, string>): {
@@ -465,15 +668,28 @@ export declare function buildReferenceContext(files: Record<string, string>): {
465
668
  rows: string[][];
466
669
  }>;
467
670
  };
468
- export declare function normalizeStringNullsForSchema(value: unknown, schema: Record<string, unknown> | undefined, depth?: number): unknown;
671
+ export declare function normalizeStringNullsForSchema(value: unknown, schema: Record<string, unknown> | undefined, depth?: number, root?: Record<string, unknown> | undefined): unknown;
469
672
  export declare function workflowSha256(workflow: Workflow): string;
470
673
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
471
674
  * objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
472
675
  export declare function workflowDocumentError(value: unknown): string | undefined;
473
- /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
474
- * without evaluating authored expressions or probing transforms. This is not execution admission;
475
- * trusted/default validation and runtime output checks remain authoritative. */
476
- export declare function validateWorkflow(workflow: Workflow, opts?: {
676
+ /** The rule a validation issue breaks. A closed set: a new code widens it, so a consumer keeps a default branch; renaming
677
+ * one is a breaking change. `docs/guide.md` lists each with an example. */
678
+ export type ValidationCode = "DOCUMENT_INVALID" | "SHAPE_INVALID" | "WORKFLOW_FIELD_INVALID" | "SCHEMA_INVALID" | "SCHEMA_UNKNOWN" | "INPUT_INVALID" | "NODE_KIND_UNKNOWN" | "NODE_KEY_UNKNOWN" | "NODE_FIELD_INVALID" | "STATE_KEY_RESERVED" | "STATE_PATH_UNPRODUCED" | "STATE_PATH_EXCLUDED" | "PARALLEL_WRITE_CONFLICT" | "STRUCTURE_INVALID" | "PREDICATE_INVALID" | "CODE_INVALID";
679
+ /** One validation error. `message` is the matching entry of `errors`, unchanged. `path` is a JSON Pointer (RFC 6901)
680
+ * into the workflow as written, naming what the rule is about: a node (the same path `inspectWorkflow` gives it), a
681
+ * schema (`/schemas/<id>`), a value the shape check refused, or `""` for the document's own fields and for the input
682
+ * supplied to validation. It never names a key that is missing. */
683
+ export type ValidationIssue = {
684
+ path: string;
685
+ code: ValidationCode;
686
+ message: string;
687
+ };
688
+ /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse.
689
+ * Set `executeCode: false` for untrusted author feedback: check syntax and mechanical contracts without evaluating
690
+ * authored expressions or probing transforms. That is not execution admission; trusted/default validation and runtime
691
+ * output checks remain authoritative. */
692
+ export type ValidateWorkflowOptions = {
477
693
  executeCode?: boolean;
478
694
  input?: Record<string, unknown>;
479
695
  inputKeys?: string[];
@@ -484,11 +700,18 @@ export declare function validateWorkflow(workflow: Workflow, opts?: {
484
700
  rows: string[][];
485
701
  }>;
486
702
  };
487
- }): {
703
+ /** The host's tool names. Given, a node that names a tool outside them (a model or artifact node's `tools`, a call
704
+ * node's `tool`) is refused here. Absent, tool names are not checked until a node runs. */
705
+ tools?: readonly string[];
706
+ };
707
+ export declare function validateWorkflow(workflow: Workflow, opts?: ValidateWorkflowOptions): {
488
708
  ok: true;
709
+ warnings?: string[];
489
710
  } | {
490
711
  ok: false;
491
712
  errors: string[];
713
+ issues: ValidationIssue[];
714
+ warnings?: string[];
492
715
  };
493
716
  export declare class EscalationSignal extends Error {
494
717
  readonly escalation: Escalation;
@@ -500,9 +723,11 @@ export declare function schemaProblems(validator: {
500
723
  export declare class WorkflowInvalidError extends Error {
501
724
  readonly workflowName: string;
502
725
  readonly problems: string[];
726
+ readonly issues: ValidationIssue[];
503
727
  readonly code = "workflow_invalid";
504
728
  readonly stage = "validate";
505
- constructor(workflowName: string, problems: string[]);
729
+ /** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
730
+ constructor(workflowName: string, problems: string[], issues?: ValidationIssue[]);
506
731
  }
507
732
  export declare class WorkflowInputInvalidError extends Error {
508
733
  readonly workflowName: string;
@@ -557,13 +782,37 @@ export declare class WorkflowCodeError extends Error {
557
782
  export declare class WorkflowStateError extends Error {
558
783
  readonly stage: string;
559
784
  readonly path: string;
560
- readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key";
785
+ readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type";
561
786
  readonly code = "state_invalid";
562
- constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key");
787
+ constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type");
563
788
  }
789
+ /** A map item that ended on its failure (`onItemFailure: "collect"`), as `failedAs` holds it: the item's index, the
790
+ * label of the node that failed, the failure's code and its message (at most 300 characters). `needs_review` marks an
791
+ * item whose decision went to a person instead of failing: one sent whose outcome was lost (`decision_interrupted`,
792
+ * never asked again) or one its provider refused (`decision_refused`); its code is that escalation's kind. */
793
+ export type MapItemFailure = {
794
+ item_index: number;
795
+ label: string;
796
+ code: string;
797
+ message: string;
798
+ needs_review?: true;
799
+ };
800
+ /** Whether an item's failure is one a map with `onItemFailure: "collect"` ends the item on: one of the interpreter's own
801
+ * typed node failures (a call that failed after its retries, output that does not match its schema, a state contract, a
802
+ * code transform, a failed verification), or a host's failure that declares itself one, with a string `code` and
803
+ * `itemFailure: true`. Never one whose cause chain holds an effect whose outcome is unknown, a recovery failure, an
804
+ * escalation or an abort, never several failures at once, and nothing else: a new error class is never collected by
805
+ * accident. */
806
+ export declare function isItemFailure(error: unknown): boolean;
564
807
  export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
565
808
  export declare const submissionSchemaForNode: typeof stageSchemaForNode;
566
809
  export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
810
+ /** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
811
+ export declare class WorkflowDecisionRecordError extends Error {
812
+ readonly label: string;
813
+ readonly decisionId: string;
814
+ constructor(label: string, decisionId: string, cause: unknown);
815
+ }
567
816
  /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
568
817
  export declare const HOST_STATE_KEY = "$host";
569
818
  export declare class WorkflowVerificationError extends Error {