@parcha/agentrun-dsl 0.1.0-beta.5 → 0.1.0-beta.9

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.
@@ -20,14 +20,14 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
20
20
  This is the complete set. Each kind accepts exactly these fields; any other field is an error.
21
21
  - `chain`: `steps`
22
22
  - `code`: `label`, `code`, `as`
23
- - `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
23
+ - `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `budget_usd`, `context`
24
24
  - `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
25
25
  - `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
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`
29
29
  - `parallel`: `label`, `branches`
30
- - `loop`: `label`, `body`, `until`, `maxIters`
30
+ - `loop`: `label`, `body`, `until`, `maxIters`, `expect_iters`
31
31
  - `escalate`: `label`, `when`, `kind`, `stage`, `summary`
32
32
  - `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`
33
33
  - `workflow`: `label`, `workflow`, `input`, `out`, `as`
@@ -51,9 +51,10 @@ Their fields:
51
51
  - `out` names the schema the submission must satisfy; the value lands at `as`.
52
52
  - `requires` lists state paths that must hold evidence before the node runs, each produced upstream: missing values, null, blank strings, empty arrays and empty objects stop the run; `false` and `0` pass.
53
53
  - `tools` names tools the host offers. `[]` means no tools; omitting `tools` offers every tool the host allows. Never name a tool the host did not offer.
54
- - `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's, and nodes carry no budgets.
54
+ - `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's.
55
+ - An `agent` node may carry `budget_usd`, the most it asks to spend in dollars (above 0), which the host caps by what it has left, and `context`, fresh|fork: `fresh` (the default) sees only its instructions and state; `fork` asks the host to start it from the caller's transcript, which a host refuses where it has none.
55
56
  - `sopSection` names one heading of the host's SOP, or a list of them, as the exact text after "## ". The node receives those sections verbatim.
56
- - `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: 1..4 (default 2), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
57
+ - `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: an integer >= 1 (default 2, no maximum), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
57
58
  - When the workflow has a report, no decide or extract `out` schema carries `report_markdown`.
58
59
 
59
60
  ### Terminal nodes: report and artifact
@@ -68,7 +69,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
68
69
  - A question schema is a flat object. Each property's `description` is its question. A boolean yields a yes-probability; a string enum (at most 240 options, optional per-option `criteria`) yields a choice; an integer with `criteria`: [level descriptions] (2 to 10 levels, minimum 0, maximum the last level index) yields a score. Nothing else is a question.
69
70
  - `judge`: a non-empty `state` map, `out` (a question schema) and `as`. The decoded value lands at `as`, the raw answers at `<as>$answers`.
70
71
  - `pick`: `itemsPath`, `describe` (the option text per item, such as "{item.name}"), `instructions` (the one question) and `as`; `allowNone` adds a none-of-these option. The result is {index, item, none, option}.
71
- - `sift`: `itemsPath`, `out` (a question schema asked of every item in one request) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
72
+ - `sift`: `itemsPath`, `out` (a question schema asked of every item; the host splits the items across requests when they exceed its limits) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
72
73
  - `route`: a non-empty `state` map, `instructions` (the one question) and 2 to 240 named `branches`, each {criteria?, body}. `unsure` {branch: one of the branches, gte: a number in (0, 1]} takes that branch when the choice's confidence is below `gte`. `as` records the choice.
73
74
  - A decoded boolean is true at yes-probability 0.5. To hold a different threshold, read `<as>$answers.answers.<id>.noul` in a code node.
74
75
 
@@ -77,21 +78,22 @@ Typed questions answered by the host's judge in one request each: no tools, no s
77
78
  - `chain`: non-empty `steps`, run in order.
78
79
  - `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state.
79
80
  - `parallel`: at least two `branches`, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
80
- - `loop`: `body`, `until` (a predicate) and an integer `maxIters` from 1 to 20. At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
81
+ - `loop`: `body`, `until` (a predicate) and an integer `maxIters` of at least 1 (no maximum), optionally an integer `expect_iters` of at least 1 (priced passes). At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
81
82
  - `escalate`: `when` (a predicate), and non-empty `kind`, `stage` and `summary`. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
82
83
  - `workflow`: `label`, `workflow` (a complete inline child), `input` (an object, interpolated, the child's entire initial state), `out` (a parent schema checked against the child's output) and `as`. The child declares `input.schemaId` in its own schemas and contains no report or artifact.
83
84
  - `code`: `code` is one synchronous function expression such as "(s) => ({ total: s.items.length })". It receives the full state; return new values and never mutate it. `Date`, `Promise`, timers, `fetch`, `require`, `process`, `Function` and `globalThis` are unavailable. It is trusted host JavaScript, not a sandbox. Use code for typed-state mechanics, never to read meaning from prose.
84
- - `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (greater than 0, at most 3600) are required.
85
+ - `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (a finite number greater than 0, no maximum) are required — an unbounded effect is how a stalled provider becomes a stalled job.
85
86
  - `via: tool` takes `tool` (a host tool address), `args` (an object) and `out` (the tool's result schema).
86
87
  - `via: executor` takes `code` (a body that returns its JSON result and uses only `tools` and `input`), `input` and `out`.
87
88
  - `via: shell` takes `command` (literal) and `env` (UPPER_CASE names to strings, interpolated by value; the way long values reach a command). Its result has the fixed shape {code, stdout, stderr, truncated?}: no `out`. Only a shell call may declare `produces` (workspace-relative files, checked after the effect).
88
- - `retry` {attempts: 1..5, backoff_s?: 0..60, on?: [timeout, http_5xx, http_429, connection, exit]}. `where` accepts only "sandbox".
89
- - `poll` {until, fail_when?, interval_s: 0.1..300, deadline_s: from the call's deadline_s to 7200} 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.
89
+ - `retry` {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [timeout, http_5xx, http_429, connection, exit, effect_timeout, effect_exit, effect_transport, effect_not_granted, effect_produces_missing, effect_path_escape, effect_code_unsafe, output_invalid, state_invalid, effect_unknown_transport]}. `where` accepts only "sandbox".
90
+ - `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.
90
91
  - Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
91
92
 
92
93
  ## Predicates
93
94
 
94
95
  `loop.until` and `escalate.when` take one of these; `poll` takes only the first 8. Each path or key reads a state value an input or an earlier node produced.
96
+ 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"}`.
95
97
  - `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
96
98
  - `field_true` {path}: holds when the value at `path` is `true`
97
99
  - `in` {path, values}: holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)