@parcha/agentrun-dsl 0.1.0-beta.1 → 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.
- package/README.md +11 -2
- package/dist/author.d.ts +86 -0
- package/dist/author.js +304 -0
- package/dist/index.d.ts +7 -2
- package/dist/index.js +8 -1
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/vocabulary.d.ts +31 -0
- package/dist/vocabulary.js +60 -0
- package/dist/workflow.d.ts +54 -2
- package/dist/workflow.js +274 -48
- package/package.json +3 -2
- package/skills/author/SKILL.md +120 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +113 -0
- package/skills/author/references/language.md +113 -0
- package/skills/author/references/sdk-authoring.md +9 -0
- package/skills/author/references/workflow-format.md +137 -0
|
@@ -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.
|