@parcha/agentrun-dsl 0.1.0-beta.14 → 0.1.0-beta.15
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 +3 -1
- package/dist/author.js +1 -1
- package/dist/dry-run.d.ts +6 -0
- package/dist/dry-run.js +30 -5
- package/dist/graph.d.ts +67 -0
- package/dist/graph.js +158 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.js +1 -0
- package/dist/job.d.ts +14 -0
- package/dist/job.js +5 -0
- package/dist/recovery/canonical-hash.d.ts +1 -1
- package/dist/recovery/canonical-hash.js +3 -3
- package/dist/recovery/driver.d.ts +21 -1
- package/dist/recovery/driver.js +394 -16
- package/dist/recovery/execution-path.d.ts +8 -0
- package/dist/recovery/execution-path.js +14 -0
- package/dist/recovery/frozen-snapshot.d.ts +76 -1
- package/dist/recovery/frozen-snapshot.js +21 -0
- package/dist/recovery/index.d.ts +3 -3
- package/dist/recovery/index.js +2 -2
- package/dist/recovery/item-state.d.ts +48 -0
- package/dist/recovery/item-state.js +89 -0
- package/dist/recovery/journal.d.ts +6 -3
- package/dist/recovery/journal.js +20 -8
- package/dist/recovery/store.d.ts +33 -9
- package/dist/recovery/testing/conformance.js +55 -0
- package/dist/system-one.d.ts +17 -1
- package/dist/system-one.js +17 -1
- package/dist/workflow.d.ts +3 -0
- package/dist/workflow.js +42 -1
- package/package.json +8 -1
- package/skills/author/references/language.md +1 -1
- package/skills/author/references/sdk-authoring.md +2 -0
package/README.md
CHANGED
|
@@ -39,7 +39,7 @@ The package root exports a deliberate API. The beta retains agent, structured-ou
|
|
|
39
39
|
| Integrate a host | `runWorkflowSlice`, `assertWorkflowCapabilities`, `desugarWorkflow`, `resolveSchemaForWorkflow`, `stageSchemaForNode`, `submissionSchemaForNode`, `mergeStageDelta`, `REPORT_SCHEMA`, `SHELL_RESULT_SCHEMA`, `getPath`, `predicateMatches`, `deniedGlobalReferences`. |
|
|
40
40
|
| Author workflows | `authorContract`, `renderAuthorContract` (text and sha256), `renderAuthorHostAddendum`, `authorWorkflow`, `candidatePolicyErrors`, `applyHostOutputTypes`, `AUTHOR_SKILL_NAME`, `authorSkillDirectory`, `loadAuthorReference`, `loadAuthorSkillBundle`; `AuthorHostAddendum`, `AuthorWorkflowOptions`, `AuthoredWorkflow`, `CandidatePolicyOptions`. The one author contract and its packaged skill (`skills/author`); a host adds only an addendum. See [the author contract](../../docs/authoring.md#one-author-contract). |
|
|
41
41
|
| Language vocabulary | `WORKFLOW_NODE_KINDS`, `GENERATIVE_NODE_KINDS`, `JUDGMENT_NODE_KINDS`, `NODE_FIELDS`, `IGNORED_NODE_FIELDS`, `WORKFLOW_PREDICATES`, `MECHANICAL_PREDICATES`, `PREDICATE_FIELDS`, `EFFORT_LEVELS`, `THINKING_LEVELS`, `MODEL_TIERS`, `CALL_TRANSPORTS`, `CALL_RETRY_CLASSES`, `EFFECT_FAILURE_CODES`, `PROSE_ARTIFACT_TYPES`; `WorkflowNodeKind`, `WorkflowPredicateName`. The validator and the author contract read these same constants. |
|
|
42
|
-
| Test without a model | `synthesizeInstance`, `synthesizeAnswers`, `DryRunOptions`, `DryRunResult`. Synthetic answers exercise execution mechanics; they do not establish judgment quality. |
|
|
42
|
+
| Test without a model | `synthesizeInstance`, `synthesizeAnswers`, `DryRunOptions`, `DryRunResult`. Synthetic answers exercise execution mechanics; they do not establish judgment quality. A dry run stops after `maxSteps` synthetic steps (10,000 by default) or at its `signal`, with `skipped` saying so. |
|
|
43
43
|
|
|
44
44
|
A `code` node runs in the host process through the package's own executor, which shadows common globals and is not a sandbox. A host that runs code from an untrusted author supplies `deps.runCode`: the interpreter then hands it each code node with the state and the transform's context, merges what it returns under the same patch rules and state checks, and never executes a code body itself, not even as a validation probe. `dryRunWorkflow` takes the same `runCode` option and honors it the same way. `validateWorkflow` is synchronous and cannot call a host executor: a host that has one validates with `executeCode: false`, as `runWorkflow` and `dryRunWorkflow` do for it. `deniedGlobalReferences` names the globals a code body reaches for (a lint, never a boundary), so such a host can refuse the node before it runs. A failed effect carries a closed `code` from `EFFECT_FAILURE_CODES` on its `EffectFailure` and on every `effect.failed` event (null when the failure is not an `EffectFailure` with a listed code; any other typed error's own code rides as `error_code`), and `retry.on` names codes as well as retry classes.
|
|
45
45
|
|
|
@@ -47,6 +47,8 @@ A `code` node runs in the host process through the package's own executor, which
|
|
|
47
47
|
|
|
48
48
|
The schema helpers resolve the owning workflow's schema catalog; `stageSchemaForNode` and `submissionSchemaForNode` name the same submission contract. `mergeStageDelta` stores declared submission fields under the node's output key; callers must validate the submission first. Internal traversal, compilation, CSV, reference-file and input-normalization helpers are not package-root APIs.
|
|
49
49
|
|
|
50
|
+
`@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. The pi session's text view draws the same graph.
|
|
51
|
+
|
|
50
52
|
The separate `@parcha/agentrun-dsl/demo` entrypoint provides the support-triage example. `@parcha/agentrun-dsl/schema` provides the generated workflow JSON Schema.
|
|
51
53
|
|
|
52
54
|
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.
|
package/dist/author.js
CHANGED
|
@@ -84,7 +84,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
|
|
|
84
84
|
### Control nodes
|
|
85
85
|
|
|
86
86
|
- ${code("chain")}: non-empty ${code("steps")}, run in order.
|
|
87
|
-
- ${code("map")}: ${code("itemsPath")} (an upstream list), ${code("body")} and ${code("as")}. The body sees ${code("item")} and ${code("item_index")}; ${code("maxConcurrency")} is a positive integer (default 4); ${code("resultPath")} selects one path from each completed item's state.
|
|
87
|
+
- ${code("map")}: ${code("itemsPath")} (an upstream list), ${code("body")} and ${code("as")}. The body sees ${code("item")} and ${code("item_index")}; ${code("maxConcurrency")} is a positive integer (default 4); ${code("resultPath")} selects one path from each completed item's state. Without ${code("resultPath")}, and with no ${code("as")} in the body, each item's result is its whole state, the mapped list included: set ${code("resultPath")} (or an ${code("as")} in the body) for a large map; the validator warns.
|
|
88
88
|
- ${code("parallel")}: at least two ${code("branches")}, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
|
|
89
89
|
- ${code("loop")}: ${code("body")}, ${code("until")} (a predicate) and an integer ${code("maxIters")} of at least 1 (no maximum), optionally an integer ${code("expect_iters")} of at least 1 (priced passes). At the bound the state passes through with ${code("until")} unmet; follow the loop with an escalate or gate on that condition.
|
|
90
90
|
- ${code("escalate")}: ${code("when")} (a predicate), and non-empty ${code("kind")}, ${code("stage")} and ${code("summary")}. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
|
package/dist/dry-run.d.ts
CHANGED
|
@@ -18,5 +18,11 @@ export type DryRunOptions = {
|
|
|
18
18
|
/** The host's executor for `code` nodes (WorkflowDeps.runCode). Present, the dry run validates
|
|
19
19
|
* with executeCode:false and hands every code node to it, so no code body runs in this process. */
|
|
20
20
|
runCode?: WorkflowDeps["runCode"];
|
|
21
|
+
/** Ends the dry run: it stops at its next step, as not run. */
|
|
22
|
+
signal?: AbortSignal;
|
|
23
|
+
/** The most synthetic steps (an agent's or a judge's answer, an effect, a code node the host runs) before the dry run
|
|
24
|
+
* stops, as not run: synthetic answers can keep a loop going to its bound, and a map over a long list. 10,000 by
|
|
25
|
+
* default. */
|
|
26
|
+
maxSteps?: number;
|
|
21
27
|
};
|
|
22
28
|
export declare function dryRunWorkflow(workflow: Workflow, opts?: DryRunOptions): Promise<DryRunResult>;
|
package/dist/dry-run.js
CHANGED
|
@@ -156,23 +156,46 @@ export async function dryRunWorkflow(workflow, opts = {}) {
|
|
|
156
156
|
} };
|
|
157
157
|
}
|
|
158
158
|
let currentLabel = "";
|
|
159
|
+
// Every synthetic step counts, and every 64th yields to the event loop, so the host can take a stop meanwhile.
|
|
160
|
+
const maxSteps = opts.maxSteps ?? 10_000;
|
|
161
|
+
let steps = 0;
|
|
162
|
+
// Why the dry run stopped early, kept here: the interpreter may wrap what an adapter throws.
|
|
163
|
+
let stopped;
|
|
164
|
+
const stop = (reason) => { stopped ??= reason; throw new Error(stopped); };
|
|
165
|
+
const step = async () => {
|
|
166
|
+
if (opts.signal?.aborted)
|
|
167
|
+
stop("The dry run was stopped before it finished.");
|
|
168
|
+
steps += 1;
|
|
169
|
+
if (steps > maxSteps)
|
|
170
|
+
stop(`The dry run stopped after ${maxSteps} synthetic steps: on synthetic values the workflow's loops or maps go on further. Supply input, or lower a loop's maxIters.`);
|
|
171
|
+
if (steps % 64 === 0) {
|
|
172
|
+
await new Promise((resolve) => setTimeout(resolve, 0));
|
|
173
|
+
if (opts.signal?.aborted)
|
|
174
|
+
stop("The dry run was stopped before it finished.");
|
|
175
|
+
}
|
|
176
|
+
};
|
|
177
|
+
const runCode = opts.runCode;
|
|
159
178
|
try {
|
|
160
179
|
const result = await runWorkflow(workflow, input, {
|
|
161
180
|
sop: opts.sop,
|
|
162
|
-
...(
|
|
181
|
+
...(runCode ? { runCode: async (...args) => { await step(); return runCode(...args); } } : {}),
|
|
163
182
|
onEvent: (event) => { if (typeof event.label === "string")
|
|
164
183
|
currentLabel = event.label; },
|
|
165
184
|
runNode: async ({ schema, review }) => {
|
|
185
|
+
await step();
|
|
166
186
|
const candidate = synthesizeInstance(schema, schema.definitions ?? workflow.schemas);
|
|
167
187
|
if (review)
|
|
168
188
|
await review(candidate);
|
|
169
189
|
return candidate;
|
|
170
190
|
},
|
|
171
|
-
runJudge: async ({ questions }) => ({ answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "" }
|
|
191
|
+
runJudge: async ({ questions }) => { await step(); return { answers: synthesizeAnswers(questions), model: "synthetic", usage: null, cost_usd: null, request_sha256: "" }; },
|
|
172
192
|
syntheticEffects: true,
|
|
173
|
-
runEffect: async ({ node, schema }) =>
|
|
174
|
-
|
|
175
|
-
|
|
193
|
+
runEffect: async ({ node, schema }) => {
|
|
194
|
+
await step();
|
|
195
|
+
return node.via === "shell"
|
|
196
|
+
? { code: 0, stdout: "{}", stderr: "", truncated: false }
|
|
197
|
+
: synthesizeInstance(schema ?? (workflow.schemas || {})[node.out], schema?.definitions ?? workflow.schemas ?? {});
|
|
198
|
+
},
|
|
176
199
|
});
|
|
177
200
|
if (result.status === "escalated") {
|
|
178
201
|
// Synthetic values tripping an escalate predicate proves nothing about real cases.
|
|
@@ -181,6 +204,8 @@ export async function dryRunWorkflow(workflow, opts = {}) {
|
|
|
181
204
|
return { ok: true };
|
|
182
205
|
}
|
|
183
206
|
catch (error) {
|
|
207
|
+
if (stopped)
|
|
208
|
+
return { ok: true, skipped: [stopped] };
|
|
184
209
|
if (error instanceof WorkflowOutputInvalidError) {
|
|
185
210
|
return { ok: false, problems: error.problems, stage: error.stage };
|
|
186
211
|
}
|
package/dist/graph.d.ts
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/** One node of the workflow as written. `path` is a JSON Pointer (RFC 6901) into the document: `/root` is the root,
|
|
2
|
+
* `/root/steps/1` a chain's second step, `/root/branches/<name>/body` a route's branch, `/root/body` a map's or a
|
|
3
|
+
* loop's body, `/root/workflow/root` a child workflow's root: the pointers `inspectWorkflow` and a validation issue
|
|
4
|
+
* use for the same node. `label` is the node's label, or its kind when it has none. `via` is a `call` node's transport. */
|
|
5
|
+
export type GraphNode = {
|
|
6
|
+
path: string;
|
|
7
|
+
kind: string;
|
|
8
|
+
label: string;
|
|
9
|
+
via?: string;
|
|
10
|
+
};
|
|
11
|
+
/** How control reaches `to` from `from`.
|
|
12
|
+
* - `next`: a chain enters its first step and each step is followed by the next; a loop enters its body, which runs again
|
|
13
|
+
* until the loop ends.
|
|
14
|
+
* - `branch`: a parallel node starts each of its branches.
|
|
15
|
+
* - `route`: a route node takes one of its branches (the branch's name is the last pointer segment before `/body`).
|
|
16
|
+
* - `item`: a map runs its body once for each item.
|
|
17
|
+
* - `child`: a workflow node runs the child workflow's root. */
|
|
18
|
+
export type GraphEdgeKind = "next" | "branch" | "route" | "item" | "child";
|
|
19
|
+
export type GraphEdge = {
|
|
20
|
+
from: string;
|
|
21
|
+
to: string;
|
|
22
|
+
kind: GraphEdgeKind;
|
|
23
|
+
};
|
|
24
|
+
export type WorkflowGraph = {
|
|
25
|
+
nodes: GraphNode[];
|
|
26
|
+
edges: GraphEdge[];
|
|
27
|
+
};
|
|
28
|
+
/** The graph of `workflow`, computed from its JSON alone: nodes in document order (a node, then its descendants), and the
|
|
29
|
+
* edges between them. A value that is not a workflow, or a node the walk does not know, adds nothing and never throws:
|
|
30
|
+
* validation is `validateWorkflow`'s. */
|
|
31
|
+
export declare function workflowGraph(workflow: unknown): WorkflowGraph;
|
|
32
|
+
/** What a run has done at a node. A node inside a map's or a loop's body stands for every item or iteration, and the record names
|
|
33
|
+
* only those that started, so it is `done` only once the map or loop is: until then it is `working`, and a done node never
|
|
34
|
+
* goes back. A container (chain, parallel, map, loop, route, workflow) is `working` while some of
|
|
35
|
+
* its descendants are, or some are done and it is not; a node a run never reached, a branch a route did not take among
|
|
36
|
+
* them, is `not-run`. */
|
|
37
|
+
export type NodeState = "done" | "working" | "failed" | "not-run";
|
|
38
|
+
type Frame = {
|
|
39
|
+
done?: unknown;
|
|
40
|
+
steps?: unknown;
|
|
41
|
+
inputs?: unknown;
|
|
42
|
+
partial?: unknown;
|
|
43
|
+
};
|
|
44
|
+
/** The part of an `agentrun.items` value the status reads: the map item's `status` and its frame. */
|
|
45
|
+
export type ItemRecordLike = {
|
|
46
|
+
map?: unknown;
|
|
47
|
+
index?: unknown;
|
|
48
|
+
status?: unknown;
|
|
49
|
+
frame?: Frame;
|
|
50
|
+
};
|
|
51
|
+
/** What `nodeStatus` reads: a driver frame (the `pin` of a frozen snapshot: `done`, `steps`, `inputs`), a frozen snapshot
|
|
52
|
+
* (its `pin`), or the map items' records, alone or together with the driver's record (`{ pin, items }`). */
|
|
53
|
+
export type StatusSource = Frame | {
|
|
54
|
+
pin: Frame;
|
|
55
|
+
items?: readonly ItemRecordLike[];
|
|
56
|
+
} | readonly ItemRecordLike[];
|
|
57
|
+
/** `item`: the source is one map item's (or loop iteration's) record, read on its own, and this is its execution path
|
|
58
|
+
* (`<map path>/items/<index>`, `<loop path>/iterations/<index>`). That item is then the instance, not one of many: its body is done
|
|
59
|
+
* when the item is, whether or not the map is. A map or loop inside the item still stands for all of its own items. */
|
|
60
|
+
export type StatusOptions = {
|
|
61
|
+
item?: string;
|
|
62
|
+
};
|
|
63
|
+
/** For every node of `graph`, the state the record shows. `source` is what the driver kept: its frame and, in the keyed
|
|
64
|
+
* layout, the records of the map items (a run's whole story is the frame and the items together). A source that is not
|
|
65
|
+
* one of those shows no node run. */
|
|
66
|
+
export declare function nodeStatus(graph: WorkflowGraph, source: StatusSource, options?: StatusOptions): Record<string, NodeState>;
|
|
67
|
+
export {};
|
package/dist/graph.js
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
// The graph of a workflow document, and what a run has done in it. This module imports nothing, so a reader with no Node
|
|
2
|
+
// (the static viewer inlines it) and the pi session's text view draw the same graph; nothing here validates, runs or
|
|
3
|
+
// reads a store. `workflowGraph` reads the workflow JSON as written; `nodeStatus` reads the driver's record of a run
|
|
4
|
+
// (the `agentrun.driver` frame of the frozen snapshot, and the `agentrun.items` of a keyed-layout run) and says, for
|
|
5
|
+
// each node of that graph, whether it is done, working, failed or not run.
|
|
6
|
+
const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
7
|
+
const pointer = (part) => part.replace(/~/g, "~0").replace(/\//g, "~1");
|
|
8
|
+
/** The nesting depth `validateWorkflow` and `inspectWorkflow` accept (128 JSON levels): a node nests at least one level deeper than its parent, so every node of such a document is within it. */
|
|
9
|
+
const MAX_DEPTH = 128;
|
|
10
|
+
/** The graph of `workflow`, computed from its JSON alone: nodes in document order (a node, then its descendants), and the
|
|
11
|
+
* edges between them. A value that is not a workflow, or a node the walk does not know, adds nothing and never throws:
|
|
12
|
+
* validation is `validateWorkflow`'s. */
|
|
13
|
+
export function workflowGraph(workflow) {
|
|
14
|
+
const nodes = [];
|
|
15
|
+
const edges = [];
|
|
16
|
+
const visit = (node, path, depth) => {
|
|
17
|
+
if (!isObject(node) || typeof node.node !== "string" || depth > MAX_DEPTH)
|
|
18
|
+
return;
|
|
19
|
+
nodes.push({ path, kind: node.node, label: typeof node.label === "string" ? node.label : node.node,
|
|
20
|
+
...(node.node === "call" && typeof node.via === "string" ? { via: node.via } : {}) });
|
|
21
|
+
const child = (target, at, kind, from = path) => {
|
|
22
|
+
if (!isObject(target) || typeof target.node !== "string" || depth + 1 > MAX_DEPTH)
|
|
23
|
+
return;
|
|
24
|
+
edges.push({ from, to: at, kind });
|
|
25
|
+
visit(target, at, depth + 1);
|
|
26
|
+
};
|
|
27
|
+
switch (node.node) {
|
|
28
|
+
case "chain":
|
|
29
|
+
if (Array.isArray(node.steps))
|
|
30
|
+
node.steps.forEach((step, index) => child(step, `${path}/steps/${index}`, "next", index === 0 ? path : `${path}/steps/${index - 1}`));
|
|
31
|
+
break;
|
|
32
|
+
case "parallel":
|
|
33
|
+
if (Array.isArray(node.branches))
|
|
34
|
+
node.branches.forEach((branch, index) => child(branch, `${path}/branches/${index}`, "branch"));
|
|
35
|
+
break;
|
|
36
|
+
case "map":
|
|
37
|
+
child(node.body, `${path}/body`, "item");
|
|
38
|
+
break;
|
|
39
|
+
case "loop":
|
|
40
|
+
child(node.body, `${path}/body`, "next");
|
|
41
|
+
break;
|
|
42
|
+
case "route":
|
|
43
|
+
if (isObject(node.branches))
|
|
44
|
+
for (const [name, branch] of Object.entries(node.branches))
|
|
45
|
+
if (isObject(branch))
|
|
46
|
+
child(branch.body, `${path}/branches/${pointer(name)}/body`, "route");
|
|
47
|
+
break;
|
|
48
|
+
case "workflow":
|
|
49
|
+
if (isObject(node.workflow))
|
|
50
|
+
child(node.workflow.root, `${path}/workflow/root`, "child");
|
|
51
|
+
break;
|
|
52
|
+
}
|
|
53
|
+
};
|
|
54
|
+
visit(isObject(workflow) ? workflow.root : undefined, "/root", 0);
|
|
55
|
+
return { nodes, edges };
|
|
56
|
+
}
|
|
57
|
+
/** The execution path an instance of a node ran at, as the node's path in the document: a map's item and a loop's
|
|
58
|
+
* iteration have no node of their own. */
|
|
59
|
+
const definitionPath = (path) => path.replace(/\/items\/\d+\/body/g, "/body").replace(/\/iterations\/\d+(?=\/|$)/g, "");
|
|
60
|
+
const RANK = { working: 1, done: 2, failed: 3 };
|
|
61
|
+
/** For every node of `graph`, the state the record shows. `source` is what the driver kept: its frame and, in the keyed
|
|
62
|
+
* layout, the records of the map items (a run's whole story is the frame and the items together). A source that is not
|
|
63
|
+
* one of those shows no node run. */
|
|
64
|
+
export function nodeStatus(graph, source, options = {}) {
|
|
65
|
+
const instances = new Map();
|
|
66
|
+
const note = (path, state) => {
|
|
67
|
+
if (typeof path !== "string")
|
|
68
|
+
return;
|
|
69
|
+
const held = instances.get(path);
|
|
70
|
+
if (held === undefined || RANK[state] > RANK[held])
|
|
71
|
+
instances.set(path, state);
|
|
72
|
+
};
|
|
73
|
+
const readFrame = (frame) => {
|
|
74
|
+
if (!isObject(frame))
|
|
75
|
+
return;
|
|
76
|
+
if (isObject(frame.inputs))
|
|
77
|
+
for (const path of Object.keys(frame.inputs))
|
|
78
|
+
note(path, "working");
|
|
79
|
+
if (isObject(frame.steps))
|
|
80
|
+
for (const [path, step] of Object.entries(frame.steps)) {
|
|
81
|
+
const status = isObject(step) ? step.status : undefined;
|
|
82
|
+
note(path, status === "failed" ? "failed" : "working");
|
|
83
|
+
}
|
|
84
|
+
if (Array.isArray(frame.done))
|
|
85
|
+
for (const path of frame.done)
|
|
86
|
+
note(path, "done");
|
|
87
|
+
// A map that ended on an item's failure is kept as `partial` (its path and the finished items' results); no step or item says failed.
|
|
88
|
+
if (isObject(frame.partial) && typeof frame.partial.path === "string")
|
|
89
|
+
note(frame.partial.path, "failed");
|
|
90
|
+
};
|
|
91
|
+
const readItem = (item) => {
|
|
92
|
+
if (!isObject(item))
|
|
93
|
+
return;
|
|
94
|
+
readFrame(item.frame);
|
|
95
|
+
if (typeof item.map === "string" && Number.isInteger(item.index)) {
|
|
96
|
+
const body = `${item.map}/items/${item.index}/body`;
|
|
97
|
+
note(body, item.status === "committed" ? "done" : item.status === "failed" ? "failed" : "working");
|
|
98
|
+
}
|
|
99
|
+
};
|
|
100
|
+
const raw = source;
|
|
101
|
+
if (Array.isArray(raw))
|
|
102
|
+
raw.forEach(readItem);
|
|
103
|
+
else if (isObject(raw) && isObject(raw.pin)) {
|
|
104
|
+
readFrame(raw.pin);
|
|
105
|
+
if (Array.isArray(raw.items))
|
|
106
|
+
raw.items.forEach(readItem);
|
|
107
|
+
}
|
|
108
|
+
else
|
|
109
|
+
readFrame(raw);
|
|
110
|
+
// A done mark outranks a working one at the same path (a step's record stays after its node commits); a failure outranks both.
|
|
111
|
+
const byNode = new Map();
|
|
112
|
+
for (const [path, state] of instances) {
|
|
113
|
+
const at = definitionPath(path), list = byNode.get(at) ?? [];
|
|
114
|
+
list.push(state);
|
|
115
|
+
byNode.set(at, list);
|
|
116
|
+
}
|
|
117
|
+
const below = (path) => {
|
|
118
|
+
const found = [];
|
|
119
|
+
for (const [at, list] of byNode)
|
|
120
|
+
if (at.startsWith(`${path}/`))
|
|
121
|
+
found.push(...list);
|
|
122
|
+
return found;
|
|
123
|
+
};
|
|
124
|
+
const out = {};
|
|
125
|
+
for (const node of graph.nodes) {
|
|
126
|
+
const own = byNode.get(node.path) ?? [], inside = below(node.path);
|
|
127
|
+
out[node.path] = own.includes("failed") || inside.includes("failed") ? "failed"
|
|
128
|
+
: own.length && own.every((state) => state === "done") ? "done"
|
|
129
|
+
: own.includes("working") || inside.includes("working") ? "working"
|
|
130
|
+
: inside.length ? "working"
|
|
131
|
+
: own.length ? "working"
|
|
132
|
+
: "not-run";
|
|
133
|
+
}
|
|
134
|
+
// A chain is never recorded as done itself: the driver commits its steps. It is done when its steps all are, which a
|
|
135
|
+
// run that ended on its last step shows. Children are finished before their parents: the nodes are walked from the end.
|
|
136
|
+
for (const node of [...graph.nodes].reverse()) {
|
|
137
|
+
if (node.kind !== "chain" || byNode.has(node.path))
|
|
138
|
+
continue;
|
|
139
|
+
const prefix = `${node.path}/steps/`;
|
|
140
|
+
const steps = graph.nodes.filter((other) => other.path.startsWith(prefix) && /^\d+$/.test(other.path.slice(prefix.length)));
|
|
141
|
+
if (steps.length && steps.every((step) => out[step.path] === "done"))
|
|
142
|
+
out[node.path] = "done";
|
|
143
|
+
}
|
|
144
|
+
// A node inside a map's or a loop's body stands for every item or iteration, and the record names only those that started: it is
|
|
145
|
+
// done only when the map or loop is. Parents come before their descendants in the node list, so the container is settled first.
|
|
146
|
+
// The map or loop an `item` belongs to is the exception, and so is every one that encloses it: that item is the instance, and
|
|
147
|
+
// the source holds nothing of the items around it. A map or loop inside the item still stands for its own items.
|
|
148
|
+
const owner = typeof options.item === "string" ? definitionPath(options.item.replace(/\/(?:items|iterations)\/\d+$/, "")) : undefined;
|
|
149
|
+
const containers = graph.nodes.filter((node) => (node.kind === "map" || node.kind === "loop")
|
|
150
|
+
&& !(owner !== undefined && (node.path === owner || owner.startsWith(`${node.path}/body`))));
|
|
151
|
+
for (const node of graph.nodes) {
|
|
152
|
+
if (out[node.path] !== "done")
|
|
153
|
+
continue;
|
|
154
|
+
if (containers.some((container) => node.path.startsWith(`${container.path}/body`) && out[container.path] !== "done"))
|
|
155
|
+
out[node.path] = "working";
|
|
156
|
+
}
|
|
157
|
+
return out;
|
|
158
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
export { defineWorkflow, runTypedWorkflow, WorkflowSchemaConversionError } from "./authoring.js";
|
|
2
2
|
export type { StandardJSONSchema, AuthoringSchema, TypedWorkflow, TypedWorkflowRunResult, WorkflowInput, WorkflowOutput, } from "./authoring.js";
|
|
3
3
|
export { runWorkflow, validateWorkflow, workflowSha256, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, WorkflowVerificationError, WorkflowDecisionRecordError, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal, routesByValue, } from "./workflow.js";
|
|
4
|
+
export { defineJob } from "./job.js";
|
|
5
|
+
export type { Job } from "./job.js";
|
|
4
6
|
export { DECISION_RECEIPT_VERSION, rederiveDecision } from "./decision-receipts.js";
|
|
5
7
|
export type { DecisionKind, DecisionReceipt, DecisionRule } from "./decision-receipts.js";
|
|
6
8
|
export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowEvent, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, DecisionExchange, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, RouteByJudgmentNode, RouteByValueNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CodeNode, CallRetryClass, EffectFailureCode, CallPredicate, PollClause, ModelTier, AgentContext, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, MechanicalPredicate, Predicate, } from "./workflow.js";
|
|
7
9
|
export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
|
|
8
10
|
export type { DryRunOptions, DryRunResult } from "./dry-run.js";
|
|
9
11
|
export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, } from "./system-one.js";
|
|
10
|
-
export type { SystemOneQuestion, SystemOneAnswer, SystemOneResult, SystemOneRetryClass, SystemOneResponseReason, CompiledQuestions, AnswersSidecar, } from "./system-one.js";
|
|
12
|
+
export type { SystemOneQuestion, SystemOneAnswer, SystemOneBox, SystemOneResult, SystemOneRetryClass, SystemOneResponseReason, CompiledQuestions, AnswersSidecar, } from "./system-one.js";
|
|
11
13
|
export { inspectWorkflow, formatWorkflowTree } from "./inspection.js";
|
|
12
14
|
export type { WorkflowInspection, WorkflowInspectionNode } from "./inspection.js";
|
|
13
15
|
export { runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, stageSchemaForNode, submissionSchemaForNode, mergeStageDelta, REPORT_SCHEMA, SHELL_RESULT_SCHEMA, childSteps, declaredWrites, terminalArtifactType, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY, buildReferenceContext, normalizeStringNullsForSchema, parseCsvRows, } from "./workflow.js";
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
export { defineWorkflow, runTypedWorkflow, WorkflowSchemaConversionError } from "./authoring.js";
|
|
2
2
|
export { runWorkflow, validateWorkflow, workflowSha256, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, WorkflowVerificationError, WorkflowDecisionRecordError, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal, routesByValue, } from "./workflow.js";
|
|
3
|
+
export { defineJob } from "./job.js";
|
|
3
4
|
export { DECISION_RECEIPT_VERSION, rederiveDecision } from "./decision-receipts.js";
|
|
4
5
|
export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
|
|
5
6
|
export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, } from "./system-one.js";
|
package/dist/job.d.ts
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import type { Workflow } from "./workflow.js";
|
|
2
|
+
/** A unit of work a host runs: the workflow, the input it runs on, and the files it starts with (by path, as bytes). */
|
|
3
|
+
export type Job = {
|
|
4
|
+
workflow: Workflow;
|
|
5
|
+
input: Record<string, unknown>;
|
|
6
|
+
files?: Record<string, Uint8Array>;
|
|
7
|
+
};
|
|
8
|
+
/** Returns `job` itself. It checks the job's shape and keeps the workflow's literal type, so a job written beside a workflow
|
|
9
|
+
* declared `as const satisfies Workflow` still names the workflow's literal values. */
|
|
10
|
+
export declare function defineJob<const W extends Workflow>(job: {
|
|
11
|
+
workflow: W;
|
|
12
|
+
input: Record<string, unknown>;
|
|
13
|
+
files?: Record<string, Uint8Array>;
|
|
14
|
+
}): typeof job;
|
package/dist/job.js
ADDED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
/** SHA-256 of a value's JSON with every object's keys sorted: the identity of a binding, an input,
|
|
1
|
+
/** SHA-256 of a value's JSON with every object's keys sorted (`canonicalJson`): the identity of a binding, an input,
|
|
2
2
|
* an intent's arguments or a set of file hashes, independent of key order. */
|
|
3
3
|
export declare const canonicalHash: (value: unknown) => string;
|
|
4
4
|
/** SHA-256 of a value serialized with sorted keys: an identity for a contract a host persists. Not interchangeable
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
|
-
|
|
2
|
+
import { canonicalJson } from "./item-state.js";
|
|
3
|
+
/** SHA-256 of a value's JSON with every object's keys sorted (`canonicalJson`): the identity of a binding, an input,
|
|
3
4
|
* an intent's arguments or a set of file hashes, independent of key order. */
|
|
4
|
-
export const canonicalHash = (value) => createHash("sha256").update(
|
|
5
|
-
? Object.fromEntries(Object.keys(item).sort().map(key => [key, item[key]])) : item)).digest("hex");
|
|
5
|
+
export const canonicalHash = (value) => createHash("sha256").update(canonicalJson(value)).digest("hex");
|
|
6
6
|
function canonical(value) {
|
|
7
7
|
if (value === null || typeof value !== "object")
|
|
8
8
|
return JSON.stringify(value);
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { RouteNode, Workflow, WorkflowDeps, WorkflowNode } from "../workflow.js";
|
|
2
|
-
import { type RouteDecision, type QuestionReceipts, type StepRecord, type EscalationRow } from "./frozen-snapshot.js";
|
|
2
|
+
import { FROZEN_SNAPSHOT_SCHEMA, FROZEN_SNAPSHOT_SCHEMA_V4, type RouteDecision, type QuestionReceipts, type StepRecord, type EscalationRow } from "./frozen-snapshot.js";
|
|
3
3
|
import type { RecoveryBinding, RecoveryEffect, RecoveryStore } from "./store.js";
|
|
4
4
|
/** The branch a route runs for its answer, as the interpreter takes it: the node's `unsure` branch when
|
|
5
5
|
* the answer's confidence is below `unsure.gte`, else the choice the answer names. */
|
|
@@ -65,6 +65,21 @@ export type RecoveryOptions = {
|
|
|
65
65
|
};
|
|
66
66
|
calls?: unknown[];
|
|
67
67
|
}) => Promise<void>) => Promise<void>;
|
|
68
|
+
/** How a new run, or one stored whole, is kept. `"v3"` (the default in this release) keeps the driver's whole state in
|
|
69
|
+
* one record, rewritten at every commit, so a map's commits grow with the square of its items. `"v4"`, the keyed
|
|
70
|
+
* layout, keeps what lies in each map item in that item's record and each state the driver references once by its
|
|
71
|
+
* digest (a failed map's finished results too), so a commit writes what it changed: a run stored whole moves to it at
|
|
72
|
+
* its first commit. After that move, the checkpoint bases of the driver's record keep the ids of the effects admitted
|
|
73
|
+
* before it: a cost bounded by the work done before the move, which later commits do not grow; each commit after the
|
|
74
|
+
* move costs the same however many items the map has. Only a store that
|
|
75
|
+
* keeps parts (its opened journal has `items` and `stateOf`) can hold it; on any other the driver keeps `"v3"` and says
|
|
76
|
+
* why once per open, in a `layout` note. A run stored in the keyed layout stays in it whatever this says, and a driver
|
|
77
|
+
* that knows only `"v3"` refuses to open it (`FROZEN_CHECKPOINT_INVALID`). Release 0.1.0-beta.13 and earlier fail their
|
|
78
|
+
* own task on a run in the keyed layout and report it refused; that ends the run's agent nodes in flight, and the run
|
|
79
|
+
* then fails on this release too, with no call repeated and nothing corrupted. So opt in only when no process on an
|
|
80
|
+
* earlier release can open the run. A build from this release on leaves a run stored in a schema newer than it knows
|
|
81
|
+
* pending (`RECOVERY_SCHEMA_NEWER`), for a build that knows it. */
|
|
82
|
+
layout?: "v3" | "v4";
|
|
68
83
|
};
|
|
69
84
|
/** What a host's effect adapter receives under the driver: the interpreter's parameters, `call`, which keeps each
|
|
70
85
|
* outside call the effect makes on its record as the call ends, and `effect`, the admitted effect: its journal id and
|
|
@@ -101,6 +116,11 @@ export declare function openRecovery(store: RecoveryStore, workflow: Workflow, o
|
|
|
101
116
|
message: string;
|
|
102
117
|
label: string;
|
|
103
118
|
} | null;
|
|
119
|
+
/** How this open keeps the run: the layout's schema, and why it is not the keyed one the host asked for. */
|
|
120
|
+
readonly layout: {
|
|
121
|
+
schema: typeof FROZEN_SNAPSHOT_SCHEMA | typeof FROZEN_SNAPSHOT_SCHEMA_V4;
|
|
122
|
+
reason?: string;
|
|
123
|
+
};
|
|
104
124
|
binding: string;
|
|
105
125
|
/** The run's key: what its step sessions and effects are named under. */
|
|
106
126
|
driverId: string;
|