@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
@@ -1,10 +1,14 @@
1
1
  import { type AcceptPredicate } from "./predicates.js";
2
+ import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
2
3
  import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
4
+ import { type DecisionReceipt } from "./decision-receipts.js";
3
5
  export { resolveSchemaForWorkflow } from "./schema-references.js";
4
6
  /** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
5
7
  * or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
6
8
  * decision is on the edge. */
7
9
  export type ModelTier = "fast" | "default" | "strong";
10
+ /** An `agent` node's context (`AGENT_CONTEXTS`). */
11
+ export type AgentContext = "fresh" | "fork";
8
12
  export type VerifyClause = {
9
13
  out: string;
10
14
  state?: Record<string, unknown>;
@@ -28,14 +32,21 @@ export type Predicate = MechanicalPredicate | AskPredicate;
28
32
  export type WorkflowEffort = "minimal" | "low" | "medium" | "high";
29
33
  /** The author's thinking dial. There is deliberately no "off": thinking is never off. */
30
34
  export type WorkflowThinking = "low" | "medium" | "high";
35
+ /** Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the
36
+ * document and never reads it; it never reaches state, events, prompts or effect identities. */
37
+ export type NodeMetadata = {
38
+ [key: string]: unknown;
39
+ };
31
40
  export type WorkflowNode = {
32
41
  node: "chain";
33
42
  steps: WorkflowNode[];
43
+ metadata?: NodeMetadata;
34
44
  } | {
35
45
  node: "code";
36
46
  label: string;
37
47
  code: string;
38
48
  as?: string;
49
+ metadata?: NodeMetadata;
39
50
  } | {
40
51
  node: "agent";
41
52
  label: string;
@@ -50,6 +61,10 @@ export type WorkflowNode = {
50
61
  thinking?: WorkflowThinking;
51
62
  verify?: VerifyClause;
52
63
  tier?: ModelTier;
64
+ /** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
65
+ budget_usd?: number;
66
+ context?: AgentContext;
67
+ metadata?: NodeMetadata;
53
68
  } | {
54
69
  node: "decide";
55
70
  label: string;
@@ -64,6 +79,7 @@ export type WorkflowNode = {
64
79
  thinking?: WorkflowThinking;
65
80
  verify?: VerifyClause;
66
81
  tier?: ModelTier;
82
+ metadata?: NodeMetadata;
67
83
  } | {
68
84
  node: "extract";
69
85
  label: string;
@@ -78,6 +94,7 @@ export type WorkflowNode = {
78
94
  thinking?: WorkflowThinking;
79
95
  verify?: VerifyClause;
80
96
  tier?: ModelTier;
97
+ metadata?: NodeMetadata;
81
98
  } | {
82
99
  node: "report";
83
100
  label: string;
@@ -88,6 +105,7 @@ export type WorkflowNode = {
88
105
  tools?: string[];
89
106
  effort?: WorkflowEffort;
90
107
  thinking?: WorkflowThinking;
108
+ metadata?: NodeMetadata;
91
109
  } | ArtifactNode | {
92
110
  node: "map";
93
111
  label: string;
@@ -96,16 +114,26 @@ export type WorkflowNode = {
96
114
  as: string;
97
115
  resultPath?: string;
98
116
  maxConcurrency?: number;
117
+ /** What an item's failure does: `stop` (the default) stops the map and the run; `collect` ends the item as a row
118
+ * of `failedAs` when its failure is an item failure (`isItemFailure`), and the other items finish. */
119
+ onItemFailure?: "stop" | "collect";
120
+ /** With `onItemFailure: "collect"`, the state key the map writes its failed items under, one row each in item order:
121
+ * `{ item_index, label, code, message }`. `as` stays aligned with the items, `null` in a failed item's slot. */
122
+ failedAs?: string;
123
+ metadata?: NodeMetadata;
99
124
  } | {
100
125
  node: "parallel";
101
126
  label: string;
102
127
  branches: WorkflowNode[];
128
+ metadata?: NodeMetadata;
103
129
  } | {
104
130
  node: "loop";
105
131
  label: string;
106
132
  body: WorkflowNode;
107
133
  until: Predicate;
108
134
  maxIters: number;
135
+ expect_iters?: number;
136
+ metadata?: NodeMetadata;
109
137
  } | {
110
138
  node: "escalate";
111
139
  label: string;
@@ -113,6 +141,7 @@ export type WorkflowNode = {
113
141
  kind: string;
114
142
  stage: string;
115
143
  summary: string;
144
+ metadata?: NodeMetadata;
116
145
  } | JudgeNode | PickNode | SiftNode | RouteNode | CallNode | WorkflowInvocation;
117
146
  /** A judgment as typed questions. `state` is what the questions see, interpolated by value from the
118
147
  * workflow state (a whole-string placeholder keeps its type); `out` is a flat schema of enums,
@@ -125,6 +154,7 @@ export type JudgeNode = {
125
154
  out: string;
126
155
  as: string;
127
156
  requires?: string[];
157
+ metadata?: NodeMetadata;
128
158
  };
129
159
  /** One choice whose options are the items of a list. `describe` renders each item as its option
130
160
  * text (`{item.field}`); `allowNone` adds a none-of-these option. The result at `as` is
@@ -140,6 +170,7 @@ export type PickNode = {
140
170
  allowNone?: boolean;
141
171
  as: string;
142
172
  requires?: string[];
173
+ metadata?: NodeMetadata;
143
174
  };
144
175
  /** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
145
176
  * questions are prefixed `i.`; every answer lands in `as.answers[i]` and `as.values[i]`. `keep`
@@ -158,11 +189,15 @@ export type SiftNode = {
158
189
  gte?: number;
159
190
  };
160
191
  requires?: string[];
192
+ metadata?: NodeMetadata;
161
193
  };
162
- /** A choice among subgraphs. The options are the branch names, their criteria the branch
194
+ /** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
195
+ * already holds the choice as a string at `valuePath` and no model is asked. */
196
+ export type RouteNode = RouteByJudgmentNode | RouteByValueNode;
197
+ /** A choice among subgraphs that Jev makes. The options are the branch names, their criteria the branch
163
198
  * descriptions; the chosen branch runs on the state. `as` (optional) records the choice and its
164
199
  * distribution; `unsure` names the branch taken when confidence is below `gte`. */
165
- export type RouteNode = {
200
+ export type RouteByJudgmentNode = {
166
201
  node: "route";
167
202
  label: string;
168
203
  state: Record<string, unknown>;
@@ -177,9 +212,33 @@ export type RouteNode = {
177
212
  branch: string;
178
213
  gte: number;
179
214
  };
215
+ valuePath?: never;
216
+ otherwise?: never;
217
+ as?: string;
218
+ requires?: string[];
219
+ metadata?: NodeMetadata;
220
+ };
221
+ /** A route by a value already in state: the string at `valuePath` names the branch. A missing value or
222
+ * an unknown name takes `otherwise` when declared and fails before any branch otherwise; a value that is
223
+ * not a string always fails. `as` records `{value, taken, fallback}`. */
224
+ export type RouteByValueNode = {
225
+ node: "route";
226
+ label: string;
227
+ valuePath: string;
228
+ branches: {
229
+ [branch: string]: {
230
+ body: WorkflowNode;
231
+ };
232
+ };
233
+ otherwise?: string;
234
+ state?: never;
235
+ instructions?: never;
236
+ unsure?: never;
180
237
  as?: string;
181
238
  requires?: string[];
239
+ metadata?: NodeMetadata;
182
240
  };
241
+ export declare const routesByValue: (node: RouteNode) => node is RouteByValueNode;
183
242
  /** A child workflow invoked as one step of its parent. The child is embedded whole, so the parent
184
243
  * digest covers every child byte; `input` is interpolated by value and is the child's ENTIRE initial
185
244
  * state (no parent state leaks in); the child's validated output is checked against the parent's
@@ -192,10 +251,13 @@ export type WorkflowInvocation = {
192
251
  input: Record<string, unknown>;
193
252
  out: string;
194
253
  as: string;
254
+ metadata?: NodeMetadata;
195
255
  };
196
256
  /** `exit` is a shell command that ended with a non-zero status: retried only when the author
197
257
  * declared retry, since re-running a command is the author's call. */
198
258
  export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
259
+ /** A failed effect's closed code (EFFECT_FAILURE_CODES). */
260
+ export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
199
261
  /** The workflow's terminal deliverable. Types "markdown" and "report" use the report
200
262
  * writer; other non-empty types name a workspace file produced by an earlier call.
201
263
  * File existence and delivery are the host's responsibility. */
@@ -214,6 +276,7 @@ export type ArtifactNode = {
214
276
  effort?: WorkflowEffort;
215
277
  thinking?: WorkflowThinking;
216
278
  requires?: string[];
279
+ metadata?: NodeMetadata;
217
280
  };
218
281
  export type ArtifactState = {
219
282
  path: string;
@@ -263,19 +326,24 @@ export type CallNode = {
263
326
  produces?: string[];
264
327
  /** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
265
328
  deadline_s: number;
329
+ /** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
266
330
  retry?: {
267
331
  attempts: number;
268
332
  backoff_s?: number;
269
- on?: CallRetryClass[];
333
+ on?: (CallRetryClass | EffectFailureCode)[];
270
334
  };
271
335
  /** Repeat the call until its result settles (a queued job, an eventually consistent read). */
272
336
  poll?: PollClause;
273
337
  requires?: string[];
338
+ metadata?: NodeMetadata;
274
339
  };
275
340
  export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
276
341
  export type LlmNode = Extract<WorkflowNode, {
277
342
  node: "agent" | "decide" | "extract" | "report";
278
343
  }>;
344
+ export type CodeNode = Extract<WorkflowNode, {
345
+ node: "code";
346
+ }>;
279
347
  export declare const REPORT_SCHEMA: Record<string, unknown>;
280
348
  export type Workflow = {
281
349
  v: 2;
@@ -366,6 +434,10 @@ export type HostPolicy = {
366
434
  };
367
435
  export type WorkflowDeps = {
368
436
  maxQuestionsPerRequest?: number;
437
+ /** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
438
+ * measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
439
+ * requests. Absent = no byte limit. */
440
+ maxStateBytesPerRequest?: number;
369
441
  /** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
370
442
  hostPolicy?: HostPolicy;
371
443
  runNode?: (params: {
@@ -390,6 +462,12 @@ export type WorkflowDeps = {
390
462
  message: string;
391
463
  }>;
392
464
  tier?: ModelTier;
465
+ /** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
466
+ * No runner stops a run on money. A host may cap it by what it has left. */
467
+ budgetUsd?: number;
468
+ /** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
469
+ * a host that has none to fork refuses it. */
470
+ context?: AgentContext;
393
471
  }) => Promise<unknown>;
394
472
  runEffect?: (params: {
395
473
  node: CallNode;
@@ -399,9 +477,25 @@ export type WorkflowDeps = {
399
477
  attempt: number;
400
478
  idempotencyKey: string;
401
479
  signal: AbortSignal;
480
+ /** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
481
+ * interpreter armed its deadline timer, so the host measures its own kill and duration against
482
+ * the instant the timer fires. Absent when the call has no deadline. */
483
+ deadlineAt?: number;
402
484
  item?: MapItem;
403
485
  executionPath?: string;
404
486
  }) => Promise<unknown>;
487
+ /** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
488
+ * the context the transform would receive and uses what it resolves to as the transform's result
489
+ * (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
490
+ * Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
491
+ * which is not a sandbox: a host that runs code from an untrusted author supplies this. */
492
+ runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
493
+ sop: string;
494
+ label: string;
495
+ executionPath: string;
496
+ item?: MapItem;
497
+ signal?: AbortSignal;
498
+ }) => Promise<unknown>;
405
499
  runJudge?: (params: {
406
500
  label: string;
407
501
  kind: "judge" | "pick" | "sift" | "route" | "ask";
@@ -410,6 +504,9 @@ export type WorkflowDeps = {
410
504
  signal?: AbortSignal;
411
505
  state: unknown;
412
506
  questions: Record<string, SystemOneQuestion>;
507
+ /** The id of this request's decision receipt (`DecisionReceipt.id`): the same request asked again
508
+ * carries the same id. */
509
+ decisionId?: string;
413
510
  }) => Promise<{
414
511
  answers: Record<string, SystemOneAnswer>;
415
512
  model?: string | null;
@@ -420,6 +517,12 @@ export type WorkflowDeps = {
420
517
  cost_usd?: number | null;
421
518
  request_sha256?: string;
422
519
  }>;
520
+ /** Records one typed-question request and what its answers decide. It is awaited before the answers
521
+ * reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
522
+ * rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
523
+ * recorded too, before its failure is thrown. A decision answered from `recovery.decision` was
524
+ * recorded by the run that asked it and is not recorded again. */
525
+ recordDecision?: (receipt: DecisionReceipt, exchange: DecisionExchange) => Promise<void>;
423
526
  syntheticEffects?: boolean;
424
527
  checkpoint?: (state: Record<string, unknown>, label: string, executionPath?: string) => Promise<void>;
425
528
  /** Critical recovery stores stop execution on write failure; omitted retains legacy best effort. */
@@ -432,6 +535,17 @@ export type WorkflowDeps = {
432
535
  pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
433
536
  wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
434
537
  fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
538
+ /** A map with `onItemFailure: "collect"` commits an item that ended on its failure here, at the item's body path,
539
+ * once, before the map goes on; `node` is the map. A store without both hooks cannot hold such a map: it is refused
540
+ * before any step runs. */
541
+ failItem?: (node: WorkflowNode, failure: MapItemFailure, executionPath?: string) => Promise<void>;
542
+ /** The failure an earlier process committed for the item whose body path this is, if any: the item ends on it again,
543
+ * and its body never runs again. */
544
+ itemFailure?: (node: WorkflowNode, executionPath?: string) => Promise<MapItemFailure | undefined>;
545
+ /** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
546
+ * the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
547
+ * other receipt, or none, means the request is asked. */
548
+ decision?: (id: string) => Promise<DecisionReceipt | undefined>;
435
549
  };
436
550
  /** A completed-effect memo keyed by the call's idempotency key. A hit skips the effect and
437
551
  * reuses its result; polled calls are never memoized (their result is a moment in time). */
@@ -444,18 +558,39 @@ export type WorkflowDeps = {
444
558
  signal?: AbortSignal;
445
559
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
446
560
  * 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;
561
+ onEvent?: (event: WorkflowEvent) => void;
562
+ /** Trusted host boundary: return a detached snapshot without mutating the input.
563
+ * Runs before generic copying; undefined or thrown errors omit the event.
564
+ * Required trace validation cancels through the host signal, preserving execution cleanup. */
565
+ prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
566
+ };
567
+ export type WorkflowEvent = {
568
+ type: string;
569
+ label: string;
570
+ detail?: unknown;
571
+ executionPath?: string;
572
+ };
573
+ type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
574
+ type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
575
+ /** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
576
+ * and, when the judge returned, the very object it returned, so a host reads back what it put there. */
577
+ export type DecisionExchange = {
578
+ request: JudgeRequest;
579
+ result?: JudgeResult;
453
580
  };
454
581
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
455
582
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
583
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
584
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
456
585
  export declare class EffectFailure extends Error {
457
586
  readonly retryClass: CallRetryClass | null;
458
- constructor(message: string, retryClass?: CallRetryClass | null);
587
+ readonly code: EffectFailureCode | null;
588
+ readonly detail?: Record<string, unknown>;
589
+ constructor(message: string, retryClass?: CallRetryClass | null, options?: {
590
+ code?: EffectFailureCode | null;
591
+ detail?: Record<string, unknown>;
592
+ cause?: unknown;
593
+ });
459
594
  }
460
595
  export declare function parseCsvRows(text: string): string[][];
461
596
  export declare function buildReferenceContext(files: Record<string, string>): {
@@ -470,9 +605,19 @@ export declare function workflowSha256(workflow: Workflow): string;
470
605
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
471
606
  * objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
472
607
  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. */
608
+ /** The rule a validation issue breaks. A closed set: a new code widens it, so a consumer keeps a default branch; renaming
609
+ * one is a breaking change. `docs/guide.md` lists each with an example. */
610
+ 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";
611
+ /** One validation error. `message` is the matching entry of `errors`, unchanged. `path` is a JSON Pointer (RFC 6901)
612
+ * into the workflow as written, naming what the rule is about: a node (the same path `inspectWorkflow` gives it), a
613
+ * schema (`/schemas/<id>`), a value the shape check refused, or `""` for the document's own fields and for the input
614
+ * supplied to validation. It never names a key that is missing. */
615
+ export type ValidationIssue = {
616
+ path: string;
617
+ code: ValidationCode;
618
+ message: string;
619
+ };
620
+ /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
476
621
  export declare function validateWorkflow(workflow: Workflow, opts?: {
477
622
  executeCode?: boolean;
478
623
  input?: Record<string, unknown>;
@@ -486,9 +631,12 @@ export declare function validateWorkflow(workflow: Workflow, opts?: {
486
631
  };
487
632
  }): {
488
633
  ok: true;
634
+ warnings?: string[];
489
635
  } | {
490
636
  ok: false;
491
637
  errors: string[];
638
+ issues: ValidationIssue[];
639
+ warnings?: string[];
492
640
  };
493
641
  export declare class EscalationSignal extends Error {
494
642
  readonly escalation: Escalation;
@@ -500,9 +648,11 @@ export declare function schemaProblems(validator: {
500
648
  export declare class WorkflowInvalidError extends Error {
501
649
  readonly workflowName: string;
502
650
  readonly problems: string[];
651
+ readonly issues: ValidationIssue[];
503
652
  readonly code = "workflow_invalid";
504
653
  readonly stage = "validate";
505
- constructor(workflowName: string, problems: string[]);
654
+ /** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
655
+ constructor(workflowName: string, problems: string[], issues?: ValidationIssue[]);
506
656
  }
507
657
  export declare class WorkflowInputInvalidError extends Error {
508
658
  readonly workflowName: string;
@@ -557,13 +707,34 @@ export declare class WorkflowCodeError extends Error {
557
707
  export declare class WorkflowStateError extends Error {
558
708
  readonly stage: string;
559
709
  readonly path: string;
560
- readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key";
710
+ 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
711
  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");
712
+ 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
713
  }
714
+ /** A map item that ended on its failure (`onItemFailure: "collect"`), as `failedAs` holds it: the item's index, the
715
+ * label of the node that failed, the failure's code and its message (at most 300 characters). */
716
+ export type MapItemFailure = {
717
+ item_index: number;
718
+ label: string;
719
+ code: string;
720
+ message: string;
721
+ };
722
+ /** Whether an item's failure is one a map with `onItemFailure: "collect"` ends the item on: one of the interpreter's own
723
+ * typed node failures (a call that failed after its retries, output that does not match its schema, a state contract, a
724
+ * code transform, a failed verification), or a host's failure that declares itself one, with a string `code` and
725
+ * `itemFailure: true`. Never one whose cause chain holds an effect whose outcome is unknown, a recovery failure, an
726
+ * escalation or an abort, never several failures at once, and nothing else: a new error class is never collected by
727
+ * accident. */
728
+ export declare function isItemFailure(error: unknown): boolean;
564
729
  export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
565
730
  export declare const submissionSchemaForNode: typeof stageSchemaForNode;
566
731
  export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
732
+ /** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
733
+ export declare class WorkflowDecisionRecordError extends Error {
734
+ readonly label: string;
735
+ readonly decisionId: string;
736
+ constructor(label: string, decisionId: string, cause: unknown);
737
+ }
567
738
  /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
568
739
  export declare const HOST_STATE_KEY = "$host";
569
740
  export declare class WorkflowVerificationError extends Error {