@parcha/agentrun-dsl 0.1.0-beta.36 → 0.1.0-beta.38

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.
@@ -1,5 +1,5 @@
1
1
  import { type AcceptPredicate } from "./predicates.js";
2
- import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
2
+ import { type GuardSignal, EFFECT_FAILURE_CODES } from "./vocabulary.js";
3
3
  import { type ConfidenceSource, type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
4
4
  import { type CostBasis, type DecisionEvidence, type DecisionProvider } from "./decision-provider.js";
5
5
  import { type DecisionImageDigest, type DecisionReceipt } from "./decision-receipts.js";
@@ -49,6 +49,32 @@ export type WorkflowThinking = "low" | "medium" | "high";
49
49
  export type NodeMetadata = {
50
50
  [key: string]: unknown;
51
51
  };
52
+ /** A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field
53
+ * by field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's. */
54
+ export type NodeGuard = {
55
+ [key: string]: unknown;
56
+ };
57
+ /** A logistic fitted on the job's graded runs: p = 1 / (1 + e^-(b + w·x)), x the guard's signals in order ([self], [jev] or
58
+ * [self, jev]); `n` the graded runs it was fitted on, `fitted_at` when (ISO 8601). */
59
+ export type GuardFit = {
60
+ w: number[];
61
+ b: number;
62
+ n: number;
63
+ fitted_at: string;
64
+ };
65
+ /** The longest question a guard asks Jev, in characters. */
66
+ export declare const GUARD_QUESTION_MAX = 2000;
67
+ /** A step guard: after the step ran, the probability it is right (`p`, from its signal, through `fit` when one is stored);
68
+ * below `threshold` the run hands the job back (escalates, kind `guard`). `self` reads the step's own confidence (agent,
69
+ * decide, judge, pick, sift); `jev` one Jev question over the step's input and output (`question`, or the host's default);
70
+ * `both` a fitted logistic over [self, jev], or with no fit the lower of the two. The engine reads its shape and the
71
+ * step's own confidence; the host's `guardStep` computes p (it asks Jev). */
72
+ export type StepGuard = {
73
+ signal: GuardSignal;
74
+ threshold: number;
75
+ question?: string;
76
+ fit?: GuardFit;
77
+ };
52
78
  export type WorkflowNode = {
53
79
  node: "chain";
54
80
  steps: WorkflowNode[];
@@ -58,6 +84,7 @@ export type WorkflowNode = {
58
84
  label: string;
59
85
  code: string;
60
86
  as?: string;
87
+ guard?: NodeGuard;
61
88
  metadata?: NodeMetadata;
62
89
  } | {
63
90
  node: "agent";
@@ -79,6 +106,7 @@ export type WorkflowNode = {
79
106
  * enforces nothing. @minimum 1 @TJS-type integer */
80
107
  max_turns?: number;
81
108
  context?: AgentContext;
109
+ guard?: NodeGuard;
82
110
  metadata?: NodeMetadata;
83
111
  } | {
84
112
  node: "decide";
@@ -94,6 +122,7 @@ export type WorkflowNode = {
94
122
  thinking?: WorkflowThinking;
95
123
  verify?: VerifyClause;
96
124
  tier?: ModelTier;
125
+ guard?: NodeGuard;
97
126
  metadata?: NodeMetadata;
98
127
  } | {
99
128
  node: "extract";
@@ -109,6 +138,7 @@ export type WorkflowNode = {
109
138
  thinking?: WorkflowThinking;
110
139
  verify?: VerifyClause;
111
140
  tier?: ModelTier;
141
+ guard?: NodeGuard;
112
142
  metadata?: NodeMetadata;
113
143
  } | {
114
144
  node: "report";
@@ -174,6 +204,7 @@ export type JudgeNode = {
174
204
  evidence?: DecisionEvidenceMode;
175
205
  timeoutMs?: number;
176
206
  images?: DecisionImages;
207
+ guard?: NodeGuard;
177
208
  metadata?: NodeMetadata;
178
209
  };
179
210
  /** One choice whose options are the items of a list. `describe` renders each item as its option
@@ -195,6 +226,7 @@ export type PickNode = {
195
226
  evidence?: DecisionEvidenceMode;
196
227
  timeoutMs?: number;
197
228
  images?: DecisionImages;
229
+ guard?: NodeGuard;
198
230
  metadata?: NodeMetadata;
199
231
  };
200
232
  /** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
@@ -219,6 +251,7 @@ export type SiftNode = {
219
251
  evidence?: DecisionEvidenceMode;
220
252
  timeoutMs?: number;
221
253
  images?: DecisionImages;
254
+ guard?: NodeGuard;
222
255
  metadata?: NodeMetadata;
223
256
  };
224
257
  /** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
@@ -286,6 +319,7 @@ export type WorkflowInvocation = {
286
319
  input: Record<string, unknown>;
287
320
  out: string;
288
321
  as: string;
322
+ guard?: NodeGuard;
289
323
  metadata?: NodeMetadata;
290
324
  };
291
325
  /** `exit` is a shell command that ended with a non-zero status: retried only when the author
@@ -369,6 +403,8 @@ export type CallNode = {
369
403
  /** Repeat the call until its result settles (a queued job, an eventually consistent read). */
370
404
  poll?: PollClause;
371
405
  requires?: string[];
406
+ /** A step guard (StepGuard): its signal can only be `jev`, a call reports no confidence. */
407
+ guard?: NodeGuard;
372
408
  metadata?: NodeMetadata;
373
409
  };
374
410
  export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
@@ -588,6 +624,18 @@ export type WorkflowDeps = {
588
624
  /** The images the request carried, by digest (never the bytes), as the host loaded them. */
589
625
  images?: DecisionImageDigest[];
590
626
  }>;
627
+ /** The host's step guards (StepGuard), asked after each guarded step ran and before its state is committed: what the
628
+ * step saw (`input`), what it wrote (`output`), and its own confidence (`self`: an agent or decide node's submitted
629
+ * one, a judge, pick or sift node's weakest answer's; null when the guard reads none or the step reported none). It
630
+ * answers the probability the step is right (`p`); below the guard's threshold, or with no p, the run hands the job
631
+ * back: it escalates (kind `guard`, stage the step's label) with the step's state. A workflow that holds a guard is
632
+ * refused before any node runs on a host without it. */
633
+ guardStep?: (params: GuardStepParams) => Promise<GuardVerdict>;
634
+ /** Escalate nodes the host records instead of obeying, by label (a child workflow's as its events name it,
635
+ * `parent/child`): one it says true of evaluates its `when` as any does and says so in its `escalate.evaluated` event
636
+ * (`soft: true`), and the run goes on past it whether it fired or not. A replay reads what the workflow would have
637
+ * answered past a check it is measuring. Absent: every escalate that fires hands the job back. */
638
+ softEscalate?: (label: string) => boolean;
591
639
  /** Records one typed-question request and what its answers decide. It is awaited before the answers
592
640
  * reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
593
641
  * rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
@@ -644,6 +692,46 @@ export type WorkflowEvent = {
644
692
  detail?: unknown;
645
693
  executionPath?: string;
646
694
  };
695
+ /** What a host's `guardStep` is asked with (WorkflowDeps.guardStep). */
696
+ export type GuardStepParams = {
697
+ label: string;
698
+ kind: WorkflowNode["node"];
699
+ guard: StepGuard;
700
+ /** What the step was asked to do (guardAskOf): without it two steps over the same input that ask for different things
701
+ * read the same to Jev. */
702
+ task: GuardTask;
703
+ /** What the step saw: its interpolated `state` (or a call's `args`, an executor's `input`, a child's `input`), else the
704
+ * workflow's state before it. */
705
+ input: unknown;
706
+ /** What the step wrote: the value under its `as` (or its label), or the keys it changed. */
707
+ output: unknown;
708
+ /** The step's own confidence in [0, 1], for a guard that reads it; null otherwise or when it reported none. */
709
+ self: number | null;
710
+ executionPath: string;
711
+ item?: MapItem;
712
+ signal?: AbortSignal;
713
+ };
714
+ /** What a guarded step was asked to do, as its guard is asked about it, its instructions first: an agent, decide, extract
715
+ * or pick node's `instructions` (a pick's with whether none may fit); a judge or sift's questions (its `out` compiled,
716
+ * each question's type and words, as its judge was asked them); the schema its value meets (an agent, decide or extract
717
+ * node's `out`, a call's or a child workflow's); a code node's or an executor's code, a tool call's tool, a shell's
718
+ * command, a child's workflow name. */
719
+ export type GuardTask = {
720
+ instructions?: string;
721
+ allow_none?: boolean;
722
+ questions?: Record<string, unknown>;
723
+ schema?: unknown;
724
+ code?: string;
725
+ tool?: string;
726
+ command?: string;
727
+ workflow?: string;
728
+ };
729
+ /** A host's guard verdict: `p`, the probability the step is right. */
730
+ export type GuardVerdict = {
731
+ p: number;
732
+ /** Jev's answer, for a guard that asked it: what the run record keeps beside p. */
733
+ jev?: number | null;
734
+ };
647
735
  type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
648
736
  type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
649
737
  /** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
@@ -815,6 +903,12 @@ export declare class WorkflowDecisionRecordError extends Error {
815
903
  }
816
904
  /** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
817
905
  export declare const HOST_STATE_KEY = "$host";
906
+ /** A node's step guard, as the document holds it (validateWorkflow refused any other shape). */
907
+ export declare function stepGuardOf(node: WorkflowNode): StepGuard | undefined;
908
+ /** The field an agent or decide node whose guard reads `self` submits its confidence in, beside its record. */
909
+ export declare const SELF_CONFIDENCE_FIELD = "confidence";
910
+ /** The engine-owned state key an agent or decide node's own confidence lands under, beside its value: `<key>$confidence`. */
911
+ export declare const confidenceKey: (key: string) => string;
818
912
  export declare class WorkflowVerificationError extends Error {
819
913
  readonly stage: string;
820
914
  readonly candidate: unknown;
package/dist/workflow.js CHANGED
@@ -2,7 +2,7 @@ import { observerSnapshot } from "./observer-snapshot.js";
2
2
  import { createHash } from "node:crypto";
3
3
  import { isDeepStrictEqual, types as utilTypes } from "node:util";
4
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";
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);
@@ -844,6 +846,58 @@ export function validateWorkflow(workflow, opts) {
844
846
  return checkPredicate(pred.of, label, path, `${field}.of`, "not");
845
847
  return true;
846
848
  };
849
+ /** A node's step guard (StepGuard), field by field, in words an author can act on: where it may sit, its signal (and
850
+ * whether the node reports the confidence `self` reads), its threshold, its question and its fit. */
851
+ const checkGuard = (node, path) => {
852
+ if (node.guard === undefined)
853
+ return;
854
+ const at = `${path} (${node.label || node.node}): guard`;
855
+ const bad = (message) => fail("NODE_FIELD_INVALID", ptrOf(path), `${at}${message}`);
856
+ if (!GUARDED_NODE_KINDS.includes(node.node)) {
857
+ 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`);
858
+ return;
859
+ }
860
+ const guard = node.guard;
861
+ if (!guard || typeof guard !== "object" || Array.isArray(guard)) {
862
+ bad(` must be an object: {"signal": "self" | "jev" | "both", "threshold": a number between 0 and 1, "question"?: text, "fit"?: {...}}`);
863
+ return;
864
+ }
865
+ const extra = Object.keys(guard).filter((key) => !GUARD_FIELDS.includes(key));
866
+ if (extra.length)
867
+ bad(`: unknown key(s) ${extra.join(", ")}; a guard takes ${GUARD_FIELDS.join(", ")}`);
868
+ const signal = guard.signal;
869
+ const known = GUARD_SIGNALS.includes(signal);
870
+ if (!known)
871
+ bad(`.signal must be "self", "jev" or "both" (got ${JSON.stringify(signal) ?? "none"})`);
872
+ else if (signal !== "jev" && !SELF_CONFIDENCE_KINDS.includes(node.node))
873
+ 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"`);
874
+ else if (signal !== "jev" && (node.node === "agent" || node.node === "decide") && typeof node.out === "string" && Object.hasOwn(workflow.schemas ?? {}, node.out)) {
875
+ const out = resolveSchemaForWorkflow(workflow, workflow.schemas[node.out]);
876
+ if (!confidenceChannelOf(out))
877
+ bad(`.signal "${signal}" has the node submit its confidence beside its record, so its out schema "${node.out}" must be an object schema`);
878
+ }
879
+ const threshold = guard.threshold;
880
+ if (!(typeof threshold === "number" && Number.isFinite(threshold) && threshold > 0 && threshold < 1))
881
+ 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"})`);
882
+ if (guard.question !== undefined) {
883
+ if (typeof guard.question !== "string" || !guard.question.trim())
884
+ bad(`.question must be non-empty text: the yes/no question Jev is asked about the step's input and output`);
885
+ else if (signal === "self")
886
+ bad(`.question is Jev's; a "self" guard asks Jev nothing. Use "jev" or "both", or leave question out`);
887
+ else if (guard.question.length > GUARD_QUESTION_MAX)
888
+ bad(`.question is ${guard.question.length} characters; at most ${GUARD_QUESTION_MAX}`);
889
+ }
890
+ if (guard.fit !== undefined) {
891
+ const fit = guard.fit;
892
+ const width = signal === "both" ? 2 : 1;
893
+ const finite = (n) => typeof n === "number" && Number.isFinite(n);
894
+ const ok = fit && typeof fit === "object" && !Array.isArray(fit) && Array.isArray(fit.w) && fit.w.length === width && fit.w.every(finite) && finite(fit.b)
895
+ && Number.isSafeInteger(fit.n) && fit.n >= 1 && typeof fit.fitted_at === "string" && !Number.isNaN(Date.parse(fit.fitted_at))
896
+ && Object.keys(fit).every((key) => ["w", "b", "n", "fitted_at"].includes(key));
897
+ if (!ok)
898
+ 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}`);
899
+ }
900
+ };
847
901
  const walk = (node, path, ptr) => {
848
902
  // A node that is missing (a map or loop without a body) is reported on the node that should hold it.
849
903
  pointers.set(path, node === undefined ? ptr.slice(0, ptr.lastIndexOf("/")) : ptr);
@@ -853,9 +907,11 @@ export function validateWorkflow(workflow, opts) {
853
907
  }
854
908
  {
855
909
  const allowed = KIND_KEYS[node.node];
856
- const extraneous = Object.keys(node).filter((key) => !allowed.has(key));
910
+ // A guard is checked on its own (checkGuard), with its own words where it may not sit.
911
+ const extraneous = Object.keys(node).filter((key) => !allowed.has(key) && key !== "guard");
857
912
  if (extraneous.length)
858
913
  fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${node.label || node.node}): unknown key(s) for a ${node.node} node: ${extraneous.join(", ")}`);
914
+ checkGuard(node, path);
859
915
  // State keys that hold a `$` are engine-owned (`$host`, and a typed question's `<as>$answers` and `<as>$verify`): no node
860
916
  // 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
917
  if (typeof node.as === "string" && holdsDollar(node.as))
@@ -2400,6 +2456,14 @@ async function runJudgeNode(node, state, workflow, deps) {
2400
2456
  deps.onEvent?.({ type: "judge.answered", label: node.label, detail: { kind: "judge", as: node.as, value, sidecar, ...meteringOf(decided), decision_id: decided.id } });
2401
2457
  return { ...state, [node.as]: value, [`${node.as}$answers`]: sidecar };
2402
2458
  }
2459
+ /** What a pick's judge is asked about `items`: each candidate described (`item_<i>`), beside its interpolated `state` (else
2460
+ * the workflow's state as context). Its guard is asked about the same (guardInputOf). */
2461
+ function pickAskOf(node, state, items, workflow) {
2462
+ const options = Object.fromEntries(items.map((item, i) => [`item_${i}`, describeItem(node.describe, state, item, i) || `item ${i}`]));
2463
+ return { options, asked: { ...(node.state ? interpolateValue(node.state, state, node.label) : { context: promptStateOf(state, workflow) }), candidates: options } };
2464
+ }
2465
+ /** The items a sift's judge is asked about, by id (`item_<i>`), each with its description when the sift has one. */
2466
+ const siftItemsOf = (node, state, items) => items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
2403
2467
  async function runPickNode(node, state, deps, workflow) {
2404
2468
  assertNodeInputs(node, state);
2405
2469
  const items = getPath(state, node.itemsPath);
@@ -2417,9 +2481,8 @@ async function runPickNode(node, state, deps, workflow) {
2417
2481
  const capacity = SYSTEM_ONE_LIMITS.maxChoiceOptions - (node.allowNone ? 1 : 0);
2418
2482
  if (items.length > capacity)
2419
2483
  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}`]));
2484
+ const { options, asked } = pickAskOf(node, state, items, workflow);
2421
2485
  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
2486
  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
2487
  const a = answers.pick;
2425
2488
  if (!a || a.type !== "choice")
@@ -2452,7 +2515,7 @@ async function runSiftNode(node, state, workflow, deps) {
2452
2515
  if (items.length) {
2453
2516
  const base = node.state ? interpolateValue(node.state, state, node.label) : {};
2454
2517
  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 }));
2518
+ const named = siftItemsOf(node, state, items);
2456
2519
  const chunks = siftChunks(deps, node.label, ids.length, base, named);
2457
2520
  const measure = keepTail === "confidence" ? "confidence" : "value";
2458
2521
  // The keep rule, as applied and as a receipt states it: the author's threshold, else 0.5 for a yes/no
@@ -2674,6 +2737,8 @@ function scopeDepsToChild(deps, invocation) {
2674
2737
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2675
2738
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
2676
2739
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2740
+ ...(deps.guardStep ? { guardStep: params => deps.guardStep({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2741
+ ...(deps.softEscalate ? { softEscalate: label => deps.softEscalate(`${prefix}/${label}`) } : {}),
2677
2742
  ...(deps.recordDecision ? { recordDecision: (receipt, exchange) => deps.recordDecision({ ...receipt, node: `${prefix}/${receipt.node}` }, { ...exchange, request: { ...exchange.request, label: `${prefix}/${exchange.request.label}` } }) } : {}),
2678
2743
  ...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
2679
2744
  ...(recovery ? { recovery: {
@@ -2691,6 +2756,197 @@ function scopeDepsToChild(deps, invocation) {
2691
2756
  };
2692
2757
  }
2693
2758
  const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
2759
+ /** A node's step guard, as the document holds it (validateWorkflow refused any other shape). */
2760
+ export function stepGuardOf(node) {
2761
+ const guard = node.guard;
2762
+ return guard && typeof guard === "object" && !Array.isArray(guard) ? guard : undefined;
2763
+ }
2764
+ /** Whether a guard reads the step's own confidence. */
2765
+ const readsSelf = (guard) => guard.signal === "self" || guard.signal === "both";
2766
+ /** The field an agent or decide node whose guard reads `self` submits its confidence in, beside its record. */
2767
+ export const SELF_CONFIDENCE_FIELD = "confidence";
2768
+ /** What the model is told the field holds. */
2769
+ 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.";
2770
+ /** The engine-owned state key an agent or decide node's own confidence lands under, beside its value: `<key>$confidence`. */
2771
+ export const confidenceKey = (key) => `${key}$confidence`;
2772
+ /** The state key a step writes its value under: its `as`, or an unaliased agent, decide, extract or code node's label. */
2773
+ const writeKeyOf = (node) => {
2774
+ const { as, label } = node;
2775
+ if (typeof as === "string" && as)
2776
+ return as;
2777
+ return ["agent", "decide", "extract", "code"].includes(node.node) && typeof label === "string" ? label : undefined;
2778
+ };
2779
+ /** An object out schema the confidence field can sit beside, widened with it (required), or as it is when it declares the
2780
+ * field itself (then the node's own field is its confidence, kept in its value); undefined for a schema that is no object. */
2781
+ function confidenceChannelOf(schema) {
2782
+ const properties = schema.properties;
2783
+ if (schema.type !== "object" && (!properties || typeof properties !== "object"))
2784
+ return undefined;
2785
+ if (declaresConfidence(schema))
2786
+ return { schema, declared: true };
2787
+ const field = { type: "number", minimum: 0, maximum: 1, description: SELF_CONFIDENCE_WORDS };
2788
+ const required = Array.isArray(schema.required) ? schema.required : [];
2789
+ const widened = withConfidenceInMembers(schema, field);
2790
+ return {
2791
+ schema: { ...widened, properties: { ...(properties ?? {}), [SELF_CONFIDENCE_FIELD]: field }, required: [...required, SELF_CONFIDENCE_FIELD] },
2792
+ declared: false,
2793
+ };
2794
+ }
2795
+ const COMPOSED = ["allOf", "anyOf", "oneOf"];
2796
+ const membersOf = (schema) => COMPOSED.flatMap((key) => (Array.isArray(schema[key]) ? schema[key] : [])).filter((m) => Boolean(m) && typeof m === "object" && !Array.isArray(m));
2797
+ /** Whether the schema, or a member of its allOf / anyOf / oneOf (at any depth), declares the confidence field itself. */
2798
+ function declaresConfidence(schema) {
2799
+ const properties = schema.properties;
2800
+ if (properties && typeof properties === "object" && Object.hasOwn(properties, SELF_CONFIDENCE_FIELD))
2801
+ return true;
2802
+ return membersOf(schema).some(declaresConfidence);
2803
+ }
2804
+ /** The schema with the confidence field allowed in every allOf / anyOf / oneOf member (at any depth): a member that is
2805
+ * closed (`additionalProperties` or `unevaluatedProperties` other than true) would otherwise refuse the field the root
2806
+ * requires, and every submission with it. The field is never required in a member; the root requires it. */
2807
+ function withConfidenceInMembers(schema, field) {
2808
+ let out = schema;
2809
+ for (const key of COMPOSED) {
2810
+ const members = schema[key];
2811
+ if (!Array.isArray(members))
2812
+ continue;
2813
+ out = { ...out, [key]: members.map((member) => {
2814
+ if (!member || typeof member !== "object" || Array.isArray(member))
2815
+ return member;
2816
+ const inner = withConfidenceInMembers(member, field);
2817
+ const own = inner.properties && typeof inner.properties === "object" ? inner.properties : {};
2818
+ return { ...inner, properties: { ...own, [SELF_CONFIDENCE_FIELD]: field } };
2819
+ }) };
2820
+ }
2821
+ return out;
2822
+ }
2823
+ /** A confidence as a guard reads it: a number in [0, 1], else none. */
2824
+ const confidenceOf = (value) => (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1 ? value : null);
2825
+ /** The step's own confidence from its state once it ran: an agent or decide node's `<key>$confidence`, a judge or pick
2826
+ * node's weakest answer's (`<as>$answers.min_confidence`), a sift's weakest over every item's answers (`<as>.answers[i]`,
2827
+ * none when it was asked about no item, or one item's is missing). */
2828
+ function selfConfidenceOf(node, out) {
2829
+ const key = writeKeyOf(node);
2830
+ if (!key)
2831
+ return null;
2832
+ if (node.node === "agent" || node.node === "decide")
2833
+ return confidenceOf(out[confidenceKey(key)]);
2834
+ if (node.node === "sift") {
2835
+ const answers = out[key]?.answers;
2836
+ if (!Array.isArray(answers) || !answers.length)
2837
+ return null;
2838
+ // A loop, not Math.min(...each): a sift may hold more items than a call takes arguments.
2839
+ let weakest = 1;
2840
+ for (const sidecar of answers) {
2841
+ const confidence = confidenceOf(sidecar?.min_confidence);
2842
+ if (confidence === null)
2843
+ return null;
2844
+ if (confidence < weakest)
2845
+ weakest = confidence;
2846
+ }
2847
+ return weakest;
2848
+ }
2849
+ return confidenceOf(out[`${key}$answers`]?.min_confidence);
2850
+ }
2851
+ /** What a guarded step is asked about, for every node kind in one place: what it was asked to do (guardTaskOf), what it
2852
+ * saw (guardInputOf) and what it wrote (guardOutputOf). */
2853
+ function guardAskOf(node, before, after, workflow) {
2854
+ return { task: guardTaskOf(node, workflow), input: guardInputOf(node, before, workflow), output: guardOutputOf(node, before, after) };
2855
+ }
2856
+ /** What a step was asked to do (GuardTask). The step ran, so its schemas resolve and its questions compile; should one
2857
+ * not, the schema as the document holds it stands in. */
2858
+ function guardTaskOf(node, workflow) {
2859
+ const schemaOf = (id) => {
2860
+ if (typeof id !== "string" || !Object.hasOwn(workflow.schemas, id))
2861
+ return {};
2862
+ try {
2863
+ return { schema: resolveSchemaForWorkflow(workflow, workflow.schemas[id]) };
2864
+ }
2865
+ catch {
2866
+ return { schema: workflow.schemas[id] };
2867
+ }
2868
+ };
2869
+ switch (node.node) {
2870
+ case "agent":
2871
+ case "decide":
2872
+ case "extract": return { instructions: node.instructions, ...schemaOf(node.out) };
2873
+ case "pick": return { instructions: node.instructions, allow_none: node.allowNone === true };
2874
+ case "judge":
2875
+ case "sift":
2876
+ try {
2877
+ return { questions: questionSetOf(workflow, node).questions };
2878
+ }
2879
+ catch {
2880
+ return schemaOf(node.out);
2881
+ }
2882
+ case "code": return { code: node.code };
2883
+ case "call": {
2884
+ const what = node.via === "tool" ? { tool: node.tool } : node.via === "executor" ? { code: node.code } : { command: node.command };
2885
+ return { ...what, ...(node.via === "shell" ? {} : schemaOf(node.out)) };
2886
+ }
2887
+ case "workflow": return { workflow: node.workflow?.name, ...schemaOf(node.out) };
2888
+ default: return {};
2889
+ }
2890
+ }
2891
+ /** What a step saw, as its guard is asked about it: its interpolated `state`, a call's `args` (or an executor's `input`, a
2892
+ * shell's `env`), a child's `input`; a pick's, what its judge chose among (its state, the candidates); a sift's, its
2893
+ * state and the items its judge was asked about; else the workflow's state before it, as a generative node with no
2894
+ * `state` sees it. */
2895
+ function guardInputOf(node, state, workflow) {
2896
+ try {
2897
+ if (node.node === "call")
2898
+ return interpolateValue(node.via === "tool" ? node.args ?? {} : node.via === "executor" ? node.input ?? {} : node.env ?? {}, state, node.label);
2899
+ if (node.node === "workflow")
2900
+ return interpolateValue(node.input, state, node.label);
2901
+ if (node.node === "pick" || node.node === "sift") {
2902
+ const items = getPath(state, node.itemsPath);
2903
+ const list = Array.isArray(items) ? items : [];
2904
+ if (node.node === "pick")
2905
+ return pickAskOf(node, state, list, workflow).asked;
2906
+ return { ...(node.state ? interpolateValue(node.state, state, node.label) : {}), items: siftItemsOf(node, state, list) };
2907
+ }
2908
+ const own = node.state;
2909
+ if (own && typeof own === "object")
2910
+ return interpolateValue(own, state, node.label);
2911
+ }
2912
+ catch { /* The step ran on it, so it resolves; should it not, the state it ran on stands in. */ }
2913
+ return promptStateOf(state, workflow);
2914
+ }
2915
+ /** What a code node returned, by the state it produced: a code node with no `as` merges an object it returns, so its
2916
+ * write key alone cannot say what it wrote. */
2917
+ const codeWrote = new WeakMap();
2918
+ /** What a step wrote, even when it equals what was there before: what a code node returned, else the value under its
2919
+ * write key, else the keys it changed (none engine-owned). */
2920
+ function guardOutputOf(node, before, after) {
2921
+ const returned = node.node === "code" ? codeWrote.get(after) : undefined;
2922
+ if (returned)
2923
+ return returned.value;
2924
+ const key = writeKeyOf(node);
2925
+ if (key && Object.hasOwn(after, key))
2926
+ return after[key];
2927
+ return Object.fromEntries(Object.entries(after).filter(([name, value]) => !holdsDollar(name) && before[name] !== value));
2928
+ }
2929
+ /** 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)
2930
+ * hands the job back, an escalation of kind `guard` at the step, with the state it reached. Every check is an event
2931
+ * (`guard.evaluated`: signal, threshold, p, self, jev, escalated). */
2932
+ async function checkStepGuard(node, guard, before, after, workflow, deps) {
2933
+ const label = node.label;
2934
+ if (!deps.guardStep)
2935
+ throw new Error(`${node.node} node "${label}" requires guardStep`);
2936
+ const self = readsSelf(guard) ? selfConfidenceOf(node, after) : null;
2937
+ const item = deps[MAP_ITEM];
2938
+ 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 } : {}) });
2939
+ const p = typeof verdict?.p === "number" && Number.isFinite(verdict.p) ? Math.min(1, Math.max(0, verdict.p)) : null;
2940
+ const jev = typeof verdict?.jev === "number" && Number.isFinite(verdict.jev) ? verdict.jev : null;
2941
+ // No p is no evidence the step is right: it hands back, never passes.
2942
+ const escalated = p === null || p < guard.threshold;
2943
+ deps.onEvent?.({ type: "guard.evaluated", label, detail: { kind: node.node, signal: guard.signal, threshold: guard.threshold, p, self, jev, escalated } });
2944
+ if (!escalated)
2945
+ return;
2946
+ const said = (n) => (n === null ? "none" : n.toFixed(2));
2947
+ 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)}`;
2948
+ 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) });
2949
+ }
2694
2950
  const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
2695
2951
  const guardedObservers = new WeakSet();
2696
2952
  function forwardObserver(observer, transform) {
@@ -2748,6 +3004,10 @@ async function runNodeOnState(node, state, workflow, deps) {
2748
3004
  let out = await runNodeBody(node, state, workflow, deps);
2749
3005
  if (deps.signal?.aborted)
2750
3006
  throw deps.signal.reason ?? new Error("workflow aborted");
3007
+ // A guarded step's check, before anything of it is committed: one that hands back is never resumed as done.
3008
+ const guard = isStep ? stepGuardOf(node) : undefined;
3009
+ if (guard)
3010
+ await checkStepGuard(node, guard, state, out, workflow, deps);
2751
3011
  // Host policy enrichment lands before commit and checkpoint: a resumed run sees exactly what ran.
2752
3012
  if (isStep && deps.hostPolicy?.afterNode) {
2753
3013
  const patch = deps.hostPolicy.afterNode({ ...hostContext(workflow, node, deps), state: out });
@@ -2838,7 +3098,9 @@ async function runNodeBody(node, state, workflow, deps) {
2838
3098
  if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
2839
3099
  throw new WorkflowStateError(`code node "${node.label}" wrote the reserved "${HOST_STATE_KEY}" state key`, node.label, HOST_STATE_KEY, "reserved_state_key");
2840
3100
  deps.onEvent?.({ type: "code.patch", label: node.label, detail: patch });
2841
- return { ...state, ...patch };
3101
+ const next = { ...state, ...patch };
3102
+ codeWrote.set(next, { value: out });
3103
+ return next;
2842
3104
  }
2843
3105
  case "agent":
2844
3106
  case "decide":
@@ -2857,14 +3119,28 @@ async function runNodeBody(node, state, workflow, deps) {
2857
3119
  // channels); the decoded domain value is what the stage schema, the verifier and the state see.
2858
3120
  const policy = deps.hostPolicy;
2859
3121
  const context = policy ? hostContext(workflow, node, deps) : null;
2860
- const transportSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
3122
+ const hostSchema = policy?.submissionSchema && context ? policy.submissionSchema(schema, context) : schema;
3123
+ // A guard that reads the node's own confidence (agent, decide): the node submits it beside its record, in the field
3124
+ // SELF_CONFIDENCE_FIELD, split off before the stage schema sees the value (unless the stage schema declares it), and
3125
+ // kept at `<key>$confidence`.
3126
+ const guard = node.node === "agent" || node.node === "decide" ? stepGuardOf(node) : undefined;
3127
+ const channel = guard && readsSelf(guard) ? confidenceChannelOf(hostSchema) : undefined;
3128
+ const transportSchema = channel ? channel.schema : hostSchema;
2861
3129
  const transportValidator = transportSchema === schema ? validator : Compile(transportSchema);
2862
3130
  const stageName = node.node === "report" ? "report" : node.out;
3131
+ let confidence = null;
2863
3132
  const decode = (raw) => {
2864
3133
  normalizeStringNullsForSchema(raw, transportSchema);
2865
3134
  if (!transportValidator.Check(raw)) {
2866
3135
  throw new WorkflowOutputInvalidError(`${node.node} node "${node.label}" submission does not satisfy schema "${stageName}"`, schemaProblems(transportValidator, raw), node.label);
2867
3136
  }
3137
+ if (channel && raw && typeof raw === "object" && !Array.isArray(raw)) {
3138
+ confidence = confidenceOf(raw[SELF_CONFIDENCE_FIELD]);
3139
+ if (!channel.declared) {
3140
+ const { [SELF_CONFIDENCE_FIELD]: _confidence, ...rest } = raw;
3141
+ raw = rest;
3142
+ }
3143
+ }
2868
3144
  const decoded = policy?.decodeSubmission && context ? policy.decodeSubmission(raw, { ...context, host: hostStateOf(state) }) : { value: raw };
2869
3145
  if (decoded !== null && typeof decoded === "object" && decoded.value !== raw)
2870
3146
  normalizeStringNullsForSchema(decoded.value, schema);
@@ -2912,6 +3188,8 @@ async function runNodeBody(node, state, workflow, deps) {
2912
3188
  let merged = mergeStageDelta(state, node, verified ? verified.submission : result, stageSchema);
2913
3189
  if (verified)
2914
3190
  merged = { ...merged, [`${("as" in node && node.as) || node.label}$verify`]: verified.record };
3191
+ if (channel)
3192
+ merged = { ...merged, [confidenceKey(writeKeyOf(node))]: confidence };
2915
3193
  const hostState = decoded.host && typeof decoded.host === "object" && !Array.isArray(decoded.host) ? decoded.host : null;
2916
3194
  if (hostState && Object.keys(hostState).length) {
2917
3195
  deps.onEvent?.({ type: "host.decoded", label: node.label, detail: { keys: Object.keys(hostState) } });
@@ -3161,8 +3439,9 @@ async function runNodeBody(node, state, workflow, deps) {
3161
3439
  const pathValue = node.when?.path
3162
3440
  ? String(node.when.path).split(".").reduce((acc, key) => (acc == null ? acc : acc[key]), state)
3163
3441
  : 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) {
3442
+ const soft = deps.softEscalate?.(node.label) === true;
3443
+ deps.onEvent?.({ type: "escalate.evaluated", label: node.label, detail: { fired, path: node.when?.path ?? null, path_resolved: pathValue !== undefined, ...(evaluated.detail ?? {}), ...(soft ? { soft: true } : {}) } });
3444
+ if (fired && !soft) {
3166
3445
  throw new EscalationSignal({ kind: node.kind, stage: node.stage, summary: interpolate(node.summary, state), state, label: node.label, executionPath: executionPath(deps) });
3167
3446
  }
3168
3447
  return state;
@@ -3300,6 +3579,11 @@ function checkDecisionProviders(node, deps, workflow) {
3300
3579
  asked.push({ choice: node, types: ["choice"], count: 1, what: `pick node "${label}"` });
3301
3580
  if (node.node === "route" && !routesByValue(node))
3302
3581
  asked.push({ choice: node, types: ["choice"], count: 1, what: `route node "${label}"` });
3582
+ // A node's `verify` is asked of the host's default decision provider (no provider of its own): a host without it refuses the node.
3583
+ if ("verify" in node && node.verify) {
3584
+ const types = questionsOf(node.verify.out);
3585
+ asked.push({ choice: {}, types, count: types.length, what: `${node.node} node "${label}" (verify)` });
3586
+ }
3303
3587
  for (const pred of [node.node === "loop" ? node.until : undefined, node.node === "escalate" ? node.when : undefined]) {
3304
3588
  if (pred?.predicate === "ask")
3305
3589
  asked.push({ choice: pred, types: ["noul"], count: 1, what: `${node.node} node "${label}" (ask predicate)` });
@@ -3352,6 +3636,8 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
3352
3636
  node.node === "loop" && node.until?.predicate === "ask" ||
3353
3637
  node.node === "escalate" && node.when?.predicate === "ask") && !deps.runJudge)
3354
3638
  missing("runJudge");
3639
+ if (stepGuardOf(node) && !deps.guardStep)
3640
+ missing("guardStep");
3355
3641
  checkDecisionProviders(node, deps, workflow);
3356
3642
  // A store that cannot commit an item's failure would run the item again in the next process.
3357
3643
  if (node.node === "map" && node.onItemFailure === "collect" && deps.recovery && !(deps.recovery.failItem && deps.recovery.itemFailure))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.36",
3
+ "version": "0.1.0-beta.38",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",