@parcha/agentrun-dsl 0.1.0-beta.20 → 0.1.0-beta.21

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 CHANGED
@@ -26,7 +26,7 @@ A workflow is a JSON document of typed nodes: each node that asks a model names
26
26
  1. **Draft.** In Pi, `/agentrun <task>` has the agent draft the workflow with the packaged author skill (see [the Pi extension](../pi/README.md)). In your own host, `authorWorkflow` gives your agent the same author contract and keeps the candidate and its feedback without running it.
27
27
  2. **Check.** `validateWorkflow(workflow)` checks the structure, the schemas, the state paths between nodes and the predicates, with no model call. A refused workflow lists its `issues`: each names the node or schema at fault with a JSON Pointer `path`, and the rule it breaks with a `code`, so the agent repairs that node and checks again. `inspectWorkflow` shows the tree and the tools and adapters it needs, without running any code.
28
28
  3. **Dry-run, for free.** `dryRunWorkflow(workflow)` runs the whole workflow on synthetic values made from its schemas, with no model, Jev or tool call. Its `status` is `passed` when every check ran, `failed` with the `problems`, or `not_run` when a check could not run, with the reasons in `skipped`. A `not_run` dry run proves nothing.
29
- 4. **Run.** `runWorkflow(workflow, input, deps)` runs it with your agent, judgment and effect functions, and returns an output that matches the output schema, or an escalation.
29
+ 4. **Run.** `runWorkflow(workflow, input, deps)` runs it with your agent, judgment and effect functions, and returns an output that matches the output schema, or an escalation. `deps` is the object of adapters your application supplies (`runNode`, `runJudge`, `runEffect`); [Integrate with your application](https://github.com/Parcha-ai/agentrun/blob/main/docs/host-integration.md) says what each one owes the engine.
30
30
  5. **Watch every node.** `workflowGraph(workflow)` from `@parcha/agentrun-dsl/graph` lists every node and edge from the JSON alone, and `nodeStatus` marks each node `done`, `working`, `failed` or `not-run` from what a durable run kept. Pi's `/agentrun` view draws the same graph, with each node's state as the run goes.
31
31
 
32
32
  The same checks from a shell, in the project where you installed the package, on one of the author skill's examples that ships with it (an agent extracts the change in each release note, then summarizes the migration):
@@ -40,6 +40,66 @@ npx @parcha/agentrun-dsl@beta dry-run workflow.json --trusted
40
40
 
41
41
  Its dry run is `passed`: every node ran on synthetic values, with no model call. The demo's workflow (`npx @parcha/agentrun-dsl@beta example demo.json`) comes back `not_run` instead: its confidence check escalates on a synthetic answer, so the queue choice after it is not exercised, and `skipped` says so. `dry-run --strict` exits 3 on `not_run`, for a script that must stop there; a failure exits 1.
42
42
 
43
+ ### Run it with no key
44
+
45
+ `runWorkflow` calls back into your application for every model step. To see a run end to end with no key and no network, give it a `runNode` that returns a fixed record. Save this as `run.mjs` next to `node_modules` and run `node run.mjs`:
46
+
47
+ ```js
48
+ import { readFileSync } from 'node:fs';
49
+ import { runWorkflow } from '@parcha/agentrun-dsl';
50
+
51
+ const dir = 'node_modules/@parcha/agentrun-dsl/skills/author/examples/';
52
+ const workflow = JSON.parse(readFileSync(dir + 'review-release-notes.json', 'utf8'));
53
+ const input = JSON.parse(readFileSync(dir + 'review-release-notes.input.json', 'utf8'));
54
+
55
+ // deps holds the adapters your application supplies. This runNode answers each
56
+ // model step with a fixed record instead of calling a model.
57
+ const deps = {
58
+ async runNode({ label, user }) {
59
+ const state = JSON.parse(user); // the node's projected state, as JSON text
60
+ if (label === 'extract-change') {
61
+ return { breakingChange: state.text, migrationAction: 'Follow the release note.' };
62
+ }
63
+ return { summary: `${state.changes.length} breaking changes.`, changes: state.changes };
64
+ },
65
+ };
66
+
67
+ const result = await runWorkflow(workflow, input, deps);
68
+ console.log(result.status, result.output);
69
+ ```
70
+
71
+ It prints `complete` and a report with the two changes. Each answer is checked against the node's schema: a `runNode` that returns `{}` makes the run throw `submission does not satisfy schema "Change"`. A node whose adapter you did not supply fails with a message that names the node and the adapter (`extract node "extract-change" requires runNode`). The three adapters take different parameters, listed in `WorkflowDeps`: `runNode` (agent, decide, extract and report nodes) receives `kind`, `label`, `system`, `user`, `schema`, `tools` and `signal`, which a real host forwards to its agent; `runJudge` (judge, pick, sift, route and ask) receives `label`, `kind`, `state` and `questions`, and returns an object with the `answers`; `runEffect` (call nodes) receives `node`, `input`, `attempt`, `idempotencyKey` and `signal`, and returns the tool's result.
72
+
73
+ The `run` command of the CLI supplies no adapters, so it runs only a workflow that needs none, such as one made of `code` nodes. Save this as `total.json`:
74
+
75
+ ```json
76
+ {
77
+ "v": 2,
78
+ "name": "total",
79
+ "schemas": {
80
+ "Input": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "number" } } }, "required": ["items"] },
81
+ "Output": { "type": "object", "properties": { "total": { "type": "number" } }, "required": ["total"] }
82
+ },
83
+ "input": { "schemaId": "Input" },
84
+ "output": { "schemaId": "Output" },
85
+ "root": { "node": "code", "label": "sum", "code": "(s) => ({ total: s.items.reduce((a, b) => a + b, 0) })" }
86
+ }
87
+ ```
88
+
89
+ Save its input as `total.input.json`:
90
+
91
+ ```json
92
+ { "items": [1, 2, 3] }
93
+ ```
94
+
95
+ Then run it:
96
+
97
+ ```sh
98
+ npx @parcha/agentrun-dsl@beta run total.json total.input.json --trusted
99
+ ```
100
+
101
+ It prints `"status": "complete"` and an output with `"total": 6`. The shipped examples each need an adapter, so `run` stops on them naming it: `review-release-notes.json` needs `runNode`, `evidence-gate.json` needs `runJudge`, and `read-file.json` and `read-source-decision.json` need `runEffect` (the latter also `runJudge`). Run those with `runWorkflow` and your own adapters.
102
+
43
103
  The `agentrun` CLI provides `demo`, `example`, `inspect`, `validate`, `dry-run`, and deterministic `run`. `inspect workflow.json [--json]` displays structure without executing code. Validation/run require `--trusted` because workflow JavaScript can execute, including during validation. This package is not an isolation boundary.
44
104
 
45
105
  `runWorkflow(workflow, input, deps)` returns a complete schema-validated output or an escalation; its TypeScript output type is `unknown`. `defineWorkflow` binds Standard JSON Schema contracts, including supported Zod schemas, to a frozen v2 document; `runTypedWorkflow` infers those input/output types and delegates to the same interpreter. Intermediate state paths remain runtime-validated. Execution and verification failures throw. Hosts own tools, durable storage, file delivery, idempotency, recovery, and activation. A durable run's store keeps each effect's arguments as given, so redact secrets before they reach an effect.
@@ -70,7 +130,7 @@ The schema helpers resolve the owning workflow's schema catalog; `stageSchemaFor
70
130
 
71
131
  `@parcha/agentrun-dsl/graph` imports nothing, so a static viewer bundles it and a reader with no Node runs it. `workflowGraph(workflow)` returns `{ nodes, edges }` for a workflow document, computed from its JSON alone: a node is `{ path, kind, label, via? }` with `path` a JSON Pointer into the document as written (`/root/steps/1`, `/root/branches/<name>/body`, `/root/body` for a map's or a loop's body, `/root/workflow/root` for a child; the pointers `inspectWorkflow` and a validation issue use), and an edge is `{ from, to, kind }` with `kind` one of `next` (a chain's steps in order, a loop into its body), `branch` (a parallel node's branches), `route` (a route's branches), `item` (a map into its body) and `child` (a workflow node into its child's root). `nodeStatus(graph, source)` says, for each node, `done`, `working`, `failed` or `not-run`, read from what the recovery driver kept: its frame (the `pin` of the frozen snapshot), the map items' records (`agentrun.items`, keyed layout), or both as `{ pin, items }`. A run's map item or loop iteration has no node of its own: its instances count toward the body's node, and a node inside a map's or loop's body is done only once the map or loop is. To read one item's record on its own, pass `{ item: "<map path>/items/<index>" }` as a third argument: that item is then the instance, and its body is done when the item is. `graphNodeOf(graph, executionPath)` names the node an execution path (an event's or a record's) ran at: `{ path, at }`, where `path` is the node's pointer and `at` lists the map items (`{ kind: "item", index }`) and loop iterations (`{ kind: "iteration", index }`) it ran in, outermost first. An execution path is the node's pointer with `items/<i>` before a map's `body` and `iterations/<i>` before a loop's; the path is read by walking the graph by node kind, so a route branch named `items` stays a branch, and a path the graph does not have is `undefined`. The pi session's text view draws the same graph.
72
132
 
73
- The separate `@parcha/agentrun-dsl/demo` entrypoint provides the support-triage example. `@parcha/agentrun-dsl/schema` provides the generated workflow JSON Schema.
133
+ The separate `@parcha/agentrun-dsl/demo` entrypoint provides the support-triage example. `@parcha/agentrun-dsl/schema` provides the generated workflow JSON Schema, a JSON file: import it with `import schema from '@parcha/agentrun-dsl/schema' with { type: 'json' };` (a plain `import` throws `ERR_IMPORT_ATTRIBUTE_MISSING`), or load it with `require('@parcha/agentrun-dsl/schema')` in CommonJS.
74
134
 
75
135
  Children can contain maps, loops, routes, parallel branches and other children, and appear inside those structures. Their input/state and schema catalogs stay isolated; terminal report/artifact delivery remains parent-owned. New composed structures require path-aware recovery stores when recovery is enabled. `executionPath` is supplied to adapters, events and checkpoint/recovery hooks. Existing host validators and durable-cursor limits remain authoritative.
76
136
 
package/dist/workflow.js CHANGED
@@ -581,9 +581,36 @@ export function validateWorkflow(workflow, opts) {
581
581
  for (const file of branch.files)
582
582
  producedFiles.add(file);
583
583
  }
584
- // The merged state depends on which branches ran how; later reachability checks stand down, as before.
584
+ // Every branch runs, so the state after holds what each one writes: the check goes on past the parallel, unless the state
585
+ // before it, or a branch's own, is not known (a code node's keys are probed, not known).
585
586
  if (reachability)
586
- reachability.unknowable = true;
587
+ reachability.unknowable = before.unknowable || branches.some((branch) => branch.unknowable);
588
+ };
589
+ /** After a route node: one branch runs, so the state after holds what every branch leaves. A key some branch may not leave
590
+ * is not known; a key's shape is kept only when every branch leaves the same one. A file any branch produces is counted, as
591
+ * before. The check goes on past the route unless the state before it, or a branch's own, is not known. */
592
+ const routeKnowledge = (before, branches) => {
593
+ restoreKnowledge(before);
594
+ if (!branches.length)
595
+ return;
596
+ if (reachability && branches.every((branch) => branch.available)) {
597
+ reachability.available = new Set([...branches[0].available].filter((key) => branches.every((branch) => branch.available.has(key))));
598
+ reachability.unknowable = before.unknowable || branches.some((branch) => branch.unknowable);
599
+ }
600
+ typedOutputs.clear();
601
+ for (const [key, value] of branches[0].typed)
602
+ if (branches.every((branch) => branch.typed.get(key) === value))
603
+ typedOutputs.set(key, value);
604
+ probedSubtrees.clear();
605
+ for (const key of branches[0].probed.keys())
606
+ if (branches.every((branch) => branch.probed.has(key)))
607
+ probedSubtrees.set(key, [...new Set(branches.flatMap((branch) => branch.probed.get(key)))]);
608
+ for (const branch of branches) {
609
+ for (const key of branch.spread)
610
+ spreadTaintedKeys.add(key);
611
+ for (const file of branch.files)
612
+ producedFiles.add(file);
613
+ }
587
614
  };
