@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/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
- const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
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 predPath = negated(pred).path;
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 = Object.fromEntries(items.map((item, i) => [`item_${i}`, describeItem(node.describe, state, item, i) || `item ${i}`]));
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 = items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
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
- return { ...state, ...patch };
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 transportSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
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.onEvent?.({ type: "escalate.evaluated", label: node.label, detail: { fired, path: node.when?.path ?? null, path_resolved: pathValue !== undefined, ...(evaluated.detail ?? {}) } });
3165
- if (fired) {
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))