@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.3

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.
@@ -0,0 +1,37 @@
1
+ {
2
+ "v": 2,
3
+ "name": "fictional-read-source-decision",
4
+ "schemas": {
5
+ "Input": { "type": "object", "properties": {
6
+ "question": { "type": "string", "minLength": 1 },
7
+ "paths": { "type": "array", "items": { "type": "string", "minLength": 1 } }
8
+ }, "required": ["question", "paths"], "additionalProperties": false },
9
+ "ToolResult": { "type": "object", "properties": {
10
+ "content": { "type": "array", "items": { "type": "object", "properties": {
11
+ "type": { "const": "text" }, "text": { "type": "string" }
12
+ }, "required": ["type", "text"] } }, "details": {}
13
+ }, "required": ["content"] },
14
+ "Questions": { "type": "object", "properties": {
15
+ "matches": { "type": "boolean", "description": "Does the original source text satisfy the condition asked in question, taking account of its headings, scope and exclusions rather than keyword overlap?" }
16
+ }, "required": ["matches"], "additionalProperties": false },
17
+ "Results": { "type": "array", "items": { "type": "object", "properties": {
18
+ "path": { "type": "string" }, "source": { "$ref": "#/definitions/ToolResult" },
19
+ "probability": { "type": "number", "minimum": 0, "maximum": 1 }
20
+ }, "required": ["path", "source", "probability"], "additionalProperties": false } }
21
+ },
22
+ "input": { "schemaId": "Input" },
23
+ "output": { "schemaId": "Results", "path": "results" },
24
+ "root": {
25
+ "node": "map", "label": "read-and-judge-originals", "itemsPath": "paths", "maxConcurrency": 2,
26
+ "as": "results", "resultPath": "record",
27
+ "body": { "node": "chain", "steps": [
28
+ { "node": "call", "label": "read-original", "via": "tool", "tool": "read",
29
+ "args": { "path": "{item}" }, "out": "ToolResult", "as": "source", "deadline_s": 30 },
30
+ { "node": "judge", "label": "source-membership", "state": {
31
+ "question": "{question}", "source": "{source}"
32
+ }, "out": "Questions", "as": "decision" },
33
+ { "node": "code", "label": "retain-source-and-probability", "as": "record",
34
+ "code": "(s) => ({ path: s.item, source: s.source, probability: s['decision$answers'].answers.matches.noul })" }
35
+ ] }
36
+ }
37
+ }
@@ -0,0 +1,10 @@
1
+ FICTIONAL EXAMPLE — not a real product release
2
+
3
+ # Current release
4
+
5
+ Clients MUST send the X-Workspace header with their workspace slug.
6
+
7
+ # Future proposals — not approved
8
+
9
+ Changing the authentication mechanism remains a proposal. No authentication
10
+ migration is required by this release.
@@ -0,0 +1,6 @@
1
+ {
2
+ "notes": [
3
+ "Requests now require the X-Workspace header. Older clients must send X-Workspace with their workspace slug.",
4
+ "The legacy /events endpoint has been removed. Send event queries to /v2/events instead."
5
+ ]
6
+ }
@@ -0,0 +1,123 @@
1
+ {
2
+ "v": 2,
3
+ "name": "review-release-notes",
4
+ "schemas": {
5
+ "Input": {
6
+ "type": "object",
7
+ "properties": {
8
+ "notes": {
9
+ "type": "array",
10
+ "items": {
11
+ "type": "string",
12
+ "minLength": 1
13
+ },
14
+ "minItems": 1,
15
+ "maxItems": 5
16
+ }
17
+ },
18
+ "required": [
19
+ "notes"
20
+ ],
21
+ "additionalProperties": false
22
+ },
23
+ "Change": {
24
+ "type": "object",
25
+ "properties": {
26
+ "breakingChange": {
27
+ "type": "string",
28
+ "minLength": 1
29
+ },
30
+ "migrationAction": {
31
+ "type": "string",
32
+ "minLength": 1
33
+ }
34
+ },
35
+ "required": [
36
+ "breakingChange",
37
+ "migrationAction"
38
+ ],
39
+ "additionalProperties": false
40
+ },
41
+ "Report": {
42
+ "type": "object",
43
+ "properties": {
44
+ "summary": {
45
+ "type": "string",
46
+ "minLength": 1
47
+ },
48
+ "changes": {
49
+ "type": "array",
50
+ "items": {
51
+ "type": "object",
52
+ "properties": {
53
+ "breakingChange": {
54
+ "type": "string",
55
+ "minLength": 1
56
+ },
57
+ "migrationAction": {
58
+ "type": "string",
59
+ "minLength": 1
60
+ }
61
+ },
62
+ "required": [
63
+ "breakingChange",
64
+ "migrationAction"
65
+ ],
66
+ "additionalProperties": false
67
+ },
68
+ "minItems": 1
69
+ }
70
+ },
71
+ "required": [
72
+ "summary",
73
+ "changes"
74
+ ],
75
+ "additionalProperties": false
76
+ }
77
+ },
78
+ "input": {
79
+ "schemaId": "Input"
80
+ },
81
+ "output": {
82
+ "schemaId": "Report",
83
+ "path": "report"
84
+ },
85
+ "root": {
86
+ "node": "chain",
87
+ "steps": [
88
+ {
89
+ "node": "map",
90
+ "label": "extract-each-release-note",
91
+ "itemsPath": "notes",
92
+ "as": "changes",
93
+ "maxConcurrency": 2,
94
+ "body": {
95
+ "node": "extract",
96
+ "label": "extract-change",
97
+ "instructions": "Extract the breaking change and its migration action from the supplied release note. Preserve the exact header name and required action. Do not invent a migration step.",
98
+ "state": {
99
+ "text": "{item}"
100
+ },
101
+ "requires": [
102
+ "item"
103
+ ],
104
+ "out": "Change",
105
+ "as": "change"
106
+ }
107
+ },
108
+ {
109
+ "node": "extract",
110
+ "label": "summarize-migration",
111
+ "instructions": "Summarize these migration actions for a client maintainer. Return the supplied changes unchanged alongside the summary. Do not invent steps.",
112
+ "state": {
113
+ "changes": "{changes}"
114
+ },
115
+ "requires": [
116
+ "changes"
117
+ ],
118
+ "out": "Report",
119
+ "as": "report"
120
+ }
121
+ ]
122
+ }
123
+ }
@@ -0,0 +1,113 @@
1
+ # Design Jev decisions in AgentRun
2
+
3
+ Jev returns typed judgments and probabilities, not generated prose, tool calls or
4
+ multi-step research. The host supplies its adapter and credentials; the workflow
5
+ names the question. Do not write
6
+ HTTP requests or SDK setup into workflow code. This guide maps the TypeSafe
7
+ programming model to the installed DSL; the general TypeSafe skill is optional.
8
+
9
+ ## Choose the boundary
10
+
11
+ Work backward from the action the result controls. Code handles exact lookups,
12
+ parsing, arithmetic, joins, grouping and constraints. An agent handles open-ended
13
+ research or generation. Jev can select relevant evidence, interpret a boundary,
14
+ compare a claim to its source or choose among known actions. It need not be a
15
+ final approval stage, and a workflow without a semantic decision need not use it.
16
+
17
+ Ask one coherent judgment per property. Separate independently useful conditions;
18
+ keep related context together. Avoid asking whether a whole complex answer is
19
+ "correct" when no source supporting that answer is supplied. Question descriptions
20
+ must carry their meaning; property names alone are not instructions.
21
+
22
+ ## Construct the evidence, not another opinion
23
+
24
+ For source-grounded work, a useful pattern is:
25
+
26
+ 1. A tool or agent locates candidate references, retaining their identities.
27
+ 2. Direct tool calls fetch the original text at those references.
28
+ 3. Jev sees the question or full selection rule **and that original text**.
29
+ 4. Code uses the returned values; an agent may repair missing evidence or synthesize.
30
+
31
+ Keep source text separate from a candidate extraction, paraphrase or claim. An
32
+ agent's field named `quote`, `headerContext` or `verified` does not make it original
33
+ evidence. Re-read the cited source through the host tool when independent checking
34
+ matters. Include relevant headings, units, dates, neighboring rows, exclusions and
35
+ section boundaries. An exact quote match checks presence, not interpretation.
36
+
37
+ Judge only what the supplied context can establish. If a source is truncated,
38
+ follow its continuation when relevant; if it is missing, retrieve or surface the
39
+ gap. Do not silently substitute a summary to fit a size limit. Narrow or partition
40
+ large contexts at meaningful boundaries while retaining their qualifiers.
41
+ The adapter has no default byte ceiling. A host may explicitly configure
42
+ `maxStateBytes`; local size errors then report the measured UTF-8 JSON bytes and
43
+ that host's limit before any HTTP request is sent. Provider context limits are
44
+ separate and token-based, not a fixed bytes-to-tokens conversion. Jev 1.13's
45
+ documented contract, checked on 2026-09-22, allows 32k tokens for state plus the
46
+ longest question and 64k for state plus all questions combined; check the selected
47
+ model's current contract. Oversized provider requests remain
48
+ errors, not permission to truncate evidence or silently retry a different graph.
49
+
50
+ `sift` sends **all items together in one request**. Shared `state` is added to
51
+ that batch; it does not replace or narrow each item. `describe` adds an item
52
+ summary, but the full original item is still sent. A tool envelope can contain
53
+ the same text in both `content` and `details`, so character limits on individual
54
+ reads do not establish the final serialized size.
55
+
56
+ When judgments are independent, explicitly use `map` with a `judge` body for one
57
+ request per original. For records that already contain `document`, `page` and
58
+ `text`, a body can use `state: {rule: "{question}", original: "{item}"}`. For tool
59
+ envelopes, select the host's actual original-text and provenance fields instead
60
+ of sending duplicate representations. Retain the full reviewed rule, relevant
61
+ headers, units, dates, exclusions and neighboring rows. If an individual original
62
+ is still too large, retrieve or partition it at meaningful boundaries; do not
63
+ silently truncate it or replace it with an agent's interpretation. This explicit
64
+ graph change changes request count; no automatic batching or truncation occurs.
65
+
66
+ The fictional [read-source decision](../examples/read-source-decision.json) and
67
+ [input](../examples/read-source-decision.input.json) show direct tool results passed
68
+ to a judge unchanged, followed by deterministic probability projection in code. Its
69
+ paths are inputs, not a built-in corpus: place the bundled fictional
70
+ [release note](../examples/release-note.txt) in the working directory before running
71
+ that input. Adapt the tool and its
72
+ return schema to the tools the host actually names; an agent locator can produce the
73
+ references earlier in the same graph.
74
+
75
+ ## Use the installed primitives
76
+
77
+ - `judge`: a flat output schema describes several independent questions over one
78
+ explicit `state` map. Boolean properties become yes-probabilities (Noul); enums
79
+ become Choice; integer properties with minimum 0, maximum N−1 and N described
80
+ levels in `criteria` (2–10 levels) become Score. Put the complete question in each
81
+ `description`.
82
+ - `sift`: ask questions about each candidate and retain originals. Pass shared task
83
+ context in `state`; each item also needs its own original evidence. Candidate
84
+ coverage matters: no judge can recover a source absent from the candidate set.
85
+ - `pick`: choose from known candidates, with `allowNone` when none may fit.
86
+ - `route`: choose a semantic branch. Its uncertainty gate concerns that new
87
+ decision, not an earlier judge's probability.
88
+
89
+ Batch independent questions over the same state. They cannot read each other's
90
+ answers. Use another step when a decision is needed to retrieve new evidence or
91
+ construct new state. Inspect the assembled state and questions, not just node names.
92
+
93
+ ## Consume uncertainty honestly
94
+
95
+ `judge` stores decoded values at its `as` key and raw answers at `<as>$answers`.
96
+ A boolean is true at yes-probability 0.5; to enforce another threshold, read the
97
+ raw `.answers.<property>.noul` number and compare in code. A Noul near 0.5 means
98
+ uncertainty between yes and no, not medium intensity. Choice/Score confidence is
99
+ distribution concentration, not proof that the workflow is right.
100
+
101
+ Use thresholds appropriate to the task, with an explicit missing/uncertain path.
102
+ An example threshold is not calibrated policy. Low probability can justify
103
+ exclusion, another retrieval, cheap-agent repair or escalation, depending on the
104
+ question. Do not reject an entire result just because an unused condition is
105
+ uncertain. Preserve raw decisions so these policies can be inspected separately.
106
+
107
+ Typed output proves an interface, not truth. Test source coverage, semantics and
108
+ the downstream action independently. A fake-judge fixture proves wiring only.
109
+
110
+ Maintained against TypeSafe's state, primitives/Noul, confidence and citation-check
111
+ documentation, reviewed 2026-09-22. Upstream reference locations:
112
+ `https://docs.typesafe.ai/concepts/state`, `https://docs.typesafe.ai/primitives`,
113
+ `https://docs.typesafe.ai/confidence`, `https://docs.typesafe.ai/cookbooks/citation_check`.
@@ -0,0 +1,113 @@
1
+ <!-- Generated from packages/dsl/src/author.ts by node scripts/generate-author-contract.mjs. Do not edit. -->
2
+
3
+ # AgentRun workflow language
4
+
5
+ You author AgentRun workflows: JSON documents the AgentRun interpreter runs.
6
+ Deliver the complete JSON document the way your host asks; never deliver prose, a file name or a fragment. Make the smallest workflow that satisfies the request. A candidate runs nothing until its host accepts it, and an accepted candidate is not activated by acceptance.
7
+
8
+ ## Document
9
+
10
+ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
11
+ - `schemas` maps ids to inline JSON Schema objects. Every schema id a node, `input` or `output` names must exist there. Inside a schema, reference a catalog schema or an inline definition only as {"$ref":"#/definitions/<id>"}.
12
+ - The input contract: the run starts from the input object and nothing else. `input.schemaId`, when present, is enforced before the first node. A node may read only input keys and keys an earlier node wrote.
13
+ - `output.schemaId` validates the final value; `output.path` selects it from state and must name an input key or a key an earlier node wrote.
14
+ - State is one object. Each step writes its result under one key: its `as`, or, for an agent, decide, extract or code node without `as`, its label. A report writes `report_markdown`. A code node without `as` that returns an object merges that object's top-level fields instead.
15
+ - Keys that begin with `$` are engine-owned: `$host` (host state), `<as>$answers` (raw judge answers and confidences) and `<as>$verify` (verifier results). Read them; never write one. No `as` may begin with `$`, and neither may the label of an agent, decide, extract or code node without `as`.
16
+ - `{dot.path}` placeholders are replaced from state in `state` maps (including `verify.state` and `ask.state`), call `args`, `input`, `env` and `produces`, a child workflow's `input`, and `escalate.summary`; `pick` and `sift` `describe` templates also see `{item...}`. A placeholder that is the whole string keeps its value's type. Every key a state map, call or child input interpolates must be produced upstream. `instructions`, `code` and `command` are literal and never interpolated.
17
+
18
+ ## Node kinds
19
+
20
+ This is the complete set. Each kind accepts exactly these fields; any other field is an error.
21
+ - `chain`: `steps`
22
+ - `code`: `label`, `code`, `as`
23
+ - `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
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`
26
+ - `report`: `label`, `state`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
27
+ - `artifact`: `label`, `state`, `type`, `path`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
28
+ - `map`: `label`, `itemsPath`, `body`, `as`, `resultPath`, `maxConcurrency`
29
+ - `parallel`: `label`, `branches`
30
+ - `loop`: `label`, `body`, `until`, `maxIters`
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`
35
+ - `pick`: `label`, `itemsPath`, `describe`, `instructions`, `state`, `allowNone`, `as`, `requires`
36
+ - `sift`: `label`, `itemsPath`, `describe`, `state`, `out`, `as`, `keep`, `requires`
37
+ - `route`: `label`, `state`, `instructions`, `branches`, `unsure`, `as`, `requires`
38
+
39
+ ### Generative nodes: agent, decide, extract, report
40
+
41
+ Each runs one adapter session. A kind is a preset (its duty, default effort and model tier), not a capability limit:
42
+ - `extract` transcribes facts already present in its input into `out`: faithfully, null for an absent field, nothing invented, no judgment.
43
+ - `decide` judges what is already in state.
44
+ - `agent` gathers new evidence with its tools.
45
+ - `report` renders the final record as the deliverable prose. It has no `out` or `as`: it writes `report_markdown`.
46
+
47
+ Their fields:
48
+ - `instructions` (required, non-empty) states the node's duty as literal prose. The node receives `state` (an interpolated map) or, without it, the accumulated state as its JSON input; refer to keys by name.
49
+ - `out` names the schema the submission must satisfy; the value lands at `as`.
50
+ - `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.
51
+ - `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.
52
+ - `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.
53
+ - `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.
54
+ - `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.
55
+ - When the workflow has a report, no decide or extract `out` schema carries `report_markdown`.
56
+
57
+ ### Terminal nodes: report and artifact
58
+
59
+ A workflow has at most one terminal node, a `report` or an `artifact`, and it is the last step of the root chain. No terminal node sits inside a map, loop, parallel branch, route branch or child workflow.
60
+ - An `artifact` of type `markdown` or `report` is the report writer: give it the report's fields.
61
+ - Any other `artifact` type names a file: `path` is the workspace-relative file an earlier shell call declared in `produces`, and the node has no model fields (`instructions`, `state`, `sopSection`, `tools`, `effort`, `thinking`).
62
+
63
+ ### Judgment nodes: judge, pick, sift, route
64
+
65
+ Typed questions answered by the host's judge in one request each: no tools, no session, no `sopSection`.
66
+ - 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.
67
+ - `judge`: a non-empty `state` map, `out` (a question schema) and `as`. The decoded value lands at `as`, the raw answers at `<as>$answers`.
68
+ - `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}.
69
+ - `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`.
70
+ - `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.
71
+ - 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.
72
+
73
+ ### Control nodes
74
+
75
+ - `chain`: non-empty `steps`, run in order.
76
+ - `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.
77
+ - `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.
78
+ - `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.
79
+ - `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.
80
+ - `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.
81
+ - `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.
82
+ - `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.
83
+ - `via: tool` takes `tool` (a host tool address), `args` (an object) and `out` (the tool's result schema).
84
+ - `via: executor` takes `code` (a body that returns its JSON result and uses only `tools` and `input`), `input` and `out`.
85
+ - `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).
86
+ - `retry` {attempts: 1..5, backoff_s?: 0..60, on?: [timeout, http_5xx, http_429, connection, exit]}. `where` accepts only "sandbox".
87
+ - `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.
88
+ - Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
89
+
90
+ ## Predicates
91
+
92
+ `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.
93
+ - `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
94
+ - `field_true` {path}: holds when the value at `path` is `true`
95
+ - `in` {path, values}: holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)
96
+ - `count_gte` {path, n}: holds when the array (or number) at `path` has at least `n` items
97
+ - `gte` {path, n}: holds when the finite number at `path` is at least `n`
98
+ - `lt` {path, n}: holds when the finite number at `path` is below `n`
99
+ - `empty` {path}: holds when the value at `path` is an empty array, an empty string, null or absent
100
+ - `no_new_items` {key}: takes `key`, not `path`; holds when that state key is an empty array or falsy
101
+ - `ask` {instructions, state, criteria, gte}: 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)
102
+
103
+ ## Authority
104
+
105
+ - Use only tools the host names. Never invent a tool, capability, evidence source or successful check.
106
+ - Code, call and artifact nodes need the host's explicit authorization for executable candidates.
107
+ - When the host supplies rubric sections, they are authoritative source text: every generative node's `sopSection` lists all of them, a merged judgment inherits the union of its parents' sections, and policy is never paraphrased into instructions. Judgment nodes, `ask` predicates and `verify` clauses are then refused until the host reviews a separate question contract.
108
+ - Acceptance checks are the host's. Never change a check, fixture or threshold to pass.
109
+ - Bound loops and parallelism. Uncertainty escalates or takes an explicit fallback such as `route.unsure` or a threshold gate.
110
+
111
+ ## Example
112
+
113
+ {"v":2,"name":"summarize","schemas":{"Input":{"type":"object","properties":{"text":{"type":"string","minLength":1}},"required":["text"],"additionalProperties":false},"Result":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}},"input":{"schemaId":"Input"},"output":{"schemaId":"Result","path":"result"},"root":{"node":"extract","label":"summarize","instructions":"Summarize the text field faithfully. Invent nothing.","out":"Result","as":"result","requires":["text"],"tools":[]}}
@@ -0,0 +1,9 @@
1
+ # The SDK authoring path
2
+
3
+ Use this path when the host calls `authorWorkflow` from `@parcha/agentrun-dsl` rather than exposing the `agentrun` tool. The host supplies its own `runNode` adapter; the author asks it for one session with no tools and a `submit` tool. Deliver each candidate as the submit tool's value. Read validation and acceptance feedback, then repair within that session. The host retains each version and rejection. Acceptance does not activate or execute a replacement.
4
+
5
+ The session's system text is the [language reference](language.md) followed by the host's addendum, when the host supplies one. The addendum names the host's initial state, output types, node kinds and rules. Candidates using a node kind or artifact type outside a declared addendum are refused before validation.
6
+
7
+ With `rubricSections`, every generated LLM node must reference every supplied section, including child workflows. This conservative author policy rejects Jev nodes, semantic `ask` predicates, and `verify` clauses until the host has a separately reviewed question contract. Execution must receive the same authoritative SOP text. A schema field named `node`, `verify`, or `predicate` is ordinary data, not a judgment clause.
8
+
9
+ Host-owned acceptance callbacks and fixtures remain outside generated workflows. Do not edit them to obtain a pass. Structural acceptance alone does not establish behavior. Keep request text, rubric text, candidates, and reviews in storage appropriate for their contents.
@@ -0,0 +1,137 @@
1
+ # Workflow format
2
+
3
+ AgentRun documents are JSON data: `v: 2`, `name`, `schemas`, optional `input: {schemaId}`, `output: {schemaId, path}`, and `root`. Schema identifiers refer to the document's own catalog. Define the input and expected output before adding nodes. The [language reference](language.md) is the complete contract: every node kind, field and predicate the validator admits. The installed `@parcha/agentrun-dsl/schema` is the editor schema; execution performs additional semantic checks. This guide shows the patterns.
4
+
5
+ ## Minimal typed answer
6
+
7
+ The complete [inline typed example](../SKILL.md#minimal-typed-example) shows the minimal extraction pattern and its input. The model must extract the stated facts; the example itself is not a passed quality test.
8
+
9
+ Important fields:
10
+
11
+ - `requires` names paths in workflow state, not renamed keys in the prompt map. It is a **nonempty-evidence guard**, not a field-existence check: missing/null values, blank strings, empty arrays and objects without concrete values fail before model construction. `false` and `0` are concrete values. If an empty search result is valid input to a recovery step, handle it explicitly rather than declaring it nonempty.
12
+ - LLM `instructions` are literal prose. They do not substitute `{text}`.
13
+ - `state: {text: "{text}"}` explicitly chooses the JSON user message. Omitted `state` sends accumulated state, excluding legacy reference catalogs.
14
+ - `out` names the node's schema; `as` stores its value in state. For agent/extract/decide nodes, omitting `as` stores under the node's `label`; fields are not merged into top-level state. `output.path` selects the final value to validate.
15
+
16
+ For repository work, an agent can declare `tools: ["read", "grep"]` only if those tools are available. Read the host's tool argument schemas; do not invent parameters. Use `tools: []` for a tool-free agent or extraction. Omitting the list inherits the runner's allowed tools; it does not mean tool-free execution.
17
+
18
+ ## One direct tool operation
19
+
20
+ Read [read-file.json](../examples/read-file.json) and its [input](../examples/read-file.input.json). This performs one active built-in `read` call; it needs no model or Jev system one decision. Replace the input path with the file the user asked to read.
21
+
22
+ A host tool returns the host's own result envelope. The example's `read` built-in (from the Pi host) returns `content`, an array of text/image blocks, and optional `details`. Give `call.out` a schema for that tool return, rather than the final answer or a plain string. A later extraction can transform it into a different output schema. The bundled fictional `search` tool is the exception: its direct effect result is `{sources}`. A `call` needs its host tool name, typed `args`, result `out`, state key `as`, and positive `deadline_s`.
23
+
24
+ ## Composition and decisions
25
+
26
+ Read the complete [release-note review](../examples/review-release-notes.json) and its [input](../examples/review-release-notes.input.json) before composing nodes. It maps a typed extraction over two notes, collects only each `change`, then summarizes the collected changes. This needs an agent adapter, but no Jev or external tools.
27
+
28
+ The structure nodes (`chain`, `parallel`, `map`, `loop`) and the question nodes (`judge`, `sift`, `pick`, `route`) are defined in the [language reference](language.md). A question node runs only when the host configures a judge. Use an explicit uncertainty gate or escalation rather than inventing evidence, and supply the complete reviewed rubric: Jev question text is not a substitute for an unavailable SOP.
29
+
30
+ For `sift`, add a flat question schema to `schemas`, then a node such as:
31
+
32
+ ```json
33
+ {
34
+ "node": "sift", "label": "select-migration-notes",
35
+ "itemsPath": "notes", "out": "MigrationQuestions", "as": "selected",
36
+ "keep": { "path": "actionable", "gte": 0.8 }
37
+ }
38
+ ```
39
+
40
+ `MigrationQuestions` can declare `actionable` as `{"type":"boolean","description":"Does this release note state a concrete change a client maintainer must make, rather than only announce a feature?"}` inside its object `properties`. Set `required: ["actionable"]`. Read selected originals from `selected.items`, retained decisions from `selected.values`, and evidence sidecars from `selected.answers`. The `gte` value gates the yes-probability; it is an example threshold to review, not a calibrated guarantee. Handle empty results explicitly with an `escalate` node using `when: {predicate: "empty", path: "selected.items"}` before synthesis.
41
+
42
+ A `sift` batches all full items into one Jev request; `state` adds shared context
43
+ and `describe` adds summaries, neither replaces the items. The assembled request
44
+ must fit the selected provider's token context and any explicit host byte guard;
45
+ the adapter does not impose a default byte ceiling. A local `jev_state_too_large`
46
+ report names the node, measured bytes and configured host limit; it means no HTTP
47
+ request was sent. For independent judgments over larger originals,
48
+ use an explicit `map` with a `judge` body and selected original-text/provenance
49
+ fields, preserving the full rubric and necessary headers/qualifiers. See the
50
+ [Jev guide](jev-decisions.md); no automatic splitting or truncation occurs.
51
+
52
+ ### Check the edges before running
53
+
54
+ For each connection, name the actual value produced and the exact path consumed.
55
+ These are different contracts; do not make them all the final answer schema:
56
+
57
+ Inspection displays typed state keys and the final selection. It rejects nested
58
+ paths excluded by known closed producer schemas before execution. Dynamic code,
59
+ open schemas, unions and conditional control flow may leave shapes unknown;
60
+ passing inspection does not prove those paths exist at runtime.
61
+
62
+ | Producer | Value available downstream |
63
+ | --- | --- |
64
+ | Host tool called with `as: "read"` | `read.content` and optional `read.details`; not the fields inside `details` at top level |
65
+ | Agent/extract with `out: "Row", as: "row"` | The schema-valid Row at `row`, not `{row: Row}` inside it |
66
+ | Code with `as: "total"` returning a number | The number at `total`; returning `{total: number}` adds a second wrapper |
67
+ | Map with an agent body using `as: "row"` | An array of Row values; no `row` wrapper on each item |
68
+ | Map with a chain body and `resultPath: "row"` | An array of Row values selected from each completed body state |
69
+
70
+ Without `resultPath`, a chain map body retains the whole item state. That is not
71
+ the same as collecting its last step. After mapping, an array is still an array:
72
+ if the final contract is an object, explicitly assemble that object and point
73
+ `output.path` to it. Preserve the same distinction for tool result schemas and
74
+ final answer schemas. Inspection does not execute transforms or prove these
75
+ runtime shapes; check the reported value and contract when execution fails.
76
+
77
+ An `escalate` node always requires `when`. Inside a route branch, the branch-taken predicate below makes escalation unconditional for that branch; outside a branch, provide a predicate for the actual stopping condition.
78
+
79
+ A `route` needs a nonempty `state` map and at least two named branch objects with `body` nodes. This fragment uses the release review's `changes` state and `Report` schema:
80
+
81
+ ```json
82
+ {
83
+ "node": "route", "label": "check-migration-detail", "as": "routing",
84
+ "state": { "changes": "{changes}" },
85
+ "instructions": "Can a maintainer follow every supplied migration action without guessing missing details?",
86
+ "branches": {
87
+ "ready": {
88
+ "criteria": "Every action specifies the concrete client change needed.",
89
+ "body": {
90
+ "node": "extract", "label": "summarize-ready-changes",
91
+ "instructions": "Summarize the supplied migration actions and return changes unchanged.",
92
+ "state": { "changes": "{changes}" }, "out": "Report", "as": "report"
93
+ }
94
+ },
95
+ "needs_details": {
96
+ "criteria": "Any action lacks a required detail or the supplied changes conflict.",
97
+ "body": {
98
+ "node": "escalate", "label": "request-migration-details",
99
+ "when": { "predicate": "field_equals", "path": "routing.taken", "value": "needs_details" },
100
+ "kind": "needs_input", "stage": "migration", "summary": "Migration details need clarification."
101
+ }
102
+ }
103
+ },
104
+ "unsure": { "branch": "needs_details", "gte": 0.8 }
105
+ }
106
+ ```
107
+
108
+ `unsure` selects the conservative branch below its confidence gate. Preserve the raw decision evidence; reaching `ready` does not prove migration correctness.
109
+
110
+ Mechanical checks belong in predicates; semantic questions belong in agent/Jev nodes. Code is trusted JavaScript, not a sandbox, and runs only when the host authorizes it (the addendum names how). Do not turn an unavailable tool or missing verifier into generated code that bypasses the host.
111
+
112
+ ## Code transforms and schema references
113
+
114
+ Read the complete fictional [evidence gate](../examples/evidence-gate.json) and its [input](../examples/evidence-gate.input.json). It preserves a supplied claim and evidence, asks one Jev question, and gates the raw yes-probability in code before returning a typed record. It uses no agent or tool; running it with a real judge still needs Jev. The repository test uses a fake judge and proves interface behavior, not semantic quality.
115
+
116
+ The code node's fields, its `as` versus patch semantics and the `$ref` form are in the [language reference](language.md). Code is trusted host JavaScript, not a sandbox, and runs only when the host authorizes it.
117
+
118
+ Tool-host inspection uses nonexecuting syntax/mechanical validation, equivalent to SDK `validateWorkflow(workflow, {executeCode: false})`. It neither evaluates code factories nor probes their outputs. The ordinary SDK validation default is for trusted code and may execute factories/probes. Neither mode is a sandbox or a proof that the eventual result will satisfy the output schema.
119
+
120
+ Use synchronous data operations such as `Math`, `JSON`, `Array`, `Object`, `Map`, and `Set`. The current executor shadows `Date`, `Promise`, timers, host/network globals, and `Function`; they are unavailable even in a trusted run. For example, derive calendar-month sequences from integer year/month pairs rather than `new Date(...)`. This catches accidental host dependencies; it is not an isolation or security boundary.
121
+
122
+ ### Gate the raw probability, not the decoded boolean
123
+
124
+ For a judge with `as: "check"` and boolean question `supported`, read:
125
+
126
+ ```js
127
+ (s) => {
128
+ const p = s['check$answers']?.answers?.supported?.noul;
129
+ return {
130
+ accepted: typeof p === 'number' && Number.isFinite(p) && p >= 0.90 && p <= 1
131
+ };
132
+ }
133
+ ```
134
+
135
+ With `as: "gate"`, this stores `gate.accepted`. Missing, malformed, nonfinite, or out-of-range probabilities fail closed. Follow it with an `escalate` whose `when` is `{predicate: "field_equals", path: "gate.accepted", value: false}`, as in the example. The threshold is illustrative policy, not a calibrated accuracy guarantee.
136
+
137
+ `check.supported` is only the decoded boolean (yes at probability 0.5); it does **not** prove a 0.90 threshold. Likewise, `route.unsure.gte` gates the route's **own new choice confidence**, not an upstream judge's yes-probability. Giving a route the earlier boolean or asking it to enforce a number is not this deterministic gate.