@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.37",
3
+ "version": "0.1.0-beta.39",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -51,6 +51,12 @@
51
51
  "type": "string",
52
52
  "title": "as"
53
53
  },
54
+ "guard": {
55
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
56
+ "type": "object",
57
+ "additionalProperties": {},
58
+ "title": "guard"
59
+ },
54
60
  "metadata": {
55
61
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
56
62
  "type": "object",
@@ -205,6 +211,12 @@
205
211
  "type": "string",
206
212
  "title": "context"
207
213
  },
214
+ "guard": {
215
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
216
+ "type": "object",
217
+ "additionalProperties": {},
218
+ "title": "guard"
219
+ },
208
220
  "metadata": {
209
221
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
210
222
  "type": "object",
@@ -339,6 +351,12 @@
339
351
  "type": "string",
340
352
  "title": "tier"
341
353
  },
354
+ "guard": {
355
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
356
+ "type": "object",
357
+ "additionalProperties": {},
358
+ "title": "guard"
359
+ },
342
360
  "metadata": {
343
361
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
344
362
  "type": "object",
@@ -473,6 +491,12 @@
473
491
  "type": "string",
474
492
  "title": "tier"
475
493
  },
494
+ "guard": {
495
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
496
+ "type": "object",
497
+ "additionalProperties": {},
498
+ "title": "guard"
499
+ },
476
500
  "metadata": {
477
501
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
478
502
  "type": "object",
@@ -900,6 +924,12 @@
900
924
  "$ref": "#/definitions/DecisionImages",
901
925
  "title": "images"
902
926
  },
927
+ "guard": {
928
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
929
+ "type": "object",
930
+ "additionalProperties": {},
931
+ "title": "guard"
932
+ },
903
933
  "metadata": {
904
934
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
905
935
  "type": "object",
@@ -986,6 +1016,12 @@
986
1016
  "$ref": "#/definitions/DecisionImages",
987
1017
  "title": "images"
988
1018
  },
1019
+ "guard": {
1020
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
1021
+ "type": "object",
1022
+ "additionalProperties": {},
1023
+ "title": "guard"
1024
+ },
989
1025
  "metadata": {
990
1026
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
991
1027
  "type": "object",
@@ -1086,6 +1122,12 @@
1086
1122
  "$ref": "#/definitions/DecisionImages",
1087
1123
  "title": "images"
1088
1124
  },
1125
+ "guard": {
1126
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
1127
+ "type": "object",
1128
+ "additionalProperties": {},
1129
+ "title": "guard"
1130
+ },
1089
1131
  "metadata": {
1090
1132
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
1091
1133
  "type": "object",
@@ -1647,6 +1689,37 @@
1647
1689
  "type"
1648
1690
  ]
1649
1691
  },
1692
+ {
1693
+ "description": "Holds when a quote at `path` is in none of the page text at `pages`. `path` names a quote (a string) or a list of them;\nwith `field`, a list (or one record) of records, each holding its quote at `field`. Each of `pages` names a state value\nthis run wrote, a call's result most often: every string under it is page text.",
1694
+ "type": "object",
1695
+ "properties": {
1696
+ "predicate": {
1697
+ "type": "string",
1698
+ "const": "quote_missing",
1699
+ "title": "predicate"
1700
+ },
1701
+ "path": {
1702
+ "type": "string",
1703
+ "title": "path"
1704
+ },
1705
+ "field": {
1706
+ "type": "string",
1707
+ "title": "field"
1708
+ },
1709
+ "pages": {
1710
+ "type": "array",
1711
+ "items": {
1712
+ "type": "string"
1713
+ },
1714
+ "title": "pages"
1715
+ }
1716
+ },
1717
+ "required": [
1718
+ "pages",
1719
+ "path",
1720
+ "predicate"
1721
+ ]
1722
+ },
1650
1723
  {
1651
1724
  "$ref": "#/definitions/NotPredicate",
1652
1725
  "description": "Holds when `of` does not. `of` is mechanical: a judged question never sits inside a negation."
@@ -1677,6 +1750,12 @@
1677
1750
  },
1678
1751
  "title": "requires"
1679
1752
  },
1753
+ "guard": {
1754
+ "description": "A step guard (StepGuard): its signal can only be `jev`, a call reports no confidence.",
1755
+ "type": "object",
1756
+ "additionalProperties": {},
1757
+ "title": "guard"
1758
+ },
1680
1759
  "metadata": {
1681
1760
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
1682
1761
  "type": "object",
@@ -1721,6 +1800,12 @@
1721
1800
  "type": "string",
1722
1801
  "title": "as"
1723
1802
  },
