@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.
@@ -37,6 +37,47 @@ function hasType(value, type) {
37
37
  throw new Error(`agentrun: unsupported field_type type "${String(type)}" — fail closed, never silently false`);
38
38
  }
39
39
  }
40
+ /** A quote shorter than this, normalised, is not checked: too short to say which page it came from. */
41
+ export const QUOTE_MIN_CHARS = 8;
42
+ const QUOTE_MARKS = { "‘": "'", "’": "'", "“": "\"", "”": "\"", "–": "-", "—": "-" };
43
+ /** A quote or a page as quote_missing compares them: lowercase, curly quotes straight, en and em dashes "-", each run of
44
+ * whitespace one space, trimmed. */
45
+ export const quoteText = (text) => text.toLowerCase().replace(/[‘’“”–—]/g, (mark) => QUOTE_MARKS[mark]).replace(/\s+/g, " ").trim();
46
+ /** The looser reading: the letters and digits of `text` alone, each run joined by one space. */
47
+ const quoteTokens = (text) => (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []).join(" ");
48
+ /** How deep under a page path strings are read: past it a value is no page. */
49
+ const PAGE_DEPTH = 64;
50
+ function pageStrings(value, out, depth = 0) {
51
+ if (typeof value === "string")
52
+ out.push(value);
53
+ else if (depth < PAGE_DEPTH && value !== null && typeof value === "object")
54
+ for (const inner of Array.isArray(value) ? value : Object.values(value))
55
+ pageStrings(inner, out, depth + 1);
56
+ }
57
+ function quotesAt(value, field) {
58
+ if (field === undefined)
59
+ return typeof value === "string" ? [value] : Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
60
+ const records = Array.isArray(value) ? value : isRecord(value) ? [value] : [];
61
+ return records.map((record) => getPath(record, field)).filter((quote) => typeof quote === "string");
62
+ }
63
+ /** quote_missing's reading of `value`: how many quotes it checked (each at least QUOTE_MIN_CHARS once normalised) and how
64
+ * many of them are in no page. A quote is found when its normalised text is in one page string's (each string under the
65
+ * pages read alone, so no quote runs from one into the next), or when its letters and digits are in that string's; the
66
+ * pages are only what `value` holds, the run's own state. Counts alone: no quote or page text leaves here. */
67
+ export function quoteCheck(predicate, value) {
68
+ const quotes = quotesAt(getPath(value, predicate.path), predicate.field).map(quoteText).filter((quote) => quote.length >= QUOTE_MIN_CHARS);
69
+ if (!quotes.length)
70
+ return { checked: 0, missed: 0 };
71
+ const strings = [];
72
+ for (const page of predicate.pages)
73
+ pageStrings(getPath(value, page), strings);
74
+ const texts = strings.map((string) => { const text = quoteText(string); return { text, tokens: quoteTokens(text) }; });
75
+ const missed = quotes.filter((quote) => {
76
+ const loose = quoteTokens(quote);
77
+ return !texts.some(({ text, tokens }) => text.includes(quote) || (loose !== "" && tokens.includes(loose)));
78
+ }).length;
79
+ return { checked: quotes.length, missed };
80
+ }
40
81
  export function predicateMatches(predicate, value) {
41
82
  switch (predicate.predicate) {
42
83
  case "field_equals":
@@ -69,6 +110,8 @@ export function predicateMatches(predicate, value) {
69
110
  }
70
111
  case "field_type":
71
112
  return hasType(getPath(value, predicate.path), predicate.type);
113
+ case "quote_missing":
114
+ return quoteCheck(predicate, value).missed > 0;
72
115
  case "not":
73
116
  // A judged `of` reaches the default case below and throws: validation refuses it first.
74
117
  return !predicateMatches(predicate.of, value);
@@ -9,6 +9,18 @@ export declare const DECISION_NODE_FIELDS: readonly ["provider", "model", "evide
9
9
  export declare const DECISION_TIMEOUT_MAX_MS = 120000;
10
10
  /** Typed-question kinds: one judge request each, no tools and no session. */
11
11
  export declare const JUDGMENT_NODE_KINDS: readonly ["judge", "pick", "sift", "route"];
12
+ /** A step guard's signals: `self`, the step's own confidence; `jev`, one Jev question over the step's input and output;
13
+ * `both`, the two combined. */
14
+ export declare const GUARD_SIGNALS: readonly ["self", "jev", "both"];
15
+ export type GuardSignal = typeof GUARD_SIGNALS[number];
16
+ /** The fields a step guard takes. */
17
+ export declare const GUARD_FIELDS: readonly ["signal", "threshold", "question", "fit"];
18
+ /** The kinds a guard may sit on: the steps that write a value. */
19
+ export declare const GUARDED_NODE_KINDS: readonly ["agent", "decide", "extract", "code", "call", "workflow", "judge", "pick", "sift"];
20
+ /** The kinds that report a confidence of their own, so a guard on one may read `self`: agent and decide nodes submit one
21
+ * beside their record, judge, pick and sift nodes take their answers' weakest. The others (extract, code, call,
22
+ * workflow) have none: their guard reads jev only. */
23
+ export declare const SELF_CONFIDENCE_KINDS: readonly ["agent", "decide", "judge", "pick", "sift"];
12
24
  /** The fields each node kind accepts. Any other key is an authoring error. */
13
25
  export declare const NODE_FIELDS: {
14
26
  readonly [Kind in WorkflowNodeKind]: readonly string[];
@@ -21,9 +33,9 @@ export declare const IGNORED_NODE_FIELDS: {
21
33
  readonly [Kind in WorkflowNodeKind]?: readonly string[];
22
34
  };
23
35
  /** Predicates that read a state value. `poll` accepts only these, and `not` holds only one of these. */
24
- export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not"];
36
+ export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "quote_missing", "not"];
25
37
  /** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
26
- export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not", "ask"];
38
+ export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "quote_missing", "not", "ask"];
27
39
  export type WorkflowPredicateName = typeof WORKFLOW_PREDICATES[number];
28
40
  /** The fields each predicate takes. */
29
41
  export declare const PREDICATE_FIELDS: {
@@ -13,11 +13,22 @@ export const DECISION_NODE_FIELDS = ["provider", "model", "evidence", "timeoutMs
13
13
  export const DECISION_TIMEOUT_MAX_MS = 120_000;
14
14
  /** Typed-question kinds: one judge request each, no tools and no session. */
15
15
  export const JUDGMENT_NODE_KINDS = ["judge", "pick", "sift", "route"];
16
- const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"];
16
+ const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier", "guard"];
17
+ /** A step guard's signals: `self`, the step's own confidence; `jev`, one Jev question over the step's input and output;
18
+ * `both`, the two combined. */
19
+ export const GUARD_SIGNALS = ["self", "jev", "both"];
20
+ /** The fields a step guard takes. */
21
+ export const GUARD_FIELDS = ["signal", "threshold", "question", "fit"];
22
+ /** The kinds a guard may sit on: the steps that write a value. */
23
+ export const GUARDED_NODE_KINDS = ["agent", "decide", "extract", "code", "call", "workflow", "judge", "pick", "sift"];
24
+ /** The kinds that report a confidence of their own, so a guard on one may read `self`: agent and decide nodes submit one
25
+ * beside their record, judge, pick and sift nodes take their answers' weakest. The others (extract, code, call,
26
+ * workflow) have none: their guard reads jev only. */
27
+ export const SELF_CONFIDENCE_KINDS = ["agent", "decide", "judge", "pick", "sift"];
17
28
  /** The fields each node kind accepts. Any other key is an authoring error. */
18
29
  export const NODE_FIELDS = {
19
30
  chain: ["node", "steps"],
20
- code: ["node", "label", "code", "as"],
31
+ code: ["node", "label", "code", "as", "guard"],
21
32
  agent: [...GENERATIVE_FIELDS, "budget_usd", "max_turns", "context"],
22
33
  decide: GENERATIVE_FIELDS,
23
34
  extract: GENERATIVE_FIELDS,
@@ -27,11 +38,11 @@ export const NODE_FIELDS = {
27
38
  parallel: ["node", "label", "branches"],
28
39
  loop: ["node", "label", "body", "until", "maxIters", "expect_iters"],
29
40
  escalate: ["node", "label", "when", "kind", "stage", "summary"],
30
- call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires"],
31
- workflow: ["node", "label", "workflow", "input", "out", "as"],
32
- judge: ["node", "label", "state", "out", "as", "requires", ...DECISION_NODE_FIELDS],
33
- pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires", ...DECISION_NODE_FIELDS],
34
- sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires", ...DECISION_NODE_FIELDS],
41
+ call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires", "guard"],
42
+ workflow: ["node", "label", "workflow", "input", "out", "as", "guard"],
43
+ judge: ["node", "label", "state", "out", "as", "requires", ...DECISION_NODE_FIELDS, "guard"],
44
+ pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires", ...DECISION_NODE_FIELDS, "guard"],
45
+ sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires", ...DECISION_NODE_FIELDS, "guard"],
35
46
  route: ["node", "label", "state", "instructions", "branches", "unsure", "valuePath", "otherwise", "as", "requires", ...DECISION_NODE_FIELDS],
36
47
  };
37
48
  /** Fields every node kind accepts in addition to its own. `metadata` is the host's: an optional object of
@@ -43,7 +54,7 @@ export const IGNORED_NODE_FIELDS = {
43
54
  decide: ["samples", "voteField"],
44
55
  };
45
56
  /** Predicates that read a state value. `poll` accepts only these, and `not` holds only one of these. */
46
- export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "not"];
57
+ export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "field_type", "quote_missing", "not"];
47
58
  /** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
48
59
  export const WORKFLOW_PREDICATES = [...MECHANICAL_PREDICATES, "ask"];
49
60
  /** The fields each predicate takes. */
@@ -57,6 +68,7 @@ export const PREDICATE_FIELDS = {
57
68
  empty: ["path"],
58
69
  no_new_items: ["key"],
59
70
  field_type: ["path", "type"],
71
+ quote_missing: ["path", "field", "pages"],
60
72
  not: ["of"],
61
73
  ask: ["instructions", "state", "criteria", "gte", ...DECISION_NODE_FIELDS],
62
74
  };
@@ -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,21 @@ 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;
912
+ /** The escalate nodes of a workflow document that read a judge's output, by label as a run names its step (a child's
913
+ * `parent/child`, as WorkflowDeps.softEscalate is asked): each whose `when` (under any number of `not`s) reads a field a
914
+ * 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
915
+ * escalate (a judge an extract overwrites, one in only some of a route's branches, one a code node with no `as` may have
916
+ * overwritten, are not). A judge's field is one model's opinion of a draft the workflow already wrote, so a host that
917
+ * measures the check may record it instead of obeying it (WorkflowDeps.softEscalate) and read the draft past it. A
918
+ * document too deep to walk, or whose loop's writes do not settle, has none. The document is read as it is: no
919
+ * validation, and a malformed node writes nothing it cannot name. */
920
+ export declare function softEscalates(doc: unknown): Set<string>;
818
921
  export declare class WorkflowVerificationError extends Error {
819
922
  readonly stage: string;
820
923
  readonly candidate: unknown;