@parcha/agentrun-dsl 0.1.0-beta.1 → 0.1.0-beta.10

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 (38) hide show
  1. package/README.md +25 -11
  2. package/dist/author.d.ts +89 -0
  3. package/dist/author.js +317 -0
  4. package/dist/code-exec.d.ts +6 -0
  5. package/dist/code-exec.js +126 -0
  6. package/dist/dry-run.d.ts +4 -1
  7. package/dist/dry-run.js +2 -1
  8. package/dist/index.d.ts +8 -3
  9. package/dist/index.js +9 -2
  10. package/dist/inspection.js +2 -2
  11. package/dist/long-timer.d.ts +7 -0
  12. package/dist/long-timer.js +22 -0
  13. package/dist/observer-snapshot.d.ts +3 -0
  14. package/dist/observer-snapshot.js +46 -0
  15. package/dist/predicates.d.ts +4 -0
  16. package/dist/predicates.js +19 -2
  17. package/dist/system-one.js +45 -4
  18. package/dist/vocabulary.d.ts +42 -0
  19. package/dist/vocabulary.js +74 -0
  20. package/dist/workflow-shape.js +6 -2
  21. package/dist/workflow.d.ts +164 -15
  22. package/dist/workflow.js +551 -118
  23. package/package.json +3 -2
  24. package/schema/workflow.schema.json +237 -15
  25. package/skills/author/SKILL.md +120 -0
  26. package/skills/author/examples/evidence-gate.input.json +6 -0
  27. package/skills/author/examples/evidence-gate.json +125 -0
  28. package/skills/author/examples/read-file.input.json +1 -0
  29. package/skills/author/examples/read-file.json +44 -0
  30. package/skills/author/examples/read-source-decision.input.json +4 -0
  31. package/skills/author/examples/read-source-decision.json +37 -0
  32. package/skills/author/examples/release-note.txt +10 -0
  33. package/skills/author/examples/review-release-notes.input.json +6 -0
  34. package/skills/author/examples/review-release-notes.json +123 -0
  35. package/skills/author/references/jev-decisions.md +125 -0
  36. package/skills/author/references/language.md +118 -0
  37. package/skills/author/references/sdk-authoring.md +9 -0
  38. package/skills/author/references/workflow-format.md +137 -0
