@parcha/agentrun-dsl 0.1.0-beta.5 → 0.1.0-beta.8
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 +13 -9
- package/dist/author.js +12 -7
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/dry-run.d.ts +4 -1
- package/dist/dry-run.js +2 -1
- package/dist/index.d.ts +3 -3
- package/dist/index.js +2 -2
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/vocabulary.d.ts +8 -0
- package/dist/vocabulary.js +13 -2
- package/dist/workflow-shape.js +1 -1
- package/dist/workflow.d.ts +41 -5
- package/dist/workflow.js +89 -36
- package/package.json +1 -1
- package/schema/workflow.schema.json +38 -13
- package/skills/author/references/language.md +10 -8
package/README.md
CHANGED
|
@@ -36,11 +36,13 @@ The package root exports a deliberate API. The beta retains agent, structured-ou
|
|
|
36
36
|
| Run and inspect | `runWorkflow`, `validateWorkflow`, `workflowSha256`, `dryRunWorkflow`; core contracts `Workflow`, `WorkflowNode`, `WorkflowDeps`, `WorkflowRunResult`, plus the named node, predicate, effect, effort and result types. |
|
|
37
37
|
| Recognize outcomes | `WorkflowInvalidError`, `WorkflowInputInvalidError`, `WorkflowOutputInvalidError`, `WorkflowVerificationError`, `EffectFailure`, `EffectDeadlineExceededError`, `EffectOutcomeUnknownError`, `EscalationSignal`. A concurrent failure may contain typed outcomes in `AggregateError.errors`; inspect them before deciding whether an effect is safe to retry. |
|
|
38
38
|
| Build judgment adapters | `compileQuestions`, `validateAnswers`, `answersToValue`, `answersSidecar`, `answerConfidence`, `SYSTEM_ONE_LIMITS`, `SystemOneError`; `SystemOneQuestion`, `SystemOneAnswer`, `SystemOneResult`, `SystemOneRetryClass`, `CompiledQuestions`, `AnswersSidecar`. |
|
|
39
|
-
| Integrate a host | `runWorkflowSlice`, `assertWorkflowCapabilities`, `desugarWorkflow`, `resolveSchemaForWorkflow`, `stageSchemaForNode`, `submissionSchemaForNode`, `mergeStageDelta`, `REPORT_SCHEMA`, `SHELL_RESULT_SCHEMA`, `getPath`, `predicateMatches`. |
|
|
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
|
-
| 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`, `PROSE_ARTIFACT_TYPES`; `WorkflowNodeKind`, `WorkflowPredicateName`. The validator and the author contract read these same constants. |
|
|
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
42
|
| Test without a model | `synthesizeInstance`, `synthesizeAnswers`, `DryRunOptions`, `DryRunResult`. Synthetic answers exercise execution mechanics; they do not establish judgment quality. |
|
|
43
43
|
|
|
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
|
+
|
|
44
46
|
`runWorkflowSlice` runs selected root steps against supplied state and optional seed data. It returns the slice state without checking the full workflow's terminal output contract. Use `runWorkflow` for a complete run. `getPath` reads dot-separated record keys and canonical in-bounds array indexes, returning `undefined` when a segment cannot be resolved. `predicateMatches` evaluates mechanical predicates only; use `field_equals` with an explicit path for a stored label.
|
|
45
47
|
|
|
46
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.
|
|
@@ -51,17 +53,19 @@ Children can contain maps, loops, routes, parallel branches and other children,
|
|
|
51
53
|
|
|
52
54
|
## Bounds
|
|
53
55
|
|
|
54
|
-
These are the current beta's validation
|
|
56
|
+
These are the current beta's validation rules. The numeric knobs below carry no upper ceiling: the author picks the number, and a host may set its own default, but the validator never caps how high it goes. What remains are lower bounds and structural requirements — a floor a value must sit at or above, a field that must be present — plus the parser's own safety guards, and the System-One question shape (a bounded multiple choice). Hosts may still impose their own budgets as defaults.
|
|
55
57
|
|
|
56
58
|
| Setting | Bound |
|
|
57
59
|
| --- | --- |
|
|
58
60
|
| Document traversal | At most 100,000 visited values and 128 levels of object nesting; cycles, accessors and proxies rejected |
|
|
59
|
-
| `loop.maxIters` | Integer 1
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `call.
|
|
63
|
-
| `call.
|
|
64
|
-
| `call.
|
|
61
|
+
| `loop.maxIters` | Integer >= 1 |
|
|
62
|
+
| `loop.expect_iters` | Integer >= 1, optional (gate prices the loop at this; default the floor) |
|
|
63
|
+
| `verify.maxDrives` | Integer >= 1; default 2 |
|
|
64
|
+
| `call.deadline_s` | Required; a finite number greater than 0 seconds |
|
|
65
|
+
| `call.retry.attempts` | Integer >= 1, including the first attempt |
|
|
66
|
+
| `call.retry.backoff_s` | Finite number >= 0 |
|
|
67
|
+
| `call.poll.interval_s` | Finite number, at least 0.1 seconds (busy-loop guard) |
|
|
68
|
+
| `call.poll.deadline_s` | Finite number, at least the call deadline |
|
|
65
69
|
| Choice options / route branches | At most 240; `pick.allowNone` reserves one option |
|
|
66
70
|
| Score rubric | 2–10 levels, indexed from 0 |
|
|
67
71
|
| Questions per judgment request | Default 256; override with host-owned `WorkflowDeps.maxQuestionsPerRequest` |
|
package/dist/author.js
CHANGED
|
@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
|
|
|
5
5
|
import { join, resolve } from "node:path";
|
|
6
6
|
import { validateWorkflow } from "./workflow.js";
|
|
7
7
|
import { SYSTEM_ONE_LIMITS } from "./system-one.js";
|
|
8
|
-
import { WORKFLOW_NODE_KINDS, NODE_FIELDS, WORKFLOW_PREDICATES, PREDICATE_FIELDS, MECHANICAL_PREDICATES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, } from "./vocabulary.js";
|
|
8
|
+
import { WORKFLOW_NODE_KINDS, NODE_FIELDS, WORKFLOW_PREDICATES, PREDICATE_FIELDS, MECHANICAL_PREDICATES, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, } from "./vocabulary.js";
|
|
9
9
|
const code = (value) => `\`${value}\``;
|
|
10
10
|
const list = (values) => values.map(code).join(", ");
|
|
11
11
|
const alternatives = (values) => values.join("|");
|
|
@@ -59,9 +59,10 @@ Their fields:
|
|
|
59
59
|
- ${code("out")} names the schema the submission must satisfy; the value lands at ${code("as")}.
|
|
60
60
|
- ${code("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; ${code("false")} and ${code("0")} pass.
|
|
61
61
|
- ${code("tools")} names tools the host offers. ${code("[]")} means no tools; omitting ${code("tools")} offers every tool the host allows. Never name a tool the host did not offer.
|
|
62
|
-
- ${code("effort")} is ${alternatives(EFFORT_LEVELS)}; ${code("thinking")} is ${alternatives(THINKING_LEVELS)} (never off); ${code("tier")} is ${alternatives(MODEL_TIERS)}. They are requests to the host: resource ceilings are the host's
|
|
62
|
+
- ${code("effort")} is ${alternatives(EFFORT_LEVELS)}; ${code("thinking")} is ${alternatives(THINKING_LEVELS)} (never off); ${code("tier")} is ${alternatives(MODEL_TIERS)}. They are requests to the host: resource ceilings are the host's.
|
|
63
|
+
- An ${code("agent")} node may carry ${code("budget_usd")}, the most it asks to spend in dollars (above 0), which the host caps by what it has left, and ${code("context")}, ${alternatives(AGENT_CONTEXTS)}: ${code("fresh")} (the default) sees only its instructions and state; ${code("fork")} asks the host to start it from the caller's transcript, which a host refuses where it has none.
|
|
63
64
|
- ${code("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.
|
|
64
|
-
- ${code("verify")} reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: 1
|
|
65
|
+
- ${code("verify")} reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: an integer >= 1 (default 2, no maximum), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below ${code("override.below")}; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
|
|
65
66
|
- When the workflow has a report, no decide or extract ${code("out")} schema carries ${code("report_markdown")}.
|
|
66
67
|
|
|
67
68
|
### Terminal nodes: report and artifact
|
|
@@ -85,21 +86,22 @@ Typed questions answered by the host's judge in one request each: no tools, no s
|
|
|
85
86
|
- ${code("chain")}: non-empty ${code("steps")}, run in order.
|
|
86
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
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.
|
|
88
|
-
- ${code("loop")}: ${code("body")}, ${code("until")} (a predicate) and an integer ${code("maxIters")}
|
|
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.
|
|
89
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.
|
|
90
91
|
- ${code("workflow")}: ${code("label")}, ${code("workflow")} (a complete inline child), ${code("input")} (an object, interpolated, the child's entire initial state), ${code("out")} (a parent schema checked against the child's output) and ${code("as")}. The child declares ${code("input.schemaId")} in its own schemas and contains no report or artifact.
|
|
91
92
|
- ${code("code")}: ${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. ${code("Date")}, ${code("Promise")}, timers, ${code("fetch")}, ${code("require")}, ${code("process")}, ${code("Function")} and ${code("globalThis")} are unavailable. It is trusted host JavaScript, not a sandbox. Use code for typed-state mechanics, never to read meaning from prose.
|
|
92
|
-
- ${code("call")}: one side effect with no model in the loop. ${code("via")} is ${alternatives(CALL_TRANSPORTS)}; ${code("as")} and ${code("deadline_s")} (greater than 0,
|
|
93
|
+
- ${code("call")}: one side effect with no model in the loop. ${code("via")} is ${alternatives(CALL_TRANSPORTS)}; ${code("as")} and ${code("deadline_s")} (a finite number greater than 0, no maximum) are required — an unbounded effect is how a stalled provider becomes a stalled job.
|
|
93
94
|
- ${code("via: tool")} takes ${code("tool")} (a host tool address), ${code("args")} (an object) and ${code("out")} (the tool's result schema).
|
|
94
95
|
- ${code("via: executor")} takes ${code("code")} (a body that returns its JSON result and uses only ${code("tools")} and ${code("input")}), ${code("input")} and ${code("out")}.
|
|
95
96
|
- ${code("via: shell")} takes ${code("command")} (literal) and ${code("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 ${code("out")}. Only a shell call may declare ${code("produces")} (workspace-relative files, checked after the effect).
|
|
96
|
-
- ${code("retry")} {attempts: 1
|
|
97
|
-
- ${code("poll")} {until, fail_when?, interval_s: 0.1
|
|
97
|
+
- ${code("retry")} {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [${[...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES].join(", ")}]}. ${code("where")} accepts only "sandbox".
|
|
98
|
+
- ${code("poll")} {until, fail_when?, interval_s: >= 0.1 (a busy-loop guard), deadline_s: at least the call's deadline_s (no maximum)} repeats the call until ${code("until")} holds on its own result; ${code("fail_when")} fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
|
|
98
99
|
- Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
|
|
99
100
|
|
|
100
101
|
## Predicates
|
|
101
102
|
|
|
102
103
|
${code("loop.until")} and ${code("escalate.when")} take one of these; ${code("poll")} takes only the first ${MECHANICAL_PREDICATES.length}. Each path or key reads a state value an input or an earlier node produced.
|
|
104
|
+
A predicate is one JSON object that names itself in its ${code("predicate")} field beside its own fields, for example ${code('{"predicate": "field_true", "path": "review.approved"}')}.
|
|
103
105
|
${predicateLines()}
|
|
104
106
|
|
|
105
107
|
## Authority
|
|
@@ -161,6 +163,9 @@ export function candidatePolicyErrors(candidate, options) {
|
|
|
161
163
|
errors.push(`${String(node.label ?? kind)}: this host does not run ${String(kind)} nodes`);
|
|
162
164
|
if (!options.allowExecutableCandidates && ["code", "call", "artifact"].includes(String(kind)) && !(kind === "call" && node.via === "tool" && typeof node.tool === "string" && options.allowedEffectTools?.includes(node.tool)))
|
|
163
165
|
errors.push(`${kind} requires allowExecutableCandidates`);
|
|
166
|
+
// `budget` on an agent is accepted for older documents and never read: an author writes budget_usd.
|
|
167
|
+
if (kind === "agent" && Object.hasOwn(node, "budget"))
|
|
168
|
+
errors.push(`${String(node.label ?? kind)}: budget is not read; declare budget_usd, the dollars the node asks to spend`);
|
|
164
169
|
if (sections.length && JUDGMENT_NODE_KINDS.includes(String(kind)))
|
|
165
170
|
errors.push(`${String(kind)} cannot carry supplied SOP sections; use an LLM node with sopSection`);
|
|
166
171
|
const llm = GENERATIVE_NODE_KINDS.includes(String(kind));
|
package/dist/code-exec.d.ts
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
/** The denied globals a transform's source names, in DENIED_GLOBALS order: a lexical scan of the source
|
|
2
|
+
* that skips comments, string and template text and regular-expression literals, and ignores a name
|
|
3
|
+
* read as a property (after `.` or `?.`). A name used as an object key or a local binding is still
|
|
4
|
+
* named: the lint refuses rather than guesses. It is a lint for untrusted authors, never a boundary:
|
|
5
|
+
* a host that runs such code isolates it (deps.runCode). */
|
|
6
|
+
export declare function deniedGlobalReferences(src: string): string[];
|
|
1
7
|
/** Parse the same expression as trusted execution, without evaluating it or calling its body.
|
|
2
8
|
* Syntax validity does not prove that the expression produces a function or a valid patch. */
|
|
3
9
|
export declare function compileTransformSyntax(src: string): void;
|
package/dist/code-exec.js
CHANGED
|
@@ -10,6 +10,132 @@ const DENIED_GLOBALS = [
|
|
|
10
10
|
"fetch", "XMLHttpRequest", "Function", "Buffer",
|
|
11
11
|
"setTimeout", "setInterval", "setImmediate", "queueMicrotask", "Promise", "Date",
|
|
12
12
|
];
|
|
13
|
+
/** Words after which a `/` starts a regular expression rather than a division. */
|
|
14
|
+
const REGEX_AFTER_WORDS = new Set(["return", "typeof", "instanceof", "in", "of", "new", "delete", "void", "throw", "case", "do", "else", "yield", "await"]);
|
|
15
|
+
const IDENTIFIER_START = /[A-Za-z_$\u0080-\uffff]/;
|
|
16
|
+
const IDENTIFIER_PART = /[A-Za-z0-9_$\u0080-\uffff]/;
|
|
17
|
+
/** The denied globals a transform's source names, in DENIED_GLOBALS order: a lexical scan of the source
|
|
18
|
+
* that skips comments, string and template text and regular-expression literals, and ignores a name
|
|
19
|
+
* read as a property (after `.` or `?.`). A name used as an object key or a local binding is still
|
|
20
|
+
* named: the lint refuses rather than guesses. It is a lint for untrusted authors, never a boundary:
|
|
21
|
+
* a host that runs such code isolates it (deps.runCode). */
|
|
22
|
+
export function deniedGlobalReferences(src) {
|
|
23
|
+
const denied = new Set(DENIED_GLOBALS);
|
|
24
|
+
const found = new Set();
|
|
25
|
+
const braces = [];
|
|
26
|
+
const n = typeof src === "string" ? src.length : 0;
|
|
27
|
+
let i = 0;
|
|
28
|
+
// The previous significant token: a word, a value (literal, closing bracket), or punctuation.
|
|
29
|
+
let prev = null;
|
|
30
|
+
/** Template text from i: true when it stopped at `${` (code follows), false at its closing backtick. */
|
|
31
|
+
const templateText = () => {
|
|
32
|
+
while (i < n) {
|
|
33
|
+
if (src[i] === "\\") {
|
|
34
|
+
i += 2;
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (src[i] === "`") {
|
|
38
|
+
i += 1;
|
|
39
|
+
return false;
|
|
40
|
+
}
|
|
41
|
+
if (src[i] === "$" && src[i + 1] === "{") {
|
|
42
|
+
i += 2;
|
|
43
|
+
braces.push("template");
|
|
44
|
+
return true;
|
|
45
|
+
}
|
|
46
|
+
i += 1;
|
|
47
|
+
}
|
|
48
|
+
return false;
|
|
49
|
+
};
|
|
50
|
+
while (i < n) {
|
|
51
|
+
const c = src[i];
|
|
52
|
+
if (/\s/.test(c)) {
|
|
53
|
+
i += 1;
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
if (c === "/" && src[i + 1] === "/") {
|
|
57
|
+
const end = src.indexOf("\n", i);
|
|
58
|
+
i = end < 0 ? n : end;
|
|
59
|
+
continue;
|
|
60
|
+
}
|
|
61
|
+
if (c === "/" && src[i + 1] === "*") {
|
|
62
|
+
const end = src.indexOf("*/", i + 2);
|
|
63
|
+
i = end < 0 ? n : end + 2;
|
|
64
|
+
continue;
|
|
65
|
+
}
|
|
66
|
+
if (c === "'" || c === '"') {
|
|
67
|
+
i += 1;
|
|
68
|
+
while (i < n && src[i] !== c)
|
|
69
|
+
i += src[i] === "\\" ? 2 : 1;
|
|
70
|
+
i += 1;
|
|
71
|
+
prev = { kind: "value", text: c };
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
if (c === "`" || (c === "}" && braces[braces.length - 1] === "template")) {
|
|
75
|
+
if (c === "}")
|
|
76
|
+
braces.pop();
|
|
77
|
+
i += 1;
|
|
78
|
+
prev = templateText() ? null : { kind: "value", text: "`" };
|
|
79
|
+
continue;
|
|
80
|
+
}
|
|
81
|
+
if (c === "/") {
|
|
82
|
+
const regex = prev === null || (prev.kind === "punct" && !")]}".includes(prev.text)) || (prev.kind === "word" && REGEX_AFTER_WORDS.has(prev.text));
|
|
83
|
+
if (regex) {
|
|
84
|
+
i += 1;
|
|
85
|
+
let inClass = false;
|
|
86
|
+
while (i < n && (inClass || src[i] !== "/")) {
|
|
87
|
+
if (src[i] === "\\") {
|
|
88
|
+
i += 2;
|
|
89
|
+
continue;
|
|
90
|
+
}
|
|
91
|
+
if (src[i] === "[")
|
|
92
|
+
inClass = true;
|
|
93
|
+
else if (src[i] === "]")
|
|
94
|
+
inClass = false;
|
|
95
|
+
i += 1;
|
|
96
|
+
}
|
|
97
|
+
i += 1;
|
|
98
|
+
while (i < n && IDENTIFIER_PART.test(src[i]))
|
|
99
|
+
i += 1;
|
|
100
|
+
prev = { kind: "value", text: "/" };
|
|
101
|
+
continue;
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
if (IDENTIFIER_START.test(c)) {
|
|
105
|
+
const start = i;
|
|
106
|
+
while (i < n && IDENTIFIER_PART.test(src[i]))
|
|
107
|
+
i += 1;
|
|
108
|
+
const word = src.slice(start, i);
|
|
109
|
+
if (denied.has(word) && !(prev?.kind === "punct" && prev.text === "."))
|
|
110
|
+
found.add(word);
|
|
111
|
+
prev = { kind: "word", text: word };
|
|
112
|
+
continue;
|
|
113
|
+
}
|
|
114
|
+
if (/[0-9]/.test(c)) {
|
|
115
|
+
while (i < n && IDENTIFIER_PART.test(src[i]))
|
|
116
|
+
i += 1;
|
|
117
|
+
prev = { kind: "value", text: "0" };
|
|
118
|
+
continue;
|
|
119
|
+
}
|
|
120
|
+
if (c === "." && src.startsWith("...", i)) {
|
|
121
|
+
i += 3;
|
|
122
|
+
prev = { kind: "punct", text: "..." };
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
if (c === "?" && src[i + 1] === "." && !/[0-9]/.test(src[i + 2] ?? "")) {
|
|
126
|
+
i += 2;
|
|
127
|
+
prev = { kind: "punct", text: "." };
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
if (c === "{")
|
|
131
|
+
braces.push("brace");
|
|
132
|
+
if (c === "}")
|
|
133
|
+
braces.pop();
|
|
134
|
+
i += 1;
|
|
135
|
+
prev = c === ")" || c === "]" || c === "}" ? { kind: "value", text: c } : { kind: "punct", text: c };
|
|
136
|
+
}
|
|
137
|
+
return DENIED_GLOBALS.filter((name) => found.has(name));
|
|
138
|
+
}
|
|
13
139
|
function createTransformFactory(src) {
|
|
14
140
|
if (typeof src !== "string" || !src.trim())
|
|
15
141
|
throw new Error("code transform source must be a non-empty string");
|
package/dist/dry-run.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { type Workflow } from "./workflow.js";
|
|
1
|
+
import { type Workflow, type WorkflowDeps } from "./workflow.js";
|
|
2
2
|
export type DryRunResult = {
|
|
3
3
|
ok: true;
|
|
4
4
|
skipped?: string[];
|
|
@@ -15,5 +15,8 @@ export type DryRunOptions = {
|
|
|
15
15
|
references_parsed?: Record<string, unknown>;
|
|
16
16
|
};
|
|
17
17
|
input?: Record<string, unknown>;
|
|
18
|
+
/** The host's executor for `code` nodes (WorkflowDeps.runCode). Present, the dry run validates
|
|
19
|
+
* with executeCode:false and hands every code node to it, so no code body runs in this process. */
|
|
20
|
+
runCode?: WorkflowDeps["runCode"];
|
|
18
21
|
};
|
|
19
22
|
export declare function dryRunWorkflow(workflow: Workflow, opts?: DryRunOptions): Promise<DryRunResult>;
|
package/dist/dry-run.js
CHANGED
|
@@ -116,7 +116,7 @@ function unsupportedConstructs(schema, path, found, depth = 0) {
|
|
|
116
116
|
return found;
|
|
117
117
|
}
|
|
118
118
|
export async function dryRunWorkflow(workflow, opts = {}) {
|
|
119
|
-
const valid = validateWorkflow(workflow, opts.input === undefined ?
|
|
119
|
+
const valid = validateWorkflow(workflow, { ...(opts.input === undefined ? {} : { input: opts.input }), ...(opts.runCode ? { executeCode: false } : {}) });
|
|
120
120
|
if (!valid.ok)
|
|
121
121
|
return { ok: false, problems: [new WorkflowInvalidError(String(workflow?.name), valid.errors).message] };
|
|
122
122
|
const skipped = [];
|
|
@@ -159,6 +159,7 @@ export async function dryRunWorkflow(workflow, opts = {}) {
|
|
|
159
159
|
try {
|
|
160
160
|
const result = await runWorkflow(workflow, input, {
|
|
161
161
|
sop: opts.sop,
|
|
162
|
+
...(opts.runCode ? { runCode: opts.runCode } : {}),
|
|
162
163
|
onEvent: (event) => { if (typeof event.label === "string")
|
|
163
164
|
currentLabel = event.label; },
|
|
164
165
|
runNode: async ({ schema, review }) => {
|
package/dist/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
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, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal, } from "./workflow.js";
|
|
4
|
-
export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CallRetryClass, CallPredicate, PollClause, ModelTier, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, MechanicalPredicate, Predicate, } from "./workflow.js";
|
|
4
|
+
export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CodeNode, CallRetryClass, EffectFailureCode, CallPredicate, PollClause, ModelTier, AgentContext, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, MechanicalPredicate, Predicate, } from "./workflow.js";
|
|
5
5
|
export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
|
|
6
6
|
export type { DryRunOptions, DryRunResult } from "./dry-run.js";
|
|
7
7
|
export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, } from "./system-one.js";
|
|
@@ -9,11 +9,11 @@ export type { SystemOneQuestion, SystemOneAnswer, SystemOneResult, SystemOneRetr
|
|
|
9
9
|
export { inspectWorkflow, formatWorkflowTree } from "./inspection.js";
|
|
10
10
|
export type { WorkflowInspection, WorkflowInspectionNode } from "./inspection.js";
|
|
11
11
|
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";
|
|
12
|
-
export { compileTransform, compileTransformSyntax } from "./code-exec.js";
|
|
12
|
+
export { compileTransform, compileTransformSyntax, deniedGlobalReferences } from "./code-exec.js";
|
|
13
13
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
14
14
|
export { getPath, predicateMatches } from "./predicates.js";
|
|
15
15
|
export type { StopPredicate, AcceptPredicate } from "./predicates.js";
|
|
16
16
|
export { authorContract, renderAuthorContract, renderAuthorHostAddendum, candidatePolicyErrors, applyHostOutputTypes, authorWorkflow, AUTHOR_SKILL_NAME, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
|
|
17
17
|
export type { AuthorHostAddendum, CandidatePolicyOptions, AuthorWorkflowOptions, AuthoredWorkflow } from "./author.js";
|
|
18
|
-
export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
|
|
18
|
+
export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
|
|
19
19
|
export type { WorkflowNodeKind, WorkflowPredicateName } from "./vocabulary.js";
|
package/dist/index.js
CHANGED
|
@@ -8,8 +8,8 @@ export { runWorkflowSlice, assertWorkflowCapabilities, desugarWorkflow, stageSch
|
|
|
8
8
|
childSteps, declaredWrites, terminalArtifactType, artifactNodeIsProse, schemaProblems, HOST_STATE_KEY,
|
|
9
9
|
// Host-side data helpers the interpreter itself uses: the same normalization and reference shaping.
|
|
10
10
|
buildReferenceContext, normalizeStringNullsForSchema, parseCsvRows, } from "./workflow.js";
|
|
11
|
-
export { compileTransform, compileTransformSyntax } from "./code-exec.js";
|
|
11
|
+
export { compileTransform, compileTransformSyntax, deniedGlobalReferences } from "./code-exec.js";
|
|
12
12
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
13
13
|
export { getPath, predicateMatches } from "./predicates.js";
|
|
14
14
|
export { authorContract, renderAuthorContract, renderAuthorHostAddendum, candidatePolicyErrors, applyHostOutputTypes, authorWorkflow, AUTHOR_SKILL_NAME, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
|
|
15
|
-
export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
|
|
15
|
+
export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, MECHANICAL_PREDICATES, WORKFLOW_PREDICATES, PREDICATE_FIELDS, EFFORT_LEVELS, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES, } from "./vocabulary.js";
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
export declare const MAX_TIMER_DELAY_MS: number;
|
|
2
|
+
export type LongTimer = {
|
|
3
|
+
clear(): void;
|
|
4
|
+
};
|
|
5
|
+
/** Schedule `fn` after `ms`, re-arming in <= MAX_TIMER_DELAY_MS chunks so a delay past Node's timer
|
|
6
|
+
* limit still fires on time instead of overflowing. `clear()` cancels the pending chunk. */
|
|
7
|
+
export declare function setLongTimeout(fn: () => void, ms: number): LongTimer;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// Node's timers accept a delay of at most 2^31-1 ms (~24.8 days); a larger delay silently overflows
|
|
2
|
+
// to a near-immediate fire with a TimeoutOverflowWarning. A workflow's deadline_s, poll.deadline_s,
|
|
3
|
+
// poll.interval_s and retry.backoff_s carry no upper ceiling, so a delay derived from them can exceed
|
|
4
|
+
// that. `setLongTimeout` re-arms in <= MAX_TIMER_DELAY_MS chunks, so the callback fires at the
|
|
5
|
+
// intended time however far out it is, and returns a handle that clears whichever chunk is pending.
|
|
6
|
+
export const MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
|
|
7
|
+
/** Schedule `fn` after `ms`, re-arming in <= MAX_TIMER_DELAY_MS chunks so a delay past Node's timer
|
|
8
|
+
* limit still fires on time instead of overflowing. `clear()` cancels the pending chunk. */
|
|
9
|
+
export function setLongTimeout(fn, ms) {
|
|
10
|
+
let remaining = Number.isFinite(ms) ? Math.max(0, ms) : MAX_TIMER_DELAY_MS;
|
|
11
|
+
let handle;
|
|
12
|
+
const tick = () => {
|
|
13
|
+
if (remaining <= MAX_TIMER_DELAY_MS) {
|
|
14
|
+
handle = setTimeout(fn, remaining);
|
|
15
|
+
return;
|
|
16
|
+
}
|
|
17
|
+
remaining -= MAX_TIMER_DELAY_MS;
|
|
18
|
+
handle = setTimeout(tick, MAX_TIMER_DELAY_MS);
|
|
19
|
+
};
|
|
20
|
+
tick();
|
|
21
|
+
return { clear() { clearTimeout(handle); } };
|
|
22
|
+
}
|
package/dist/vocabulary.d.ts
CHANGED
|
@@ -28,7 +28,15 @@ export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"
|
|
|
28
28
|
/** There is no "off": every generative node thinks. */
|
|
29
29
|
export declare const THINKING_LEVELS: readonly ["low", "medium", "high"];
|
|
30
30
|
export declare const MODEL_TIERS: readonly ["fast", "default", "strong"];
|
|
31
|
+
/** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
|
|
32
|
+
* the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
|
|
33
|
+
export declare const AGENT_CONTEXTS: readonly ["fresh", "fork"];
|
|
31
34
|
export declare const CALL_TRANSPORTS: readonly ["tool", "executor", "shell"];
|
|
32
35
|
export declare const CALL_RETRY_CLASSES: readonly ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
36
|
+
/** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
|
|
37
|
+
* `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
|
|
38
|
+
* effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
|
|
39
|
+
* that types a failure itself names the code. */
|
|
40
|
+
export declare const EFFECT_FAILURE_CODES: readonly ["effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing", "effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport"];
|
|
33
41
|
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
34
42
|
export declare const PROSE_ARTIFACT_TYPES: readonly ["markdown", "report"];
|
package/dist/vocabulary.js
CHANGED
|
@@ -13,14 +13,14 @@ const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection
|
|
|
13
13
|
export const NODE_FIELDS = {
|
|
14
14
|
chain: ["node", "steps"],
|
|
15
15
|
code: ["node", "label", "code", "as"],
|
|
16
|
-
agent: GENERATIVE_FIELDS,
|
|
16
|
+
agent: [...GENERATIVE_FIELDS, "budget_usd", "context"],
|
|
17
17
|
decide: GENERATIVE_FIELDS,
|
|
18
18
|
extract: GENERATIVE_FIELDS,
|
|
19
19
|
report: ["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
20
20
|
artifact: ["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
21
21
|
map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"],
|
|
22
22
|
parallel: ["node", "label", "branches"],
|
|
23
|
-
loop: ["node", "label", "body", "until", "maxIters"],
|
|
23
|
+
loop: ["node", "label", "body", "until", "maxIters", "expect_iters"],
|
|
24
24
|
escalate: ["node", "label", "when", "kind", "stage", "summary"],
|
|
25
25
|
call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires"],
|
|
26
26
|
workflow: ["node", "label", "workflow", "input", "out", "as"],
|
|
@@ -57,7 +57,18 @@ export const EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
|
|
|
57
57
|
/** There is no "off": every generative node thinks. */
|
|
58
58
|
export const THINKING_LEVELS = ["low", "medium", "high"];
|
|
59
59
|
export const MODEL_TIERS = ["fast", "default", "strong"];
|
|
60
|
+
/** An `agent` node's context: `fresh` sees its instructions and state only; `fork` asks the host to start
|
|
61
|
+
* the node from the caller's transcript, where the host can (a host refuses it where it cannot). */
|
|
62
|
+
export const AGENT_CONTEXTS = ["fresh", "fork"];
|
|
60
63
|
export const CALL_TRANSPORTS = ["tool", "executor", "shell"];
|
|
61
64
|
export const CALL_RETRY_CLASSES = ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
65
|
+
/** The closed codes a failed effect carries: a call's, or a code node's that a host runs out of process.
|
|
66
|
+
* `retry.on` names these or the retry classes above. A retry class implies its code (timeout is
|
|
67
|
+
* effect_timeout, exit is effect_exit, the transient transport classes are effect_transport); a host
|
|
68
|
+
* that types a failure itself names the code. */
|
|
69
|
+
export const EFFECT_FAILURE_CODES = [
|
|
70
|
+
"effect_timeout", "effect_exit", "effect_transport", "effect_not_granted", "effect_produces_missing",
|
|
71
|
+
"effect_path_escape", "effect_code_unsafe", "output_invalid", "state_invalid", "effect_unknown_transport",
|
|
72
|
+
];
|
|
62
73
|
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
63
74
|
export const PROSE_ARTIFACT_TYPES = ["markdown", "report"];
|
package/dist/workflow-shape.js
CHANGED
|
@@ -117,7 +117,7 @@ export function workflowShapeErrors(value, complete = false) {
|
|
|
117
117
|
if (!record(entry, path))
|
|
118
118
|
return;
|
|
119
119
|
strings(entry, path, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier"]);
|
|
120
|
-
numeric(entry, path, ["maxConcurrency", "maxIters", "deadline_s"]);
|
|
120
|
+
numeric(entry, path, ["maxConcurrency", "maxIters", "expect_iters", "deadline_s"]);
|
|
121
121
|
for (const key of ["requires", "tools", "produces"])
|
|
122
122
|
stringList(entry[key], `${path}.${key}`);
|
|
123
123
|
if (entry.sopSection !== undefined && typeof entry.sopSection !== "string")
|
package/dist/workflow.d.ts
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
import { type AcceptPredicate } from "./predicates.js";
|
|
2
|
+
import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
|
|
2
3
|
import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
|
|
3
4
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
4
5
|
/** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
|
|
5
6
|
* or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
|
|
6
7
|
* decision is on the edge. */
|
|
7
8
|
export type ModelTier = "fast" | "default" | "strong";
|
|
9
|
+
/** An `agent` node's context (`AGENT_CONTEXTS`). */
|
|
10
|
+
export type AgentContext = "fresh" | "fork";
|
|
8
11
|
export type VerifyClause = {
|
|
9
12
|
out: string;
|
|
10
13
|
state?: Record<string, unknown>;
|
|
@@ -57,6 +60,9 @@ export type WorkflowNode = {
|
|
|
57
60
|
thinking?: WorkflowThinking;
|
|
58
61
|
verify?: VerifyClause;
|
|
59
62
|
tier?: ModelTier;
|
|
63
|
+
/** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
|
|
64
|
+
budget_usd?: number;
|
|
65
|
+
context?: AgentContext;
|
|
60
66
|
metadata?: NodeMetadata;
|
|
61
67
|
} | {
|
|
62
68
|
node: "decide";
|
|
@@ -119,6 +125,7 @@ export type WorkflowNode = {
|
|
|
119
125
|
body: WorkflowNode;
|
|
120
126
|
until: Predicate;
|
|
121
127
|
maxIters: number;
|
|
128
|
+
expect_iters?: number;
|
|
122
129
|
metadata?: NodeMetadata;
|
|
123
130
|
} | {
|
|
124
131
|
node: "escalate";
|
|
@@ -216,6 +223,8 @@ export type WorkflowInvocation = {
|
|
|
216
223
|
/** `exit` is a shell command that ended with a non-zero status: retried only when the author
|
|
217
224
|
* declared retry, since re-running a command is the author's call. */
|
|
218
225
|
export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
|
|
226
|
+
/** A failed effect's closed code (EFFECT_FAILURE_CODES). */
|
|
227
|
+
export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
|
|
219
228
|
/** The workflow's terminal deliverable. Types "markdown" and "report" use the report
|
|
220
229
|
* writer; other non-empty types name a workspace file produced by an earlier call.
|
|
221
230
|
* File existence and delivery are the host's responsibility. */
|
|
@@ -284,10 +293,11 @@ export type CallNode = {
|
|
|
284
293
|
produces?: string[];
|
|
285
294
|
/** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
|
|
286
295
|
deadline_s: number;
|
|
296
|
+
/** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
|
|
287
297
|
retry?: {
|
|
288
298
|
attempts: number;
|
|
289
299
|
backoff_s?: number;
|
|
290
|
-
on?: CallRetryClass[];
|
|
300
|
+
on?: (CallRetryClass | EffectFailureCode)[];
|
|
291
301
|
};
|
|
292
302
|
/** Repeat the call until its result settles (a queued job, an eventually consistent read). */
|
|
293
303
|
poll?: PollClause;
|
|
@@ -298,6 +308,9 @@ export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
|
|
|
298
308
|
export type LlmNode = Extract<WorkflowNode, {
|
|
299
309
|
node: "agent" | "decide" | "extract" | "report";
|
|
300
310
|
}>;
|
|
311
|
+
export type CodeNode = Extract<WorkflowNode, {
|
|
312
|
+
node: "code";
|
|
313
|
+
}>;
|
|
301
314
|
export declare const REPORT_SCHEMA: Record<string, unknown>;
|
|
302
315
|
export type Workflow = {
|
|
303
316
|
v: 2;
|
|
@@ -412,6 +425,12 @@ export type WorkflowDeps = {
|
|
|
412
425
|
message: string;
|
|
413
426
|
}>;
|
|
414
427
|
tier?: ModelTier;
|
|
428
|
+
/** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
|
|
429
|
+
* No runner stops a run on money. A host may cap it by what it has left. */
|
|
430
|
+
budgetUsd?: number;
|
|
431
|
+
/** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
|
|
432
|
+
* a host that has none to fork refuses it. */
|
|
433
|
+
context?: AgentContext;
|
|
415
434
|
}) => Promise<unknown>;
|
|
416
435
|
runEffect?: (params: {
|
|
417
436
|
node: CallNode;
|
|
@@ -424,6 +443,18 @@ export type WorkflowDeps = {
|
|
|
424
443
|
item?: MapItem;
|
|
425
444
|
executionPath?: string;
|
|
426
445
|
}) => Promise<unknown>;
|
|
446
|
+
/** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
|
|
447
|
+
* the context the transform would receive and uses what it resolves to as the transform's result
|
|
448
|
+
* (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
|
|
449
|
+
* Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
|
|
450
|
+
* which is not a sandbox: a host that runs code from an untrusted author supplies this. */
|
|
451
|
+
runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
|
|
452
|
+
sop: string;
|
|
453
|
+
label: string;
|
|
454
|
+
executionPath: string;
|
|
455
|
+
item?: MapItem;
|
|
456
|
+
signal?: AbortSignal;
|
|
457
|
+
}) => Promise<unknown>;
|
|
427
458
|
runJudge?: (params: {
|
|
428
459
|
label: string;
|
|
429
460
|
kind: "judge" | "pick" | "sift" | "route" | "ask";
|
|
@@ -475,9 +506,17 @@ export type WorkflowDeps = {
|
|
|
475
506
|
};
|
|
476
507
|
export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
|
|
477
508
|
export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
|
|
509
|
+
/** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
|
|
510
|
+
* and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
|
|
478
511
|
export declare class EffectFailure extends Error {
|
|
479
512
|
readonly retryClass: CallRetryClass | null;
|
|
480
|
-
|
|
513
|
+
readonly code: EffectFailureCode | null;
|
|
514
|
+
readonly detail?: Record<string, unknown>;
|
|
515
|
+
constructor(message: string, retryClass?: CallRetryClass | null, options?: {
|
|
516
|
+
code?: EffectFailureCode | null;
|
|
517
|
+
detail?: Record<string, unknown>;
|
|
518
|
+
cause?: unknown;
|
|
519
|
+
});
|
|
481
520
|
}
|
|
482
521
|
export declare function parseCsvRows(text: string): string[][];
|
|
483
522
|
export declare function buildReferenceContext(files: Record<string, string>): {
|
|
@@ -492,9 +531,6 @@ export declare function workflowSha256(workflow: Workflow): string;
|
|
|
492
531
|
/** Bound the complete document before any recursive schema or semantic traversal. Shared
|
|
493
532
|
* objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
|
|
494
533
|
export declare function workflowDocumentError(value: unknown): string | undefined;
|
|
495
|
-
/** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
|
|
496
|
-
* without evaluating authored expressions or probing transforms. This is not execution admission;
|
|
497
|
-
* trusted/default validation and runtime output checks remain authoritative. */
|
|
498
534
|
export declare function validateWorkflow(workflow: Workflow, opts?: {
|
|
499
535
|
executeCode?: boolean;
|
|
500
536
|
input?: Record<string, unknown>;
|
package/dist/workflow.js
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
import { createHash } from "node:crypto";
|
|
2
2
|
import { isDeepStrictEqual, types as utilTypes } from "node:util";
|
|
3
3
|
import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
|
|
4
|
-
import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
|
|
4
|
+
import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
|
|
5
5
|
import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
|
|
6
6
|
import { Compile } from "typebox/compile";
|
|
7
7
|
import { compileTransform, compileTransformSyntax } from "./code-exec.js";
|
|
8
8
|
import { workflowShapeErrors } from "./workflow-shape.js";
|
|
9
9
|
import { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
10
10
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
11
|
+
import { setLongTimeout } from "./long-timer.js";
|
|
11
12
|
export function artifactNodeIsProse(node) {
|
|
12
13
|
return PROSE_ARTIFACT_TYPES.includes(node.type);
|
|
13
14
|
}
|
|
@@ -130,12 +131,21 @@ export const childSteps = (child) => {
|
|
|
130
131
|
return null;
|
|
131
132
|
return root.node === "chain" ? (Array.isArray(root.steps) ? root.steps : null) : [root];
|
|
132
133
|
};
|
|
134
|
+
/** The code a retry class implies when the failure names none. */
|
|
135
|
+
const codeOfRetryClass = (retryClass) => retryClass === null ? null : retryClass === "timeout" ? "effect_timeout" : retryClass === "exit" ? "effect_exit" : "effect_transport";
|
|
136
|
+
/** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
|
|
137
|
+
* and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
|
|
133
138
|
export class EffectFailure extends Error {
|
|
134
139
|
retryClass;
|
|
135
|
-
|
|
136
|
-
|
|
140
|
+
code;
|
|
141
|
+
detail;
|
|
142
|
+
constructor(message, retryClass = null, options = {}) {
|
|
143
|
+
super(message, options.cause === undefined ? undefined : { cause: options.cause });
|
|
137
144
|
this.retryClass = retryClass;
|
|
138
145
|
this.name = "EffectFailure";
|
|
146
|
+
this.code = options.code === undefined ? codeOfRetryClass(retryClass) : options.code;
|
|
147
|
+
if (options.detail)
|
|
148
|
+
this.detail = options.detail;
|
|
139
149
|
}
|
|
140
150
|
}
|
|
141
151
|
function containsReportNode(node) {
|
|
@@ -317,6 +327,7 @@ export function workflowDocumentError(value) {
|
|
|
317
327
|
/** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
|
|
318
328
|
* without evaluating authored expressions or probing transforms. This is not execution admission;
|
|
319
329
|
* trusted/default validation and runtime output checks remain authoritative. */
|
|
330
|
+
const RETRY_ON_NAMES = [...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES];
|
|
320
331
|
export function validateWorkflow(workflow, opts) {
|
|
321
332
|
const bounded = workflowDocumentError(workflow);
|
|
322
333
|
if (bounded)
|
|
@@ -695,6 +706,13 @@ export function validateWorkflow(workflow, opts) {
|
|
|
695
706
|
};
|
|
696
707
|
const checkPredicate = (pred, label, path, field, mechanicalOnly = false) => {
|
|
697
708
|
const name = pred?.predicate;
|
|
709
|
+
// A predicate with no `predicate` field is the shape mistaken, not an unknown name: say the shape
|
|
710
|
+
// (GRE-2809), naming a predicate the object used as a key when it did.
|
|
711
|
+
if (pred && typeof pred === "object" && !Array.isArray(pred) && name === undefined) {
|
|
712
|
+
const keyed = Object.keys(pred).find((key) => PREDICATES.has(key));
|
|
713
|
+
errors.push(`${path} (${label}): ${field}: a predicate names itself in its "predicate" field beside its own fields, e.g. {"predicate": "${keyed ?? "field_true"}", "path": "..."}${keyed ? `, not {"${keyed}": {...}}` : ""}`);
|
|
714
|
+
return false;
|
|
715
|
+
}
|
|
698
716
|
if (!pred || !PREDICATES.has(name) || (mechanicalOnly && !MECHANICAL_PREDICATE_NAMES.has(name))) {
|
|
699
717
|
errors.push(`${path} (${label}): ${field}: unknown predicate "${name}"${mechanicalOnly && name === "ask" ? " (a poll reads a value, never asks a question)" : ""}`);
|
|
700
718
|
return false;
|
|
@@ -777,6 +795,10 @@ export function validateWorkflow(workflow, opts) {
|
|
|
777
795
|
checkRequires(node, path);
|
|
778
796
|
if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
|
|
779
797
|
errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
|
|
798
|
+
if (node.node === "agent" && node.budget_usd !== undefined && !(typeof node.budget_usd === "number" && Number.isFinite(node.budget_usd) && node.budget_usd > 0))
|
|
799
|
+
errors.push(`${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
|
|
800
|
+
if (node.node === "agent" && node.context !== undefined && !AGENT_CONTEXTS.includes(String(node.context)))
|
|
801
|
+
errors.push(`${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
|
|
780
802
|
if (node.node !== "report" && node.verify !== undefined) {
|
|
781
803
|
const v = node.verify;
|
|
782
804
|
if (!v || typeof v !== "object" || typeof v.out !== "string")
|
|
@@ -787,8 +809,8 @@ export function validateWorkflow(workflow, opts) {
|
|
|
787
809
|
errors.push(`${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
|
|
788
810
|
if (v.state !== undefined)
|
|
789
811
|
checkStateMap(v.state, node.label, path, "verify.state");
|
|
790
|
-
if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1
|
|
791
|
-
errors.push(`${path} (${node.label}): verify.maxDrives must be an integer 1
|
|
812
|
+
if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
|
|
813
|
+
errors.push(`${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
|
|
792
814
|
if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
|
|
793
815
|
errors.push(`${path} (${node.label}): verify.override.below must be in (0, 1)`);
|
|
794
816
|
}
|
|
@@ -856,8 +878,10 @@ export function validateWorkflow(workflow, opts) {
|
|
|
856
878
|
}
|
|
857
879
|
return;
|
|
858
880
|
case "loop":
|
|
859
|
-
if (!Number.isInteger(node.maxIters) || node.maxIters < 1
|
|
860
|
-
errors.push(`${path} (${node.label}): maxIters must be 1
|
|
881
|
+
if (!Number.isInteger(node.maxIters) || node.maxIters < 1)
|
|
882
|
+
errors.push(`${path} (${node.label}): maxIters must be an integer >= 1`);
|
|
883
|
+
if (node.expect_iters !== undefined && (!Number.isInteger(node.expect_iters) || node.expect_iters < 1))
|
|
884
|
+
errors.push(`${path} (${node.label}): expect_iters must be an integer >= 1`);
|
|
861
885
|
if (containsReportNode(node.body))
|
|
862
886
|
errors.push(`${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
|
|
863
887
|
checkPredicate(node.until, node.label, path, "until");
|
|
@@ -1104,8 +1128,8 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1104
1128
|
errors.push(`${path} (${label}): as required`);
|
|
1105
1129
|
if (node.where !== undefined && node.where !== "sandbox")
|
|
1106
1130
|
errors.push(`${path} (${label}): where accepts only "sandbox"`);
|
|
1107
|
-
if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0
|
|
1108
|
-
errors.push(`${path} (${label}): deadline_s must be greater than 0
|
|
1131
|
+
if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0))
|
|
1132
|
+
errors.push(`${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
|
|
1109
1133
|
if (node.produces !== undefined && (!Array.isArray(node.produces) || !node.produces.length || node.produces.some((f) => typeof f !== "string" || !f.trim() || f.startsWith("/") || f.split("/").includes(".."))))
|
|
1110
1134
|
errors.push(`${path} (${label}): produces must be non-empty workspace-relative paths`);
|
|
1111
1135
|
else
|
|
@@ -1113,12 +1137,12 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1113
1137
|
producedFiles.add(f);
|
|
1114
1138
|
if (node.retry !== undefined) {
|
|
1115
1139
|
const r = node.retry;
|
|
1116
|
-
if (!r || !Number.isInteger(r.attempts) || r.attempts < 1
|
|
1117
|
-
errors.push(`${path} (${label}): retry.attempts must be 1
|
|
1118
|
-
if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0
|
|
1119
|
-
errors.push(`${path} (${label}): retry.backoff_s must be 0
|
|
1120
|
-
if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !
|
|
1121
|
-
errors.push(`${path} (${label}): retry.on may name only
|
|
1140
|
+
if (!r || !Number.isInteger(r.attempts) || r.attempts < 1)
|
|
1141
|
+
errors.push(`${path} (${label}): retry.attempts must be an integer >= 1`);
|
|
1142
|
+
if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0))
|
|
1143
|
+
errors.push(`${path} (${label}): retry.backoff_s must be a finite number >= 0`);
|
|
1144
|
+
if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !RETRY_ON_NAMES.includes(String(c)))))
|
|
1145
|
+
errors.push(`${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
|
|
1122
1146
|
}
|
|
1123
1147
|
if (node.poll !== undefined) {
|
|
1124
1148
|
const p = node.poll;
|
|
@@ -1138,10 +1162,10 @@ export function validateWorkflow(workflow, opts) {
|
|
|
1138
1162
|
if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
|
|
1139
1163
|
errors.push(`${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
|
|
1140
1164
|
}
|
|
1141
|
-
if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1
|
|
1142
|
-
errors.push(`${path} (${label}): poll.interval_s must be 0.1
|
|
1143
|
-
if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)
|
|
1144
|
-
errors.push(`${path} (${label}): poll.deadline_s must be
|
|
1165
|
+
if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
|
|
1166
|
+
errors.push(`${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
|
|
1167
|
+
if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)))
|
|
1168
|
+
errors.push(`${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
|
|
1145
1169
|
}
|
|
1146
1170
|
}
|
|
1147
1171
|
checkRequires({ label, requires: node.requires }, path);
|
|
@@ -1493,8 +1517,8 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
|
|
|
1493
1517
|
reject(signal.reason ?? new Error("workflow aborted"));
|
|
1494
1518
|
return;
|
|
1495
1519
|
}
|
|
1496
|
-
const aborted = () => {
|
|
1497
|
-
const timer =
|
|
1520
|
+
const aborted = () => { timer.clear(); reject(signal?.reason ?? new Error("workflow aborted")); };
|
|
1521
|
+
const timer = setLongTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
|
|
1498
1522
|
signal?.addEventListener("abort", aborted, { once: true });
|
|
1499
1523
|
});
|
|
1500
1524
|
async function runCallNode(node, state, workflow, deps) {
|
|
@@ -1533,7 +1557,7 @@ async function runCallNode(node, state, workflow, deps) {
|
|
|
1533
1557
|
throw new EffectFailure(`call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline`, "timeout");
|
|
1534
1558
|
const controller = new AbortController();
|
|
1535
1559
|
const attemptMs = Math.max(1, Math.min(node.deadline_s * 1000, remainingMs <= 0 && deps.recovery ? Infinity : remainingMs));
|
|
1536
|
-
const attemptDeadlineMs =
|
|
1560
|
+
const attemptDeadlineMs = performance.now() + attemptMs;
|
|
1537
1561
|
let settled;
|
|
1538
1562
|
let unknownOutcome;
|
|
1539
1563
|
let interruptionCheck;
|
|
@@ -1569,13 +1593,26 @@ async function runCallNode(node, state, workflow, deps) {
|
|
|
1569
1593
|
};
|
|
1570
1594
|
const onAbort = () => interrupt("cancelled", deps.signal?.reason);
|
|
1571
1595
|
deps.signal?.addEventListener("abort", onAbort, { once: true });
|
|
1572
|
-
|
|
1596
|
+
// libuv may fire a timer up to 1 ms before the requested instant. Re-read the monotonic
|
|
1597
|
+
// clock and re-arm for the remainder, so the deadline never interrupts an effect early.
|
|
1598
|
+
// setLongTimeout keeps a deadline past Node's 2^31-1 ms timer limit from overflowing.
|
|
1599
|
+
let timer;
|
|
1600
|
+
const armDeadline = (ms) => {
|
|
1601
|
+
timer = setLongTimeout(() => {
|
|
1602
|
+
const remainingMs = attemptDeadlineMs - performance.now();
|
|
1603
|
+
if (remainingMs > 0)
|
|
1604
|
+
armDeadline(Math.ceil(remainingMs));
|
|
1605
|
+
else
|
|
1606
|
+
interrupt("deadline");
|
|
1607
|
+
}, ms);
|
|
1608
|
+
};
|
|
1609
|
+
armDeadline(attemptMs);
|
|
1573
1610
|
try {
|
|
1574
1611
|
deps.onEvent?.({ type: "effect.attempt", label: node.label, detail: { via: node.via, attempt, idempotency_key: idempotencyKey } });
|
|
1575
1612
|
Promise.resolve().then(() => {
|
|
1576
1613
|
if (deps.signal?.aborted)
|
|
1577
1614
|
throw deps.signal.reason ?? new Error("workflow aborted");
|
|
1578
|
-
if (controller.signal.aborted ||
|
|
1615
|
+
if (controller.signal.aborted || performance.now() >= attemptDeadlineMs) {
|
|
1579
1616
|
throw new EffectFailure(`call node "${node.label}" deadline elapsed before effect admission`, "timeout");
|
|
1580
1617
|
}
|
|
1581
1618
|
return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal });
|
|
@@ -1588,7 +1625,7 @@ async function runCallNode(node, state, workflow, deps) {
|
|
|
1588
1625
|
result = outcome.value;
|
|
1589
1626
|
if (deps.signal?.aborted)
|
|
1590
1627
|
throw deps.signal.reason ?? new Error("workflow aborted");
|
|
1591
|
-
if (controller.signal.aborted ||
|
|
1628
|
+
if (controller.signal.aborted || performance.now() >= attemptDeadlineMs)
|
|
1592
1629
|
throw new EffectDeadlineExceededError(node.label, result);
|
|
1593
1630
|
failed = false;
|
|
1594
1631
|
lastError = undefined;
|
|
@@ -1603,16 +1640,21 @@ async function runCallNode(node, state, workflow, deps) {
|
|
|
1603
1640
|
? new EffectFailure(cutByPoll ? `call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline` : `call node "${node.label}" exceeded its ${node.deadline_s}s deadline`, "timeout")
|
|
1604
1641
|
: error;
|
|
1605
1642
|
const retryClass = lastError instanceof EffectFailure ? lastError.retryClass : null;
|
|
1643
|
+
// The row's `code` is closed: an EffectFailure's code when it is one of EFFECT_FAILURE_CODES, else
|
|
1644
|
+
// null. Any other typed error's own code (an unknown outcome, a host's receipts failure) rides
|
|
1645
|
+
// beside it as `error_code`, never as `code`.
|
|
1646
|
+
const code = lastError instanceof EffectFailure && EFFECT_FAILURE_CODES.includes(lastError.code) ? lastError.code : null;
|
|
1647
|
+
const errorCode = code === null && typeof lastError?.code === "string" ? lastError.code : null;
|
|
1606
1648
|
// Durable admission is uncertain after failure; only the host can reconcile it.
|
|
1607
|
-
const retryable = !deps.signal?.aborted && !deps.recovery && retryClass !== null && retryOn.has(retryClass) && attempt < attempts;
|
|
1608
|
-
deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { via: node.via, attempt, retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
|
|
1649
|
+
const retryable = !deps.signal?.aborted && !deps.recovery && ((retryClass !== null && retryOn.has(retryClass)) || (code !== null && retryOn.has(code))) && attempt < attempts;
|
|
1650
|
+
deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { ...(lastError instanceof EffectFailure ? lastError.detail : undefined), via: node.via, attempt, code, ...(errorCode !== null ? { error_code: errorCode } : {}), retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
|
|
1609
1651
|
if (!retryable || (budgetUntilMs !== undefined && Date.now() >= budgetUntilMs))
|
|
1610
1652
|
break;
|
|
1611
1653
|
const delay = Math.min((node.retry?.backoff_s ?? 1) * 1000 * attempt, budgetUntilMs === undefined ? Infinity : Math.max(0, budgetUntilMs - Date.now()));
|
|
1612
1654
|
await sleep(delay, deps.signal);
|
|
1613
1655
|
}
|
|
1614
1656
|
finally {
|
|
1615
|
-
|
|
1657
|
+
timer?.clear();
|
|
1616
1658
|
if (interruptionCheck)
|
|
1617
1659
|
clearImmediate(interruptionCheck);
|
|
1618
1660
|
deps.signal?.removeEventListener("abort", onAbort);
|
|
@@ -1894,6 +1936,7 @@ function scopeDepsToChild(deps, invocation) {
|
|
|
1894
1936
|
...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
|
|
1895
1937
|
...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
|
|
1896
1938
|
...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
|
|
1939
|
+
...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
|
|
1897
1940
|
...(recovery ? { recovery: {
|
|
1898
1941
|
supportsExecutionPaths: recovery.supportsExecutionPaths,
|
|
1899
1942
|
resume: (node, state, item, path) => recovery.resume(relabel(node), state, item, path),
|
|
@@ -2011,12 +2054,18 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2011
2054
|
}
|
|
2012
2055
|
case "code": {
|
|
2013
2056
|
let out;
|
|
2014
|
-
|
|
2015
|
-
const
|
|
2016
|
-
out =
|
|
2057
|
+
if (deps.runCode) {
|
|
2058
|
+
const item = deps[MAP_ITEM];
|
|
2059
|
+
out = await deps.runCode(node, state, { sop: deps.sop || "", label: node.label, executionPath: executionPath(deps), ...(item ? { item } : {}), ...(deps.signal ? { signal: deps.signal } : {}) });
|
|
2017
2060
|
}
|
|
2018
|
-
|
|
2019
|
-
|
|
2061
|
+
else {
|
|
2062
|
+
try {
|
|
2063
|
+
const fn = compileTransform(node.code);
|
|
2064
|
+
out = fn(state, { sop: deps.sop || "" });
|
|
2065
|
+
}
|
|
2066
|
+
catch (cause) {
|
|
2067
|
+
throw new WorkflowCodeError(node.label, cause);
|
|
2068
|
+
}
|
|
2020
2069
|
}
|
|
2021
2070
|
const patch = node.as ? { [node.as]: out } : (out && typeof out === "object" && !Array.isArray(out) ? out : { [node.label]: out });
|
|
2022
2071
|
if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
|
|
@@ -2080,6 +2129,8 @@ async function runNodeBody(node, state, workflow, deps) {
|
|
|
2080
2129
|
kind: node.node, label: node.label,
|
|
2081
2130
|
...(review ? { review } : {}),
|
|
2082
2131
|
...(node.tier ? { tier: node.tier } : {}),
|
|
2132
|
+
...(node.node === "agent" && node.budget_usd !== undefined ? { budgetUsd: node.budget_usd } : {}),
|
|
2133
|
+
...(node.node === "agent" && node.context !== undefined ? { context: node.context } : {}),
|
|
2083
2134
|
system: [sopSlice, deps.skill, node.instructions, ...(policy?.systemBlocks && context ? policy.systemBlocks(context) : [])].filter(Boolean),
|
|
2084
2135
|
user: JSON.stringify(promptState),
|
|
2085
2136
|
schema: transportSchema,
|
|
@@ -2444,7 +2495,9 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
|
|
|
2444
2495
|
export async function runWorkflow(workflow, input, deps) {
|
|
2445
2496
|
if (!input || typeof input !== "object" || Array.isArray(input))
|
|
2446
2497
|
throw new WorkflowInputInvalidError(String(workflow?.name), ["input must be a JSON object"]);
|
|
2447
|
-
|
|
2498
|
+
// A host that executes code nodes itself never has them executed here, not even as validation probes.
|
|
2499
|
+
const executeCode = deps.runCode ? false : undefined;
|
|
2500
|
+
const valid = validateWorkflow(workflow, { executeCode });
|
|
2448
2501
|
if (!valid.ok)
|
|
2449
2502
|
throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
|
|
2450
2503
|
workflow = desugarWorkflow(workflow);
|
|
@@ -2453,7 +2506,7 @@ export async function runWorkflow(workflow, input, deps) {
|
|
|
2453
2506
|
if (!validator.Check(input))
|
|
2454
2507
|
throw new WorkflowInputInvalidError(workflow.name, schemaProblems(validator, input));
|
|
2455
2508
|
}
|
|
2456
|
-
const reachable = validateWorkflow(workflow, { inputKeys: Object.keys(input) });
|
|
2509
|
+
const reachable = validateWorkflow(workflow, { executeCode, inputKeys: Object.keys(input) });
|
|
2457
2510
|
if (!reachable.ok)
|
|
2458
2511
|
throw new WorkflowInvalidError(workflow.name, reachable.errors);
|
|
2459
2512
|
assertWorkflowCapabilities(workflow.root, deps, workflow);
|
|
@@ -2482,7 +2535,7 @@ export async function runWorkflow(workflow, input, deps) {
|
|
|
2482
2535
|
}
|
|
2483
2536
|
}
|
|
2484
2537
|
export async function runWorkflowSlice(workflow, input, focus, deps) {
|
|
2485
|
-
const valid = validateWorkflow(workflow);
|
|
2538
|
+
const valid = validateWorkflow(workflow, { executeCode: deps.runCode ? false : undefined });
|
|
2486
2539
|
if (!valid.ok)
|
|
2487
2540
|
throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
|
|
2488
2541
|
const desugared = desugarWorkflow(workflow);
|
package/package.json
CHANGED
|
@@ -184,6 +184,21 @@
|
|
|
184
184
|
"type": "string",
|
|
185
185
|
"title": "tier"
|
|
186
186
|
},
|
|
187
|
+
"budget_usd": {
|
|
188
|
+
"description": "The most the node asks to spend, in dollars.",
|
|
189
|
+
"exclusiveMinimum": 0,
|
|
190
|
+
"type": "number",
|
|
191
|
+
"title": "budget_usd"
|
|
192
|
+
},
|
|
193
|
+
"context": {
|
|
194
|
+
"description": "An `agent` node's context (`AGENT_CONTEXTS`).",
|
|
195
|
+
"enum": [
|
|
196
|
+
"fork",
|
|
197
|
+
"fresh"
|
|
198
|
+
],
|
|
199
|
+
"type": "string",
|
|
200
|
+
"title": "context"
|
|
201
|
+
},
|
|
187
202
|
"metadata": {
|
|
188
203
|
"description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
|
|
189
204
|
"type": "object",
|
|
@@ -743,6 +758,10 @@
|
|
|
743
758
|
"type": "number",
|
|
744
759
|
"title": "maxIters"
|
|
745
760
|
},
|
|
761
|
+
"expect_iters": {
|
|
762
|
+
"type": "number",
|
|
763
|
+
"title": "expect_iters"
|
|
764
|
+
},
|
|
746
765
|
"metadata": {
|
|
747
766
|
"description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
|
|
748
767
|
"type": "object",
|
|
@@ -1150,6 +1169,7 @@
|
|
|
1150
1169
|
"title": "deadline_s"
|
|
1151
1170
|
},
|
|
1152
1171
|
"retry": {
|
|
1172
|
+
"description": "`on` names retry classes or effect failure codes; absent, the transient retry classes.",
|
|
1153
1173
|
"type": "object",
|
|
1154
1174
|
"properties": {
|
|
1155
1175
|
"attempts": {
|
|
@@ -1163,7 +1183,24 @@
|
|
|
1163
1183
|
"on": {
|
|
1164
1184
|
"type": "array",
|
|
1165
1185
|
"items": {
|
|
1166
|
-
"
|
|
1186
|
+
"enum": [
|
|
1187
|
+
"connection",
|
|
1188
|
+
"effect_code_unsafe",
|
|
1189
|
+
"effect_exit",
|
|
1190
|
+
"effect_not_granted",
|
|
1191
|
+
"effect_path_escape",
|
|
1192
|
+
"effect_produces_missing",
|
|
1193
|
+
"effect_timeout",
|
|
1194
|
+
"effect_transport",
|
|
1195
|
+
"effect_unknown_transport",
|
|
1196
|
+
"exit",
|
|
1197
|
+
"http_429",
|
|
1198
|
+
"http_5xx",
|
|
1199
|
+
"output_invalid",
|
|
1200
|
+
"state_invalid",
|
|
1201
|
+
"timeout"
|
|
1202
|
+
],
|
|
1203
|
+
"type": "string"
|
|
1167
1204
|
},
|
|
1168
1205
|
"title": "on"
|
|
1169
1206
|
}
|
|
@@ -1681,18 +1718,6 @@
|
|
|
1681
1718
|
}
|
|
1682
1719
|
]
|
|
1683
1720
|
},
|
|
1684
|
-
"CallRetryClass": {
|
|
1685
|
-
"description": "`exit` is a shell command that ended with a non-zero status: retried only when the author\ndeclared retry, since re-running a command is the author's call.",
|
|
1686
|
-
"title": "CallRetryClass",
|
|
1687
|
-
"enum": [
|
|
1688
|
-
"connection",
|
|
1689
|
-
"exit",
|
|
1690
|
-
"http_429",
|
|
1691
|
-
"http_5xx",
|
|
1692
|
-
"timeout"
|
|
1693
|
-
],
|
|
1694
|
-
"type": "string"
|
|
1695
|
-
},
|
|
1696
1721
|
"AcceptPredicate": {
|
|
1697
1722
|
"description": "A predicate a `call` evaluates against ITS OWN RESULT: paths are result-relative.",
|
|
1698
1723
|
"title": "AcceptPredicate",
|
|
@@ -20,14 +20,14 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
|
|
|
20
20
|
This is the complete set. Each kind accepts exactly these fields; any other field is an error.
|
|
21
21
|
- `chain`: `steps`
|
|
22
22
|
- `code`: `label`, `code`, `as`
|
|
23
|
-
- `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
|
|
23
|
+
- `agent`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`, `budget_usd`, `context`
|
|
24
24
|
- `decide`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
|
|
25
25
|
- `extract`: `label`, `state`, `instructions`, `sopSection`, `out`, `as`, `requires`, `tools`, `effort`, `thinking`, `verify`, `tier`
|
|
26
26
|
- `report`: `label`, `state`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
|
|
27
27
|
- `artifact`: `label`, `state`, `type`, `path`, `instructions`, `sopSection`, `requires`, `tools`, `effort`, `thinking`
|
|
28
28
|
- `map`: `label`, `itemsPath`, `body`, `as`, `resultPath`, `maxConcurrency`
|
|
29
29
|
- `parallel`: `label`, `branches`
|
|
30
|
-
- `loop`: `label`, `body`, `until`, `maxIters`
|
|
30
|
+
- `loop`: `label`, `body`, `until`, `maxIters`, `expect_iters`
|
|
31
31
|
- `escalate`: `label`, `when`, `kind`, `stage`, `summary`
|
|
32
32
|
- `call`: `label`, `via`, `tool`, `args`, `code`, `input`, `command`, `env`, `where`, `out`, `as`, `produces`, `deadline_s`, `retry`, `poll`, `requires`
|
|
33
33
|
- `workflow`: `label`, `workflow`, `input`, `out`, `as`
|
|
@@ -51,9 +51,10 @@ Their fields:
|
|
|
51
51
|
- `out` names the schema the submission must satisfy; the value lands at `as`.
|
|
52
52
|
- `requires` lists state paths that must hold evidence before the node runs, each produced upstream: missing values, null, blank strings, empty arrays and empty objects stop the run; `false` and `0` pass.
|
|
53
53
|
- `tools` names tools the host offers. `[]` means no tools; omitting `tools` offers every tool the host allows. Never name a tool the host did not offer.
|
|
54
|
-
- `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's
|
|
54
|
+
- `effort` is minimal|low|medium|high; `thinking` is low|medium|high (never off); `tier` is fast|default|strong. They are requests to the host: resource ceilings are the host's.
|
|
55
|
+
- An `agent` node may carry `budget_usd`, the most it asks to spend in dollars (above 0), which the host caps by what it has left, and `context`, fresh|fork: `fresh` (the default) sees only its instructions and state; `fork` asks the host to start it from the caller's transcript, which a host refuses where it has none.
|
|
55
56
|
- `sopSection` names one heading of the host's SOP, or a list of them, as the exact text after "## ". The node receives those sections verbatim.
|
|
56
|
-
- `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: 1
|
|
57
|
+
- `verify` reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: an integer >= 1 (default 2, no maximum), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below `override.below`; any other boolean question is a requirement met at 0.5. A rejected submission returns to the same session with the reasons.
|
|
57
58
|
- When the workflow has a report, no decide or extract `out` schema carries `report_markdown`.
|
|
58
59
|
|
|
59
60
|
### Terminal nodes: report and artifact
|
|
@@ -77,21 +78,22 @@ Typed questions answered by the host's judge in one request each: no tools, no s
|
|
|
77
78
|
- `chain`: non-empty `steps`, run in order.
|
|
78
79
|
- `map`: `itemsPath` (an upstream list), `body` and `as`. The body sees `item` and `item_index`; `maxConcurrency` is a positive integer (default 4); `resultPath` selects one path from each completed item's state.
|
|
79
80
|
- `parallel`: at least two `branches`, each starting from the state before the parallel node. Branches write disjoint keys and never read a sibling's writes.
|
|
80
|
-
- `loop`: `body`, `until` (a predicate) and an integer `maxIters`
|
|
81
|
+
- `loop`: `body`, `until` (a predicate) and an integer `maxIters` of at least 1 (no maximum), optionally an integer `expect_iters` of at least 1 (priced passes). At the bound the state passes through with `until` unmet; follow the loop with an escalate or gate on that condition.
|
|
81
82
|
- `escalate`: `when` (a predicate), and non-empty `kind`, `stage` and `summary`. When the predicate holds the run stops without output and returns the escalation with its interpolated summary.
|
|
82
83
|
- `workflow`: `label`, `workflow` (a complete inline child), `input` (an object, interpolated, the child's entire initial state), `out` (a parent schema checked against the child's output) and `as`. The child declares `input.schemaId` in its own schemas and contains no report or artifact.
|
|
83
84
|
- `code`: `code` is one synchronous function expression such as "(s) => ({ total: s.items.length })". It receives the full state; return new values and never mutate it. `Date`, `Promise`, timers, `fetch`, `require`, `process`, `Function` and `globalThis` are unavailable. It is trusted host JavaScript, not a sandbox. Use code for typed-state mechanics, never to read meaning from prose.
|
|
84
|
-
- `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (greater than 0,
|
|
85
|
+
- `call`: one side effect with no model in the loop. `via` is tool|executor|shell; `as` and `deadline_s` (a finite number greater than 0, no maximum) are required — an unbounded effect is how a stalled provider becomes a stalled job.
|
|
85
86
|
- `via: tool` takes `tool` (a host tool address), `args` (an object) and `out` (the tool's result schema).
|
|
86
87
|
- `via: executor` takes `code` (a body that returns its JSON result and uses only `tools` and `input`), `input` and `out`.
|
|
87
88
|
- `via: shell` takes `command` (literal) and `env` (UPPER_CASE names to strings, interpolated by value; the way long values reach a command). Its result has the fixed shape {code, stdout, stderr, truncated?}: no `out`. Only a shell call may declare `produces` (workspace-relative files, checked after the effect).
|
|
88
|
-
- `retry` {attempts: 1
|
|
89
|
-
- `poll` {until, fail_when?, interval_s: 0.1
|
|
89
|
+
- `retry` {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [timeout, http_5xx, http_429, connection, exit, effect_timeout, effect_exit, effect_transport, effect_not_granted, effect_produces_missing, effect_path_escape, effect_code_unsafe, output_invalid, state_invalid, effect_unknown_transport]}. `where` accepts only "sandbox".
|
|
90
|
+
- `poll` {until, fail_when?, interval_s: >= 0.1 (a busy-loop guard), deadline_s: at least the call's deadline_s (no maximum)} repeats the call until `until` holds on its own result; `fail_when` fails it at once. Both are mechanical predicates whose paths are relative to the result and lie in its declared shape.
|
|
90
91
|
- Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
|
|
91
92
|
|
|
92
93
|
## Predicates
|
|
93
94
|
|
|
94
95
|
`loop.until` and `escalate.when` take one of these; `poll` takes only the first 8. Each path or key reads a state value an input or an earlier node produced.
|
|
96
|
+
A predicate is one JSON object that names itself in its `predicate` field beside its own fields, for example `{"predicate": "field_true", "path": "review.approved"}`.
|
|
95
97
|
- `field_equals` {path, value}: holds when the value at `path` equals `value` (a string, number or boolean)
|
|
96
98
|
- `field_true` {path}: holds when the value at `path` is `true`
|
|
97
99
|
- `in` {path, values}: holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)
|