1803
+ "guard": {
1804
+ "description": "A step guard as a document holds it (StepGuard once validateWorkflow accepted it): an object the validator reads field\nby field, so a wrong signal or threshold is refused in words an author can act on, never a schema union's.",
1805
+ "type": "object",
1806
+ "additionalProperties": {},
1807
+ "title": "guard"
1808
+ },
1724
1809
  "metadata": {
1725
1810
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
1726
1811
  "type": "object",
@@ -1949,6 +2034,37 @@
1949
2034
  "type"
1950
2035
  ]
1951
2036
  },
2037
+ {
2038
+ "description": "Holds when a quote at `path` is in none of the page text at `pages`. `path` names a quote (a string) or a list of them;\nwith `field`, a list (or one record) of records, each holding its quote at `field`. Each of `pages` names a state value\nthis run wrote, a call's result most often: every string under it is page text.",
2039
+ "type": "object",
2040
+ "properties": {
2041
+ "predicate": {
2042
+ "type": "string",
2043
+ "const": "quote_missing",
2044
+ "title": "predicate"
2045
+ },
2046
+ "path": {
2047
+ "type": "string",
2048
+ "title": "path"
2049
+ },
2050
+ "field": {
2051
+ "type": "string",
2052
+ "title": "field"
2053
+ },
2054
+ "pages": {
2055
+ "type": "array",
2056
+ "items": {
2057
+ "type": "string"
2058
+ },
2059
+ "title": "pages"
2060
+ }
2061
+ },
2062
+ "required": [
2063
+ "pages",
2064
+ "path",
2065
+ "predicate"
2066
+ ]
2067
+ },
1952
2068
  {
1953
2069
  "$ref": "#/definitions/NotPredicate",
1954
2070
  "description": "Holds when `of` does not. `of` is mechanical: a judged question never sits inside a negation."
@@ -2240,6 +2356,37 @@
2240
2356
  "type"
2241
2357
  ]
2242
2358
  },
