@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.
- package/README.md +25 -11
- package/dist/author.d.ts +89 -0
- package/dist/author.js +317 -0
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/dry-run.d.ts +4 -1
- package/dist/dry-run.js +2 -1
- package/dist/index.d.ts +8 -3
- package/dist/index.js +9 -2
- package/dist/inspection.js +2 -2
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/system-one.js +45 -4
- package/dist/vocabulary.d.ts +42 -0
- package/dist/vocabulary.js +74 -0
- package/dist/workflow-shape.js +6 -2
- package/dist/workflow.d.ts +164 -15
- package/dist/workflow.js +551 -118
- package/package.json +3 -2
- package/schema/workflow.schema.json +237 -15
- package/skills/author/SKILL.md +120 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +125 -0
- package/skills/author/references/language.md +118 -0
- package/skills/author/references/sdk-authoring.md +9 -0
- 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
|
|
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(
|
|
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
|
-
|
|
97
|
-
|
|
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(
|
|
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 && !
|
|
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 && !
|
|
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
|
|
702
|
-
errors.push(`${path} (${node.label}): verify.maxDrives must be an integer 1
|
|
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
|
-
|
|
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
|
|
759
|
-
errors.push(`${path} (${node.label}): maxIters must be 1
|
|
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
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
if (
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
if (
|
|
867
|
-
errors.push(`${path} (${label}):
|
|
868
|
-
if (
|
|
869
|
-
errors.push(`${path} (${label}):
|
|
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
|
-
|
|
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 =
|
|
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 (
|
|
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 (!
|
|
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
|
|
998
|
-
errors.push(`${path} (${label}): deadline_s must be greater than 0
|
|
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
|
|
1007
|
-
errors.push(`${path} (${label}): retry.attempts must be 1
|
|
1008
|
-
if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0
|
|
1009
|
-
errors.push(`${path} (${label}): retry.backoff_s must be 0
|
|
1010
|
-
if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !
|
|
1011
|
-
errors.push(`${path} (${label}): retry.on may name only
|
|
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
|
|
1032
|
-
errors.push(`${path} (${label}): poll.interval_s must be 0.1
|
|
1033
|
-
if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)
|
|
1034
|
-
errors.push(`${path} (${label}): poll.deadline_s must be
|
|
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 = () => {
|
|
1390
|
-
const timer =
|
|
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 =
|
|
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
|
-
|
|
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 ||
|
|
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 ||
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
1661
|
-
|
|
1662
|
-
|
|
1663
|
-
|
|
1664
|
-
|
|
1665
|
-
|
|
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 =
|
|
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 =>
|
|
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 =>
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1877
|
-
const
|
|
1878
|
-
out =
|
|
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
|
-
|
|
1881
|
-
|
|
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
|
-
...(
|
|
2280
|
+
...(review ? { review } : {}),
|
|
1905
2281
|
...(node.tier ? { tier: node.tier } : {}),
|
|
1906
|
-
|
|
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
|
-
|
|
1914
|
-
|
|
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
|
-
|
|
1920
|
-
|
|
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"
|
|
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
|
-
|
|
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
|
-
|
|
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) {
|