package/dist/workflow.js CHANGED
@@ -1,14 +1,18 @@
1
+ import { observerSnapshot } from "./observer-snapshot.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import { isDeepStrictEqual, types as utilTypes } from "node:util";
3
- import { predicateMatches, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
4
+ import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
5
+ import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
4
6
  import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
5
7
  import { Compile } from "typebox/compile";
6
8
  import { compileTransform, compileTransformSyntax } from "./code-exec.js";
7
9
  import { workflowShapeErrors } from "./workflow-shape.js";
8
10
  import { resolveSchemaForWorkflow } from "./schema-references.js";
9
11
  export { resolveSchemaForWorkflow } from "./schema-references.js";
12
+ import { setLongTimeout } from "./long-timer.js";
13
+ export const routesByValue = (node) => typeof node.valuePath === "string";
10
14
  export function artifactNodeIsProse(node) {
11
- return node.type === "markdown" || node.type === "report";
15
+ return PROSE_ARTIFACT_TYPES.includes(node.type);
12
16
  }
13
17
  export function desugarWorkflow(workflow) {
14
18
  const visit = (node) => {
@@ -75,6 +79,41 @@ export const declaredWrites = (node) => {
75
79
  visit(node);
76
80
  return out;
77
81
  };
82
+ /** The top-level keys a loop body writes, with engine sidecars; null when an unaliased code node makes them unknowable. */
83
+ const loopBodyWrites = (body) => {
84
+ const out = new Set();
85
+ let known = true;
86
+ const visit = (n) => {
87
+ if (!n || typeof n !== "object" || !known)
88
+ return;
89
+ if (n.node === "code" && n.as === undefined) {
90
+ known = false;
91
+ return;
92
+ }
93
+ if (n.node === "report")
94
+ out.add("report_markdown");
95
+ else if (typeof n.as === "string" && n.as.trim())
96
+ out.add(n.as);
97
+ else if (["agent", "decide", "extract"].includes(n.node) && typeof n.label === "string")
98
+ out.add(n.label);
99
+ if (n.node === "map" || n.node === "workflow")
100
+ return;
101
+ if (Array.isArray(n.steps))
102
+ n.steps.forEach(visit);
103
+ if (Array.isArray(n.branches))
104
+ n.branches.forEach(visit);
105
+ else if (n.node === "route" && n.branches && typeof n.branches === "object")
106
+ Object.values(n.branches).forEach((b) => visit(b?.body));
107
+ if (n.body)
108
+ visit(n.body);
109
+ };
110
+ visit(body);
111
+ if (!known)
112
+ return null;
113
+ for (const key of [...out])
114
+ out.add(`${key}$answers`).add(`${key}$verify`);
115
+ return out;
116
+ };
78
117
  const routeBodies = (node) => node.node === "route" ? Object.values(node.branches || {}).map((b) => b?.body).filter(Boolean) : [];
79
118
  const snapshotState = (state) => {
80
119
  try {
@@ -84,19 +123,31 @@ const snapshotState = (state) => {
84
123
  throw new Error("Workflow state must be structured-cloneable", { cause });
85
124
  }
86
125
  };
87
- const KINDS = new Set(["chain", "code", "agent", "decide", "extract", "report", "map", "parallel", "loop", "escalate", "call", "artifact", "workflow", "judge", "pick", "sift", "route"]);
126
+ const KINDS = new Set(WORKFLOW_NODE_KINDS);
127
+ const kindsMatchType = true;
128
+ void kindsMatchType;
129
+ const KIND_KEYS = Object.fromEntries(WORKFLOW_NODE_KINDS.map((kind) => [kind, new Set([...NODE_FIELDS[kind], ...HOST_NODE_FIELDS, ...(IGNORED_NODE_FIELDS[kind] ?? [])])]));
88
130
  export const childSteps = (child) => {
89
131
  const root = child?.root;
90
132
  if (!root || typeof root !== "object")
91
133
  return null;
92
134
  return root.node === "chain" ? (Array.isArray(root.steps) ? root.steps : null) : [root];
93
135
  };
136
+ /** The code a retry class implies when the failure names none. */
137
+ const codeOfRetryClass = (retryClass) => retryClass === null ? null : retryClass === "timeout" ? "effect_timeout" : retryClass === "exit" ? "effect_exit" : "effect_transport";
138
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
139
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
94
140
  export class EffectFailure extends Error {
95
141
  retryClass;
96
- constructor(message, retryClass = null) {
97
- super(message);
142
+ code;
143
+ detail;
144
+ constructor(message, retryClass = null, options = {}) {
145
+ super(message, options.cause === undefined ? undefined : { cause: options.cause });
98
146
  this.retryClass = retryClass;
99
147
  this.name = "EffectFailure";
148
+ this.code = options.code === undefined ? codeOfRetryClass(retryClass) : options.code;
149
+ if (options.detail)
150
+ this.detail = options.detail;
100
151
  }
101
152
  }
102
153
  function containsReportNode(node) {
@@ -114,7 +165,7 @@ function containsReportNode(node) {
114
165
  return routeBodies(node).some(containsReportNode);
115
166
  return false;
116
167
  }
117
- const PREDICATES = new Set([...MECHANICAL_PREDICATE_NAMES, "ask"]);
168
+ const PREDICATES = new Set(WORKFLOW_PREDICATES);
118
169
  function predicateShapeErrors(pred) {
119
170
  const out = [];
120
171
  if (pred.predicate === "in") {
@@ -278,6 +329,7 @@ export function workflowDocumentError(value) {
278
329
  /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
279
330
  * without evaluating authored expressions or probing transforms. This is not execution admission;
280
331
  * trusted/default validation and runtime output checks remain authoritative. */
332
+ const RETRY_ON_NAMES = [...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES];
281
333
  export function validateWorkflow(workflow, opts) {
282
334
  const bounded = workflowDocumentError(workflow);
283
335
  if (bounded)
@@ -431,6 +483,54 @@ export function validateWorkflow(workflow, opts) {
431
483
  }
432
484
  return patches;
433
485
  };
486
+ const snapshotKnowledge = () => ({
487
+ available: reachability ? new Set(reachability.available) : null, unknowable: reachability?.unknowable ?? true,
488
+ typed: new Map(typedOutputs), probed: new Map([...probedSubtrees].map(([key, values]) => [key, [...values]])),
489
+ spread: new Set(spreadTaintedKeys), files: new Set(producedFiles),
490
+ });
491
+ const restoreKnowledge = (knowledge) => {
492
+ if (reachability && knowledge.available) {
493
+ reachability.available = new Set(knowledge.available);
494
+ reachability.unknowable = knowledge.unknowable;
495
+ }
496
+ typedOutputs.clear();
497
+ for (const [key, value] of knowledge.typed)
498
+ typedOutputs.set(key, value);
499
+ probedSubtrees.clear();
500
+ for (const [key, values] of knowledge.probed)
501
+ probedSubtrees.set(key, [...values]);
502
+ spreadTaintedKeys.clear();
503
+ for (const key of knowledge.spread)
504
+ spreadTaintedKeys.add(key);
505
+ producedFiles.clear();
506
+ for (const file of knowledge.files)
507
+ producedFiles.add(file);
508
+ };
509
+ /** After a parallel node: each branch's own changes applied over the state before it; keys, files and shapes accumulate. */
510
+ const mergeKnowledge = (before, branches) => {
511
+ restoreKnowledge(before);
512
+ for (const branch of branches) {
513
+ if (reachability && branch.available)
514
+ for (const key of branch.available)
515
+ reachability.available.add(key);
516
+ for (const [key, value] of branch.typed)
517
+ if (before.typed.get(key) !== value)
518
+ typedOutputs.set(key, value);
519
+ for (const key of before.typed.keys())
520
+ if (!branch.typed.has(key))
521
+ typedOutputs.delete(key);
522
+ for (const [key, values] of branch.probed)
523
+ if (before.probed.get(key)?.length !== values.length || before.probed.get(key)?.some((v, i) => v !== values[i]))
524
+ probedSubtrees.set(key, [...values]);
525
+ for (const key of branch.spread)
526
+ spreadTaintedKeys.add(key);
527
+ for (const file of branch.files)
528
+ producedFiles.add(file);
529
+ }
530
+ // The merged state depends on which branches ran how; later reachability checks stand down, as before.
531
+ if (reachability)
532
+ reachability.unknowable = true;
533
+ };
434
534
  const checkPredicatePath = (when, label, path) => {
435
535
  if (!reachability || !when?.path)
436
536
  return;
@@ -464,6 +564,21 @@ export function validateWorkflow(workflow, opts) {
464
564
  }
465
565
  errors.push(`${path} (${label}): predicate path "${when.path}" is not produced by the code node that writes "${head}" (its shape has: ${missingAt && typeof missingAt === "object" ? Object.keys(missingAt).join(", ") : typeof missingAt}); the guard can never fire`);
466
566
  };
567
+ // A mechanical predicate reads one state key; when no input key or earlier node writes it, the guard can never fire.
568
+ const checkPredicateHead = (pred, label, path, field, produced) => {
569
+ if (!reachability || reachability.unknowable || !pred || typeof pred !== "object")
570
+ return;
571
+ const available = produced ?? reachability.available;
572
+ const { predicate, path: at, key } = pred;
573
+ const read = predicate === "no_new_items" ? key : predicate === "ask" ? undefined : at;
574
+ if (typeof read !== "string" || !read.trim())
575
+ return;
576
+ const head = read.split(".")[0];
577
+ if (!available.has(head))
578
+ errors.push(`${path} (${label}): ${field} reads "${read}" but no input key or earlier node produces "${head}"; the guard can never fire`);
579
+ else if (!produced)
580
+ checkTypedPath(read, `${path} (${label}) ${field}`);
581
+ };
467
582
  const checkInterpolations = (value, label, path) => {
468
583
  if (!reachability || reachability.unknowable || value === undefined)
469
584
  return;
@@ -570,27 +685,6 @@ export function validateWorkflow(workflow, opts) {
570
685
  catch { /* Schema diagnostics above retain the original compilation failure. */ }
571
686
  }
572
687
  }
573
- const KIND_KEYS = {
574
- chain: new Set(["node", "steps"]),
575
- code: new Set(["node", "label", "code", "as"]),
576
- // "budget" (agent) and "samples"/"voteField" (decide) are deprecated-and-ignored: tolerated
577
- // for legacy v2 documents. The engine invokes the adapter once per node.
578
- agent: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "budget", "verify", "tier"]),
579
- decide: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "samples", "voteField", "verify", "tier"]),
580
- extract: new Set(["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"]),
581
- report: new Set(["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
582
- artifact: new Set(["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"]),
583
- map: new Set(["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"]),
584
- parallel: new Set(["node", "label", "branches"]),
585
- loop: new Set(["node", "label", "body", "until", "maxIters"]),
586
- escalate: new Set(["node", "label", "when", "kind", "stage", "summary"]),
587
- call: new Set(["node", "label", "via", "tool", "args", "code", "input", "command", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires", "env"]),
588
- workflow: new Set(["node", "label", "workflow", "input", "out", "as"]),
589
- judge: new Set(["node", "label", "state", "out", "as", "requires"]),
590
- pick: new Set(["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"]),
591
- sift: new Set(["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"]),
592
- route: new Set(["node", "label", "state", "instructions", "branches", "unsure", "as", "requires"]),
593
- };
594
688
  const checkStateMap = (map, label, path, field = "state") => {
595
689
  if (map === undefined)
596
690
  return;
@@ -614,6 +708,13 @@ export function validateWorkflow(workflow, opts) {
614
708
  };
615
709
  const checkPredicate = (pred, label, path, field, mechanicalOnly = false) => {
616
710
  const name = pred?.predicate;
711
+ // A predicate with no `predicate` field is the shape mistaken, not an unknown name: say the shape
712
+ // (GRE-2809), naming a predicate the object used as a key when it did.
713
+ if (pred && typeof pred === "object" && !Array.isArray(pred) && name === undefined) {
714
+ const keyed = Object.keys(pred).find((key) => PREDICATES.has(key));
715
+ errors.push(`${path} (${label}): ${field}: a predicate names itself in its "predicate" field beside its own fields, e.g. {"predicate": "${keyed ?? "field_true"}", "path": "..."}${keyed ? `, not {"${keyed}": {...}}` : ""}`);
716
+ return false;
717
+ }
617
718
  if (!pred || !PREDICATES.has(name) || (mechanicalOnly && !MECHANICAL_PREDICATE_NAMES.has(name))) {
618
719
  errors.push(`${path} (${label}): ${field}: unknown predicate "${name}"${mechanicalOnly && name === "ask" ? " (a poll reads a value, never asks a question)" : ""}`);
619
720
  return false;
@@ -633,6 +734,14 @@ export function validateWorkflow(workflow, opts) {
633
734
  const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
634
735
  if (extraneous.length)
635
736
  errors.push(`${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
737
+ // `$`-prefixed state keys are engine-owned (`$host`, `<as>$verify`): no node may write one. A label
738
+ // is the state key whenever `as` is omitted, so labels are held to the same rule.
739
+ if (typeof node.as === "string" && node.as.startsWith("$"))
740
+ errors.push(`${path} (${node.label || node.node}): "as" must not name an engine-owned "$" state key ("${node.as}")`);
741
+ // Only an unaliased generative or code node writes under its label; every other label is a name, not a key.
742
+ const labelIsKey = (node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "code") && node.as === undefined;
743
+ if (labelIsKey && typeof node.label === "string" && node.label.startsWith("$"))
744
+ errors.push(`${path} (${node.label}): label must not begin with "$" — an unaliased ${node.node} node writes under its label, and "$" keys are engine-owned`);
636
745
  }
637
746
  switch (node.node) {
638
747
  case "chain":
@@ -681,13 +790,17 @@ export function validateWorkflow(workflow, opts) {
681
790
  errors.push(`${path} (${node.label}): instructions required`);
682
791
  if (node.node !== "report" && !Object.hasOwn(workflow.schemas, node.out))
683
792
  errors.push(`${path} (${node.label}): out schema "${node.out}" not in workflow.schemas`);
684
- if (node.thinking !== undefined && !["low", "medium", "high"].includes(String(node.thinking)))
793
+ if (node.thinking !== undefined && !THINKING_LEVELS.includes(String(node.thinking)))
685
794
  errors.push(`${path} (${node.label}): thinking must be low|medium|high — thinking is never off`);
686
795
  if (node.tools !== undefined && (!Array.isArray(node.tools) || node.tools.some((t) => typeof t !== "string" || !t.trim())))
687
796
  errors.push(`${path} (${node.label}): tools must be a list of non-empty tool names when present (an empty list disables tools)`);
688
797
  checkRequires(node, path);
689
- if (node.tier !== undefined && !["fast", "default", "strong"].includes(String(node.tier)))
798
+ if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
690
799
  errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
800
+ if (node.node === "agent" && node.budget_usd !== undefined && !(typeof node.budget_usd === "number" && Number.isFinite(node.budget_usd) && node.budget_usd > 0))
801
+ errors.push(`${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
802
+ if (node.node === "agent" && node.context !== undefined && !AGENT_CONTEXTS.includes(String(node.context)))
803
+ errors.push(`${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
691
804
  if (node.node !== "report" && node.verify !== undefined) {
692
805
  const v = node.verify;
693
806
  if (!v || typeof v !== "object" || typeof v.out !== "string")
@@ -698,8 +811,8 @@ export function validateWorkflow(workflow, opts) {
698
811
  errors.push(`${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
699
812
  if (v.state !== undefined)
700
813
  checkStateMap(v.state, node.label, path, "verify.state");
701
- if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1 || v.maxDrives > 4))
702
- errors.push(`${path} (${node.label}): verify.maxDrives must be an integer 1..4`);
814
+ if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
815
+ errors.push(`${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
703
816
  if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
704
817
  errors.push(`${path} (${node.label}): verify.override.below must be in (0, 1)`);
705
818
  }
@@ -739,8 +852,6 @@ export function validateWorkflow(workflow, opts) {
739
852
  errors.push(`${path} (${node.label}): parallel needs at least two branches`);
740
853
  if (containsReportNode(node))
741
854
  errors.push(`${path} (${node.label}): a report node cannot live inside a parallel branch — the report is rendered once, after every branch has landed`);
742
- if (reachability)
743
- reachability.unknowable = true;
744
855
  {
745
856
  const writers = new Map();
746
857
  (node.branches || []).forEach((branch, i) => {
@@ -752,14 +863,36 @@ export function validateWorkflow(workflow, opts) {
752
863
  }
753
864
  });
754
865
  }
755
- (node.branches || []).forEach((branch, i) => walk(branch, `${path}.branches[${i}]`));
866
+ {
867
+ // Every branch starts from the state before the parallel node: a branch never sees a sibling's writes.
868
+ // All walk knowledge is restored per branch, then the branches' results merge (their writes are disjoint).
869
+ const before = snapshotKnowledge();
870
+ const after = [];
871
+ (node.branches || []).forEach((branch, i) => {
872
+ restoreKnowledge(before);
873
+ walk(branch, `${path}.branches[${i}]`);
874
+ after.push(snapshotKnowledge());
875
+ });
876
+ if (after.length)
877
+ mergeKnowledge(before, after);
878
+ if (reachability)
879
+ reachability.unknowable = true;
880
+ }
756
881
  return;
757
882
  case "loop":
758
- if (!Number.isInteger(node.maxIters) || node.maxIters < 1 || node.maxIters > 20)
759
- errors.push(`${path} (${node.label}): maxIters must be 1..20`);
883
+ if (!Number.isInteger(node.maxIters) || node.maxIters < 1)
884
+ errors.push(`${path} (${node.label}): maxIters must be an integer >= 1`);
885
+ if (node.expect_iters !== undefined && (!Number.isInteger(node.expect_iters) || node.expect_iters < 1))
886
+ errors.push(`${path} (${node.label}): expect_iters must be an integer >= 1`);
760
887
  if (containsReportNode(node.body))
761
888
  errors.push(`${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
762
889
  checkPredicate(node.until, node.label, path, "until");
890
+ {
891
+ // `until` reads the state after the body: the keys before the loop plus every key the body writes.
892
+ const bodyWrites = loopBodyWrites(node.body);
893
+ if (reachability && !reachability.unknowable && bodyWrites)
894
+ checkPredicateHead(node.until, node.label, path, "until", new Set([...reachability.available, ...bodyWrites]));
895
+ }
763
896
  if (reachability)
764
897
  reachability.unknowable = true;
765
898
  walk(node.body, `${path}.body`);
@@ -769,6 +902,7 @@ export function validateWorkflow(workflow, opts) {
769
902
  checkPredicate(node.when, node.label, path, "when");
770
903
  if (!node.kind?.trim() || !node.stage?.trim() || !node.summary?.trim())
771
904
  errors.push(`${path} (${node.label}): kind, stage, summary required`);
905
+ checkPredicateHead(node.when, node.label, path, "when");
772
906
  checkPredicatePath(node.when, node.label, path);
773
907
  return;
774
908
  case "judge": {
@@ -850,23 +984,52 @@ export function validateWorkflow(workflow, opts) {
850
984
  }
851
985
  case "route": {
852
986
  const label = node.label || "route";
853
- if (!node.state || typeof node.state !== "object" || Array.isArray(node.state) || !Object.keys(node.state).length)
854
- errors.push(`${path} (${label}): state must be a non-empty object map of what the question sees`);
855
- else
856
- checkStateMap(node.state, label, path);
857
- if (typeof node.instructions !== "string" || !node.instructions.trim())
858
- errors.push(`${path} (${label}): instructions (the one question) required`);
859
- const names = node.branches && typeof node.branches === "object" && !Array.isArray(node.branches) ? Object.keys(node.branches) : [];
860
- if (names.length < 2)
861
- errors.push(`${path} (${label}): route needs at least two named branches`);
862
- if (names.length > SYSTEM_ONE_LIMITS.maxChoiceOptions)
863
- errors.push(`${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
864
- if (node.unsure !== undefined) {
865
- const u = node.unsure;
866
- if (!u || typeof u.branch !== "string" || !names.includes(u.branch))
867
- errors.push(`${path} (${label}): unsure.branch must name one of the branches`);
868
- if (!(typeof u?.gte === "number" && u.gte > 0 && u.gte <= 1))
869
- errors.push(`${path} (${label}): unsure.gte must be in (0, 1]`);
987
+ const raw = node;
988
+ // Two forms, never mixed: Jev chooses (state + instructions) or state already holds the choice (valuePath).
989
+ const byValue = raw.valuePath !== undefined;
990
+ const names = raw.branches && typeof raw.branches === "object" && !Array.isArray(raw.branches) ? Object.keys(raw.branches) : [];
991
+ if (byValue) {
992
+ const valuePath = raw.valuePath;
993
+ if (typeof valuePath !== "string" || !valuePath.trim())
994
+ errors.push(`${path} (${label}): valuePath must be the state path of the branch name`);
995
+ for (const key of ["state", "instructions", "unsure"])
996
+ if (raw[key] !== undefined)
997
+ errors.push(`${path} (${label}): ${key} belongs to a route Jev chooses; a route by valuePath asks no question`);
998
+ if (names.length < 2)
999
+ errors.push(`${path} (${label}): route needs at least two named branches`);
1000
+ if (names.some(name => !name.trim()))
1001
+ errors.push(`${path} (${label}): branch names must be non-empty`);
1002
+ if (raw.otherwise !== undefined && (typeof raw.otherwise !== "string" || !names.includes(raw.otherwise)))
1003
+ errors.push(`${path} (${label}): otherwise must name one of the branches`);
1004
+ if (typeof valuePath === "string" && valuePath.trim() && reachability && !reachability.unknowable) {
1005
+ const head = valuePath.split(".")[0];
1006
+ if (!reachability.available.has(head))
1007
+ errors.push(`${path} (${label}): valuePath "${valuePath}" has no upstream producer; route by the key an earlier node writes`);
1008
+ else
1009
+ checkTypedPath(valuePath, `${path} (${label}) valuePath`);
1010
+ }
1011
+ }
1012
+ else {
1013
+ const judged = node;
1014
+ if (!judged.state || typeof judged.state !== "object" || Array.isArray(judged.state) || !Object.keys(judged.state).length)
1015
+ errors.push(`${path} (${label}): state must be a non-empty object map of what the question sees`);
1016
+ else
1017
+ checkStateMap(judged.state, label, path);
1018
+ if (typeof judged.instructions !== "string" || !judged.instructions.trim())
1019
+ errors.push(`${path} (${label}): instructions (the one question) required`);
1020
+ if (raw.otherwise !== undefined)
1021
+ errors.push(`${path} (${label}): otherwise belongs to a route by valuePath; a route Jev chooses takes unsure for its fallback`);
1022
+ if (names.length < 2)
1023
+ errors.push(`${path} (${label}): route needs at least two named branches`);
1024
+ if (names.length > SYSTEM_ONE_LIMITS.maxChoiceOptions)
1025
+ errors.push(`${path} (${label}): route takes at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches`);
1026
+ if (judged.unsure !== undefined) {
1027
+ const u = judged.unsure;
1028
+ if (!u || typeof u.branch !== "string" || !names.includes(u.branch))
1029
+ errors.push(`${path} (${label}): unsure.branch must name one of the branches`);
1030
+ if (!(typeof u?.gte === "number" && u.gte > 0 && u.gte <= 1))
1031
+ errors.push(`${path} (${label}): unsure.gte must be in (0, 1]`);
1032
+ }
870
1033
  }
871
1034
  if (containsReportNode(node))
872
1035
  errors.push(`${path} (${label}): a report node cannot live inside a route branch — the report is rendered once, after the record is final`);
@@ -876,17 +1039,20 @@ export function validateWorkflow(workflow, opts) {
876
1039
  if (reachability) {
877
1040
  if (typeof node.as === "string" && node.as.trim()) {
878
1041
  reachability.available.add(node.as);
879
- reachability.available.add(`${node.as}$answers`);
1042
+ if (!byValue)
1043
+ reachability.available.add(`${node.as}$answers`);
880
1044
  }
881
1045
  reachability.unknowable = true;
882
1046
  }
883
1047
  for (const name of names) {
884
- const branch = node.branches[name];
1048
+ const branch = raw.branches[name];
885
1049
  if (!branch || typeof branch !== "object" || !branch.body) {
886
1050
  errors.push(`${path} (${label}): branch "${name}" needs a body`);
887
1051
  continue;
888
1052
  }
889
- if (branch.criteria !== undefined && typeof branch.criteria !== "string")
1053
+ if (byValue && branch.criteria !== undefined)
1054
+ errors.push(`${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1055
+ else if (branch.criteria !== undefined && typeof branch.criteria !== "string")
890
1056
  errors.push(`${path} (${label}): branch "${name}" criteria must be a string`);
891
1057
  walk(branch.body, `${path}.branches.${name}`);
892
1058
  }
@@ -919,6 +1085,8 @@ export function validateWorkflow(workflow, opts) {
919
1085
  errors.push(`${path} (${label}): out schema "${String(node.out)}" not in workflow.schemas`);
920
1086
  if (!node.input || typeof node.input !== "object" || Array.isArray(node.input))
921
1087
  errors.push(`${path} (${label}): input must be an object mapping onto the child's initial state`);
1088
+ else if (Object.hasOwn(node.input, HOST_STATE_KEY))
1089
+ errors.push(`${path} (${label}): input must not contain the reserved "${HOST_STATE_KEY}" key`);
922
1090
  const child = node.workflow;
923
1091
  const steps = childSteps(child);
924
1092
  if (!child || typeof child !== "object" || !steps || !steps.length)
@@ -946,7 +1114,7 @@ export function validateWorkflow(workflow, opts) {
946
1114
  }
947
1115
  case "call": {
948
1116
  const label = node.label || "call";
949
- if (!["tool", "executor", "shell"].includes(String(node.via)))
1117
+ if (!CALL_TRANSPORTS.includes(String(node.via)))
950
1118
  errors.push(`${path} (${label}): via must be tool|executor|shell`);
951
1119
  if (node.via === "tool") {
952
1120
  if (!node.tool?.trim())
@@ -994,8 +1162,8 @@ export function validateWorkflow(workflow, opts) {
994
1162
  errors.push(`${path} (${label}): as required`);
995
1163
  if (node.where !== undefined && node.where !== "sandbox")
996
1164
  errors.push(`${path} (${label}): where accepts only "sandbox"`);
997
- if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0 && node.deadline_s <= 3600))
998
- errors.push(`${path} (${label}): deadline_s must be greater than 0 and at most 3600 seconds`);
1165
+ if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0))
1166
+ errors.push(`${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
999
1167
  if (node.produces !== undefined && (!Array.isArray(node.produces) || !node.produces.length || node.produces.some((f) => typeof f !== "string" || !f.trim() || f.startsWith("/") || f.split("/").includes(".."))))
1000
1168
  errors.push(`${path} (${label}): produces must be non-empty workspace-relative paths`);
1001
1169
  else
@@ -1003,12 +1171,12 @@ export function validateWorkflow(workflow, opts) {
1003
1171
  producedFiles.add(f);
1004
1172
  if (node.retry !== undefined) {
1005
1173
  const r = node.retry;
1006
- if (!r || !Number.isInteger(r.attempts) || r.attempts < 1 || r.attempts > 5)
1007
- errors.push(`${path} (${label}): retry.attempts must be 1..5`);
1008
- if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0 && r.backoff_s <= 60))
1009
- errors.push(`${path} (${label}): retry.backoff_s must be 0..60`);
1010
- if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !["timeout", "http_5xx", "http_429", "connection", "exit"].includes(String(c)))))
1011
- errors.push(`${path} (${label}): retry.on may name only timeout|http_5xx|http_429|connection|exit`);
1174
+ if (!r || !Number.isInteger(r.attempts) || r.attempts < 1)
1175
+ errors.push(`${path} (${label}): retry.attempts must be an integer >= 1`);
1176
+ if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0))
1177
+ errors.push(`${path} (${label}): retry.backoff_s must be a finite number >= 0`);
1178
+ if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !RETRY_ON_NAMES.includes(String(c)))))
1179
+ errors.push(`${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
1012
1180
  }
1013
1181
  if (node.poll !== undefined) {
1014
1182
  const p = node.poll;
@@ -1028,10 +1196,10 @@ export function validateWorkflow(workflow, opts) {
1028
1196
  if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
1029
1197
  errors.push(`${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
1030
1198
  }
1031
- if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1 && p.interval_s <= 300))
1032
- errors.push(`${path} (${label}): poll.interval_s must be 0.1..300 seconds`);
1033
- if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0) && p.deadline_s <= 7200))
1034
- errors.push(`${path} (${label}): poll.deadline_s must be at least deadline_s and at most 7200 seconds`);
1199
+ if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
1200
+ errors.push(`${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
1201
+ if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)))
1202
+ errors.push(`${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
1035
1203
  }
1036
1204
  }
1037
1205
  checkRequires({ label, requires: node.requires }, path);
@@ -1163,9 +1331,6 @@ export function validateWorkflow(workflow, opts) {
1163
1331
  errors.push(...workflowShapeErrors(workflow, true));
1164
1332
  return errors.length ? { ok: false, errors } : { ok: true };
1165
1333
  }
1166
- function getPath(value, path) {
1167
- return path.split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), value);
1168
- }
1169
1334
  function interpolate(template, state) {
1170
1335
  return template.replace(/\{([a-zA-Z0-9_.$]+)\}/g, (_, p) => {
1171
1336
  let v = getPath(state, p);
@@ -1386,8 +1551,8 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
1386
1551
  reject(signal.reason ?? new Error("workflow aborted"));
1387
1552
  return;
1388
1553
  }
1389
- const aborted = () => { clearTimeout(timer); reject(signal?.reason ?? new Error("workflow aborted")); };
1390
- const timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1554
+ const aborted = () => { timer.clear(); reject(signal?.reason ?? new Error("workflow aborted")); };
1555
+ const timer = setLongTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1391
1556
  signal?.addEventListener("abort", aborted, { once: true });
1392
1557
  });
1393
1558
  async function runCallNode(node, state, workflow, deps) {
@@ -1426,7 +1591,7 @@ async function runCallNode(node, state, workflow, deps) {
1426
1591
  throw new EffectFailure(`call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline`, "timeout");
1427
1592
  const controller = new AbortController();
1428
1593
  const attemptMs = Math.max(1, Math.min(node.deadline_s * 1000, remainingMs <= 0 && deps.recovery ? Infinity : remainingMs));
1429
- const attemptDeadlineMs = Date.now() + attemptMs;
1594
+ const attemptDeadlineMs = performance.now() + attemptMs;
1430
1595
  let settled;
1431
1596
  let unknownOutcome;
1432
1597
  let interruptionCheck;
@@ -1462,16 +1627,29 @@ async function runCallNode(node, state, workflow, deps) {
1462
1627
  };
1463
1628
  const onAbort = () => interrupt("cancelled", deps.signal?.reason);
1464
1629
  deps.signal?.addEventListener("abort", onAbort, { once: true });
1465
- const timer = setTimeout(() => interrupt("deadline"), attemptMs);
1630
+ // libuv may fire a timer up to 1 ms before the requested instant. Re-read the monotonic
1631
+ // clock and re-arm for the remainder, so the deadline never interrupts an effect early.
1632
+ // setLongTimeout keeps a deadline past Node's 2^31-1 ms timer limit from overflowing.
1633
+ let timer;
1634
+ const armDeadline = (ms) => {
1635
+ timer = setLongTimeout(() => {
1636
+ const remainingMs = attemptDeadlineMs - performance.now();
1637
+ if (remainingMs > 0)
1638
+ armDeadline(Math.ceil(remainingMs));
1639
+ else
1640
+ interrupt("deadline");
1641
+ }, ms);
1642
+ };
1643
+ armDeadline(attemptMs);
1466
1644
  try {
1467
1645
  deps.onEvent?.({ type: "effect.attempt", label: node.label, detail: { via: node.via, attempt, idempotency_key: idempotencyKey } });
1468
1646
  Promise.resolve().then(() => {
1469
1647
  if (deps.signal?.aborted)
1470
1648
  throw deps.signal.reason ?? new Error("workflow aborted");
1471
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs) {
1649
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs) {
1472
1650
  throw new EffectFailure(`call node "${node.label}" deadline elapsed before effect admission`, "timeout");
1473
1651
  }
1474
- return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal });
1652
+ return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal, ...(Number.isFinite(attemptDeadlineMs) ? { deadlineAt: attemptDeadlineMs } : {}) });
1475
1653
  }).then(value => finish({ status: "fulfilled", value }), reason => finish({ status: "rejected", reason }));
1476
1654
  const outcome = await Promise.race([settlement, interrupted]);
1477
1655
  if (outcome.status === "unknown")
@@ -1481,7 +1659,7 @@ async function runCallNode(node, state, workflow, deps) {
1481
1659
  result = outcome.value;
1482
1660
  if (deps.signal?.aborted)
1483
1661
  throw deps.signal.reason ?? new Error("workflow aborted");
1484
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs)
1662
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs)
1485
1663
  throw new EffectDeadlineExceededError(node.label, result);
1486
1664
  failed = false;
1487
1665
  lastError = undefined;
@@ -1496,16 +1674,21 @@ async function runCallNode(node, state, workflow, deps) {
1496
1674
  ? new EffectFailure(cutByPoll ? `call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline` : `call node "${node.label}" exceeded its ${node.deadline_s}s deadline`, "timeout")
1497
1675
  : error;
1498
1676
  const retryClass = lastError instanceof EffectFailure ? lastError.retryClass : null;
1677
+ // The row's `code` is closed: an EffectFailure's code when it is one of EFFECT_FAILURE_CODES, else
1678
+ // null. Any other typed error's own code (an unknown outcome, a host's receipts failure) rides
1679
+ // beside it as `error_code`, never as `code`.
1680
+ const code = lastError instanceof EffectFailure && EFFECT_FAILURE_CODES.includes(lastError.code) ? lastError.code : null;
1681
+ const errorCode = code === null && typeof lastError?.code === "string" ? lastError.code : null;
1499
1682
  // Durable admission is uncertain after failure; only the host can reconcile it.
1500
- const retryable = !deps.signal?.aborted && !deps.recovery && retryClass !== null && retryOn.has(retryClass) && attempt < attempts;
1501
- deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { via: node.via, attempt, retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1683
+ const retryable = !deps.signal?.aborted && !deps.recovery && ((retryClass !== null && retryOn.has(retryClass)) || (code !== null && retryOn.has(code))) && attempt < attempts;
1684
+ deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { ...(lastError instanceof EffectFailure ? lastError.detail : undefined), via: node.via, attempt, code, ...(errorCode !== null ? { error_code: errorCode } : {}), retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1502
1685
  if (!retryable || (budgetUntilMs !== undefined && Date.now() >= budgetUntilMs))
1503
1686
  break;
1504
1687
  const delay = Math.min((node.retry?.backoff_s ?? 1) * 1000 * attempt, budgetUntilMs === undefined ? Infinity : Math.max(0, budgetUntilMs - Date.now()));
1505
1688
  await sleep(delay, deps.signal);
1506
1689
  }
1507
1690
  finally {
1508
- clearTimeout(timer);
1691
+ timer?.clear();
1509
1692
  if (interruptionCheck)
1510
1693
  clearImmediate(interruptionCheck);
1511
1694
  deps.signal?.removeEventListener("abort", onAbort);
@@ -1563,13 +1746,62 @@ async function runCallNode(node, state, workflow, deps) {
1563
1746
  }
1564
1747
  return { ...state, [node.as]: result };
1565
1748
  }
1566
- function assertQuestionCount(deps, count, label) {
1749
+ function questionLimit(deps) {
1567
1750
  const limit = deps.maxQuestionsPerRequest ?? 256;
1568
1751
  if (!Number.isSafeInteger(limit) || limit < 1)
1569
1752
  throw new Error("maxQuestionsPerRequest must be a positive safe integer");
1753
+ return limit;
1754
+ }
1755
+ function stateByteLimit(deps) {
1756
+ const limit = deps.maxStateBytesPerRequest;
1757
+ if (limit === undefined)
1758
+ return null;
1759
+ if (!Number.isSafeInteger(limit) || limit < 1)
1760
+ throw new Error("maxStateBytesPerRequest must be a positive safe integer");
1761
+ return limit;
1762
+ }
1763
+ function assertQuestionCount(deps, count, label) {
1764
+ const limit = questionLimit(deps);
1765
+ stateByteLimit(deps);
1570
1766
  if (count > limit)
1571
1767
  throw new Error(`node "${label}": ${count} questions exceed maxQuestionsPerRequest (${limit}); reduce the collection/question set or raise the host limit`);
1572
1768
  }
1769
+ const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
1770
+ /** A split sift's requests in flight at once: the same default as `map.maxConcurrency`. A host that
1771
+ * needs fewer bounds its own `runJudge`. */
1772
+ const SIFT_REQUESTS_IN_FLIGHT = 4;
1773
+ /** Splits a sift's items, in order, into requests that each fit the host's question limit and, when set,
1774
+ * its state byte limit: the UTF-8 length of the JSON state the judge receives, as the Jev adapter
1775
+ * measures it. Sizes are exact: JSON of `{...base, items: [a, b]}` is JSON of `{...base, items: []}`
1776
+ * plus each item's JSON plus one comma between items. */
1777
+ function siftChunks(deps, label, questionsPerItem, base, named) {
1778
+ const maxQuestions = questionLimit(deps);
1779
+ const maxBytes = stateByteLimit(deps);
1780
+ if (questionsPerItem > maxQuestions)
1781
+ throw new Error(`node "${label}": ${questionsPerItem} questions exceed maxQuestionsPerRequest (${maxQuestions}); reduce the question set or raise the host limit`);
1782
+ const perRequest = Math.floor(maxQuestions / questionsPerItem);
1783
+ const emptyBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify({ ...base, items: [] }));
1784
+ if (maxBytes !== null && emptyBytes > maxBytes)
1785
+ throw new Error(`sift node "${label}": its state alone, before any item, is ${emptyBytes} bytes, over maxStateBytesPerRequest (${maxBytes}); every request carries that state, so make the sift's state smaller or raise the host limit`);
1786
+ const chunks = [];
1787
+ let chunk = [], bytes = emptyBytes;
1788
+ for (let i = 0; i < named.length; i += 1) {
1789
+ const itemBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify(named[i]));
1790
+ if (maxBytes !== null && emptyBytes + itemBytes > maxBytes)
1791
+ throw new Error(`sift node "${label}": item ${i} alone makes a ${emptyBytes + itemBytes}-byte judge state, over maxStateBytesPerRequest (${maxBytes}); send less of each item (a code step before the sift) or raise the host limit`);
1792
+ const grown = bytes + itemBytes + (chunk.length ? 1 : 0);
1793
+ if (chunk.length && (chunk.length >= perRequest || (maxBytes !== null && grown > maxBytes))) {
1794
+ chunks.push(chunk);
1795
+ chunk = [];
1796
+ bytes = emptyBytes;
1797
+ }
1798
+ bytes += itemBytes + (chunk.length ? 1 : 0);
1799
+ chunk.push(i);
1800
+ }
1801
+ if (chunk.length)
1802
+ chunks.push(chunk);
1803
+ return chunks;
1804
+ }
1573
1805
  const requireJudge = (deps, kind, label) => {
1574
1806
  if (!deps.runJudge)
1575
1807
  throw new Error(`${kind} node "${label}": this runner has no System One runner (deps.runJudge)`);
@@ -1595,9 +1827,9 @@ function questionSetOf(workflow, node) {
1595
1827
  };
1596
1828
  }
1597
1829
  const describeItem = (template, state, item, index) => interpolate(template, { ...state, item, item_index: index }).replace(/\s+/g, " ").trim();
1598
- async function askQuestions(deps, node, asked, questions) {
1830
+ async function askQuestions(deps, node, asked, questions, signal = deps.signal) {
1599
1831
  const runJudge = requireJudge(deps, node.node, node.label);
1600
- const result = await runJudge({ label: node.label, kind: node.node, state: asked, questions, signal: deps.signal });
1832
+ const result = await runJudge({ label: node.label, kind: node.node, state: asked, questions, signal });
1601
1833
  validateAnswers(questions, result.answers);
1602
1834
  return { answers: result.answers, sidecar: answersSidecar(result.answers), model: result.model ?? null, cost_usd: result.cost_usd ?? null };
1603
1835
  }
@@ -1648,7 +1880,6 @@ async function runSiftNode(node, state, workflow, deps) {
1648
1880
  throw new WorkflowStateError(`sift node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
1649
1881
  const set = questionSetOf(workflow, node);
1650
1882
  const ids = Object.keys(set.questions);
1651
- assertQuestionCount(deps, items.length * ids.length, node.label);
1652
1883
  const [keepId, keepTail] = node.keep ? node.keep.path.split(".") : [];
1653
1884
  const values = [];
1654
1885
  const sidecars = [];
@@ -1657,16 +1888,53 @@ async function runSiftNode(node, state, workflow, deps) {
1657
1888
  if (items.length) {
1658
1889
  const base = node.state ? interpolateValue(node.state, state, node.label) : {};
1659
1890
  const named = items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
1660
- const questions = {};
1661
- for (let i = 0; i < items.length; i += 1)
1662
- for (const id of ids)
1663
- questions[`${i}.${id}`] = { ...set.questions[id], instructions: `For \`items[${i}]\` (id item_${i}): ${set.questions[id].instructions}` };
1664
- const { answers, model, cost_usd } = await askQuestions(deps, node, { ...base, items: named }, questions);
1665
- metering = { model, cost_usd };
1891
+ const chunks = siftChunks(deps, node.label, ids.length, base, named);
1892
+ // Each chunk is its own request: item ids stay global (item_<i>), `items[j]` indexes the chunk.
1893
+ // A sift that fits in one request sends exactly the request it always did. Several requests run at
1894
+ // most SIFT_REQUESTS_IN_FLIGHT at a time; the first failure stops dispatch, cancels the requests in
1895
+ // flight, and is thrown once they settle.
1896
+ const ask = (chunk, signal) => {
1897
+ const questions = {};
1898
+ chunk.forEach((i, j) => { for (const id of ids)
1899
+ questions[`${j}.${id}`] = { ...set.questions[id], instructions: `For \`items[${j}]\` (id item_${i}): ${set.questions[id].instructions}` }; });
1900
+ return askQuestions(deps, node, { ...base, items: chunk.map((i) => named[i]) }, questions, signal);
1901
+ };
1902
+ let results;
1903
+ if (chunks.length === 1)
1904
+ results = [await ask(chunks[0], deps.signal)];
1905
+ else {
1906
+ const stop = new AbortController();
1907
+ const signal = deps.signal ? AbortSignal.any([deps.signal, stop.signal]) : stop.signal;
1908
+ results = new Array(chunks.length);
1909
+ let next = 0, failure;
1910
+ await Promise.all(Array.from({ length: Math.min(SIFT_REQUESTS_IN_FLIGHT, chunks.length) }, async () => {
1911
+ while (!failure && next < chunks.length) {
1912
+ const c = next++;
1913
+ try {
1914
+ results[c] = await ask(chunks[c], signal);
1915
+ }
1916
+ catch (error) {
1917
+ failure ??= { error };
1918
+ stop.abort();
1919
+ }
1920
+ }
1921
+ }));
1922
+ if (failure)
1923
+ throw failure.error;
1924
+ }
1925
+ const models = new Set(results.map((r) => r.model));
1926
+ metering = {
1927
+ model: models.size === 1 ? results[0].model : null,
1928
+ cost_usd: results.every((r) => r.cost_usd !== null) ? results.reduce((sum, r) => sum + r.cost_usd, 0) : null,
1929
+ ...(chunks.length > 1 ? { requests: chunks.length } : {}),
1930
+ };
1931
+ const at = [];
1932
+ chunks.forEach((chunk, c) => chunk.forEach((i, j) => { at[i] = [c, j]; }));
1933
+ const answerOf = (i, id) => results[at[i][0]].answers[`${at[i][1]}.${id}`];
1666
1934
  for (let i = 0; i < items.length; i += 1) {
1667
1935
  const mine = Object.create(null);
1668
1936
  for (const id of ids) {
1669
- const a = answers[`${i}.${id}`];
1937
+ const a = answerOf(i, id);
1670
1938
  if (!a)
1671
1939
  throw new Error(`sift node "${node.label}": no answer for item ${i} question "${id}"`);
1672
1940
  mine[id] = a;
@@ -1690,6 +1958,21 @@ async function runSiftNode(node, state, workflow, deps) {
1690
1958
  }
1691
1959
  async function runRouteNode(node, state, workflow, deps) {
1692
1960
  assertNodeInputs(node, state);
1961
+ if (routesByValue(node)) {
1962
+ // The choice is already in state: no model is asked, and nothing is coerced into a branch name.
1963
+ const value = getPath(state, node.valuePath);
1964
+ if (value !== undefined && typeof value !== "string")
1965
+ throw new WorkflowStateError(`route node "${node.label}": ${node.valuePath} is not a string; a route by value reads a branch name`, node.label, node.valuePath, "route_type");
1966
+ const matched = typeof value === "string" && Object.hasOwn(node.branches, value);
1967
+ const taken = matched ? value : node.otherwise;
1968
+ if (taken === undefined)
1969
+ throw new WorkflowStateError(`route node "${node.label}": ${node.valuePath} ${value === undefined ? "is missing" : "names no branch"} and the route declares no otherwise`, node.label, node.valuePath, value === undefined ? "route_missing" : "route_unknown");
1970
+ const selection = { value: value ?? null, taken, fallback: !matched };
1971
+ // The event names only a declared branch, never an unexpected source string.
1972
+ deps.onEvent?.({ type: "route.chosen", label: node.label, detail: { kind: "route", by: "value", as: node.as ?? null, value: { taken, fallback: !matched } } });
1973
+ const routed = node.as ? { ...state, [node.as]: selection } : state;
1974
+ return runNodeOnState(node.branches[taken].body, routed, workflow, scopeExecution(deps, "branches", taken, "body"));
1975
+ }
1693
1976
  const names = Object.keys(node.branches);
1694
1977
  const criteria = Object.fromEntries(names.map((n) => [n, node.branches[n]?.criteria?.trim() || null]));
1695
1978
  const { answers, sidecar, model, cost_usd } = await askQuestions(deps, node, interpolateValue(node.state, state, node.label), { branch: { type: "choice", instructions: node.instructions, criteria } });
@@ -1705,6 +1988,25 @@ async function runRouteNode(node, state, workflow, deps) {
1705
1988
  }
1706
1989
  const EXECUTION_PATH = Symbol("workflow.executionPath");
1707
1990
  const SCOPED_EFFECTS = Symbol("workflow.scopedEffects");
1991
+ /** The map item a scoped copy of deps runs for, so host policy context can name it. */
1992
+ const MAP_ITEM = Symbol("workflow.mapItem");
1993
+ /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
1994
+ export const HOST_STATE_KEY = "$host";
1995
+ const hostStateOf = (state) => {
1996
+ const host = state[HOST_STATE_KEY];
1997
+ return host && typeof host === "object" && !Array.isArray(host) ? host : {};
1998
+ };
1999
+ const hostContext = (workflow, node, deps) => {
2000
+ const item = deps[MAP_ITEM];
2001
+ const generative = node.node === "agent" || node.node === "decide" || node.node === "extract" || node.node === "report";
2002
+ return {
2003
+ workflow: { name: workflow.name, outputSchemaId: workflow.output.schemaId },
2004
+ node: { kind: node.node, label: String(node.label ?? node.node), ...("out" in node && typeof node.out === "string" ? { out: node.out } : {}), ...("as" in node && typeof node.as === "string" ? { as: node.as } : {}) },
2005
+ terminal: generative && node.node !== "report" && node.out === workflow.output.schemaId,
2006
+ executionPath: executionPath(deps),
2007
+ ...(item ? { item } : {}),
2008
+ };
2009
+ };
1708
2010
  const executionPath = (deps) => deps[EXECUTION_PATH] ?? "/root";
1709
2011
  const scopeExecution = (deps, ...parts) => ({
1710
2012
  ...deps,
@@ -1717,7 +2019,7 @@ function withExecutionLocation(deps) {
1717
2019
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1718
2020
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1719
2021
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1720
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, executionPath: event.executionPath ?? path }) } : {}),
2022
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, executionPath: event.executionPath ?? path })) } : {}),
1721
2023
  };
1722
2024
  }
1723
2025
  /** Older hosts only support flat child chains outside repeated/branching structure. They must
@@ -1741,6 +2043,7 @@ function scopeDepsToItem(deps, item, signal) {
1741
2043
  const recovery = deps.recovery;
1742
2044
  return {
1743
2045
  ...deps,
2046
+ ...{ [MAP_ITEM]: item },
1744
2047
  checkpoint: undefined,
1745
2048
  ...(signal ? { signal } : {}),
1746
2049
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, item: params.item ?? item, ...(signal ? { signal: params.signal ?? signal } : {}) }) } : {}),
@@ -1767,6 +2070,7 @@ function scopeDepsToChild(deps, invocation) {
1767
2070
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
1768
2071
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
1769
2072
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2073
+ ...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
1770
2074
  ...(recovery ? { recovery: {
1771
2075
  supportsExecutionPaths: recovery.supportsExecutionPaths,
1772
2076
  resume: (node, state, item, path) => recovery.resume(relabel(node), state, item, path),
@@ -1775,21 +2079,37 @@ function scopeDepsToChild(deps, invocation) {
1775
2079
  wait: (node, ms, item, path) => recovery.wait(relabel(node), ms, item, path),
1776
2080
  ...(recovery.fail ? { fail: (node, results, error, path) => recovery.fail(relabel(node), results, error, path) } : {}),
1777
2081
  } } : {}),
1778
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, label: `${prefix}/${event.label}` }) } : {}),
2082
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, label: `${prefix}/${event.label}` })) } : {}),
1779
2083
  };
1780
2084
  }
1781
2085
  const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
1782
2086
  const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
1783
2087
  const guardedObservers = new WeakSet();
2088
+ function forwardObserver(observer, transform) {
2089
+ const forwarded = (event) => observer(transform(event));
2090
+ if (guardedObservers.has(observer))
2091
+ guardedObservers.add(forwarded);
2092
+ return forwarded;
2093
+ }
1784
2094
  async function runNodeOnState(node, state, workflow, deps) {
1785
2095
  deps = withExecutionLocation(deps);
1786
2096
  const observer = deps.onEvent;
1787
2097
  if (observer && !guardedObservers.has(observer)) {
1788
2098
  const guarded = event => {
2099
+ let detached;
2100
+ try {
2101
+ detached = deps.prepareEvent ? deps.prepareEvent(event) : observerSnapshot(event);
2102
+ }
2103
+ catch {
2104
+ return;
2105
+ }
2106
+ if (detached === undefined)
2107
+ return;
1789
2108
  try {
1790
2109
  // TypeScript void callbacks can still return promises. Consume rejection without
1791
2110
  // awaiting telemetry or allowing it to replace an execution or recovery outcome.
1792
- const returned = observer(event);
2111
+ // Observers receive snapshots, never objects shared with execution state.
2112
+ const returned = observer(detached);
1793
2113
  if (returned && typeof returned.then === "function") {
1794
2114
  void Promise.resolve(returned).catch(() => { });
1795
2115
  }
@@ -1816,9 +2136,20 @@ async function runNodeOnState(node, state, workflow, deps) {
1816
2136
  try {
1817
2137
  if (deps.signal?.aborted)
1818
2138
  throw deps.signal.reason ?? new Error("workflow aborted");
1819
- const out = await runNodeBody(node, state, workflow, deps);
2139
+ let out = await runNodeBody(node, state, workflow, deps);
1820
2140
  if (deps.signal?.aborted)
1821
2141
  throw deps.signal.reason ?? new Error("workflow aborted");
2142
+ // Host policy enrichment lands before commit and checkpoint: a resumed run sees exactly what ran.
2143
+ if (isStep && deps.hostPolicy?.afterNode) {
2144
+ const patch = deps.hostPolicy.afterNode({ ...hostContext(workflow, node, deps), state: out });
2145
+ if (patch && typeof patch === "object" && !Array.isArray(patch) && Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY)) {
2146
+ throw new WorkflowStateError(`host policy afterNode for "${label}" may not write the reserved "${HOST_STATE_KEY}" key; return host state from decodeSubmission`, label, HOST_STATE_KEY, "reserved_state_key");
2147
+ }
2148
+ if (patch && typeof patch === "object" && !Array.isArray(patch) && Object.keys(patch).length) {
2149
+ out = { ...out, ...patch };
2150
+ deps.onEvent?.({ type: "host.patched", label, detail: { keys: Object.keys(patch) } });
2151
+ }
2152
+ }
1822
2153
  if (deps.recovery && node.node !== "chain")
1823
2154
  await deps.recovery.commit(node, out, undefined, executionPath(deps));
1824
2155
  if (deps.signal?.aborted)
@@ -1873,14 +2204,22 @@ async function runNodeBody(node, state, workflow, deps) {
1873
2204
  }
1874
2205
  case "code": {
1875
2206
  let out;
1876
- try {
1877
- const fn = compileTransform(node.code);
1878
- out = fn(state, { sop: deps.sop || "" });
2207
+ if (deps.runCode) {
2208
+ const item = deps[MAP_ITEM];
2209
+ out = await deps.runCode(node, state, { sop: deps.sop || "", label: node.label, executionPath: executionPath(deps), ...(item ? { item } : {}), ...(deps.signal ? { signal: deps.signal } : {}) });
1879
2210
  }
1880
- catch (cause) {
1881
- throw new WorkflowCodeError(node.label, cause);
2211
+ else {
2212
+ try {
2213
+ const fn = compileTransform(node.code);
2214
+ out = fn(state, { sop: deps.sop || "" });
2215
+ }
2216
+ catch (cause) {
2217
+ throw new WorkflowCodeError(node.label, cause);
2218
+ }
1882
2219
  }
1883
2220
  const patch = node.as ? { [node.as]: out } : (out && typeof out === "object" && !Array.isArray(out) ? out : { [node.label]: out });
2221
+ if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
2222
+ throw new WorkflowStateError(`code node "${node.label}" wrote the reserved "${HOST_STATE_KEY}" state key`, node.label, HOST_STATE_KEY, "reserved_state_key");
1884
2223
  deps.onEvent?.({ type: "code.patch", label: node.label, detail: patch });
1885
2224
  return { ...state, ...patch };
1886
2225
  }
@@ -1897,27 +2236,70 @@ async function runNodeBody(node, state, workflow, deps) {
1897
2236
  assertNodeInputs(node, state);
1898
2237
  const promptState = node.state ? interpolateValue(node.state, state, node.label) : promptStateOf(state);
1899
2238
  const verifier = node.node !== "report" && node.verify ? compileVerifier(workflow, node, state, deps) : null;
2239
+ // Host policy: the adapter submits against the transport schema (the stage schema plus the host's
2240
+ // channels); the decoded domain value is what the stage schema, the verifier and the state see.
2241
+ const policy = deps.hostPolicy;
2242
+ const context = policy ? hostContext(workflow, node, deps) : null;
2243
+ const transportSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
2244
+ const transportValidator = transportSchema === schema ? validator : Compile(transportSchema);
2245
+ const stageName = node.node === "report" ? "report" : node.out;
2246
+ const decode = (raw) => {
2247
+ normalizeStringNullsForSchema(raw, transportSchema);
2248
+ if (!transportValidator.Check(raw)) {
2249
+ throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${stageName}"`, schemaProblems(transportValidator, raw), node.label);
2250
+ }
2251
+ const decoded = policy?.decodeSubmission && context ? policy.decodeSubmission(raw, { ...context, host: hostStateOf(state) }) : { value: raw };
2252
+ if (decoded !== null && typeof decoded === "object" && decoded.value !== raw)
2253
+ normalizeStringNullsForSchema(decoded.value, schema);
2254
+ if (!validator.Check(decoded.value)) {
2255
+ throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" decoded submission does not satisfy schema "${stageName}"`, schemaProblems(validator, decoded.value), node.label);
2256
+ }
2257
+ return decoded;
2258
+ };
2259
+ // A verify clause reviews the domain value: the host's channels are split off before the judge sees it.
2260
+ const review = verifier
2261
+ ? (transportSchema === schema && !policy?.decodeSubmission
2262
+ ? verifier.review
2263
+ : async (candidate) => {
2264
+ let decoded;
2265
+ try {
2266
+ decoded = decode(structuredClone(candidate));
2267
+ }
2268
+ catch (error) {
2269
+ if (error instanceof WorkflowOutputInvalidError)
2270
+ return { accepted: false, message: error.message };
2271
+ throw error;
2272
+ }
2273
+ return verifier.review(decoded.value);
2274
+ })
2275
+ : undefined;
1900
2276
  let submission;
1901
2277
  submission = await deps.runNode({
1902
2278
  signal: deps.signal,
1903
2279
  kind: node.node, label: node.label,
1904
- ...(verifier ? { review: verifier.review } : {}),
2280
+ ...(review ? { review } : {}),
1905
2281
  ...(node.tier ? { tier: node.tier } : {}),
1906
- system: [sopSlice, deps.skill, node.instructions].filter(Boolean),
2282
+ ...(node.node === "agent" && node.budget_usd !== undefined ? { budgetUsd: node.budget_usd } : {}),
2283
+ ...(node.node === "agent" && node.context !== undefined ? { context: node.context } : {}),
2284
+ system: [sopSlice, deps.skill, node.instructions, ...(policy?.systemBlocks && context ? policy.systemBlocks(context) : [])].filter(Boolean),
1907
2285
  user: JSON.stringify(promptState),
1908
- schema,
2286
+ schema: transportSchema,
1909
2287
  ...(node.effort ? { effort: node.effort } : {}),
1910
2288
  ...(node.thinking ? { thinking: node.thinking } : {}),
1911
2289
  ...(Array.isArray(node.tools) ? { tools: node.tools } : {}),
1912
2290
  });
1913
- normalizeStringNullsForSchema(submission, schema);
1914
- if (!validator.Check(submission)) {
1915
- throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${node.node === "report" ? "report" : node.out}"`, schemaProblems(validator, submission), node.label);
1916
- }
1917
- const result = submission;
2291
+ const decoded = decode(submission);
2292
+ const result = decoded.value;
1918
2293
  const verified = verifier ? await verifier.finish(result) : null;
1919
- const merged = mergeStageDelta(state, node, verified ? verified.submission : result, stageSchema);
1920
- return verified ? { ...merged, [`${("as" in node && node.as) || node.label}$verify`]: verified.record } : merged;
2294
+ let merged = mergeStageDelta(state, node, verified ? verified.submission : result, stageSchema);
2295
+ if (verified)
2296
+ merged = { ...merged, [`${("as" in node && node.as) || node.label}$verify`]: verified.record };
2297
+ const hostState = decoded.host && typeof decoded.host === "object" && !Array.isArray(decoded.host) ? decoded.host : null;
2298
+ if (hostState && Object.keys(hostState).length) {
2299
+ deps.onEvent?.({ type: "host.decoded", label: node.label, detail: { keys: Object.keys(hostState) } });
2300
+ merged = { ...merged, [HOST_STATE_KEY]: { ...hostStateOf(merged), ...hostState } };
2301
+ }
2302
+ return merged;
1921
2303
  }
1922
2304
  case "map": {
1923
2305
  const items = getPath(state, node.itemsPath);
@@ -2009,8 +2391,48 @@ async function runNodeBody(node, state, workflow, deps) {
2009
2391
  throw withSiblingUncertainty(failure, uncertainties);
2010
2392
  const merged = { ...state };
2011
2393
  const writer = new Map();
2394
+ // Host state is engine-owned and merges by delta: every branch started from the same `$host`, so an
2395
+ // array grows by what each branch appended, an unchanged value is kept, and two branches that set one
2396
+ // non-array key to different values are a write conflict like any other.
2397
+ const baseHost = hostStateOf(baseline);
2398
+ const mergedHost = { ...baseHost };
2399
+ const hostWriter = new Map();
2400
+ let hostChanged = false;
2401
+ outs.forEach((out, i) => {
2402
+ const branchHost = hostStateOf((out || {}));
2403
+ for (const [key, value] of Object.entries(branchHost)) {
2404
+ if (Object.hasOwn(baseHost, key) && isDeepStrictEqual(value, baseHost[key]))
2405
+ continue;
2406
+ hostChanged = true;
2407
+ // The same value from several branches is one write, whatever its shape.
2408
+ if (hostWriter.has(key) && isDeepStrictEqual(mergedHost[key], value))
2409
+ continue;
2410
+ const base = baseHost[key];
2411
+ const prior = hostWriter.get(key);
2412
+ const conflict = () => new WorkflowStateError(`parallel node "${node.label}": branches ${prior} and ${i} both wrote host state ${HOST_STATE_KEY}.${key} to different values`, node.label, `${HOST_STATE_KEY}.${key}`, "parallel_write_conflict");
2413
+ // An append is an array that extends the base array (or a new array on a key with no base).
2414
+ // Appends from several branches join in branch order. An append meets a prior non-append
2415
+ // write of the same key as a conflict, whichever branch came first: no shape wins silently.
2416
+ if (Array.isArray(value) && (base === undefined || Array.isArray(base)) && (!Array.isArray(base) || (value.length >= base.length && base.every((entry, n) => isDeepStrictEqual(entry, value[n]))))) {
2417
+ if (prior !== undefined && !Array.isArray(mergedHost[key]))
2418
+ throw conflict();
2419
+ const appended = value.slice(Array.isArray(base) ? base.length : 0);
2420
+ mergedHost[key] = [...(Array.isArray(mergedHost[key]) ? mergedHost[key] : []), ...appended];
2421
+ hostWriter.set(key, i);
2422
+ continue;
2423
+ }
2424
+ if (prior !== undefined && !isDeepStrictEqual(mergedHost[key], value))
2425
+ throw conflict();
2426
+ hostWriter.set(key, i);
2427
+ mergedHost[key] = value;
2428
+ }
2429
+ });
2430
+ if (hostChanged)
2431
+ merged[HOST_STATE_KEY] = mergedHost;
2012
2432
  outs.forEach((out, i) => {
2013
2433
  for (const [key, value] of Object.entries((out || {}))) {
2434
+ if (key === HOST_STATE_KEY)
2435
+ continue;
2014
2436
  if (Object.hasOwn(baseline, key) && isDeepStrictEqual(value, baseline[key]))
2015
2437
  continue;
2016
2438
  const prior = writer.get(key);
@@ -2205,7 +2627,7 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2205
2627
  missing("runNode");
2206
2628
  if (node.node === "call" && !deps.runEffect)
2207
2629
  missing("runEffect");
2208
- if ((["judge", "pick", "sift", "route"].includes(node.node) || "verify" in node && node.verify ||
2630
+ if ((["judge", "pick", "sift"].includes(node.node) || node.node === "route" && !routesByValue(node) || "verify" in node && node.verify ||
2209
2631
  node.node === "loop" && node.until?.predicate === "ask" ||
2210
2632
  node.node === "escalate" && node.when?.predicate === "ask") && !deps.runJudge)
2211
2633
  missing("runJudge");
@@ -2223,7 +2645,9 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2223
2645
  export async function runWorkflow(workflow, input, deps) {
2224
2646
  if (!input || typeof input !== "object" || Array.isArray(input))
2225
2647
  throw new WorkflowInputInvalidError(String(workflow?.name), ["input must be a JSON object"]);
2226
- const valid = validateWorkflow(workflow);
2648
+ // A host that executes code nodes itself never has them executed here, not even as validation probes.
2649
+ const executeCode = deps.runCode ? false : undefined;
2650
+ const valid = validateWorkflow(workflow, { executeCode });
2227
2651
  if (!valid.ok)
2228
2652
  throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2229
2653
  workflow = desugarWorkflow(workflow);
@@ -2232,7 +2656,7 @@ export async function runWorkflow(workflow, input, deps) {
2232
2656
  if (!validator.Check(input))
2233
2657
  throw new WorkflowInputInvalidError(workflow.name, schemaProblems(validator, input));
2234
2658
  }
2235
- const reachable = validateWorkflow(workflow, { inputKeys: Object.keys(input) });
2659
+ const reachable = validateWorkflow(workflow, { executeCode, inputKeys: Object.keys(input) });
2236
2660
  if (!reachable.ok)
2237
2661
  throw new WorkflowInvalidError(workflow.name, reachable.errors);
2238
2662
  assertWorkflowCapabilities(workflow.root, deps, workflow);
@@ -2240,14 +2664,21 @@ export async function runWorkflow(workflow, input, deps) {
2240
2664
  deps = { ...deps, [SCOPED_EFFECTS]: true };
2241
2665
  if (deps.recovery && !deps.recovery.supportsExecutionPaths && needsComposedRecovery(workflow.root))
2242
2666
  throw new Error("Composed child workflows require recovery.supportsExecutionPaths: true and stores keyed by executionPath");
2667
+ if (Object.prototype.hasOwnProperty.call(input, HOST_STATE_KEY))
2668
+ throw new WorkflowInputInvalidError(workflow.name, [`input must not contain the reserved "${HOST_STATE_KEY}" key`]);
2243
2669
  try {
2244
2670
  const state = await runNodeOnState(workflow.root, snapshotState(input), workflow, deps);
2245
- const output = workflow.output.path ? getPath(state, workflow.output.path) : state;
2671
+ if (deps.signal?.aborted)
2672
+ throw deps.signal.reason ?? new Error("workflow aborted");
2673
+ const host = hostStateOf(state);
2674
+ const output = workflow.output.path
2675
+ ? getPath(state, workflow.output.path)
2676
+ : (Object.prototype.hasOwnProperty.call(state, HOST_STATE_KEY) ? Object.fromEntries(Object.entries(state).filter(([key]) => key !== HOST_STATE_KEY)) : state);
2246
2677
  const validator = Compile(resolveSchemaForWorkflow(workflow, workflow.schemas[workflow.output.schemaId]));
2247
2678
  if (!validator.Check(output)) {
2248
2679
  throw new WorkflowOutputInvalidError(`workflow "${workflow.name}" output does not satisfy schema "${workflow.output.schemaId}"`, schemaProblems(validator, output));
2249
2680
  }
2250
- return { status: "complete", state, output };
2681
+ return { status: "complete", state, output, ...(Object.keys(host).length ? { host } : {}) };
2251
2682
  }
2252
2683
  catch (error) {
2253
2684
  if (error instanceof EscalationSignal)
@@ -2256,7 +2687,7 @@ export async function runWorkflow(workflow, input, deps) {
2256
2687
  }
2257
2688
  }
2258
2689
  export async function runWorkflowSlice(workflow, input, focus, deps) {
2259
- const valid = validateWorkflow(workflow);
2690
+ const valid = validateWorkflow(workflow, { executeCode: deps.runCode ? false : undefined });
2260
2691
  if (!valid.ok)
2261
2692
  throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2262
2693
  const desugared = desugarWorkflow(workflow);
@@ -2284,6 +2715,8 @@ export async function runWorkflowSlice(workflow, input, focus, deps) {
2284
2715
  let out = state;
2285
2716
  for (let i = a; i <= b; i++)
2286
2717
  out = await runNodeOnState(root[i], out, desugared, desugared.root.node === "chain" ? scopeExecution(deps, "steps", i) : deps);
2718
+ if (deps.signal?.aborted)
2719
+ throw deps.signal.reason ?? new Error("workflow aborted");
2287
2720
  return { status: "complete", state: out, focus: { from: labels[a], to: labels[b] } };
2288
2721
  }
2289
2722
  catch (error) {