@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -2
- package/dist/author.d.ts +86 -0
- package/dist/author.js +304 -0
- package/dist/cli.js +0 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +2 -0
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/vocabulary.d.ts +31 -0
- package/dist/vocabulary.js +60 -0
- package/dist/workflow.js +142 -37
- package/package.json +3 -2
- package/skills/author/SKILL.md +120 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +113 -0
- package/skills/author/references/language.md +113 -0
- package/skills/author/references/sdk-authoring.md +9 -0
- package/skills/author/references/workflow-format.md +137 -0
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Composable, typed workflows for agents. The core provides the v2 workflow types, validator, interpreter, events, schema, and an offline CLI. Supply agent, judgment, and effect functions only when a workflow needs them.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Beta: `0.1.0-beta.3`. Requires Node 22.19+; TypeScript consumers require TypeScript 5.4+.
|
|
6
6
|
|
|
7
7
|
```sh
|
|
8
8
|
npm install @parcha/agentrun-dsl@beta
|
|
@@ -37,9 +37,11 @@ The package root exports a deliberate API. The beta retains agent, structured-ou
|
|
|
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
39
|
| Integrate a host | `runWorkflowSlice`, `assertWorkflowCapabilities`, `desugarWorkflow`, `resolveSchemaForWorkflow`, `stageSchemaForNode`, `submissionSchemaForNode`, `mergeStageDelta`, `REPORT_SCHEMA`, `SHELL_RESULT_SCHEMA`, `getPath`, `predicateMatches`. |
|
|
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. |
|
|
40
42
|
| Test without a model | `synthesizeInstance`, `synthesizeAnswers`, `DryRunOptions`, `DryRunResult`. Synthetic answers exercise execution mechanics; they do not establish judgment quality. |
|
|
41
43
|
|
|
42
|
-
`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, returning `undefined` when
|
|
44
|
+
`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.
|
|
43
45
|
|
|
44
46
|
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.
|
|
45
47
|
|
package/dist/author.d.ts
ADDED
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { type Workflow, type WorkflowDeps } from "./workflow.js";
|
|
2
|
+
import { type WorkflowNodeKind } from "./vocabulary.js";
|
|
3
|
+
/** What a host adds to the author contract. It names the host's own vocabulary and rules and never
|
|
4
|
+
* restates or changes the language: the package renders it once, after the language section. */
|
|
5
|
+
export interface AuthorHostAddendum {
|
|
6
|
+
/** The host's name, the addendum's heading. */
|
|
7
|
+
name: string;
|
|
8
|
+
/** The keys the host seeds into the initial state, each with what it holds. Candidates are validated
|
|
9
|
+
* against exactly these keys when they declare no `input` schema. */
|
|
10
|
+
initialState?: Readonly<Record<string, string>>;
|
|
11
|
+
/** The artifact types the host delivers. A prose type is the report writer under the host's name; a file
|
|
12
|
+
* type names a file an earlier shell call produced. Declared, they are the only artifact types admitted. */
|
|
13
|
+
outputTypes?: Readonly<Record<string, {
|
|
14
|
+
kind: "prose" | "file";
|
|
15
|
+
description: string;
|
|
16
|
+
}>>;
|
|
17
|
+
/** The node kinds the host runs. Declared, a candidate using any other kind is refused. */
|
|
18
|
+
nodeKinds?: readonly WorkflowNodeKind[];
|
|
19
|
+
/** Host rules, one sentence each. The host enforces them in its own acceptance checks. */
|
|
20
|
+
rules?: readonly string[];
|
|
21
|
+
}
|
|
22
|
+
/** The host section of the contract, or "" without a host. */
|
|
23
|
+
export declare function renderAuthorHostAddendum(host: AuthorHostAddendum | undefined): string;
|
|
24
|
+
/** The rendered author contract and the sha256 of exactly that text. A host records the digest with every
|
|
25
|
+
* candidate it authors, so a workflow names the contract that wrote it. */
|
|
26
|
+
export declare function renderAuthorContract(options?: {
|
|
27
|
+
host?: AuthorHostAddendum;
|
|
28
|
+
}): {
|
|
29
|
+
text: string;
|
|
30
|
+
sha256: string;
|
|
31
|
+
};
|
|
32
|
+
/** The one author contract: the language every host shares, then the host's addendum when one is supplied. */
|
|
33
|
+
export declare function authorContract(options?: {
|
|
34
|
+
host?: AuthorHostAddendum;
|
|
35
|
+
}): string;
|
|
36
|
+
export interface CandidatePolicyOptions {
|
|
37
|
+
/** Authoritative rubric text by section name. Every generative node must name every section. */
|
|
38
|
+
rubricSections?: Record<string, string>;
|
|
39
|
+
/** Admits code, call and artifact nodes. */
|
|
40
|
+
allowExecutableCandidates?: boolean;
|
|
41
|
+
/** Direct tool calls admitted without executable authorization. */
|
|
42
|
+
allowedEffectTools?: readonly string[];
|
|
43
|
+
host?: AuthorHostAddendum;
|
|
44
|
+
}
|
|
45
|
+
/** Author policy over a candidate, checked before validation so a refused candidate never evaluates code. */
|
|
46
|
+
export declare function candidatePolicyErrors(candidate: unknown, options: CandidatePolicyOptions): string[];
|
|
47
|
+
/** The interpreter's view of a workflow written in a host's vocabulary: an artifact of a declared prose output
|
|
48
|
+
* type becomes the report writer it is. Validate and run this view; retain and digest the authored bytes. */
|
|
49
|
+
export declare function applyHostOutputTypes(candidate: Workflow, host: AuthorHostAddendum | undefined): Workflow;
|
|
50
|
+
export interface AuthorWorkflowOptions {
|
|
51
|
+
request: string;
|
|
52
|
+
outputDir: string;
|
|
53
|
+
/** The host's generative adapter. The author asks it for one agent session with no tools. */
|
|
54
|
+
runNode: NonNullable<WorkflowDeps["runNode"]>;
|
|
55
|
+
host?: AuthorHostAddendum;
|
|
56
|
+
/** Keys available to a candidate without an input schema; defaults to the host's initial state keys. */
|
|
57
|
+
inputKeys?: string[];
|
|
58
|
+
rubricSections?: Record<string, string>;
|
|
59
|
+
allowExecutableCandidates?: boolean;
|
|
60
|
+
maxCandidates?: number;
|
|
61
|
+
/** Host acceptance over a structurally valid candidate, in the interpreter's view (`applyHostOutputTypes`):
|
|
62
|
+
* diagnostics, or [] to accept. */
|
|
63
|
+
acceptance?: (candidate: Workflow) => Promise<string[]> | string[];
|
|
64
|
+
signal?: AbortSignal;
|
|
65
|
+
}
|
|
66
|
+
export interface AuthoredWorkflow {
|
|
67
|
+
/** The accepted candidate as authored. A host with prose output types runs `applyHostOutputTypes(workflow, host)`. */
|
|
68
|
+
workflow: Workflow;
|
|
69
|
+
path: string;
|
|
70
|
+
directory: string;
|
|
71
|
+
candidates: number;
|
|
72
|
+
checks: "structural" | "structural-and-host";
|
|
73
|
+
/** sha256 of the exact contract text the session received (`renderAuthorContract`). */
|
|
74
|
+
contractSha256: string;
|
|
75
|
+
}
|
|
76
|
+
/** Author one workflow and retain every candidate with its review in a new directory under `outputDir`.
|
|
77
|
+
* Policy, validation and host acceptance review each submission; a rejection returns to the same session. */
|
|
78
|
+
export declare function authorWorkflow(options: AuthorWorkflowOptions): Promise<AuthoredWorkflow>;
|
|
79
|
+
/** The packaged author skill's name, as a skill-loading host registers it. */
|
|
80
|
+
export declare const AUTHOR_SKILL_NAME = "agentrun-author";
|
|
81
|
+
/** The absolute directory of the packaged author skill (the one holding SKILL.md). */
|
|
82
|
+
export declare function authorSkillDirectory(): string;
|
|
83
|
+
/** A reference shipped with the author skill, for hosts without file-reading tools. */
|
|
84
|
+
export declare function loadAuthorReference(name: "language" | "workflow-format" | "jev-decisions"): string;
|
|
85
|
+
/** The whole skill as one text: SKILL.md, its references and its JSON examples. */
|
|
86
|
+
export declare function loadAuthorSkillBundle(): string;
|
package/dist/author.js
ADDED
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
import { createHash, randomUUID } from "node:crypto";
|
|
2
|
+
import { readFileSync, readdirSync } from "node:fs";
|
|
3
|
+
import { mkdir, writeFile } from "node:fs/promises";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
import { join, resolve } from "node:path";
|
|
6
|
+
import { validateWorkflow } from "./workflow.js";
|
|
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";
|
|
9
|
+
const code = (value) => `\`${value}\``;
|
|
10
|
+
const list = (values) => values.map(code).join(", ");
|
|
11
|
+
const alternatives = (values) => values.join("|");
|
|
12
|
+
const PREDICATE_SHAPES = {
|
|
13
|
+
field_equals: "holds when the value at `path` equals `value` (a string, number or boolean)",
|
|
14
|
+
field_true: "holds when the value at `path` is `true`",
|
|
15
|
+
in: "holds when the value at `path` is one of `values` (a non-empty list of strings, numbers or booleans)",
|
|
16
|
+
count_gte: "holds when the array (or number) at `path` has at least `n` items",
|
|
17
|
+
gte: "holds when the finite number at `path` is at least `n`",
|
|
18
|
+
lt: "holds when the finite number at `path` is below `n`",
|
|
19
|
+
empty: "holds when the value at `path` is an empty array, an empty string, null or absent",
|
|
20
|
+
no_new_items: "takes `key`, not `path`; holds when that state key is an empty array or falsy",
|
|
21
|
+
ask: "a yes/no question for the host's judge: `instructions` is the question, `state` what it sees (default: the whole state), `criteria` optional {true, false} descriptions; holds when the yes-probability is at least `gte` (in (0.5, 1], default 0.6)",
|
|
22
|
+
};
|
|
23
|
+
function nodeFieldLines() {
|
|
24
|
+
return WORKFLOW_NODE_KINDS.map((kind) => `- ${code(kind)}: ${list(NODE_FIELDS[kind].filter((field) => field !== "node"))}`).join("\n");
|
|
25
|
+
}
|
|
26
|
+
function predicateLines() {
|
|
27
|
+
return WORKFLOW_PREDICATES.map((name) => `- ${code(name)} {${PREDICATE_FIELDS[name].join(", ")}}: ${PREDICATE_SHAPES[name]}`).join("\n");
|
|
28
|
+
}
|
|
29
|
+
const LANGUAGE = `You author AgentRun workflows: JSON documents the AgentRun interpreter runs.
|
|
30
|
+
Deliver the complete JSON document the way your host asks; never deliver prose, a file name or a fragment. Make the smallest workflow that satisfies the request. A candidate runs nothing until its host accepts it, and an accepted candidate is not activated by acceptance.
|
|
31
|
+
|
|
32
|
+
## Document
|
|
33
|
+
|
|
34
|
+
A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
|
|
35
|
+
- ${code("schemas")} maps ids to inline JSON Schema objects. Every schema id a node, ${code("input")} or ${code("output")} names must exist there. Inside a schema, reference a catalog schema or an inline definition only as {"$ref":"#/definitions/<id>"}.
|
|
36
|
+
- The input contract: the run starts from the input object and nothing else. ${code("input.schemaId")}, when present, is enforced before the first node. A node may read only input keys and keys an earlier node wrote.
|
|
37
|
+
- ${code("output.schemaId")} validates the final value; ${code("output.path")} selects it from state and must name an input key or a key an earlier node wrote.
|
|
38
|
+
- State is one object. Each step writes its result under one key: its ${code("as")}, or, for an agent, decide, extract or code node without ${code("as")}, its label. A report writes ${code("report_markdown")}. A code node without ${code("as")} that returns an object merges that object's top-level fields instead.
|
|
39
|
+
- Keys that begin with ${code("$")} are engine-owned: ${code("$host")} (host state), ${code("<as>$answers")} (raw judge answers and confidences) and ${code("<as>$verify")} (verifier results). Read them; never write one. No ${code("as")} may begin with ${code("$")}, and neither may the label of an agent, decide, extract or code node without ${code("as")}.
|
|
40
|
+
- ${code("{dot.path}")} placeholders are replaced from state in ${code("state")} maps (including ${code("verify.state")} and ${code("ask.state")}), call ${code("args")}, ${code("input")}, ${code("env")} and ${code("produces")}, a child workflow's ${code("input")}, and ${code("escalate.summary")}; ${code("pick")} and ${code("sift")} ${code("describe")} templates also see ${code("{item...}")}. A placeholder that is the whole string keeps its value's type. Every key a state map, call or child input interpolates must be produced upstream. ${code("instructions")}, ${code("code")} and ${code("command")} are literal and never interpolated.
|
|
41
|
+
|
|
42
|
+
## Node kinds
|
|
43
|
+
|
|
44
|
+
This is the complete set. Each kind accepts exactly these fields; any other field is an error.
|
|
45
|
+
${nodeFieldLines()}
|
|
46
|
+
|
|
47
|
+
### Generative nodes: ${GENERATIVE_NODE_KINDS.join(", ")}
|
|
48
|
+
|
|
49
|
+
Each runs one adapter session. A kind is a preset (its duty, default effort and model tier), not a capability limit:
|
|
50
|
+
- ${code("extract")} transcribes facts already present in its input into ${code("out")}: faithfully, null for an absent field, nothing invented, no judgment.
|
|
51
|
+
- ${code("decide")} judges what is already in state.
|
|
52
|
+
- ${code("agent")} gathers new evidence with its tools.
|
|
53
|
+
- ${code("report")} renders the final record as the deliverable prose. It has no ${code("out")} or ${code("as")}: it writes ${code("report_markdown")}.
|
|
54
|
+
|
|
55
|
+
Their fields:
|
|
56
|
+
- ${code("instructions")} (required, non-empty) states the node's duty as literal prose. The node receives ${code("state")} (an interpolated map) or, without it, the accumulated state as its JSON input; refer to keys by name.
|
|
57
|
+
- ${code("out")} names the schema the submission must satisfy; the value lands at ${code("as")}.
|
|
58
|
+
- ${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.
|
|
59
|
+
- ${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.
|
|
60
|
+
- ${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, and nodes carry no budgets.
|
|
61
|
+
- ${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.
|
|
62
|
+
- ${code("verify")} reviews a submission before it is accepted: {"out": a question schema with at least one boolean question, "state"?, "maxDrives"?: 1..4 (default 2), "override"?: {"below": a number in (0, 1), default 0.3}}. A boolean question named after a submission field doubts that field when its yes-probability is below ${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.
|
|
63
|
+
- When the workflow has a report, no decide or extract ${code("out")} schema carries ${code("report_markdown")}.
|
|
64
|
+
|
|
65
|
+
### Terminal nodes: report and artifact
|
|
66
|
+
|
|
67
|
+
A workflow has at most one terminal node, a ${code("report")} or an ${code("artifact")}, and it is the last step of the root chain. No terminal node sits inside a map, loop, parallel branch, route branch or child workflow.
|
|
68
|
+
- An ${code("artifact")} of type ${PROSE_ARTIFACT_TYPES.map((type) => code(type)).join(" or ")} is the report writer: give it the report's fields.
|
|
69
|
+
- Any other ${code("artifact")} type names a file: ${code("path")} is the workspace-relative file an earlier shell call declared in ${code("produces")}, and the node has no model fields (${list(["instructions", "state", "sopSection", "tools", "effort", "thinking"])}).
|
|
70
|
+
|
|
71
|
+
### Judgment nodes: ${JUDGMENT_NODE_KINDS.join(", ")}
|
|
72
|
+
|
|
73
|
+
Typed questions answered by the host's judge in one request each: no tools, no session, no ${code("sopSection")}.
|
|
74
|
+
- A question schema is a flat object. Each property's ${code("description")} is its question. A boolean yields a yes-probability; a string enum (at most ${SYSTEM_ONE_LIMITS.maxChoiceOptions} options, optional per-option ${code("criteria")}) yields a choice; an integer with ${code("criteria")}: [level descriptions] (${SYSTEM_ONE_LIMITS.minScoreLevels} to ${SYSTEM_ONE_LIMITS.maxScoreLevels} levels, minimum 0, maximum the last level index) yields a score. Nothing else is a question.
|
|
75
|
+
- ${code("judge")}: a non-empty ${code("state")} map, ${code("out")} (a question schema) and ${code("as")}. The decoded value lands at ${code("as")}, the raw answers at ${code("<as>$answers")}.
|
|
76
|
+
- ${code("pick")}: ${code("itemsPath")}, ${code("describe")} (the option text per item, such as "{item.name}"), ${code("instructions")} (the one question) and ${code("as")}; ${code("allowNone")} adds a none-of-these option. The result is {index, item, none, option}.
|
|
77
|
+
- ${code("sift")}: ${code("itemsPath")}, ${code("out")} (a question schema asked of every item in one request) and ${code("as")}. ${code("keep")} {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at ${code("<as>.items")}.
|
|
78
|
+
- ${code("route")}: a non-empty ${code("state")} map, ${code("instructions")} (the one question) and 2 to ${SYSTEM_ONE_LIMITS.maxChoiceOptions} named ${code("branches")}, each {criteria?, body}. ${code("unsure")} {branch: one of the branches, gte: a number in (0, 1]} takes that branch when the choice's confidence is below ${code("gte")}. ${code("as")} records the choice.
|
|
79
|
+
- A decoded boolean is true at yes-probability 0.5. To hold a different threshold, read ${code("<as>$answers.answers.<id>.noul")} in a code node.
|
|
80
|
+
|
|
81
|
+
### Control nodes
|
|
82
|
+
|
|
83
|
+
- ${code("chain")}: non-empty ${code("steps")}, run in order.
|
|
84
|
+
- ${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.
|
|
85
|
+
- ${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.
|
|
86
|
+
- ${code("loop")}: ${code("body")}, ${code("until")} (a predicate) and an integer ${code("maxIters")} from 1 to 20. At the bound the state passes through with ${code("until")} unmet; follow the loop with an escalate or gate on that condition.
|
|
87
|
+
- ${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.
|
|
88
|
+
- ${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.
|
|
89
|
+
- ${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.
|
|
90
|
+
- ${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, at most 3600) are required.
|
|
91
|
+
- ${code("via: tool")} takes ${code("tool")} (a host tool address), ${code("args")} (an object) and ${code("out")} (the tool's result schema).
|
|
92
|
+
- ${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")}.
|
|
93
|
+
- ${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).
|
|
94
|
+
- ${code("retry")} {attempts: 1..5, backoff_s?: 0..60, on?: [${CALL_RETRY_CLASSES.join(", ")}]}. ${code("where")} accepts only "sandbox".
|
|
95
|
+
- ${code("poll")} {until, fail_when?, interval_s: 0.1..300, deadline_s: from the call's deadline_s to 7200} 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.
|
|
96
|
+
- Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
|
|
97
|
+
|
|
98
|
+
## Predicates
|
|
99
|
+
|
|
100
|
+
${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.
|
|
101
|
+
${predicateLines()}
|
|
102
|
+
|
|
103
|
+
## Authority
|
|
104
|
+
|
|
105
|
+
- Use only tools the host names. Never invent a tool, capability, evidence source or successful check.
|
|
106
|
+
- Code, call and artifact nodes need the host's explicit authorization for executable candidates.
|
|
107
|
+
- When the host supplies rubric sections, they are authoritative source text: every generative node's ${code("sopSection")} lists all of them, a merged judgment inherits the union of its parents' sections, and policy is never paraphrased into instructions. Judgment nodes, ${code("ask")} predicates and ${code("verify")} clauses are then refused until the host reviews a separate question contract.
|
|
108
|
+
- Acceptance checks are the host's. Never change a check, fixture or threshold to pass.
|
|
109
|
+
- Bound loops and parallelism. Uncertainty escalates or takes an explicit fallback such as ${code("route.unsure")} or a threshold gate.
|
|
110
|
+
|
|
111
|
+
## Example
|
|
112
|
+
|
|
113
|
+
{"v":2,"name":"summarize","schemas":{"Input":{"type":"object","properties":{"text":{"type":"string","minLength":1}},"required":["text"],"additionalProperties":false},"Result":{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"],"additionalProperties":false}},"input":{"schemaId":"Input"},"output":{"schemaId":"Result","path":"result"},"root":{"node":"extract","label":"summarize","instructions":"Summarize the text field faithfully. Invent nothing.","out":"Result","as":"result","requires":["text"],"tools":[]}}`;
|
|
114
|
+
/** The host section of the contract, or "" without a host. */
|
|
115
|
+
export function renderAuthorHostAddendum(host) {
|
|
116
|
+
if (!host)
|
|
117
|
+
return "";
|
|
118
|
+
const lines = [`## Host: ${host.name}`, "", "These host rules add to the language above; they never change it."];
|
|
119
|
+
if (host.initialState && Object.keys(host.initialState).length) {
|
|
120
|
+
lines.push(`- The run starts with exactly these state keys: ${Object.entries(host.initialState).map(([key, description]) => `${code(key)} (${description})`).join("; ")}. Any other key must be written by a node before it is read.`);
|
|
121
|
+
}
|
|
122
|
+
if (host.outputTypes && Object.keys(host.outputTypes).length) {
|
|
123
|
+
const types = Object.entries(host.outputTypes).map(([type, spec]) => `${code(type)} (${spec.kind === "prose" ? "prose: the report writer, with the report's fields" : `file: ${code("path")} names the file an earlier shell call produced`}; ${spec.description})`);
|
|
124
|
+
lines.push(`- A terminal artifact's ${code("type")} is one of: ${types.join("; ")}.`);
|
|
125
|
+
}
|
|
126
|
+
if (host.nodeKinds)
|
|
127
|
+
lines.push(`- This host runs only these node kinds: ${list(host.nodeKinds)}. Author no other kind.`);
|
|
128
|
+
for (const rule of host.rules ?? [])
|
|
129
|
+
lines.push(`- ${rule}`);
|
|
130
|
+
return lines.join("\n");
|
|
131
|
+
}
|
|
132
|
+
/** The rendered author contract and the sha256 of exactly that text. A host records the digest with every
|
|
133
|
+
* candidate it authors, so a workflow names the contract that wrote it. */
|
|
134
|
+
export function renderAuthorContract(options = {}) {
|
|
135
|
+
const addendum = renderAuthorHostAddendum(options.host);
|
|
136
|
+
const text = addendum ? `${LANGUAGE}\n\n${addendum}` : LANGUAGE;
|
|
137
|
+
return { text, sha256: createHash("sha256").update(text).digest("hex") };
|
|
138
|
+
}
|
|
139
|
+
/** The one author contract: the language every host shares, then the host's addendum when one is supplied. */
|
|
140
|
+
export function authorContract(options = {}) {
|
|
141
|
+
return renderAuthorContract(options).text;
|
|
142
|
+
}
|
|
143
|
+
const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
|
|
144
|
+
/** Author policy over a candidate, checked before validation so a refused candidate never evaluates code. */
|
|
145
|
+
export function candidatePolicyErrors(candidate, options) {
|
|
146
|
+
const errors = [];
|
|
147
|
+
const sections = Object.keys(options.rubricSections ?? {});
|
|
148
|
+
const kinds = options.host?.nodeKinds ? new Set(options.host.nodeKinds) : undefined;
|
|
149
|
+
const outputTypes = options.host?.outputTypes;
|
|
150
|
+
const visit = (value) => {
|
|
151
|
+
const node = record(value);
|
|
152
|
+
if (!node)
|
|
153
|
+
return;
|
|
154
|
+
const kind = node.node;
|
|
155
|
+
if (kinds && !kinds.has(String(kind)))
|
|
156
|
+
errors.push(`${String(node.label ?? kind)}: this host does not run ${String(kind)} nodes`);
|
|
157
|
+
if (!options.allowExecutableCandidates && ["code", "call", "artifact"].includes(String(kind)) && !(kind === "call" && node.via === "tool" && typeof node.tool === "string" && options.allowedEffectTools?.includes(node.tool)))
|
|
158
|
+
errors.push(`${kind} requires allowExecutableCandidates`);
|
|
159
|
+
if (sections.length && JUDGMENT_NODE_KINDS.includes(String(kind)))
|
|
160
|
+
errors.push(`${String(kind)} cannot carry supplied SOP sections; use an LLM node with sopSection`);
|
|
161
|
+
const llm = GENERATIVE_NODE_KINDS.includes(String(kind));
|
|
162
|
+
const predicate = kind === "loop" ? record(node.until) : kind === "escalate" ? record(node.when) : undefined;
|
|
163
|
+
if (sections.length && (predicate?.predicate === "ask" || (llm && node.verify !== undefined)))
|
|
164
|
+
errors.push("Semantic predicates and verify clauses require a separately reviewed question contract when rubric sections are supplied");
|
|
165
|
+
const hostType = kind === "artifact" && typeof node.type === "string" && outputTypes && Object.hasOwn(outputTypes, node.type) ? outputTypes[node.type] : undefined;
|
|
166
|
+
if (kind === "artifact" && outputTypes && !hostType)
|
|
167
|
+
errors.push(`${String(node.label ?? kind)}: artifact type ${JSON.stringify(node.type)} is not one of this host's output types`);
|
|
168
|
+
const proseArtifact = kind === "artifact" && (PROSE_ARTIFACT_TYPES.includes(node.type) || hostType?.kind === "prose");
|
|
169
|
+
if (llm || proseArtifact) {
|
|
170
|
+
const included = Array.isArray(node.sopSection) ? node.sopSection : [node.sopSection];
|
|
171
|
+
for (const section of sections)
|
|
172
|
+
if (!included.includes(section))
|
|
173
|
+
errors.push(`${String(node.label)} must include rubric section ${section}`);
|
|
174
|
+
}
|
|
175
|
+
switch (kind) {
|
|
176
|
+
case "chain":
|
|
177
|
+
if (Array.isArray(node.steps))
|
|
178
|
+
node.steps.forEach(visit);
|
|
179
|
+
break;
|
|
180
|
+
case "parallel":
|
|
181
|
+
if (Array.isArray(node.branches))
|
|
182
|
+
node.branches.forEach(visit);
|
|
183
|
+
break;
|
|
184
|
+
case "map":
|
|
185
|
+
case "loop":
|
|
186
|
+
visit(node.body);
|
|
187
|
+
break;
|
|
188
|
+
case "route": {
|
|
189
|
+
const branches = record(node.branches);
|
|
190
|
+
if (branches)
|
|
191
|
+
Object.values(branches).forEach(branch => visit(record(branch)?.body));
|
|
192
|
+
break;
|
|
193
|
+
}
|
|
194
|
+
case "workflow":
|
|
195
|
+
visit(record(node.workflow)?.root);
|
|
196
|
+
break;
|
|
197
|
+
}
|
|
198
|
+
};
|
|
199
|
+
visit(record(candidate)?.root);
|
|
200
|
+
return errors;
|
|
201
|
+
}
|
|
202
|
+
/** The interpreter's view of a workflow written in a host's vocabulary: an artifact of a declared prose output
|
|
203
|
+
* type becomes the report writer it is. Validate and run this view; retain and digest the authored bytes. */
|
|
204
|
+
export function applyHostOutputTypes(candidate, host) {
|
|
205
|
+
const prose = new Set(Object.entries(host?.outputTypes ?? {}).filter(([, spec]) => spec.kind === "prose").map(([type]) => type));
|
|
206
|
+
if (!prose.size)
|
|
207
|
+
return candidate;
|
|
208
|
+
const visit = (node) => {
|
|
209
|
+
if (!node || typeof node !== "object")
|
|
210
|
+
return node;
|
|
211
|
+
if (node.node === "artifact" && prose.has(node.type))
|
|
212
|
+
return { ...node, type: "report" };
|
|
213
|
+
if (node.node === "chain")
|
|
214
|
+
return { ...node, steps: (node.steps || []).map(visit) };
|
|
215
|
+
if (node.node === "parallel")
|
|
216
|
+
return { ...node, branches: (node.branches || []).map(visit) };
|
|
217
|
+
if (node.node === "map" || node.node === "loop")
|
|
218
|
+
return { ...node, body: visit(node.body) };
|
|
219
|
+
if (node.node === "route")
|
|
220
|
+
return { ...node, branches: Object.fromEntries(Object.entries(node.branches || {}).map(([name, branch]) => [name, { ...branch, body: visit(branch?.body) }])) };
|
|
221
|
+
return node;
|
|
222
|
+
};
|
|
223
|
+
return { ...candidate, root: visit(candidate.root) };
|
|
224
|
+
}
|
|
225
|
+
/** Author one workflow and retain every candidate with its review in a new directory under `outputDir`.
|
|
226
|
+
* Policy, validation and host acceptance review each submission; a rejection returns to the same session. */
|
|
227
|
+
export async function authorWorkflow(options) {
|
|
228
|
+
if (!options.request.trim())
|
|
229
|
+
throw new Error("Workflow request is required");
|
|
230
|
+
const maxCandidates = options.maxCandidates ?? 4;
|
|
231
|
+
if (!Number.isSafeInteger(maxCandidates) || maxCandidates < 1)
|
|
232
|
+
throw new Error("maxCandidates must be a positive integer");
|
|
233
|
+
const inputKeys = options.inputKeys ?? (options.host?.initialState ? Object.keys(options.host.initialState) : []);
|
|
234
|
+
const contract = renderAuthorContract({ host: options.host });
|
|
235
|
+
const directory = resolve(options.outputDir, `candidate-${randomUUID()}`);
|
|
236
|
+
await mkdir(directory, { recursive: true });
|
|
237
|
+
await writeFile(join(directory, "request.json"), JSON.stringify({ request: options.request, host: options.host?.name ?? null, contractSha256: contract.sha256, inputKeys, rubricSections: options.rubricSections ?? {}, allowExecutableCandidates: options.allowExecutableCandidates ?? false, maxCandidates }, null, 2), { flag: "wx" });
|
|
238
|
+
let candidates = 0;
|
|
239
|
+
let acceptedPath;
|
|
240
|
+
let accepted;
|
|
241
|
+
const checks = options.acceptance ? "structural-and-host" : "structural";
|
|
242
|
+
try {
|
|
243
|
+
await options.runNode({
|
|
244
|
+
kind: "agent", label: "author-workflow", tools: [], signal: options.signal,
|
|
245
|
+
system: [contract.text, "Deliver each candidate as the value of the submit tool. A rejected candidate comes back with its errors; repair it in the same session.", `Executable candidates authorized: ${options.allowExecutableCandidates ?? false}.`, `All supplied rubric sections (authoritative): ${JSON.stringify(options.rubricSections ?? {})}`],
|
|
246
|
+
user: `${options.request}\nAvailable input keys: ${JSON.stringify(inputKeys)}`,
|
|
247
|
+
schema: { type: "object", additionalProperties: true },
|
|
248
|
+
async review(value) {
|
|
249
|
+
candidates++;
|
|
250
|
+
if (candidates > maxCandidates)
|
|
251
|
+
throw new Error(`Candidate limit exceeded: ${maxCandidates}`);
|
|
252
|
+
const number = String(candidates).padStart(3, "0");
|
|
253
|
+
const candidatePath = join(directory, `${number}.json`);
|
|
254
|
+
await writeFile(candidatePath, JSON.stringify(value, null, 2), { flag: "wx" });
|
|
255
|
+
const errors = candidatePolicyErrors(value, options);
|
|
256
|
+
if (!errors.length) {
|
|
257
|
+
try {
|
|
258
|
+
const verdict = validateWorkflow(applyHostOutputTypes(value, options.host), { inputKeys });
|
|
259
|
+
if (!verdict.ok)
|
|
260
|
+
errors.push(...verdict.errors);
|
|
261
|
+
}
|
|
262
|
+
catch (error) {
|
|
263
|
+
errors.push(`Invalid workflow: ${error instanceof Error ? error.message : String(error)}`);
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
if (!errors.length && options.acceptance)
|
|
267
|
+
errors.push(...await options.acceptance(applyHostOutputTypes(structuredClone(value), options.host)));
|
|
268
|
+
await writeFile(join(directory, `${number}.review.json`), JSON.stringify({ accepted: !errors.length, checks, errors }, null, 2), { flag: "wx" });
|
|
269
|
+
if (errors.length)
|
|
270
|
+
return { accepted: false, message: errors.join("\n") };
|
|
271
|
+
acceptedPath = candidatePath;
|
|
272
|
+
accepted = structuredClone(value);
|
|
273
|
+
return { accepted: true };
|
|
274
|
+
},
|
|
275
|
+
});
|
|
276
|
+
// The result is the candidate review accepted, never whatever the adapter returns afterwards.
|
|
277
|
+
if (!acceptedPath || !accepted)
|
|
278
|
+
throw new Error("Author returned without a retained accepted candidate");
|
|
279
|
+
const workflow = accepted;
|
|
280
|
+
await writeFile(join(directory, "result.json"), JSON.stringify({ status: "candidate", path: acceptedPath, candidates, contractSha256: contract.sha256 }, null, 2), { flag: "wx" });
|
|
281
|
+
return { workflow, path: acceptedPath, directory, candidates, checks, contractSha256: contract.sha256 };
|
|
282
|
+
}
|
|
283
|
+
catch (error) {
|
|
284
|
+
await writeFile(join(directory, "result.json"), JSON.stringify({ status: "failed", candidates, contractSha256: contract.sha256, message: error instanceof Error ? error.message : String(error) }, null, 2), { flag: "wx" });
|
|
285
|
+
throw error;
|
|
286
|
+
}
|
|
287
|
+
}
|
|
288
|
+
/** The packaged author skill's name, as a skill-loading host registers it. */
|
|
289
|
+
export const AUTHOR_SKILL_NAME = "agentrun-author";
|
|
290
|
+
const skillRoot = new URL("../skills/author/", import.meta.url);
|
|
291
|
+
/** The absolute directory of the packaged author skill (the one holding SKILL.md). */
|
|
292
|
+
export function authorSkillDirectory() {
|
|
293
|
+
return fileURLToPath(skillRoot);
|
|
294
|
+
}
|
|
295
|
+
/** A reference shipped with the author skill, for hosts without file-reading tools. */
|
|
296
|
+
export function loadAuthorReference(name) {
|
|
297
|
+
return readFileSync(new URL(`references/${name}.md`, skillRoot), "utf8");
|
|
298
|
+
}
|
|
299
|
+
/** The whole skill as one text: SKILL.md, its references and its JSON examples. */
|
|
300
|
+
export function loadAuthorSkillBundle() {
|
|
301
|
+
const files = ["SKILL.md", "references/language.md", "references/workflow-format.md", "references/jev-decisions.md",
|
|
302
|
+
...readdirSync(new URL("examples/", skillRoot)).filter(name => name.endsWith(".json")).sort().map(name => `examples/${name}`)];
|
|
303
|
+
return files.map(path => `\n--- ${path} ---\n${readFileSync(new URL(path, skillRoot), "utf8")}`).join("\n");
|
|
304
|
+
}
|
package/dist/cli.js
CHANGED
|
File without changes
|
package/dist/index.d.ts
CHANGED
|
@@ -13,3 +13,7 @@ export { compileTransform, compileTransformSyntax } 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
|
+
export { authorContract, renderAuthorContract, renderAuthorHostAddendum, candidatePolicyErrors, applyHostOutputTypes, authorWorkflow, AUTHOR_SKILL_NAME, authorSkillDirectory, loadAuthorReference, loadAuthorSkillBundle, } from "./author.js";
|
|
17
|
+
export type { AuthorHostAddendum, CandidatePolicyOptions, AuthorWorkflowOptions, AuthoredWorkflow } from "./author.js";
|
|
18
|
+
export { WORKFLOW_NODE_KINDS, GENERATIVE_NODE_KINDS, JUDGMENT_NODE_KINDS, 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";
|
|
19
|
+
export type { WorkflowNodeKind, WorkflowPredicateName } from "./vocabulary.js";
|
package/dist/index.js
CHANGED
|
@@ -11,3 +11,5 @@ buildReferenceContext, normalizeStringNullsForSchema, parseCsvRows, } from "./wo
|
|
|
11
11
|
export { compileTransform, compileTransformSyntax } from "./code-exec.js";
|
|
12
12
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
13
13
|
export { getPath, predicateMatches } from "./predicates.js";
|
|
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, 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";
|
package/dist/predicates.d.ts
CHANGED
|
@@ -30,5 +30,9 @@ export type AcceptPredicate = StopPredicate | {
|
|
|
30
30
|
values: Array<string | number | boolean>;
|
|
31
31
|
};
|
|
32
32
|
export declare const MECHANICAL_PREDICATE_NAMES: ReadonlySet<string>;
|
|
33
|
+
/** Resolve a dotted state path the one way every reader does: a record by key, an array by a
|
|
34
|
+
* non-negative integer index, anything else (a string, a number, a missing value) to undefined.
|
|
35
|
+
* `requires`, interpolation, `itemsPath`, `output.path` and predicates all read through here, so a
|
|
36
|
+
* path that names a value for one names it for all. */
|
|
33
37
|
export declare function getPath(value: unknown, key: string): unknown;
|
|
34
38
|
export declare function predicateMatches(predicate: StopPredicate | AcceptPredicate, value: unknown): boolean;
|
package/dist/predicates.js
CHANGED
|
@@ -1,11 +1,28 @@
|
|
|
1
|
-
|
|
1
|
+
import { MECHANICAL_PREDICATES } from "./vocabulary.js";
|
|
2
|
+
export const MECHANICAL_PREDICATE_NAMES = new Set(MECHANICAL_PREDICATES);
|
|
2
3
|
function isRecord(value) {
|
|
3
4
|
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
4
5
|
}
|
|
6
|
+
/** Resolve a dotted state path the one way every reader does: a record by key, an array by a
|
|
7
|
+
* non-negative integer index, anything else (a string, a number, a missing value) to undefined.
|
|
8
|
+
* `requires`, interpolation, `itemsPath`, `output.path` and predicates all read through here, so a
|
|
9
|
+
* path that names a value for one names it for all. */
|
|
5
10
|
export function getPath(value, key) {
|
|
6
11
|
if (!key)
|
|
7
12
|
return value;
|
|
8
|
-
return key.split(".").reduce((current, part) =>
|
|
13
|
+
return key.split(".").reduce((current, part) => {
|
|
14
|
+
if (isRecord(current))
|
|
15
|
+
return current[part];
|
|
16
|
+
if (Array.isArray(current)) {
|
|
17
|
+
// Only a position inside the array resolves: a canonical integer below its length. Anything
|
|
18
|
+
// else (a property name, an out-of-range or non-canonical number) is not an element.
|
|
19
|
+
if (!/^(0|[1-9][0-9]*)$/.test(part))
|
|
20
|
+
return undefined;
|
|
21
|
+
const index = Number(part);
|
|
22
|
+
return Number.isSafeInteger(index) && index < current.length ? current[index] : undefined;
|
|
23
|
+
}
|
|
24
|
+
return undefined;
|
|
25
|
+
}, value);
|
|
9
26
|
}
|
|
10
27
|
export function predicateMatches(predicate, value) {
|
|
11
28
|
switch (predicate.predicate) {
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export declare const WORKFLOW_NODE_KINDS: readonly ["chain", "code", "agent", "decide", "extract", "report", "artifact", "map", "parallel", "loop", "escalate", "call", "workflow", "judge", "pick", "sift", "route"];
|
|
2
|
+
export type WorkflowNodeKind = typeof WORKFLOW_NODE_KINDS[number];
|
|
3
|
+
/** Generative kinds: one adapter session each, answering against a schema. */
|
|
4
|
+
export declare const GENERATIVE_NODE_KINDS: readonly ["agent", "decide", "extract", "report"];
|
|
5
|
+
/** Typed-question kinds: one judge request each, no tools and no session. */
|
|
6
|
+
export declare const JUDGMENT_NODE_KINDS: readonly ["judge", "pick", "sift", "route"];
|
|
7
|
+
/** The fields each node kind accepts. Any other key is an authoring error. */
|
|
8
|
+
export declare const NODE_FIELDS: {
|
|
9
|
+
readonly [Kind in WorkflowNodeKind]: readonly string[];
|
|
10
|
+
};
|
|
11
|
+
/** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
|
|
12
|
+
export declare const IGNORED_NODE_FIELDS: {
|
|
13
|
+
readonly [Kind in WorkflowNodeKind]?: readonly string[];
|
|
14
|
+
};
|
|
15
|
+
/** Predicates that read a state value. `poll` accepts only these. */
|
|
16
|
+
export declare const MECHANICAL_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
|
|
17
|
+
/** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
|
|
18
|
+
export declare const WORKFLOW_PREDICATES: readonly ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items", "ask"];
|
|
19
|
+
export type WorkflowPredicateName = typeof WORKFLOW_PREDICATES[number];
|
|
20
|
+
/** The fields each predicate takes. */
|
|
21
|
+
export declare const PREDICATE_FIELDS: {
|
|
22
|
+
readonly [Name in WorkflowPredicateName]: readonly string[];
|
|
23
|
+
};
|
|
24
|
+
export declare const EFFORT_LEVELS: readonly ["minimal", "low", "medium", "high"];
|
|
25
|
+
/** There is no "off": every generative node thinks. */
|
|
26
|
+
export declare const THINKING_LEVELS: readonly ["low", "medium", "high"];
|
|
27
|
+
export declare const MODEL_TIERS: readonly ["fast", "default", "strong"];
|
|
28
|
+
export declare const CALL_TRANSPORTS: readonly ["tool", "executor", "shell"];
|
|
29
|
+
export declare const CALL_RETRY_CLASSES: readonly ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
30
|
+
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
31
|
+
export declare const PROSE_ARTIFACT_TYPES: readonly ["markdown", "report"];
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
// The language's closed vocabulary. The validator admits exactly these kinds, fields and predicates,
|
|
2
|
+
// and the author contract names them from the same constants, so the two cannot drift.
|
|
3
|
+
export const WORKFLOW_NODE_KINDS = [
|
|
4
|
+
"chain", "code", "agent", "decide", "extract", "report", "artifact", "map", "parallel", "loop",
|
|
5
|
+
"escalate", "call", "workflow", "judge", "pick", "sift", "route",
|
|
6
|
+
];
|
|
7
|
+
/** Generative kinds: one adapter session each, answering against a schema. */
|
|
8
|
+
export const GENERATIVE_NODE_KINDS = ["agent", "decide", "extract", "report"];
|
|
9
|
+
/** Typed-question kinds: one judge request each, no tools and no session. */
|
|
10
|
+
export const JUDGMENT_NODE_KINDS = ["judge", "pick", "sift", "route"];
|
|
11
|
+
const GENERATIVE_FIELDS = ["node", "label", "state", "instructions", "sopSection", "out", "as", "requires", "tools", "effort", "thinking", "verify", "tier"];
|
|
12
|
+
/** The fields each node kind accepts. Any other key is an authoring error. */
|
|
13
|
+
export const NODE_FIELDS = {
|
|
14
|
+
chain: ["node", "steps"],
|
|
15
|
+
code: ["node", "label", "code", "as"],
|
|
16
|
+
agent: GENERATIVE_FIELDS,
|
|
17
|
+
decide: GENERATIVE_FIELDS,
|
|
18
|
+
extract: GENERATIVE_FIELDS,
|
|
19
|
+
report: ["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
20
|
+
artifact: ["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
|
|
21
|
+
map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"],
|
|
22
|
+
parallel: ["node", "label", "branches"],
|
|
23
|
+
loop: ["node", "label", "body", "until", "maxIters"],
|
|
24
|
+
escalate: ["node", "label", "when", "kind", "stage", "summary"],
|
|
25
|
+
call: ["node", "label", "via", "tool", "args", "code", "input", "command", "env", "where", "out", "as", "produces", "deadline_s", "retry", "poll", "requires"],
|
|
26
|
+
workflow: ["node", "label", "workflow", "input", "out", "as"],
|
|
27
|
+
judge: ["node", "label", "state", "out", "as", "requires"],
|
|
28
|
+
pick: ["node", "label", "itemsPath", "describe", "instructions", "state", "allowNone", "as", "requires"],
|
|
29
|
+
sift: ["node", "label", "itemsPath", "describe", "state", "out", "as", "keep", "requires"],
|
|
30
|
+
route: ["node", "label", "state", "instructions", "branches", "unsure", "as", "requires"],
|
|
31
|
+
};
|
|
32
|
+
/** Accepted and ignored for older v2 documents; never taught. The engine invokes the adapter once per node. */
|
|
33
|
+
export const IGNORED_NODE_FIELDS = {
|
|
34
|
+
agent: ["budget"],
|
|
35
|
+
decide: ["samples", "voteField"],
|
|
36
|
+
};
|
|
37
|
+
/** Predicates that read a state value. `poll` accepts only these. */
|
|
38
|
+
export const MECHANICAL_PREDICATES = ["field_equals", "field_true", "in", "count_gte", "gte", "lt", "empty", "no_new_items"];
|
|
39
|
+
/** Every predicate `loop.until` and `escalate.when` accept: the mechanical set plus `ask`, a yes/no judge question. */
|
|
40
|
+
export const WORKFLOW_PREDICATES = [...MECHANICAL_PREDICATES, "ask"];
|
|
41
|
+
/** The fields each predicate takes. */
|
|
42
|
+
export const PREDICATE_FIELDS = {
|
|
43
|
+
field_equals: ["path", "value"],
|
|
44
|
+
field_true: ["path"],
|
|
45
|
+
in: ["path", "values"],
|
|
46
|
+
count_gte: ["path", "n"],
|
|
47
|
+
gte: ["path", "n"],
|
|
48
|
+
lt: ["path", "n"],
|
|
49
|
+
empty: ["path"],
|
|
50
|
+
no_new_items: ["key"],
|
|
51
|
+
ask: ["instructions", "state", "criteria", "gte"],
|
|
52
|
+
};
|
|
53
|
+
export const EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
|
|
54
|
+
/** There is no "off": every generative node thinks. */
|
|
55
|
+
export const THINKING_LEVELS = ["low", "medium", "high"];
|
|
56
|
+
export const MODEL_TIERS = ["fast", "default", "strong"];
|
|
57
|
+
export const CALL_TRANSPORTS = ["tool", "executor", "shell"];
|
|
58
|
+
export const CALL_RETRY_CLASSES = ["timeout", "http_5xx", "http_429", "connection", "exit"];
|
|
59
|
+
/** Artifact types the engine itself treats as prose (the report writer). Every other type names a file. */
|
|
60
|
+
export const PROSE_ARTIFACT_TYPES = ["markdown", "report"];
|