588
615
  const checkPredicatePath = (when, label, path) => {
589
616
  if (!reachability || !when?.path)
@@ -946,8 +973,6 @@ export function validateWorkflow(workflow, opts) {
946
973
  });
947
974
  if (after.length)
948
975
  mergeKnowledge(before, after);
949
- if (reachability)
950
- reachability.unknowable = true;
951
976
  }
952
977
  return;
953
978
  case "loop":
@@ -1107,25 +1132,32 @@ export function validateWorkflow(workflow, opts) {
1107
1132
  if (node.as !== undefined && (typeof node.as !== "string" || !node.as.trim()))
1108
1133
  fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): as must be a state key when present`);
1109
1134
  checkRequires({ label, requires: node.requires }, path);
1110
- if (reachability) {
1111
- if (typeof node.as === "string" && node.as.trim()) {
1112
- reachability.available.add(node.as);
1113
- if (!byValue)
1114
- reachability.available.add(`${node.as}$answers`);
1135
+ // The route writes its choice under `as` (and a judged route its answers under `<as>$answers`) before the branch runs.
1136
+ if (typeof node.as === "string" && node.as.trim())
1137
+ for (const key of byValue ? [node.as] : [node.as, `${node.as}$answers`]) {
1138
+ reachability?.available.add(key);
1139
+ typedOutputs.delete(key);
1140
+ probedSubtrees.delete(key);
1115
1141
  }
1116
- reachability.unknowable = true;
1117
- }
1118
- for (const name of names) {
1119
- const branch = raw.branches[name];
1120
- if (!branch || typeof branch !== "object" || !branch.body) {
1121
- fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" needs a body`);
1122
- continue;
1142
+ {
1143
+ // Each branch starts from the state the route leaves it, never from a sibling's; the state after is what every branch leaves.
1144
+ const before = snapshotKnowledge();
1145
+ const after = [];
1146
+ for (const name of names) {
1147
+ const branch = raw.branches[name];
1148
+ if (!branch || typeof branch !== "object" || !branch.body) {
1149
+ fail("STRUCTURE_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" needs a body`);
1150
+ continue;
1151
+ }
1152
+ if (byValue && branch.criteria !== undefined)
1153
+ fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1154
+ else if (branch.criteria !== undefined && typeof branch.criteria !== "string")
1155
+ fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" criteria must be a string`);
1156
+ restoreKnowledge(before);
1157
+ walk(branch.body, `${path}.branches.${name}`, `${ptr}/branches/${pointerKey(name)}/body`);
1158
+ after.push(snapshotKnowledge());
1123
1159
  }
1124
- if (byValue && branch.criteria !== undefined)
1125
- fail("NODE_KEY_UNKNOWN", ptrOf(path), `${path} (${label}): branch "${name}" criteria are for Jev; a route by valuePath matches the branch name exactly`);
1126
- else if (branch.criteria !== undefined && typeof branch.criteria !== "string")
1127
- fail("NODE_FIELD_INVALID", ptrOf(path), `${path} (${label}): branch "${name}" criteria must be a string`);
1128
- walk(branch.body, `${path}.branches.${name}`, `${ptr}/branches/${pointerKey(name)}/body`);
1160
+ routeKnowledge(before, after);
1129
1161
  }
1130
1162
  return;
1131
1163
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.20",
3
+ "version": "0.1.0-beta.21",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",