@parcha/agentrun-dsl 0.1.0-beta.37 → 0.1.0-beta.39
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 +1 -1
- package/dist/author-references.d.ts +1 -1
- package/dist/author-references.js +1 -1
- package/dist/author.js +13 -1
- package/dist/dry-run.d.ts +3 -0
- package/dist/dry-run.js +3 -0
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/predicates.d.ts +23 -1
- package/dist/predicates.js +43 -0
- package/dist/vocabulary.d.ts +14 -2
- package/dist/vocabulary.js +20 -8
- package/dist/workflow.d.ts +104 -1
- package/dist/workflow.js +477 -12
- package/package.json +1 -1
- package/schema/workflow.schema.json +147 -0
- package/skills/author/references/language.md +20 -10
package/dist/workflow.js
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { observerSnapshot } from "./observer-snapshot.js";
|
|
2
2
|
import { createHash } from "node:crypto";
|
|
3
3
|
import { isDeepStrictEqual, types as utilTypes } from "node:util";
|
|
4
|
-
import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
|
|
5
|
-
import { DECISION_NODE_FIELDS, DECISION_TIMEOUT_MAX_MS, WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, FIELD_TYPES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
|
|
4
|
+
import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES, quoteCheck } from "./predicates.js";
|
|
5
|
+
import { DECISION_NODE_FIELDS, DECISION_TIMEOUT_MAX_MS, GUARD_FIELDS, GUARD_SIGNALS, GUARDED_NODE_KINDS, SELF_CONFIDENCE_KINDS, WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, FIELD_TYPES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
|
|
6
6
|
import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, refusedQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
|
|
7
7
|
import { chargedCost, DecisionProviderError } from "./decision-provider.js";
|
|
8
8
|
import { DECISION_ERROR_MAX, DECISION_RECEIPT_VERSION, DECISION_INTERRUPTED, DECISION_REFUSED, DECISION_STATE_MAX_BYTES } from "./decision-receipts.js";
|
|
@@ -16,6 +16,8 @@ import { isRecoveryError } from "./recovery/errors.js";
|
|
|
16
16
|
/** A request's error as its receipt keeps it: whole up to DECISION_ERROR_MAX characters, a longer one cut there and
|
|
17
17
|
* marked, so a host redacts it before it cuts it and holds a cut one's tail back (decision-receipts.ts). */
|
|
18
18
|
const errorOfReceipt = (text) => text.length > DECISION_ERROR_MAX ? { error: text.slice(0, DECISION_ERROR_MAX), error_truncated: true } : { error: text };
|
|
19
|
+
/** The longest question a guard asks Jev, in characters. */
|
|
20
|
+
export const GUARD_QUESTION_MAX = 2_000;
|
|
19
21
|
export const routesByValue = (node) => typeof node.valuePath === "string";
|
|
20
22
|
export function artifactNodeIsProse(node) {
|
|
21
23
|
return PROSE_ARTIFACT_TYPES.includes(node.type);
|
|
@@ -174,6 +176,8 @@ function containsReportNode(node) {
|
|
|
174
176
|
return false;
|
|
175
177
|
}
|
|
176
178
|
const PREDICATES = new Set(WORKFLOW_PREDICATES);
|
|
179
|
+
/** Whether one dotted state path is the other or lies under it. */
|
|
180
|
+
const pathsOverlap = (a, b) => a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`);
|
|
177
181
|
function predicateShapeErrors(pred) {
|
|
178
182
|
const out = [];
|
|
179
183
|
if (pred.predicate === "in") {
|
|
@@ -194,6 +198,21 @@ function predicateShapeErrors(pred) {
|
|
|
194
198
|
if (!FIELD_TYPES.includes(pred.type))
|
|
195
199
|
out.push(`field_type needs a type of ${FIELD_TYPES.join("|")}, not ${JSON.stringify(pred.type) ?? "none"}`);
|
|
196
200
|
}
|
|
201
|
+
if (pred.predicate === "quote_missing") {
|
|
202
|
+
const path = String(pred.path || "").trim();
|
|
203
|
+
if (!path)
|
|
204
|
+
out.push("quote_missing needs a path (the quote, or the list of them)");
|
|
205
|
+
if (pred.field !== undefined && !(typeof pred.field === "string" && pred.field.trim()))
|
|
206
|
+
out.push("quote_missing.field must name the quote in each item: a non-empty path");
|
|
207
|
+
const pages = pred.pages;
|
|
208
|
+
if (!Array.isArray(pages) || !pages.length || pages.some((page) => typeof page !== "string" || !page.trim()))
|
|
209
|
+
out.push("quote_missing needs pages: a non-empty list of state paths holding the text of the pages this run fetched");
|
|
210
|
+
// A page path that is the quotes, or holds them, or sits inside them, finds every quote in itself.
|
|
211
|
+
else if (path)
|
|
212
|
+
for (const page of pages)
|
|
213
|
+
if (pathsOverlap(page, path))
|
|
214
|
+
out.push(`quote_missing reads its quotes as a page: pages names "${page}", which overlaps path "${path}"`);
|
|
215
|
+
}
|
|
197
216
|
if (pred.predicate === "not" && (!pred.of || typeof pred.of !== "object" || Array.isArray(pred.of)))
|
|
198
217
|
out.push(`not needs "of", one mechanical predicate`);
|
|
199
218
|
if (pred.predicate === "ask") {
|
|
@@ -663,7 +682,16 @@ export function validateWorkflow(workflow, opts) {
|
|
|
663
682
|
if (!reachability || reachability.unknowable || !pred || typeof pred !== "object")
|
|
664
683
|
return;
|
|
665
684
|
const available = produced ?? reachability.available;
|
|
666
|
-
const { predicate, path: at, key } = pred;
|
|
685
|
+
const { predicate, path: at, key, pages } = pred;
|
|
686
|
+
// quote_missing reads its pages too: a page no input key or earlier node writes holds no text, so every quote misses.
|
|
687
|
+
if (predicate === "quote_missing" && Array.isArray(pages))
|
|
688
|
+
for (const page of pages) {
|
|
689
|
+
if (typeof page !== "string" || !page.trim())
|
|
690
|
+
continue;
|
|
691
|
+
const head = page.split(".")[0];
|
|
692
|
+
if (!available.has(head))
|
|
693
|
+
fail("STATE_PATH_UNPRODUCED", ptrOf(path), `${path} (${label}): ${field}.pages reads "${page}" but no input key or earlier node produces "${head}"; every quote would miss`);
|
|
694
|
+
}
|
|
667
695
|
const read = predicate === "no_new_items" ? key : predicate === "ask" ? undefined : at;
|
|
668
696
|
if (typeof read !== "string" || !read.trim())
|
|
669
697
|
return;
|
|
@@ -844,6 +872,58 @@ export function validateWorkflow(workflow, opts) {
|
|
|
844
872
|
return checkPredicate(pred.of, label, path, `${field}.of`, "not");
|
|
845
873
|
return true;
|
|
846
874
|
};
|
|
875
|
+
/** A node's step guard (StepGuard), field by field, in words an author can act on: where it may sit, its signal (and
|
|
876
|
+
* whether the node reports the confidence `self` reads), its threshold, its question and its fit. */
|
|
877
|
+
const checkGuard = (node, path) => {
|
|
878
|
+
if (node.guard === undefined)
|
|
879
|
+
return;
|
|
880
|
+
const at = `${path} (${node.label || node.node}): guard`;
|
|
881
|
+
const bad = (message) => fail("NODE_FIELD_INVALID", ptrOf(path), `${at}${message}`);
|
|
882
|
+
if (!GUARDED_NODE_KINDS.includes(node.node)) {
|
|
883
|
+
fail("NODE_KEY_UNKNOWN", ptrOf(path), `${at}: a guard sits on a step that writes a value (${GUARDED_NODE_KINDS.join(", ")}); a ${node.node} node takes none`);
|
|
884
|
+
return;
|
|
885
|
+
}
|
|
886
|
+
const guard = node.guard;
|
|
887
|
+
if (!guard || typeof guard !== "object" || Array.isArray(guard)) {
|
|
888
|
+
bad(` must be an object: {"signal": "self" | "jev" | "both", "threshold": a number between 0 and 1, "question"?: text, "fit"?: {...}}`);
|
|
889
|
+
return;
|
|
890
|
+
}
|
|
891
|
+
const extra = Object.keys(guard).filter((key) => !GUARD_FIELDS.includes(key));
|
|
892
|
+
if (extra.length)
|
|
893
|
+
bad(`: unknown key(s) ${extra.join(", ")}; a guard takes ${GUARD_FIELDS.join(", ")}`);
|
|
894
|
+
const signal = guard.signal;
|
|
895
|
+
const known = GUARD_SIGNALS.includes(signal);
|
|
896
|
+
if (!known)
|
|
897
|
+
bad(`.signal must be "self", "jev" or "both" (got ${JSON.stringify(signal) ?? "none"})`);
|
|
898
|
+
else if (signal !== "jev" && !SELF_CONFIDENCE_KINDS.includes(node.node))
|
|
899
|
+
bad(`.signal "${signal}" reads the step's own confidence, which a ${node.node} node does not report (only ${SELF_CONFIDENCE_KINDS.join(", ")} nodes do); use "jev"`);
|
|
900
|
+
else if (signal !== "jev" && (node.node === "agent" || node.node === "decide") && typeof node.out === "string" && Object.hasOwn(workflow.schemas ?? {}, node.out)) {
|
|
901
|
+
const out = resolveSchemaForWorkflow(workflow, workflow.schemas[node.out]);
|
|
902
|
+
if (!confidenceChannelOf(out))
|
|
903
|
+
bad(`.signal "${signal}" has the node submit its confidence beside its record, so its out schema "${node.out}" must be an object schema`);
|
|
904
|
+
}
|
|
905
|
+
const threshold = guard.threshold;
|
|
906
|
+
if (!(typeof threshold === "number" && Number.isFinite(threshold) && threshold > 0 && threshold < 1))
|
|
907
|
+
bad(`.threshold must be a number between 0 and 1, exclusive: the chance the step is right below which the run hands the job back (got ${JSON.stringify(threshold) ?? "none"})`);
|
|
908
|
+
if (guard.question !== undefined) {
|
|
909
|
+
if (typeof guard.question !== "string" || !guard.question.trim())
|
|
910
|
+
bad(`.question must be non-empty text: the yes/no question Jev is asked about the step's input and output`);
|
|
911
|
+
else if (signal === "self")
|
|
912
|
+
bad(`.question is Jev's; a "self" guard asks Jev nothing. Use "jev" or "both", or leave question out`);
|
|
913
|
+
else if (guard.question.length > GUARD_QUESTION_MAX)
|
|
914
|
+
bad(`.question is ${guard.question.length} characters; at most ${GUARD_QUESTION_MAX}`);
|
|
915
|
+
}
|
|
916
|
+
if (guard.fit !== undefined) {
|
|
917
|
+
const fit = guard.fit;
|
|
918
|
+
const width = signal === "both" ? 2 : 1;
|
|
919
|
+
const finite = (n) => typeof n === "number" && Number.isFinite(n);
|
|
920
|
+
const ok = fit && typeof fit === "object" && !Array.isArray(fit) && Array.isArray(fit.w) && fit.w.length === width && fit.w.every(finite) && finite(fit.b)
|
|
921
|
+
&& Number.isSafeInteger(fit.n) && fit.n >= 1 && typeof fit.fitted_at === "string" && !Number.isNaN(Date.parse(fit.fitted_at))
|
|
922
|
+
&& Object.keys(fit).every((key) => ["w", "b", "n", "fitted_at"].includes(key));
|
|
923
|
+
if (!ok)
|
|
924
|
+
bad(`.fit must be {"w": [${known ? (width === 2 ? "w_self, w_jev" : `w_${signal}`) : "one weight per signal"}], "b": a number, "n": the graded runs it was fitted on (an integer of at least 1), "fitted_at": an ISO 8601 time}`);
|
|
925
|
+
}
|
|
926
|
+
};
|
|
847
927
|
const walk = (node, path, ptr) => {
|
|
848
928
|
// A node that is missing (a map or loop without a body) is reported on the node that should hold it.
|
|
849
929
|
pointers.set(path, node === undefined ? ptr.slice(0, ptr.lastIndexOf("/")) : ptr);
|
|
@@ -853,9 +933,11 @@ export function validateWorkflow(workflow, opts) {
|
|
|
853
933
|
}
|
|
854
934
|
{
|
|
855
935
|
const allowed = KIND_KEYS[node.node];
|
|
856
|
-
|
|
936
|
+
// A guard is checked on its own (checkGuard), with its own words where it may not sit.
|
|
937
|
+
const extraneous = Object.keys(node).filter((key) => !allowed.has(key) && key !== "guard");
|
|
857
938
|
if (extraneous.length)
|
|
858
939
|
fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
|
|
940
|
+
checkGuard(node, path);
|
|
859
941
|
// State keys that hold a `$` are engine-owned (`$host`, and a typed question's `<as>$answers` and `<as>$verify`): no node
|
|
860
942
|
// may write one, wherever the `$` is. A label is the state key whenever `as` is omitted, so labels are held to the same rule.
|
|
861
943
|
if (typeof node.as === "string" && holdsDollar(node.as))
|
|
@@ -1359,9 +1441,16 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1359
1441
|
}
|
|
1360
1442
|
if (!checkPredicate(pred, label, path, `poll.${name}`, "poll"))
|
|
1361
1443
|
continue;
|
|
1362
|
-
const
|
|
1444
|
+
const read = negated(pred);
|
|
1445
|
+
const predPath = read.path;
|
|
1363
1446
|
if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
|
|
1364
1447
|
fail("STATE_PATH_EXCLUDED", ptrOf(path), `${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
|
|
1448
|
+
// quote_missing also reads its pages from the result: one outside it misses every quote, poll after poll.
|
|
1449
|
+
if (resultShape && typeof resultShape === "object" && read.predicate === "quote_missing" && Array.isArray(read.pages))
|
|
1450
|
+
for (const page of read.pages) {
|
|
1451
|
+
if (typeof page === "string" && page && resultPathMissing(resultShape, page))
|
|
1452
|
+
fail("STATE_PATH_EXCLUDED", ptrOf(path), `${path} (${label}): poll.${name} pages "${page}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); every quote would miss and the poll could never settle`);
|
|
1453
|
+
}
|
|
1365
1454
|
}
|
|
1366
1455
|
if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
|
|
1367
1456
|
fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
|
|
@@ -1519,6 +1608,11 @@ export class EscalationSignal extends Error {
|
|
|
1519
1608
|
}
|
|
1520
1609
|
}
|
|
1521
1610
|
async function evaluatePredicate(pred, state, deps, at, workflow) {
|
|
1611
|
+
// A quote check says how many quotes it read and how many no page holds, as counts: never their text.
|
|
1612
|
+
if (pred.predicate === "quote_missing") {
|
|
1613
|
+
const { checked, missed } = quoteCheck(pred, state);
|
|
1614
|
+
return { holds: missed > 0, detail: { quotes_checked: checked, quotes_missed: missed } };
|
|
1615
|
+
}
|
|
1522
1616
|
if (pred.predicate !== "ask")
|
|
1523
1617
|
return { holds: predicateMatches(pred, state) };
|
|
1524
1618
|
const ask = pred;
|
|
@@ -2400,6 +2494,14 @@ async function runJudgeNode(node, state, workflow, deps) {
|
|
|
2400
2494
|
deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "judge", as: node.as, value, sidecar, ...meteringOf(decided), decision_id: decided.id } });
|
|
2401
2495
|
return { ...state, [node.as]: value, [`${node.as}$answers`]: sidecar };
|
|
2402
2496
|
}
|
|
2497
|
+
/** What a pick's judge is asked about `items`: each candidate described (`item_<i>`), beside its interpolated `state` (else
|
|
2498
|
+
* the workflow's state as context). Its guard is asked about the same (guardInputOf). */
|
|
2499
|
+
function pickAskOf(node, state, items, workflow) {
|
|
2500
|
+
const options = Object.fromEntries(items.map((item, i) => [`item_${i}`, describeItem(node.describe, state, item, i) || `item ${i}`]));
|
|
2501
|
+
return { options, asked: { ...(node.state ? interpolateValue(node.state, state, node.label) : { context: promptStateOf(state, workflow) }), candidates: options } };
|
|
2502
|
+
}
|
|
2503
|
+
/** The items a sift's judge is asked about, by id (`item_<i>`), each with its description when the sift has one. */
|
|
2504
|
+
const siftItemsOf = (node, state, items) => items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
|
|
2403
2505
|
async function runPickNode(node, state, deps, workflow) {
|
|
2404
2506
|
assertNodeInputs(node, state);
|
|
2405
2507
|
const items = getPath(state, node.itemsPath);
|
|
@@ -2417,9 +2519,8 @@ async function runPickNode(node, state, deps, workflow) {
|
|
|
2417
2519
|
const capacity = SYSTEM_ONE_LIMITS.maxChoiceOptions - (node.allowNone ? 1 : 0);
|
|
2418
2520
|
if (items.length > capacity)
|
|
2419
2521
|
throw new Error(`pick node "${node.label}": ${items.length} items exceed the ${capacity} a choice can hold — sift first`);
|
|
2420
|
-
const options
|
|
2522
|
+
const { options, asked } = pickAskOf(node, state, items, workflow);
|
|
2421
2523
|
const criteria = node.allowNone ? { ...options, [NONE]: "none of the items fits" } : options;
|
|
2422
|
-
const asked = { ...(node.state ? interpolateValue(node.state, state, node.label) : { context: promptStateOf(state, workflow) }), candidates: options };
|
|
2423
2524
|
const decided = await decide(deps, { workflowState: state, decision: decisionOf(node), images: resolveImages(node.images, state, node.label), nodeKind: "pick", kind: "pick", judgeKind: "pick", label: node.label, state: asked, questions: { pick: { type: "choice", instructions: node.instructions, criteria } } }, (answers) => {
|
|
2424
2525
|
const a = answers.pick;
|
|
2425
2526
|
if (!a || a.type !== "choice")
|
|
@@ -2452,7 +2553,7 @@ async function runSiftNode(node, state, workflow, deps) {
|
|
|
2452
2553
|
if (items.length) {
|
|
2453
2554
|
const base = node.state ? interpolateValue(node.state, state, node.label) : {};
|
|
2454
2555
|
const images = resolveImages(node.images, state, node.label);
|
|
2455
|
-
const named =
|
|
2556
|
+
const named = siftItemsOf(node, state, items);
|
|
2456
2557
|
const chunks = siftChunks(deps, node.label, ids.length, base, named);
|
|
2457
2558
|
const measure = keepTail === "confidence" ? "confidence" : "value";
|
|
2458
2559
|
// The keep rule, as applied and as a receipt states it: the author's threshold, else 0.5 for a yes/no
|
|
@@ -2674,6 +2775,8 @@ function scopeDepsToChild(deps, invocation) {
|
|
|
2674
2775
|
...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
|
|
2675
2776
|
...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
|
|
2676
2777
|
...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
|
|
2778
|
+
...(deps.guardStep ? { guardStep: params => deps.guardStep({ ...params, label: `${prefix}/${params.label}` }) } : {}),
|
|
2779
|
+
...(deps.softEscalate ? { softEscalate: label => deps.softEscalate(`${prefix}/${label}`) } : {}),
|
|
2677
2780
|
...(deps.recordDecision ? { recordDecision: (receipt, exchange) => deps.recordDecision({ ...receipt, node: `${prefix}/${receipt.node}` }, { ...exchange, request: { ...exchange.request, label: `${prefix}/${exchange.request.label}` } }) } : {}),
|
|
2678
2781
|
...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
|
|
2679
2782
|
...(recovery ? { recovery: {
|
|
@@ -2691,6 +2794,197 @@ function scopeDepsToChild(deps, invocation) {
|
|
|
2691
2794
|
};
|
|
2692
2795
|
}
|
|
2693
2796
|
const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
|
|
2797
|
+
/** A node's step guard, as the document holds it (validateWorkflow refused any other shape). */
|
|
2798
|
+
export function stepGuardOf(node) {
|
|
2799
|
+
const guard = node.guard;
|
|
2800
|
+
return guard && typeof guard === "object" && !Array.isArray(guard) ? guard : undefined;
|
|
2801
|
+
}
|
|
2802
|
+
/** Whether a guard reads the step's own confidence. */
|
|
2803
|
+
const readsSelf = (guard) => guard.signal === "self" || guard.signal === "both";
|
|
2804
|
+
/** The field an agent or decide node whose guard reads `self` submits its confidence in, beside its record. */
|
|
2805
|
+
export const SELF_CONFIDENCE_FIELD = "confidence";
|
|
2806
|
+
/** What the model is told the field holds. */
|
|
2807
|
+
const SELF_CONFIDENCE_WORDS = "How sure you are that this submission is right for this input, from 0 (a guess) to 1 (certain): the probability it is correct.";
|
|
2808
|
+
/** The engine-owned state key an agent or decide node's own confidence lands under, beside its value: `<key>$confidence`. */
|
|
2809
|
+
export const confidenceKey = (key) => `${key}$confidence`;
|
|
2810
|
+
/** The state key a step writes its value under: its `as`, or an unaliased agent, decide, extract or code node's label. */
|
|
2811
|
+
const writeKeyOf = (node) => {
|
|
2812
|
+
const { as, label } = node;
|
|
2813
|
+
if (typeof as === "string" && as)
|
|
2814
|
+
return as;
|
|
2815
|
+
return ["agent", "decide", "extract", "code"].includes(node.node) && typeof label === "string" ? label : undefined;
|
|
2816
|
+
};
|
|
2817
|
+
/** An object out schema the confidence field can sit beside, widened with it (required), or as it is when it declares the
|
|
2818
|
+
* field itself (then the node's own field is its confidence, kept in its value); undefined for a schema that is no object. */
|
|
2819
|
+
function confidenceChannelOf(schema) {
|
|
2820
|
+
const properties = schema.properties;
|
|
2821
|
+
if (schema.type !== "object" && (!properties || typeof properties !== "object"))
|
|
2822
|
+
return undefined;
|
|
2823
|
+
if (declaresConfidence(schema))
|
|
2824
|
+
return { schema, declared: true };
|
|
2825
|
+
const field = { type: "number", minimum: 0, maximum: 1, description: SELF_CONFIDENCE_WORDS };
|
|
2826
|
+
const required = Array.isArray(schema.required) ? schema.required : [];
|
|
2827
|
+
const widened = withConfidenceInMembers(schema, field);
|
|
2828
|
+
return {
|
|
2829
|
+
schema: { ...widened, properties: { ...(properties ?? {}), [SELF_CONFIDENCE_FIELD]: field }, required: [...required, SELF_CONFIDENCE_FIELD] },
|
|
2830
|
+
declared: false,
|
|
2831
|
+
};
|
|
2832
|
+
}
|
|
2833
|
+
const COMPOSED = ["allOf", "anyOf", "oneOf"];
|
|
2834
|
+
const membersOf = (schema) => COMPOSED.flatMap((key) => (Array.isArray(schema[key]) ? schema[key] : [])).filter((m) => Boolean(m) && typeof m === "object" && !Array.isArray(m));
|
|
2835
|
+
/** Whether the schema, or a member of its allOf / anyOf / oneOf (at any depth), declares the confidence field itself. */
|
|
2836
|
+
function declaresConfidence(schema) {
|
|
2837
|
+
const properties = schema.properties;
|
|
2838
|
+
if (properties && typeof properties === "object" && Object.hasOwn(properties, SELF_CONFIDENCE_FIELD))
|
|
2839
|
+
return true;
|
|
2840
|
+
return membersOf(schema).some(declaresConfidence);
|
|
2841
|
+
}
|
|
2842
|
+
/** The schema with the confidence field allowed in every allOf / anyOf / oneOf member (at any depth): a member that is
|
|
2843
|
+
* closed (`additionalProperties` or `unevaluatedProperties` other than true) would otherwise refuse the field the root
|
|
2844
|
+
* requires, and every submission with it. The field is never required in a member; the root requires it. */
|
|
2845
|
+
function withConfidenceInMembers(schema, field) {
|
|
2846
|
+
let out = schema;
|
|
2847
|
+
for (const key of COMPOSED) {
|
|
2848
|
+
const members = schema[key];
|
|
2849
|
+
if (!Array.isArray(members))
|
|
2850
|
+
continue;
|
|
2851
|
+
out = { ...out, [key]: members.map((member) => {
|
|
2852
|
+
if (!member || typeof member !== "object" || Array.isArray(member))
|
|
2853
|
+
return member;
|
|
2854
|
+
const inner = withConfidenceInMembers(member, field);
|
|
2855
|
+
const own = inner.properties && typeof inner.properties === "object" ? inner.properties : {};
|
|
2856
|
+
return { ...inner, properties: { ...own, [SELF_CONFIDENCE_FIELD]: field } };
|
|
2857
|
+
}) };
|
|
2858
|
+
}
|
|
2859
|
+
return out;
|
|
2860
|
+
}
|
|
2861
|
+
/** A confidence as a guard reads it: a number in [0, 1], else none. */
|
|
2862
|
+
const confidenceOf = (value) => (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : null);
|
|
2863
|
+
/** The step's own confidence from its state once it ran: an agent or decide node's `<key>$confidence`, a judge or pick
|
|
2864
|
+
* node's weakest answer's (`<as>$answers.min_confidence`), a sift's weakest over every item's answers (`<as>.answers[i]`,
|
|
2865
|
+
* none when it was asked about no item, or one item's is missing). */
|
|
2866
|
+
function selfConfidenceOf(node, out) {
|
|
2867
|
+
const key = writeKeyOf(node);
|
|
2868
|
+
if (!key)
|
|
2869
|
+
return null;
|
|
2870
|
+
if (node.node === "agent" || node.node === "decide")
|
|
2871
|
+
return confidenceOf(out[confidenceKey(key)]);
|
|
2872
|
+
if (node.node === "sift") {
|
|
2873
|
+
const answers = out[key]?.answers;
|
|
2874
|
+
if (!Array.isArray(answers) || !answers.length)
|
|
2875
|
+
return null;
|
|
2876
|
+
// A loop, not Math.min(...each): a sift may hold more items than a call takes arguments.
|
|
2877
|
+
let weakest = 1;
|
|
2878
|
+
for (const sidecar of answers) {
|
|
2879
|
+
const confidence = confidenceOf(sidecar?.min_confidence);
|
|
2880
|
+
if (confidence === null)
|
|
2881
|
+
return null;
|
|
2882
|
+
if (confidence < weakest)
|
|
2883
|
+
weakest = confidence;
|
|
2884
|
+
}
|
|
2885
|
+
return weakest;
|
|
2886
|
+
}
|
|
2887
|
+
return confidenceOf(out[`${key}$answers`]?.min_confidence);
|
|
2888
|
+
}
|
|
2889
|
+
/** What a guarded step is asked about, for every node kind in one place: what it was asked to do (guardTaskOf), what it
|
|
2890
|
+
* saw (guardInputOf) and what it wrote (guardOutputOf). */
|
|
2891
|
+
function guardAskOf(node, before, after, workflow) {
|
|
2892
|
+
return { task: guardTaskOf(node, workflow), input: guardInputOf(node, before, workflow), output: guardOutputOf(node, before, after) };
|
|
2893
|
+
}
|
|
2894
|
+
/** What a step was asked to do (GuardTask). The step ran, so its schemas resolve and its questions compile; should one
|
|
2895
|
+
* not, the schema as the document holds it stands in. */
|
|
2896
|
+
function guardTaskOf(node, workflow) {
|
|
2897
|
+
const schemaOf = (id) => {
|
|
2898
|
+
if (typeof id !== "string" || !Object.hasOwn(workflow.schemas, id))
|
|
2899
|
+
return {};
|
|
2900
|
+
try {
|
|
2901
|
+
return { schema: resolveSchemaForWorkflow(workflow, workflow.schemas[id]) };
|
|
2902
|
+
}
|
|
2903
|
+
catch {
|
|
2904
|
+
return { schema: workflow.schemas[id] };
|
|
2905
|
+
}
|
|
2906
|
+
};
|
|
2907
|
+
switch (node.node) {
|
|
2908
|
+
case "agent":
|
|
2909
|
+
case "decide":
|
|
2910
|
+
case "extract": return { instructions: node.instructions, ...schemaOf(node.out) };
|
|
2911
|
+
case "pick": return { instructions: node.instructions, allow_none: node.allowNone === true };
|
|
2912
|
+
case "judge":
|
|
2913
|
+
case "sift":
|
|
2914
|
+
try {
|
|
2915
|
+
return { questions: questionSetOf(workflow, node).questions };
|
|
2916
|
+
}
|
|
2917
|
+
catch {
|
|
2918
|
+
return schemaOf(node.out);
|
|
2919
|
+
}
|
|
2920
|
+
case "code": return { code: node.code };
|
|
2921
|
+
case "call": {
|
|
2922
|
+
const what = node.via === "tool" ? { tool: node.tool } : node.via === "executor" ? { code: node.code } : { command: node.command };
|
|
2923
|
+
return { ...what, ...(node.via === "shell" ? {} : schemaOf(node.out)) };
|
|
2924
|
+
}
|
|
2925
|
+
case "workflow": return { workflow: node.workflow?.name, ...schemaOf(node.out) };
|
|
2926
|
+
default: return {};
|
|
2927
|
+
}
|
|
2928
|
+
}
|
|
2929
|
+
/** What a step saw, as its guard is asked about it: its interpolated `state`, a call's `args` (or an executor's `input`, a
|
|
2930
|
+
* shell's `env`), a child's `input`; a pick's, what its judge chose among (its state, the candidates); a sift's, its
|
|
2931
|
+
* state and the items its judge was asked about; else the workflow's state before it, as a generative node with no
|
|
2932
|
+
* `state` sees it. */
|
|
2933
|
+
function guardInputOf(node, state, workflow) {
|
|
2934
|
+
try {
|
|
2935
|
+
if (node.node === "call")
|
|
2936
|
+
return interpolateValue(node.via === "tool" ? node.args ?? {} : node.via === "executor" ? node.input ?? {} : node.env ?? {}, state, node.label);
|
|
2937
|
+
if (node.node === "workflow")
|
|
2938
|
+
return interpolateValue(node.input, state, node.label);
|
|
2939
|
+
if (node.node === "pick" || node.node === "sift") {
|
|
2940
|
+
const items = getPath(state, node.itemsPath);
|
|
2941
|
+
const list = Array.isArray(items) ? items : [];
|
|
2942
|
+
if (node.node === "pick")
|
|
2943
|
+
return pickAskOf(node, state, list, workflow).asked;
|
|
2944
|
+
return { ...(node.state ? interpolateValue(node.state, state, node.label) : {}), items: siftItemsOf(node, state, list) };
|
|
2945
|
+
}
|
|
2946
|
+
const own = node.state;
|
|
2947
|
+
if (own && typeof own === "object")
|
|
2948
|
+
return interpolateValue(own, state, node.label);
|
|
2949
|
+
}
|
|
2950
|
+
catch { /* The step ran on it, so it resolves; should it not, the state it ran on stands in. */ }
|
|
2951
|
+
return promptStateOf(state, workflow);
|
|
2952
|
+
}
|
|
2953
|
+
/** What a code node returned, by the state it produced: a code node with no `as` merges an object it returns, so its
|
|
2954
|
+
* write key alone cannot say what it wrote. */
|
|
2955
|
+
const codeWrote = new WeakMap();
|
|
2956
|
+
/** What a step wrote, even when it equals what was there before: what a code node returned, else the value under its
|
|
2957
|
+
* write key, else the keys it changed (none engine-owned). */
|
|
2958
|
+
function guardOutputOf(node, before, after) {
|
|
2959
|
+
const returned = node.node === "code" ? codeWrote.get(after) : undefined;
|
|
2960
|
+
if (returned)
|
|
2961
|
+
return returned.value;
|
|
2962
|
+
const key = writeKeyOf(node);
|
|
2963
|
+
if (key && Object.hasOwn(after, key))
|
|
2964
|
+
return after[key];
|
|
2965
|
+
return Object.fromEntries(Object.entries(after).filter(([name, value]) => !holdsDollar(name) && before[name] !== value));
|
|
2966
|
+
}
|
|
2967
|
+
/** A guarded step's check, once it ran: the host's guardStep gives p, and p below the guard's threshold (or no p at all)
|
|
2968
|
+
* hands the job back, an escalation of kind `guard` at the step, with the state it reached. Every check is an event
|
|
2969
|
+
* (`guard.evaluated`: signal, threshold, p, self, jev, escalated). */
|
|
2970
|
+
async function checkStepGuard(node, guard, before, after, workflow, deps) {
|
|
2971
|
+
const label = node.label;
|
|
2972
|
+
if (!deps.guardStep)
|
|
2973
|
+
throw new Error(`${node.node} node "${label}" requires guardStep`);
|
|
2974
|
+
const self = readsSelf(guard) ? selfConfidenceOf(node, after) : null;
|
|
2975
|
+
const item = deps[MAP_ITEM];
|
|
2976
|
+
const verdict = await deps.guardStep({ label, kind: node.node, guard, ...guardAskOf(node, before, after, workflow), self, executionPath: executionPath(deps), ...(item ? { item } : {}), ...(deps.signal ? { signal: deps.signal } : {}) });
|
|
2977
|
+
const p = typeof verdict?.p === "number" && Number.isFinite(verdict.p) ? Math.min(1, Math.max(0, verdict.p)) : null;
|
|
2978
|
+
const jev = typeof verdict?.jev === "number" && Number.isFinite(verdict.jev) ? verdict.jev : null;
|
|
2979
|
+
// No p is no evidence the step is right: it hands back, never passes.
|
|
2980
|
+
const escalated = p === null || p < guard.threshold;
|
|
2981
|
+
deps.onEvent?.({ type: "guard.evaluated", label, detail: { kind: node.node, signal: guard.signal, threshold: guard.threshold, p, self, jev, escalated } });
|
|
2982
|
+
if (!escalated)
|
|
2983
|
+
return;
|
|
2984
|
+
const said = (n) => (n === null ? "none" : n.toFixed(2));
|
|
2985
|
+
const why = guard.signal === "self" ? `its own confidence ${said(self)}` : guard.signal === "jev" ? `Jev's ${said(jev)}` : `its own confidence ${said(self)} and Jev's ${said(jev)}`;
|
|
2986
|
+
throw new EscalationSignal({ kind: "guard", stage: label, summary: `its guard put the chance this step is right at ${said(p)} (${why}), under its threshold ${guard.threshold}`, state: after, label, executionPath: executionPath(deps) });
|
|
2987
|
+
}
|
|
2694
2988
|
const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
|
|
2695
2989
|
const guardedObservers = new WeakSet();
|
|
2696
2990
|
function forwardObserver(observer, transform) {
|
|
@@ -2748,6 +3042,10 @@ async function runNodeOnState(node, state, workflow, deps) {
|
|
|
2748
3042
|
let out = await runNodeBody(node, state, workflow, deps);
|
|
2749
3043
|
if (deps.signal?.aborted)
|
|
2750
3044
|
throw deps.signal.reason ?? new Error("workflow aborted");
|
|
3045
|
+
// A guarded step's check, before anything of it is committed: one that hands back is never resumed as done.
|
|
3046
|
+
const guard = isStep ? stepGuardOf(node) : undefined;
|
|
3047
|
+
if (guard)
|
|
3048
|
+
await checkStepGuard(node, guard, state, out, workflow, deps);
|
|
2751
3049
|
// Host policy enrichment lands before commit and checkpoint: a resumed run sees exactly what ran.
|
|
2752
3050
|
if (isStep && deps.hostPolicy?.afterNode) {
|
|
2753
3051
|
const patch = deps.hostPolicy.afterNode({ ...hostContext(workflow, node, deps), state: out });
|
|
@@ -2811,6 +3109,152 @@ function withSiblingUncertainty(primary, uncertainties) {
|
|
|
2811
3109
|
? new AggregateError([primary, ...additional], "Workflow branches failed with uncertain effects; reconcile each effect before retrying", { cause: primary })
|
|
2812
3110
|
: primary;
|
|
2813
3111
|
}
|
|
3112
|
+
const JUDGE_WROTE = new Set(["judge"]);
|
|
3113
|
+
const OTHER_WROTE = new Set(["other"]);
|
|
3114
|
+
const writersOf = (state, key) => state.get(key) ?? OTHER_WROTE;
|
|
3115
|
+
/** The writers after any one of `states`: each key's writers on every one of them. */
|
|
3116
|
+
function joinWriters(states) {
|
|
3117
|
+
const out = new Map();
|
|
3118
|
+
for (const key of new Set(states.flatMap((state) => [...state.keys()]))) {
|
|
3119
|
+
const each = states.map((state) => writersOf(state, key));
|
|
3120
|
+
out.set(key, each.every((writers) => writers === each[0]) ? each[0] : new Set(each.flatMap((writers) => [...writers])));
|
|
3121
|
+
}
|
|
3122
|
+
return out;
|
|
3123
|
+
}
|
|
3124
|
+
const sameWriters = (a, b) => a.size === b.size && [...a].every(([key, writers]) => { const other = b.get(key); return other !== undefined && other.size === writers.size && [...writers].every((w) => other.has(w)); });
|
|
3125
|
+
/** Past this nesting, or this many passes over a loop's body, softEscalates reads every escalate as hard. */
|
|
3126
|
+
const SOFT_WALK_DEPTH = 256;
|
|
3127
|
+
const SOFT_WALK_PASSES = 16;
|
|
3128
|
+
class SoftWalkTooDeep extends Error {
|
|
3129
|
+
}
|
|
3130
|
+
const docOf = (value) => (value && typeof value === "object" && !Array.isArray(value) ? value : undefined);
|
|
3131
|
+
/** A node that writes its value under its `as`, else its label (mergeStageDelta, runCallNode, runPickNode, runSiftNode). */
|
|
3132
|
+
const writesItsKey = (node, at) => at.wrote(typeof node.as === "string" && node.as !== "" ? node.as : node.label, OTHER_WROTE);
|
|
3133
|
+
/** The state keys an `ask` predicate reads (evaluatePredicate): the head of each `{path}` its `state` and its `images`
|
|
3134
|
+
* interpolate, both `state` and the key after it for a `{state.…}` reference (interpolateValue tries either). With no
|
|
3135
|
+
* `state` it reads the whole state, the input with it: no key list, so none. */
|
|
3136
|
+
function askHeads(ask) {
|
|
3137
|
+
if (ask.state === undefined)
|
|
3138
|
+
return [];
|
|
3139
|
+
const heads = [];
|
|
3140
|
+
// String values only, at any depth: interpolateValue replaces values, so an object key that looks like a reference is a literal.
|
|
3141
|
+
const read = (value) => {
|
|
3142
|
+
if (typeof value === "string") {
|
|
3143
|
+
for (const m of value.matchAll(/\{([a-zA-Z0-9_.$]+)\}/g)) {
|
|
3144
|
+
const [head, next] = m[1].split(".");
|
|
3145
|
+
heads.push(head);
|
|
3146
|
+
if (head === "state" && next)
|
|
3147
|
+
heads.push(next);
|
|
3148
|
+
}
|
|
3149
|
+
}
|
|
3150
|
+
else if (Array.isArray(value))
|
|
3151
|
+
value.forEach(read);
|
|
3152
|
+
else if (value && typeof value === "object")
|
|
3153
|
+
Object.values(value).forEach(read);
|
|
3154
|
+
};
|
|
3155
|
+
read(ask.state);
|
|
3156
|
+
read(ask.images);
|
|
3157
|
+
return heads;
|
|
3158
|
+
}
|
|
3159
|
+
/** What each node kind writes to the state when runNodeBody (below) runs it: the writers of every key after the node runs
|
|
3160
|
+
* from `at.state`. One entry per kind, so a new kind says here what it writes. A chain runs its steps in order; a route
|
|
3161
|
+
* one branch, any of them, after its `as` (its choice); a parallel its branches each from the same state, a key one wrote
|
|
3162
|
+
* taking that branch's writer; a loop its body once or more, each pass from the last's; a map its body per item on its
|
|
3163
|
+
* own copy (with `item`, `item_index`), only its `as` (and `failedAs`) left after; a child workflow on its own state, only
|
|
3164
|
+
* its `as` left after. A judge writes its `as` and `<as>$answers`; a code node with no `as` may write any key. */
|
|
3165
|
+
const NODE_WRITES = {
|
|
3166
|
+
chain: (node, at) => (Array.isArray(node.steps) ? node.steps : []).reduce((state, step) => at.walk(step, state), at.state),
|
|
3167
|
+
route: (node, at) => {
|
|
3168
|
+
const routed = at.wrote(node.as, OTHER_WROTE);
|
|
3169
|
+
const bodies = docOf(node.branches) ? Object.values(node.branches).map((branch) => docOf(branch)?.body) : [];
|
|
3170
|
+
return bodies.length ? joinWriters(bodies.map((body) => at.walk(body, routed))) : routed;
|
|
3171
|
+
},
|
|
3172
|
+
parallel: (node, at) => {
|
|
3173
|
+
const outs = (Array.isArray(node.branches) ? node.branches : []).map((branch) => at.walk(branch, at.state));
|
|
3174
|
+
const merged = new Map(at.state);
|
|
3175
|
+
for (const key of new Set(outs.flatMap((out) => [...out.keys()]))) {
|
|
3176
|
+
const writers = outs.filter((out) => out.get(key) !== at.state.get(key));
|
|
3177
|
+
if (writers.length)
|
|
3178
|
+
merged.set(key, joinWriters(writers).get(key));
|
|
3179
|
+
}
|
|
3180
|
+
return merged;
|
|
3181
|
+
},
|
|
3182
|
+
loop: (node, at) => {
|
|
3183
|
+
let entry = at.state;
|
|
3184
|
+
for (let pass = 0; pass < SOFT_WALK_PASSES; pass++) {
|
|
3185
|
+
const out = at.walk(node.body, entry);
|
|
3186
|
+
const next = joinWriters([at.state, out]);
|
|
3187
|
+
if (sameWriters(next, entry))
|
|
3188
|
+
return out;
|
|
3189
|
+
entry = next;
|
|
3190
|
+
}
|
|
3191
|
+
throw new SoftWalkTooDeep();
|
|
3192
|
+
},
|
|
3193
|
+
map: (node, at) => {
|
|
3194
|
+
at.walk(node.body, at.wrote("item_index", OTHER_WROTE, at.wrote("item", OTHER_WROTE)));
|
|
3195
|
+
return at.wrote(node.failedAs, OTHER_WROTE, at.wrote(node.as, OTHER_WROTE));
|
|
3196
|
+
},
|
|
3197
|
+
workflow: (node, at) => {
|
|
3198
|
+
at.walk(docOf(node.workflow)?.root, new Map(), typeof node.label === "string" ? `${at.prefix}${node.label}/` : at.prefix);
|
|
3199
|
+
return at.wrote(node.as, OTHER_WROTE);
|
|
3200
|
+
},
|
|
3201
|
+
// A judge writes its `as` and the question's answers at `<as>$answers` (runJudgeNode): both are the judge's.
|
|
3202
|
+
judge: (node, at) => at.wrote(node.as, JUDGE_WROTE, typeof node.as === "string" ? at.wrote(`${node.as}$answers`, JUDGE_WROTE) : at.state),
|
|
3203
|
+
escalate: (node, at) => {
|
|
3204
|
+
if (typeof node.label !== "string")
|
|
3205
|
+
return at.state;
|
|
3206
|
+
let when = docOf(node.when);
|
|
3207
|
+
while (when?.predicate === "not")
|
|
3208
|
+
when = docOf(when.of);
|
|
3209
|
+
const heads = when?.predicate === "ask" ? askHeads(when) : typeof when?.path === "string" ? [when.path.split(".")[0]] : [];
|
|
3210
|
+
at.escalate(node.label, heads.length > 0 && heads.every((head) => { const writers = writersOf(at.state, head); return writers.size === 1 && writers.has("judge"); }));
|
|
3211
|
+
return at.state;
|
|
3212
|
+
},
|
|
3213
|
+
code: (node, at) => {
|
|
3214
|
+
if (typeof node.as === "string" && node.as !== "")
|
|
3215
|
+
return at.wrote(node.as, OTHER_WROTE);
|
|
3216
|
+
return new Map([...at.state].map(([key, writers]) => [key, writers.has("other") ? writers : new Set([...writers, "other"])]));
|
|
3217
|
+
},
|
|
3218
|
+
report: (_node, at) => at.wrote("report_markdown", OTHER_WROTE),
|
|
3219
|
+
artifact: (_node, at) => at.wrote("artifact", OTHER_WROTE),
|
|
3220
|
+
agent: writesItsKey, decide: writesItsKey, extract: writesItsKey, pick: writesItsKey, sift: writesItsKey, call: writesItsKey,
|
|
3221
|
+
};
|
|
3222
|
+
/** The writers after `value` (a node of a workflow document) runs from `state` (NODE_WRITES). Each escalate's verdict
|
|
3223
|
+
* lands in `verdicts`, false on any pass where it is not soft. */
|
|
3224
|
+
function walkWriters(value, state, prefix, verdicts, depth) {
|
|
3225
|
+
const node = docOf(value);
|
|
3226
|
+
if (!node)
|
|
3227
|
+
return state;
|
|
3228
|
+
if (depth > SOFT_WALK_DEPTH)
|
|
3229
|
+
throw new SoftWalkTooDeep();
|
|
3230
|
+
const writes = Object.hasOwn(NODE_WRITES, node.node) ? NODE_WRITES[node.node] : writesItsKey;
|
|
3231
|
+
return writes(node, {
|
|
3232
|
+
state, prefix,
|
|
3233
|
+
walk: (inner, from, at = prefix) => walkWriters(inner, from, at, verdicts, depth + 1),
|
|
3234
|
+
wrote: (key, writers, from = state) => (typeof key === "string" && key !== "" ? new Map(from).set(key, writers) : from),
|
|
3235
|
+
escalate: (label, soft) => { const name = `${prefix}${label}`; verdicts.set(name, (verdicts.get(name) ?? true) && soft); },
|
|
3236
|
+
});
|
|
3237
|
+
}
|
|
3238
|
+
/** The escalate nodes of a workflow document that read a judge's output, by label as a run names its step (a child's
|
|
3239
|
+
* `parent/child`, as WorkflowDeps.softEscalate is asked): each whose `when` (under any number of `not`s) reads a field a
|
|
3240
|
+
* judge node wrote (an `ask` predicate: every key its `state` reads, and it reads at least one), the judge being the step that last wrote that path's head on every path a run can take to the
|
|
3241
|
+
* escalate (a judge an extract overwrites, one in only some of a route's branches, one a code node with no `as` may have
|
|
3242
|
+
* overwritten, are not). A judge's field is one model's opinion of a draft the workflow already wrote, so a host that
|
|
3243
|
+
* measures the check may record it instead of obeying it (WorkflowDeps.softEscalate) and read the draft past it. A
|
|
3244
|
+
* document too deep to walk, or whose loop's writes do not settle, has none. The document is read as it is: no
|
|
3245
|
+
* validation, and a malformed node writes nothing it cannot name. */
|
|
3246
|
+
export function softEscalates(doc) {
|
|
3247
|
+
const verdicts = new Map();
|
|
3248
|
+
try {
|
|
3249
|
+
walkWriters(docOf(doc)?.root, new Map(), "", verdicts, 0);
|
|
3250
|
+
}
|
|
3251
|
+
catch (error) {
|
|
3252
|
+
if (error instanceof SoftWalkTooDeep)
|
|
3253
|
+
return new Set();
|
|
3254
|
+
throw error;
|
|
3255
|
+
}
|
|
3256
|
+
return new Set([...verdicts].flatMap(([name, soft]) => (soft ? [name] : [])));
|
|
3257
|
+
}
|
|
2814
3258
|
async function runNodeBody(node, state, workflow, deps) {
|
|
2815
3259
|
switch (node.node) {
|
|
2816
3260
|
case "chain": {
|
|
@@ -2838,7 +3282,9 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2838
3282
|
if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
|
|
2839
3283
|
throw new WorkflowStateError(`code node "${node.label}" wrote the reserved "${HOST_STATE_KEY}" state key`, node.label, HOST_STATE_KEY, "reserved_state_key");
|
|
2840
3284
|
deps.onEvent?.({ type: "code.patch", label: node.label, detail: patch });
|
|
2841
|
-
|
|
3285
|
+
const next = { ...state, ...patch };
|
|
3286
|
+
codeWrote.set(next, { value: out });
|
|
3287
|
+
return next;
|
|
2842
3288
|
}
|
|
2843
3289
|
case "agent":
|
|
2844
3290
|
case "decide":
|
|
@@ -2857,14 +3303,28 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2857
3303
|
// channels); the decoded domain value is what the stage schema, the verifier and the state see.
|
|
2858
3304
|
const policy = deps.hostPolicy;
|
|
2859
3305
|
const context = policy ? hostContext(workflow, node, deps) : null;
|
|
2860
|
-
const
|
|
3306
|
+
const hostSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
|
|
3307
|
+
// A guard that reads the node's own confidence (agent, decide): the node submits it beside its record, in the field
|
|
3308
|
+
// SELF_CONFIDENCE_FIELD, split off before the stage schema sees the value (unless the stage schema declares it), and
|
|
3309
|
+
// kept at `<key>$confidence`.
|
|
3310
|
+
const guard = node.node === "agent" || node.node === "decide" ? stepGuardOf(node) : undefined;
|
|
3311
|
+
const channel = guard && readsSelf(guard) ? confidenceChannelOf(hostSchema) : undefined;
|
|
3312
|
+
const transportSchema = channel ? channel.schema : hostSchema;
|
|
2861
3313
|
const transportValidator = transportSchema === schema ? validator : Compile(transportSchema);
|
|
2862
3314
|
const stageName = node.node === "report" ? "report" : node.out;
|
|
3315
|
+
let confidence = null;
|
|
2863
3316
|
const decode = (raw) => {
|
|
2864
3317
|
normalizeStringNullsForSchema(raw, transportSchema);
|
|
2865
3318
|
if (!transportValidator.Check(raw)) {
|
|
2866
3319
|
throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${stageName}"`, schemaProblems(transportValidator, raw), node.label);
|
|
2867
3320
|
}
|
|
3321
|
+
if (channel && raw && typeof raw === "object" && !Array.isArray(raw)) {
|
|
3322
|
+
confidence = confidenceOf(raw[SELF_CONFIDENCE_FIELD]);
|
|
3323
|
+
if (!channel.declared) {
|
|
3324
|
+
const { [SELF_CONFIDENCE_FIELD]: _confidence, ...rest } = raw;
|
|
3325
|
+
raw = rest;
|
|
3326
|
+
}
|
|
3327
|
+
}
|
|
2868
3328
|
const decoded = policy?.decodeSubmission && context ? policy.decodeSubmission(raw, { ...context, host: hostStateOf(state) }) : { value: raw };
|
|
2869
3329
|
if (decoded !== null && typeof decoded === "object" && decoded.value !== raw)
|
|
2870
3330
|
normalizeStringNullsForSchema(decoded.value, schema);
|
|
@@ -2912,6 +3372,8 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2912
3372
|
let merged = mergeStageDelta(state, node, verified ? verified.submission : result, stageSchema);
|
|
2913
3373
|
if (verified)
|
|
2914
3374
|
merged = { ...merged, [`${("as" in node && node.as) || node.label}$verify`]: verified.record };
|
|
3375
|
+
if (channel)
|
|
3376
|
+
merged = { ...merged, [confidenceKey(writeKeyOf(node))]: confidence };
|
|
2915
3377
|
const hostState = decoded.host && typeof decoded.host === "object" && !Array.isArray(decoded.host) ? decoded.host : null;
|
|
2916
3378
|
if (hostState && Object.keys(hostState).length) {
|
|
2917
3379
|
deps.onEvent?.({ type: "host.decoded", label: node.label, detail: { keys: Object.keys(hostState) } });
|
|
@@ -3161,8 +3623,9 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
3161
3623
|
const pathValue = node.when?.path
|
|
3162
3624
|
? String(node.when.path).split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), state)
|
|
3163
3625
|
: undefined;
|
|
3164
|
-
deps.
|
|
3165
|
-
|
|
3626
|
+
const soft = deps.softEscalate?.(node.label) === true;
|
|
3627
|
+
deps.onEvent?.({ type: "escalate.evaluated", label: node.label, detail: { fired, path: node.when?.path ?? null, path_resolved: pathValue !== undefined, ...(evaluated.detail ?? {}), ...(soft ? { soft: true } : {}) } });
|
|
3628
|
+
if (fired && !soft) {
|
|
3166
3629
|
throw new EscalationSignal({ kind: node.kind, stage: node.stage, summary: interpolate(node.summary, state), state, label: node.label, executionPath: executionPath(deps) });
|
|
3167
3630
|
}
|
|
3168
3631
|
return state;
|
|
@@ -3357,6 +3820,8 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
|
|
|
3357
3820
|
node.node === "loop" && node.until?.predicate === "ask" ||
|
|
3358
3821
|
node.node === "escalate" && node.when?.predicate === "ask") && !deps.runJudge)
|
|
3359
3822
|
missing("runJudge");
|
|
3823
|
+
if (stepGuardOf(node) && !deps.guardStep)
|
|
3824
|
+
missing("guardStep");
|
|
3360
3825
|
checkDecisionProviders(node, deps, workflow);
|
|
3361
3826
|
// A store that cannot commit an item's failure would run the item again in the next process.
|
|
3362
3827
|
if (node.node === "map" && node.onItemFailure === "collect" && deps.recovery && !(deps.recovery.failItem && deps.recovery.itemFailure))
|