2359
+ {
2360
+ "description": "Holds when a quote at `path` is in none of the page text at `pages`. `path` names a quote (a string) or a list of them;\nwith `field`, a list (or one record) of records, each holding its quote at `field`. Each of `pages` names a state value\nthis run wrote, a call's result most often: every string under it is page text.",
2361
+ "type": "object",
2362
+ "properties": {
2363
+ "predicate": {
2364
+ "type": "string",
2365
+ "const": "quote_missing",
2366
+ "title": "predicate"
2367
+ },
2368
+ "path": {
2369
+ "type": "string",
2370
+ "title": "path"
2371
+ },
2372
+ "field": {
2373
+ "type": "string",
2374
+ "title": "field"
2375
+ },
2376
+ "pages": {
2377
+ "type": "array",
2378
+ "items": {
2379
+ "type": "string"
2380
+ },
2381
+ "title": "pages"
2382
+ }
2383
+ },
2384
+ "required": [
2385
+ "pages",
2386
+ "path",
2387
+ "predicate"
2388
+ ]
2389
+ },
2243
2390
  {
2244
2391
  "$ref": "#/definitions/NotPredicate",
2245
2392
  "description": "Holds when `of` does not. `of` is mechanical: a judged question never sits inside a negation."
@@ -19,21 +19,21 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
19
19
 
20
20
  This is the complete set. Each kind accepts exactly these fields; any other field is an error.
21
21
  - `chain`: `steps`
22
- - `code`: `label`, `code`, `as`
23
- - `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `budget_usd`, `max_turns`, `context`
24
- - `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
25
- - `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
22
+ - `code`: `label`, `code`, `as`, `guard`
23
+ - `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `guard`, `budget_usd`, `max_turns`, `context`
24
+ - `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `guard`
25
+ - `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `guard`
26
26
  - `report`: `label`, `state`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
27
27
  - `artifact`: `label`, `state`, `type`, `path`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
28
28
  - `map`: `label`, `itemsPath`, `body`, `as`, `resultPath`, `maxConcurrency`, `onItemFailure`, `failedAs`
29
29
  - `parallel`: `label`, `branches`
30
30
  - `loop`: `label`, `body`, `until`, `maxIters`, `expect_iters`
31
31
  - `escalate`: `label`, `when`, `kind`, `stage`, `summary`
32
- - `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`
33
- - `workflow`: `label`, `workflow`, `input`, `out`, `as`
34
- - `judge`: `label`, `state`, `out`, `as`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`
35
- - `pick`: `label`, `itemsPath`, `describe`, `instructions`, `state`, `allowNone`, `as`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`
36
- - `sift`: `label`, `itemsPath`, `describe`, `state`, `out`, `as`, `keep`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`
32
+ - `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`, `guard`
33
+ - `workflow`: `label`, `workflow`, `input`, `out`, `as`, `guard`
34
+ - `judge`: `label`, `state`, `out`, `as`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`, `guard`
35
+ - `pick`: `label`, `itemsPath`, `describe`, `instructions`, `state`, `allowNone`, `as`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`, `guard`
36
+ - `sift`: `label`, `itemsPath`, `describe`, `state`, `out`, `as`, `keep`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`, `guard`
37
37
  - `route`: `label`, `state`, `instructions`, `branches`, `unsure`, `valuePath`, `otherwise`, `as`, `requires`, `provider`, `model`, `evidence`, `timeoutMs`, `images`
38
38
 
39
39
  Every kind also accepts `metadata`, an object the host owns and the engine never reads; set only the keys the host addendum names.
@@ -92,9 +92,18 @@ Typed questions answered by the host's judge in one request each: no tools, no s
92
92
  - `poll` {until, fail_when?, interval_s: >= 0.1 (a busy-loop guard), deadline_s: at least the call's deadline_s (no maximum)} repeats the call until `until` holds on its own result; `fail_when` fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
93
93
  - Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
94
94
 
95
+ ### Step guards
96
+
97
+ A `guard` on a step (agent, decide, extract, code, call, workflow, judge, pick, sift) checks the step once it ran: below its threshold, the run hands the job back (it escalates, kind `guard`, at the step, with the state it reached), so an uncertain step never answers alone.
98
+ - `guard` is {"signal": self|jev|both, "threshold": a number between 0 and 1 (exclusive), "question"?: text, "fit"?: {"w", "b", "n", "fitted_at"}}.
99
+ - `self` reads the step's own confidence: agent, decide, judge, pick, sift nodes only. An agent or decide node with it submits a `confidence` field (0 to 1) beside its record, which lands at `<key>$confidence`, never in its value; its `out` is an object schema. A judge, pick or sift reads its weakest answer's confidence.
100
+ - `jev` asks Jev one yes/no question over what the step saw and what it wrote: `question` (at most 2000 characters), or by default whether the output is right for the input. Every guarded kind may use it; it is the only signal for extract, code, call, workflow nodes.
101
+ - `both` combines the two: through `fit` when it has one, else the lower of the two.
102
+ - `fit` is the host's, written when it fits the threshold on graded runs: {"w": one weight per signal ([self, jev] for both), "b", "n": the runs it was fitted on, "fitted_at": an ISO time}. Never write or change one yourself. A raw confidence is not a calibrated probability: without a fit, set a threshold the host has measured, or leave the guard to the host.
103
+
95
104
  ## Predicates
96
105
 
97
- `loop.until` and `escalate.when` take one of these; `poll` takes only the first 10. Each path or key reads a state value an input or an earlier node produced.
106
+ `loop.until` and `escalate.when` take one of these; `poll` takes only the first 11. Each path or key reads a state value an input or an earlier node produced.
98
107
  A predicate is one JSON object that names itself in its `predicate` field beside its own fields, for example `{"predicate": "field_true", "path": "review.approved"}`.
99
108
  - `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
100
109
  - `field_true` {path}: holds when the value at `path` is `true`
@@ -105,6 +114,7 @@ A predicate is one JSON object that names itself in its `predicate` field beside
105
114
  - `empty` {path}: holds when the value at `path` is an empty array, an empty string, null or absent
106
115
  - `no_new_items` {key}: takes `key`, not `path`; holds when that state key is an empty array or falsy
107
116
  - `field_type` {path, type}: holds when the value at `path` is of `type`, one of number, string, boolean, array, object, null; a number only when finite, and an absent value is of no type
117
+ - `quote_missing` {path, field, pages}: the quote check, in code: holds when a quote at `path` (a string, or a list of them; with `field`, a list of records each holding its quote at `field`) is in none of the pages at `pages` (state paths holding what this run's call steps fetched; every string under each is page text). Both sides are compared lowercased, with curly quotes straight, dashes as "-" and whitespace runs as one space, then once more as their letters and digits alone; a quote under 8 characters is not checked. `{"predicate": "quote_missing", "path": "answer.evidence", "field": "quote", "pages": ["page"]}` on an escalate hands back an answer quoting text no fetched page holds. Check quotes with it, never with a judge or an `ask`
108
118
  - `not` {of}: holds when `of`, one mechanical predicate (never `ask`), does not; `{"predicate": "not", "of": {"predicate": "field_type", "path": "score", "type": "number"}}` holds when score is absent or not a finite number
109
119
  - `ask` {instructions, state, criteria, gte, provider, model, evidence, timeoutMs, images}: a yes/no question for the host's judge: `instructions` is the question, `state` what it sees (default: the whole state), `criteria` optional {true, false} descriptions; holds when the yes-probability is at least `gte` (in (0.5, 1], default 0.6)
110
120