@parcha/agentrun-dsl 0.1.0-beta.3 → 0.1.0-beta.30
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 +165 -21
- package/dist/author-references.d.ts +8 -0
- package/dist/author-references.js +8 -0
- package/dist/author.d.ts +16 -3
- package/dist/author.js +40 -16
- package/dist/authoring.js +2 -2
- package/dist/cli.js +17 -12
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/decision-provider.d.ts +157 -0
- package/dist/decision-provider.js +230 -0
- package/dist/decision-receipts.d.ts +143 -0
- package/dist/decision-receipts.js +93 -0
- package/dist/dry-run.d.ts +14 -1
- package/dist/dry-run.js +58 -15
- package/dist/graph.d.ts +169 -0
- package/dist/graph.js +433 -0
- package/dist/index.d.ts +15 -8
- package/dist/index.js +8 -4
- package/dist/inspection.d.ts +5 -0
- package/dist/inspection.js +16 -3
- package/dist/job.d.ts +14 -0
- package/dist/job.js +5 -0
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/predicates.d.ts +10 -0
- package/dist/predicates.js +18 -0
- package/dist/recovery/binding.d.ts +10 -0
- package/dist/recovery/binding.js +43 -0
- package/dist/recovery/call-key.d.ts +13 -0
- package/dist/recovery/call-key.js +24 -0
- package/dist/recovery/canonical-hash.d.ts +7 -0
- package/dist/recovery/canonical-hash.js +22 -0
- package/dist/recovery/driver.d.ts +238 -0
- package/dist/recovery/driver.js +1337 -0
- package/dist/recovery/effect-failure.d.ts +34 -0
- package/dist/recovery/effect-failure.js +62 -0
- package/dist/recovery/errors.d.ts +31 -0
- package/dist/recovery/errors.js +51 -0
- package/dist/recovery/execution-path.d.ts +53 -0
- package/dist/recovery/execution-path.js +167 -0
- package/dist/recovery/file-store.d.ts +7 -0
- package/dist/recovery/file-store.js +131 -0
- package/dist/recovery/frozen-snapshot.d.ts +274 -0
- package/dist/recovery/frozen-snapshot.js +187 -0
- package/dist/recovery/handoff-block.d.ts +36 -0
- package/dist/recovery/handoff-block.js +148 -0
- package/dist/recovery/handoff-digest.d.ts +58 -0
- package/dist/recovery/handoff-digest.js +195 -0
- package/dist/recovery/handoff-files.d.ts +54 -0
- package/dist/recovery/handoff-files.js +162 -0
- package/dist/recovery/handoff-receipts.d.ts +42 -0
- package/dist/recovery/handoff-receipts.js +53 -0
- package/dist/recovery/handoff-redact.d.ts +12 -0
- package/dist/recovery/handoff-redact.js +44 -0
- package/dist/recovery/handoff.d.ts +44 -0
- package/dist/recovery/handoff.js +46 -0
- package/dist/recovery/index.d.ts +19 -0
- package/dist/recovery/index.js +17 -0
- package/dist/recovery/item-state.d.ts +48 -0
- package/dist/recovery/item-state.js +89 -0
- package/dist/recovery/journal.d.ts +28 -0
- package/dist/recovery/journal.js +139 -0
- package/dist/recovery/memory-store.d.ts +4 -0
- package/dist/recovery/memory-store.js +20 -0
- package/dist/recovery/store.d.ts +105 -0
- package/dist/recovery/store.js +6 -0
- package/dist/recovery/testing/conformance.d.ts +4 -0
- package/dist/recovery/testing/conformance.js +268 -0
- package/dist/recovery/testing/crash-points.d.ts +18 -0
- package/dist/recovery/testing/crash-points.js +43 -0
- package/dist/recovery/testing/crash-sweep.d.ts +65 -0
- package/dist/recovery/testing/crash-sweep.js +146 -0
- package/dist/recovery/testing/index.d.ts +3 -0
- package/dist/recovery/testing/index.js +4 -0
- package/dist/recovery/testing/preload.d.ts +1 -0
- package/dist/recovery/testing/preload.js +3 -0
- package/dist/recovery/transport-facts.d.ts +23 -0
- package/dist/recovery/transport-facts.js +46 -0
- package/dist/recovery/with-recovery.d.ts +50 -0
- package/dist/recovery/with-recovery.js +142 -0
- package/dist/submit-envelope.d.ts +9 -0
- package/dist/submit-envelope.js +40 -0
- package/dist/system-one.d.ts +40 -1
- package/dist/system-one.js +141 -5
- package/dist/testing/decision-provider.d.ts +32 -0
- package/dist/testing/decision-provider.js +183 -0
- package/dist/testing/index.d.ts +1 -0
- package/dist/testing/index.js +2 -0
- package/dist/vocabulary.d.ts +22 -3
- package/dist/vocabulary.js +33 -10
- package/dist/workflow-shape.d.ts +7 -0
- package/dist/workflow-shape.js +115 -67
- package/dist/workflow.d.ts +269 -20
- package/dist/workflow.js +1251 -341
- package/package.json +25 -2
- package/schema/workflow.schema.json +506 -12
- package/skills/author/SKILL.md +6 -1
- package/skills/author/references/jev-decisions.md +58 -6
- package/skills/author/references/language.md +28 -19
- package/skills/author/references/sdk-authoring.md +2 -0
package/dist/author.d.ts
CHANGED
|
@@ -16,6 +16,9 @@ export interface AuthorHostAddendum {
|
|
|
16
16
|
}>>;
|
|
17
17
|
/** The node kinds the host runs. Declared, a candidate using any other kind is refused. */
|
|
18
18
|
nodeKinds?: readonly WorkflowNodeKind[];
|
|
19
|
+
/** The node `metadata` keys an author may set, each with what it holds. Undeclared, an author sets no
|
|
20
|
+
* metadata. The engine never reads them; the host enforces them in its own acceptance checks. */
|
|
21
|
+
metadataKeys?: Readonly<Record<string, string>>;
|
|
19
22
|
/** Host rules, one sentence each. The host enforces them in its own acceptance checks. */
|
|
20
23
|
rules?: readonly string[];
|
|
21
24
|
}
|
|
@@ -36,7 +39,8 @@ export declare function authorContract(options?: {
|
|
|
36
39
|
export interface CandidatePolicyOptions {
|
|
37
40
|
/** Authoritative rubric text by section name. Every generative node must name every section. */
|
|
38
41
|
rubricSections?: Record<string, string>;
|
|
39
|
-
/** Admits code, call and artifact nodes.
|
|
42
|
+
/** Admits code, call and artifact nodes. A candidate's code is syntax-checked before acceptance and run only after
|
|
43
|
+
* its host accepts it; in-process code is not a sandbox (see the README's `code` node note). */
|
|
40
44
|
allowExecutableCandidates?: boolean;
|
|
41
45
|
/** Direct tool calls admitted without executable authorization. */
|
|
42
46
|
allowedEffectTools?: readonly string[];
|
|
@@ -44,9 +48,16 @@ export interface CandidatePolicyOptions {
|
|
|
44
48
|
}
|
|
45
49
|
/** Author policy over a candidate, checked before validation so a refused candidate never evaluates code. */
|
|
46
50
|
export declare function candidatePolicyErrors(candidate: unknown, options: CandidatePolicyOptions): string[];
|
|
51
|
+
export interface HostOutputTypeOptions {
|
|
52
|
+
/** The host's name for an authored artifact type: an authored spelling (another case, dashes for underscores,
|
|
53
|
+
* an alias) mapped to one of `host.outputTypes`, or null when it names none; its answer decides, so null leaves even
|
|
54
|
+
* an exact name as authored. Absent, a type is matched exactly. */
|
|
55
|
+
normalizeType?: (type: string) => string | null | undefined;
|
|
56
|
+
}
|
|
47
57
|
/** 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
|
-
|
|
58
|
+
* type becomes the report writer it is. Validate and run this view; retain and digest the authored bytes. With
|
|
59
|
+
* `normalizeType`, an artifact's type is first mapped to the host's name for it. */
|
|
60
|
+
export declare function applyHostOutputTypes(candidate: Workflow, host: AuthorHostAddendum | undefined, options?: HostOutputTypeOptions): Workflow;
|
|
50
61
|
export interface AuthorWorkflowOptions {
|
|
51
62
|
request: string;
|
|
52
63
|
outputDir: string;
|
|
@@ -56,6 +67,8 @@ export interface AuthorWorkflowOptions {
|
|
|
56
67
|
/** Keys available to a candidate without an input schema; defaults to the host's initial state keys. */
|
|
57
68
|
inputKeys?: string[];
|
|
58
69
|
rubricSections?: Record<string, string>;
|
|
70
|
+
/** Admits code, call and artifact nodes. A candidate's code is syntax-checked before acceptance and run only after
|
|
71
|
+
* its host accepts it; in-process code is not a sandbox (see the README's `code` node note). */
|
|
59
72
|
allowExecutableCandidates?: boolean;
|
|
60
73
|
maxCandidates?: number;
|
|
61
74
|
/** Host acceptance over a structurally valid candidate, in the interpreter's view (`applyHostOutputTypes`):
|
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, FIELD_TYPES, 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("|");
|
|
@@ -18,6 +18,8 @@ const PREDICATE_SHAPES = {
|
|
|
18
18
|
lt: "holds when the finite number at `path` is below `n`",
|
|
19
19
|
empty: "holds when the value at `path` is an empty array, an empty string, null or absent",
|
|
20
20
|
no_new_items: "takes `key`, not `path`; holds when that state key is an empty array or falsy",
|
|
21
|
+
field_type: `holds when the value at \`path\` is of \`type\`, one of ${FIELD_TYPES.join(", ")}; a number only when finite, and an absent value is of no type`,
|
|
22
|
+
not: "holds when `of`, one mechanical predicate (never `ask`), does not; `{\"predicate\": \"not\", \"of\": {\"predicate\": \"field_type\", \"path\": \"score\", \"type\": \"number\"}}` holds when score is absent or not a finite number",
|
|
21
23
|
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
24
|
};
|
|
23
25
|
function nodeFieldLines() {
|
|
@@ -36,7 +38,7 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
|
|
|
36
38
|
- 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
39
|
- ${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
40
|
- 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
|
|
41
|
+
- Keys that hold a ${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 hold a ${code("$")}, and neither may the label of an agent, decide, extract or code node without ${code("as")}.
|
|
40
42
|
- ${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
43
|
|
|
42
44
|
## Node kinds
|
|
@@ -44,6 +46,8 @@ A workflow is {"v":2,"name","schemas","input"?,"output","root"}.
|
|
|
44
46
|
This is the complete set. Each kind accepts exactly these fields; any other field is an error.
|
|
45
47
|
${nodeFieldLines()}
|
|
46
48
|
|
|
49
|
+
Every kind also accepts ${code("metadata")}, an object the host owns and the engine never reads; set only the keys the host addendum names.
|
|
50
|
+
|
|
47
51
|
### Generative nodes: ${GENERATIVE_NODE_KINDS.join(", ")}
|
|
48
52
|
|
|
49
53
|
Each runs one adapter session. A kind is a preset (its duty, default effort and model tier), not a capability limit:
|
|
@@ -57,9 +61,10 @@ Their fields:
|
|
|
57
61
|
- ${code("out")} names the schema the submission must satisfy; the value lands at ${code("as")}.
|
|
58
62
|
- ${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
63
|
- ${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
|
|
64
|
+
- ${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. A node that names no ${code("thinking")} thinks at medium, unless its host sets another level.
|
|
65
|
+
- 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; ${code("max_turns")}, a positive integer, the most turns it asks its host for per attempt, which the host applies within its own cap and refuses above it (the engine enforces nothing, and naming it changes the workflow's digest); 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.
|
|
61
66
|
- ${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
|
|
67
|
+
- ${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.
|
|
63
68
|
- When the workflow has a report, no decide or extract ${code("out")} schema carries ${code("report_markdown")}.
|
|
64
69
|
|
|
65
70
|
### Terminal nodes: report and artifact
|
|
@@ -74,30 +79,33 @@ Typed questions answered by the host's judge in one request each: no tools, no s
|
|
|
74
79
|
- 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
80
|
- ${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
81
|
- ${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
|
|
78
|
-
- ${code("route")}: a non-empty ${code("state")} map, ${code("instructions")} (the one question) and
|
|
82
|
+
- ${code("sift")}: ${code("itemsPath")}, ${code("out")} (a question schema asked of every item; the host splits the items across requests when they exceed its limits) 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")}.
|
|
83
|
+
- ${code("route")} runs one of 2 or more named ${code("branches")}. Jev chooses: a non-empty ${code("state")} map, ${code("instructions")} (the one question) and up to ${SYSTEM_ONE_LIMITS.maxChoiceOptions} branches, each {criteria?, body}; ${code("unsure")} {branch, gte: a number in (0, 1]} takes that branch when the choice's confidence is below ${code("gte")}. Or the workflow already holds the choice: ${code("valuePath")} names the state string that is the branch, each branch is {body}, no question is asked, and ${code("otherwise")} (a branch) takes a missing or unknown name, which otherwise fails; a non-string fails. ${code("as")} records the choice.
|
|
79
84
|
- 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.
|
|
85
|
+
- ${code("images")} {token: reference} sends images with a decision (judge, pick, sift, a route Jev chooses, ask). Each token, such as "<page1>", must appear literally in the node's ${code("state")} or in a question's text; each reference is written as a state value is, such as "{item.pages.0.image}", and must resolve to an image path the host can read. Only a provider that takes image input answers such a node. Pass images by reference, never their bytes in state.
|
|
86
|
+
- Inside a ${code("map")} with ${code("onItemFailure")} ${code("collect")}, a decision whose provider fails (rate limit, HTTP error, invalid answer, timeout) fails that item, and one sent whose outcome was lost, or one the provider refused, ends the item as a row marked ${code("needs_review")}; the other items go on.
|
|
80
87
|
|
|
81
88
|
### Control nodes
|
|
82
89
|
|
|
83
90
|
- ${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.
|
|
91
|
+
- ${code("map")}: ${code("itemsPath")} (an upstream list), ${code("body")} and ${code("as")}. The body sees ${code("item")} and ${code("item_index")}; ${code("maxConcurrency")} is a positive integer (default 4); ${code("resultPath")} selects one path from each completed item's state. Without ${code("resultPath")}, and with no ${code("as")} in the body, each item's result is its whole state, the mapped list included: set ${code("resultPath")} (or an ${code("as")} in the body) for a large map; the validator warns. ${code("onItemFailure")} is ${code("stop")} (default: the first failing item stops the map and the run) or ${code("collect")}. With ${code("collect")}, an item whose node fails (a call that failed after its retries, an agent that delivered no record, output that does not match its schema, a failed check) ends as {item_index, label, code, message} in the list at ${code("failedAs")}, the other items finish, and ${code("as")} stays aligned with the items: ${code("as[i]")} is item i's result, or ${code("null")} when item i failed. Filter the nulls explicitly if only successes are wanted. Gate on ${code("failedAs")} with ${code("escalate")} or a code node; never let failures pass silently. A crash, a cancel, an ${code("escalate")} inside the item or an effect whose outcome is unknown is never collected.
|
|
85
92
|
- ${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")}
|
|
93
|
+
- ${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.
|
|
87
94
|
- ${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
95
|
- ${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
96
|
- ${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,
|
|
97
|
+
- ${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.
|
|
91
98
|
- ${code("via: tool")} takes ${code("tool")} (a host tool address), ${code("args")} (an object) and ${code("out")} (the tool's result schema).
|
|
92
99
|
- ${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
100
|
- ${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
|
|
95
|
-
- ${code("poll")} {until, fail_when?, interval_s: 0.1
|
|
101
|
+
- ${code("retry")} {attempts: an integer >= 1, backoff_s?: a number >= 0, on?: [${[...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES].join(", ")}]}. ${code("where")} accepts only "sandbox".
|
|
102
|
+
- ${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.
|
|
96
103
|
- Validation and dry runs never perform effects: they synthesize the declared result, and a shell result's stdout is "{}".
|
|
97
104
|
|
|
98
105
|
## Predicates
|
|
99
106
|
|
|
100
107
|
${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.
|
|
108
|
+
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"}')}.
|
|
101
109
|
${predicateLines()}
|
|
102
110
|
|
|
103
111
|
## Authority
|
|
@@ -107,6 +115,7 @@ ${predicateLines()}
|
|
|
107
115
|
- 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
116
|
- Acceptance checks are the host's. Never change a check, fixture or threshold to pass.
|
|
109
117
|
- Bound loops and parallelism. Uncertainty escalates or takes an explicit fallback such as ${code("route.unsure")} or a threshold gate.
|
|
118
|
+
- Ask Jev only what needs judgment; compute what is certain in code. Once a judge and code have decided, route by ${code("valuePath")}: asking a route again can contradict that decision.
|
|
110
119
|
|
|
111
120
|
## Example
|
|
112
121
|
|
|
@@ -123,6 +132,9 @@ export function renderAuthorHostAddendum(host) {
|
|
|
123
132
|
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
133
|
lines.push(`- A terminal artifact's ${code("type")} is one of: ${types.join("; ")}.`);
|
|
125
134
|
}
|
|
135
|
+
if (host.metadataKeys && Object.keys(host.metadataKeys).length) {
|
|
136
|
+
lines.push(`- A node's ${code("metadata")} may carry only these keys: ${Object.entries(host.metadataKeys).map(([key, description]) => `${code(key)} (${description})`).join("; ")}.`);
|
|
137
|
+
}
|
|
126
138
|
if (host.nodeKinds)
|
|
127
139
|
lines.push(`- This host runs only these node kinds: ${list(host.nodeKinds)}. Author no other kind.`);
|
|
128
140
|
for (const rule of host.rules ?? [])
|
|
@@ -156,7 +168,12 @@ export function candidatePolicyErrors(candidate, options) {
|
|
|
156
168
|
errors.push(`${String(node.label ?? kind)}: this host does not run ${String(kind)} nodes`);
|
|
157
169
|
if (!options.allowExecutableCandidates && ["code", "call", "artifact"].includes(String(kind)) && !(kind === "call" && node.via === "tool" && typeof node.tool === "string" && options.allowedEffectTools?.includes(node.tool)))
|
|
158
170
|
errors.push(`${kind} requires allowExecutableCandidates`);
|
|
159
|
-
|
|
171
|
+
// `budget` on an agent is accepted for older documents and never read: an author writes budget_usd.
|
|
172
|
+
if (kind === "agent" && Object.hasOwn(node, "budget"))
|
|
173
|
+
errors.push(`${String(node.label ?? kind)}: budget is not read; declare budget_usd, the dollars the node asks to spend`);
|
|
174
|
+
// A route by valuePath asks no question, so like code it carries no rubric.
|
|
175
|
+
const asksJev = JUDGMENT_NODE_KINDS.includes(String(kind)) && !(kind === "route" && node.valuePath !== undefined);
|
|
176
|
+
if (sections.length && asksJev)
|
|
160
177
|
errors.push(`${String(kind)} cannot carry supplied SOP sections; use an LLM node with sopSection`);
|
|
161
178
|
const llm = GENERATIVE_NODE_KINDS.includes(String(kind));
|
|
162
179
|
const predicate = kind === "loop" ? record(node.until) : kind === "escalate" ? record(node.when) : undefined;
|
|
@@ -200,15 +217,18 @@ export function candidatePolicyErrors(candidate, options) {
|
|
|
200
217
|
return errors;
|
|
201
218
|
}
|
|
202
219
|
/** 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
|
-
|
|
220
|
+
* type becomes the report writer it is. Validate and run this view; retain and digest the authored bytes. With
|
|
221
|
+
* `normalizeType`, an artifact's type is first mapped to the host's name for it. */
|
|
222
|
+
export function applyHostOutputTypes(candidate, host, options = {}) {
|
|
205
223
|
const prose = new Set(Object.entries(host?.outputTypes ?? {}).filter(([, spec]) => spec.kind === "prose").map(([type]) => type));
|
|
206
224
|
if (!prose.size)
|
|
207
225
|
return candidate;
|
|
226
|
+
// With a normaliser the host's answer is the name: null or undefined matches no type, the exact one included.
|
|
227
|
+
const nameOf = (type) => typeof type === "string" && options.normalizeType ? options.normalizeType(type) : type;
|
|
208
228
|
const visit = (node) => {
|
|
209
229
|
if (!node || typeof node !== "object")
|
|
210
230
|
return node;
|
|
211
|
-
if (node.node === "artifact" && prose.has(node.type))
|
|
231
|
+
if (node.node === "artifact" && prose.has(nameOf(node.type)))
|
|
212
232
|
return { ...node, type: "report" };
|
|
213
233
|
if (node.node === "chain")
|
|
214
234
|
return { ...node, steps: (node.steps || []).map(visit) };
|
|
@@ -218,6 +238,8 @@ export function applyHostOutputTypes(candidate, host) {
|
|
|
218
238
|
return { ...node, body: visit(node.body) };
|
|
219
239
|
if (node.node === "route")
|
|
220
240
|
return { ...node, branches: Object.fromEntries(Object.entries(node.branches || {}).map(([name, branch]) => [name, { ...branch, body: visit(branch?.body) }])) };
|
|
241
|
+
// Unlike desugarWorkflow, this does not descend into a child workflow: a child may not hold an artifact node
|
|
242
|
+
// (validateWorkflow rejects it, see containsReportNode), so there is nothing for the prose-type rewrite to reach there.
|
|
221
243
|
return node;
|
|
222
244
|
};
|
|
223
245
|
return { ...candidate, root: visit(candidate.root) };
|
|
@@ -255,7 +277,9 @@ export async function authorWorkflow(options) {
|
|
|
255
277
|
const errors = candidatePolicyErrors(value, options);
|
|
256
278
|
if (!errors.length) {
|
|
257
279
|
try {
|
|
258
|
-
|
|
280
|
+
// executeCode: false — a candidate's code is syntax-checked here, never run, so a candidate runs nothing
|
|
281
|
+
// until its host accepts it. Runs and dry runs after acceptance still probe the code.
|
|
282
|
+
const verdict = validateWorkflow(applyHostOutputTypes(value, options.host), { inputKeys, executeCode: false });
|
|
259
283
|
if (!verdict.ok)
|
|
260
284
|
errors.push(...verdict.errors);
|
|
261
285
|
}
|
package/dist/authoring.js
CHANGED
|
@@ -57,7 +57,7 @@ export function defineWorkflow(definition) {
|
|
|
57
57
|
});
|
|
58
58
|
const result = validateWorkflow(document);
|
|
59
59
|
if (!result.ok)
|
|
60
|
-
throw new WorkflowInvalidError(document.name, result.errors);
|
|
60
|
+
throw new WorkflowInvalidError(document.name, result.errors, result.issues);
|
|
61
61
|
const inputSchema = resolveSchemaForWorkflow(document, document.schemas[definition.input]);
|
|
62
62
|
if (!objectContract(inputSchema)) {
|
|
63
63
|
throw new WorkflowSchemaConversionError(definition.input, new Error("workflow input must be constrained to JSON objects; declare type: object or object-only schema alternatives"));
|
|
@@ -98,7 +98,7 @@ function copyJson(value, ancestors, budget, depth) {
|
|
|
98
98
|
return value;
|
|
99
99
|
if (typeof value === "number" && Number.isFinite(value))
|
|
100
100
|
return value;
|
|
101
|
-
if (typeof value !== "object"
|
|
101
|
+
if (typeof value !== "object")
|
|
102
102
|
throw new Error("workflow documents must contain only finite JSON values");
|
|
103
103
|
if (utilTypes.isProxy(value))
|
|
104
104
|
throw new Error("workflow documents must not contain proxies");
|
package/dist/cli.js
CHANGED
|
@@ -8,12 +8,12 @@ import { demoScenarios, runTriageDemo, supportTriage } from "./demo.js";
|
|
|
8
8
|
import { inspectWorkflow, formatWorkflowTree } from "./inspection.js";
|
|
9
9
|
const help = `AgentRun DSL — build, test, and run agent workflows
|
|
10
10
|
|
|
11
|
-
agentrun demo [--scenario billing|technical|ambiguous] [--json]
|
|
12
|
-
agentrun example [file.json] Write the demo workflow (never overwrite)
|
|
13
|
-
agentrun inspect workflow.json [--json] Show structure without executing code
|
|
14
|
-
agentrun validate workflow.json [input.json] --trusted
|
|
15
|
-
agentrun dry-run workflow.json [input.json] --trusted
|
|
16
|
-
agentrun run workflow.json input.json --trusted
|
|
11
|
+
agentrun-dsl demo [--scenario billing|technical|ambiguous] [--json]
|
|
12
|
+
agentrun-dsl example [file.json] Write the demo workflow (never overwrite)
|
|
13
|
+
agentrun-dsl inspect workflow.json [--json] Show structure without executing code
|
|
14
|
+
agentrun-dsl validate workflow.json [input.json] --trusted
|
|
15
|
+
agentrun-dsl dry-run workflow.json [input.json] --trusted [--strict]
|
|
16
|
+
agentrun-dsl run workflow.json input.json --trusted
|
|
17
17
|
|
|
18
18
|
demo runs the real interpreter with scripted judgments, without a key or network.
|
|
19
19
|
run supports deterministic workflows; use the JavaScript API to supply agent,
|
|
@@ -22,6 +22,8 @@ during validation and running. Only use workflows you trust; this is not a sandb
|
|
|
22
22
|
validate checks a supplied input against the workflow's input contract.
|
|
23
23
|
dry-run uses supplied input, or synthesizes it from the declared input schema.
|
|
24
24
|
Without an input schema, dry-run starts with an empty input object.
|
|
25
|
+
dry-run exits 1 when a check fails. A check that could not run (status not_run, the
|
|
26
|
+
reasons under skipped) exits 0 unless --strict is given, which makes it exit 3.
|
|
25
27
|
`;
|
|
26
28
|
async function main(args) {
|
|
27
29
|
const [command] = args;
|
|
@@ -33,7 +35,7 @@ async function main(args) {
|
|
|
33
35
|
let scenario = "billing";
|
|
34
36
|
let scenarioProvided = false;
|
|
35
37
|
let json = false;
|
|
36
|
-
const usage = "Usage: agentrun demo [--scenario billing|technical|ambiguous] [--json]";
|
|
38
|
+
const usage = "Usage: agentrun-dsl demo [--scenario billing|technical|ambiguous] [--json]";
|
|
37
39
|
for (let i = 1; i < args.length; i++) {
|
|
38
40
|
const arg = args[i];
|
|
39
41
|
if (arg === "--json") {
|
|
@@ -77,23 +79,24 @@ async function main(args) {
|
|
|
77
79
|
if (command === "inspect") {
|
|
78
80
|
const positional = args.slice(1).filter(arg => arg !== "--json");
|
|
79
81
|
if (positional.length !== 1 || positional[0].startsWith("--"))
|
|
80
|
-
throw new Error("Usage: agentrun inspect workflow.json [--json]");
|
|
82
|
+
throw new Error("Usage: agentrun-dsl inspect workflow.json [--json]");
|
|
81
83
|
const inspection = inspectWorkflow(JSON.parse(await readFile(resolve(positional[0]), "utf8")));
|
|
82
84
|
console.log(args.includes("--json") ? JSON.stringify(inspection, null, 2) : formatWorkflowTree(inspection));
|
|
83
85
|
return;
|
|
84
86
|
}
|
|
85
87
|
if (!["validate", "dry-run", "run"].includes(command))
|
|
86
|
-
throw new Error(`Unknown command "${command}". Use agentrun --help.`);
|
|
88
|
+
throw new Error(`Unknown command "${command}". Use agentrun-dsl --help.`);
|
|
87
89
|
if (!args.includes("--trusted"))
|
|
88
90
|
throw new Error("Pass --trusted only after reviewing the workflow. Authored JavaScript may execute, including during validation.");
|
|
89
|
-
const
|
|
91
|
+
const strict = command === "dry-run" && args.includes("--strict");
|
|
92
|
+
const positional = args.slice(1).filter(arg => arg !== "--trusted" && !(strict && arg === "--strict"));
|
|
90
93
|
const unknown = positional.find(arg => arg.startsWith("--"));
|
|
91
94
|
if (unknown)
|
|
92
|
-
throw new Error(`Unknown option "${unknown}". Use agentrun --help.`);
|
|
95
|
+
throw new Error(`Unknown option "${unknown}". Use agentrun-dsl --help.`);
|
|
93
96
|
if (!positional[0])
|
|
94
97
|
throw new Error("Provide a workflow JSON file.");
|
|
95
98
|
if (positional.length > 2)
|
|
96
|
-
throw new Error(`Usage: agentrun ${command} workflow.json ${command === "run" ? "input.json" : "[input.json]"} --trusted`);
|
|
99
|
+
throw new Error(`Usage: agentrun-dsl ${command} workflow.json ${command === "run" ? "input.json" : "[input.json]"} --trusted${command === "dry-run" ? " [--strict]" : ""}`);
|
|
97
100
|
if (command === "run" && !positional[1])
|
|
98
101
|
throw new Error("Provide an input JSON file.");
|
|
99
102
|
const workflow = JSON.parse(await readFile(resolve(positional[0]), "utf8"));
|
|
@@ -121,6 +124,8 @@ async function main(args) {
|
|
|
121
124
|
console.log(JSON.stringify(result, null, 2));
|
|
122
125
|
if (!result.ok)
|
|
123
126
|
process.exitCode = 1;
|
|
127
|
+
else if (strict && result.status === "not_run")
|
|
128
|
+
process.exitCode = 3;
|
|
124
129
|
}
|
|
125
130
|
else {
|
|
126
131
|
const result = await runWorkflow(workflow, input, {});
|
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");
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
|
|
2
|
+
import type { WorkflowDeps } from "./workflow.js";
|
|
3
|
+
type RunJudge = NonNullable<WorkflowDeps["runJudge"]>;
|
|
4
|
+
type JudgeParams = Parameters<RunJudge>[0];
|
|
5
|
+
export type DecisionInput = "text" | "json" | "image" | "pdf" | "url";
|
|
6
|
+
/** What a provider answers, so a workflow or host can tell before it asks. */
|
|
7
|
+
export interface DecisionCapabilities {
|
|
8
|
+
types: SystemOneQuestion["type"][];
|
|
9
|
+
inputs: DecisionInput[];
|
|
10
|
+
/** What grounds the answers: nothing, sources for the whole call, or spans per answer. */
|
|
11
|
+
evidence: "none" | "citations" | "spans";
|
|
12
|
+
/** Where the probabilities come from. Only "calibrated" claims to have been measured against outcomes. */
|
|
13
|
+
probability: "calibrated" | "model" | "self_reported" | "none";
|
|
14
|
+
/** Whether it looks things up on the web. */
|
|
15
|
+
grounding: boolean;
|
|
16
|
+
/** "never": a request is paid once sent, so it is never sent again unasked. The provider retries only a request that
|
|
17
|
+
* provably never reached the service (a connect error before sending) or one refused unanswered with a time to
|
|
18
|
+
* retry (a 429 with Retry-After). A failure after sending (a 408, a 5xx, a lost connection) is `outcome_unknown`,
|
|
19
|
+
* and the decision escalates as interrupted. "deduped": the provider answers a decision id it has seen with the
|
|
20
|
+
* same answer and no new charge. */
|
|
21
|
+
replay: "never" | "deduped";
|
|
22
|
+
/** The most questions one request may hold, or null for no limit. */
|
|
23
|
+
maxQuestions: number | null;
|
|
24
|
+
/** The largest state one request may hold, as UTF-8 JSON bytes, or null for no limit. */
|
|
25
|
+
maxStateBytes: number | null;
|
|
26
|
+
/** The models a node may pin, by name; absent or null, any name goes to the provider. */
|
|
27
|
+
models?: readonly string[] | null;
|
|
28
|
+
}
|
|
29
|
+
/** An image a request carries, loaded by the host: its bytes, its type, and the reference it was loaded from. */
|
|
30
|
+
export interface DecisionImage {
|
|
31
|
+
bytes: Uint8Array;
|
|
32
|
+
mime: string;
|
|
33
|
+
ref: string;
|
|
34
|
+
}
|
|
35
|
+
/** A PNG's or JPEG's width and height in pixels, read from its header (PNG's IHDR, a JPEG's first frame marker); null
|
|
36
|
+
* when the bytes are neither or the header is cut short. A provider with a size cap checks it before a paid call. */
|
|
37
|
+
export declare function imageDimensions(bytes: Uint8Array): {
|
|
38
|
+
width: number;
|
|
39
|
+
height: number;
|
|
40
|
+
} | null;
|
|
41
|
+
/** How a host reads an image a decision node names: `ref` is the node's resolved reference (a run-relative path). */
|
|
42
|
+
export type LoadImage = (ref: string, ctx: {
|
|
43
|
+
signal: AbortSignal;
|
|
44
|
+
}) => Promise<{
|
|
45
|
+
bytes: Uint8Array;
|
|
46
|
+
mime: string;
|
|
47
|
+
}>;
|
|
48
|
+
export type DecisionRequest = Pick<JudgeParams, "label" | "kind" | "state" | "questions" | "item" | "executionPath" | "model"> & {
|
|
49
|
+
/** The images, by the token the state or a question names each with; only for a provider whose inputs include image. */
|
|
50
|
+
images?: Record<string, DecisionImage>;
|
|
51
|
+
};
|
|
52
|
+
export interface DecisionContext {
|
|
53
|
+
/** The decision receipt's id: the same request asked again has the same id. */
|
|
54
|
+
decisionId: string;
|
|
55
|
+
signal: AbortSignal;
|
|
56
|
+
/** How long the provider has, every attempt included, in milliseconds; null leaves it to the provider. */
|
|
57
|
+
deadlineMs: number | null;
|
|
58
|
+
}
|
|
59
|
+
/** A source an answer rests on. `scope` is "call" when the provider grounds the whole request in it, or the id of the one
|
|
60
|
+
* question it supports. */
|
|
61
|
+
export interface DecisionEvidence {
|
|
62
|
+
url: string;
|
|
63
|
+
title: string | null;
|
|
64
|
+
excerpts: string[];
|
|
65
|
+
scope: string;
|
|
66
|
+
}
|
|
67
|
+
type WithoutConfidence<A> = A extends {
|
|
68
|
+
confidence: unknown;
|
|
69
|
+
} ? Omit<A, "confidence"> & {
|
|
70
|
+
confidence?: number | null;
|
|
71
|
+
} : A;
|
|
72
|
+
/** An answer as a provider gives it: a choice or score may lack a confidence, which judgeFromProvider derives. */
|
|
73
|
+
export type ProviderAnswer = SystemOneAnswer | WithoutConfidence<Extract<SystemOneAnswer, {
|
|
74
|
+
type: "choice" | "score";
|
|
75
|
+
}>>;
|
|
76
|
+
/** How a cost was reached. "unknown" goes with a null cost, never with 0. */
|
|
77
|
+
export type CostBasis = "reported" | "estimate" | "unknown";
|
|
78
|
+
export interface DecisionOutcome {
|
|
79
|
+
answers: Record<string, ProviderAnswer>;
|
|
80
|
+
evidence: DecisionEvidence[];
|
|
81
|
+
model: string | null;
|
|
82
|
+
usage: {
|
|
83
|
+
input_tokens: number;
|
|
84
|
+
output_tokens: number;
|
|
85
|
+
} | null;
|
|
86
|
+
cost_usd: number | null;
|
|
87
|
+
cost_basis: CostBasis;
|
|
88
|
+
provider_request_id: string | null;
|
|
89
|
+
}
|
|
90
|
+
/** `outcome_unknown`: the request was sent and its outcome is not known (a 408, a 5xx, a connection lost after
|
|
91
|
+
* sending). It may have been answered and billed, so it is not sent again; the run escalates the decision as
|
|
92
|
+
* interrupted. */
|
|
93
|
+
export type DecisionProviderErrorCode = "configuration" | "auth" | "rate_limited" | "timeout" | "aborted" | "invalid_request" | "invalid_response" | "http" | "connection" | "outcome_unknown";
|
|
94
|
+
/** A provider's failure. Its message names what failed, never a key, a header, a request or response body. */
|
|
95
|
+
export declare class DecisionProviderError extends Error {
|
|
96
|
+
readonly code: DecisionProviderErrorCode;
|
|
97
|
+
readonly status?: number;
|
|
98
|
+
readonly attempts: number;
|
|
99
|
+
/** The provider's own reference for the failure, when it gives one. */
|
|
100
|
+
readonly refId?: string;
|
|
101
|
+
/** What a request that was or may have been billed is booked at (`outcome_unknown`, `invalid_response`), with how it was
|
|
102
|
+
* reached; null when unknown. */
|
|
103
|
+
readonly costUsd?: number | null;
|
|
104
|
+
readonly costBasis?: CostBasis;
|
|
105
|
+
/** True when the provider knows the request was never sent (a check before it, cut by the deadline or a cancel):
|
|
106
|
+
* judgeFromProviders keeps its code under a node's timeoutMs, where any other cut is taken for a request that may
|
|
107
|
+
* have been billed. Absent when it may have been sent; `attempts` alone never says so. */
|
|
108
|
+
readonly unsent?: true;
|
|
109
|
+
constructor(code: DecisionProviderErrorCode, message: string, details?: {
|
|
110
|
+
status?: number;
|
|
111
|
+
attempts?: number;
|
|
112
|
+
refId?: string;
|
|
113
|
+
costUsd?: number | null;
|
|
114
|
+
costBasis?: CostBasis;
|
|
115
|
+
unsent?: boolean;
|
|
116
|
+
cause?: unknown;
|
|
117
|
+
});
|
|
118
|
+
}
|
|
119
|
+
export interface DecisionProvider {
|
|
120
|
+
/** "jev", "parallel", "http:<name>" and the like. */
|
|
121
|
+
readonly id: string;
|
|
122
|
+
/** The environment variables it reads its keys from, by name; never their values. */
|
|
123
|
+
readonly needs: readonly string[];
|
|
124
|
+
readonly capabilities: DecisionCapabilities;
|
|
125
|
+
decide(request: DecisionRequest, ctx: DecisionContext): Promise<DecisionOutcome>;
|
|
126
|
+
}
|
|
127
|
+
/** What a provider's error books for its request: one sent whose outcome was lost (`outcome_unknown`), or one answered
|
|
128
|
+
* with what the seam or the provider rejects (`invalid_response`), was or may have been paid for, and is booked at the
|
|
129
|
+
* cost the error carries, null when that is unknown (never 0). Undefined for an error that books nothing. */
|
|
130
|
+
export declare function chargedCost(error: unknown): number | null | undefined;
|
|
131
|
+
/** Refuses, as invalid_request, a request beyond what `capabilities` declares: a question type it does not answer, more
|
|
132
|
+
* questions than it takes, a larger state, or a model it does not serve. A provider calls it before it sends anything. */
|
|
133
|
+
export declare function checkCapabilities(capabilities: DecisionCapabilities, request: Pick<DecisionRequest, "questions" | "state" | "model">): void;
|
|
134
|
+
export interface JudgeFromProviderOptions {
|
|
135
|
+
deadlineMs?: number | null;
|
|
136
|
+
/** Reads the images a node names. A request with images on a host without it is refused as configuration. */
|
|
137
|
+
loadImage?: LoadImage;
|
|
138
|
+
}
|
|
139
|
+
/** The interpreter's runJudge, answered by `provider`: the request goes to it with the decision's id, its signal and
|
|
140
|
+
* `deadlineMs`, and with the images it names, loaded through `loadImage` within that deadline (the provider gets what is
|
|
141
|
+
* left of it; a load the deadline cuts is `timeout`, one the signal cuts `aborted`, and neither was sent); a choice or
|
|
142
|
+
* score without a confidence gets one derived, and the result names each one's source and each image's digest. The
|
|
143
|
+
* answers are validated against the questions, and ones that do not match them are invalid_response. */
|
|
144
|
+
export declare function judgeFromProvider(provider: DecisionProvider, options?: JudgeFromProviderOptions): RunJudge;
|
|
145
|
+
/** The interpreter's runJudge over a host's providers: each request goes to the provider its node names, or to
|
|
146
|
+
* `default`, with the node's pinned model, within the shorter of the node's `timeoutMs` and the provider's own
|
|
147
|
+
* `deadlineMs`: a node only ever shortens it. The node's bound is kept here: when it passes, the call is cut, and a cut
|
|
148
|
+
* call may already have been sent and billed, so it is `outcome_unknown` (the decision escalates as interrupted), never
|
|
149
|
+
* asked again. A call cut while its images load was not sent, and stays `timeout`. The result names the provider that
|
|
150
|
+
* answered. */
|
|
151
|
+
export declare function judgeFromProviders(options: {
|
|
152
|
+
providers: Readonly<Record<string, DecisionProvider>>;
|
|
153
|
+
default: string;
|
|
154
|
+
deadlineMs?: number | null;
|
|
155
|
+
loadImage?: LoadImage;
|
|
156
|
+
}): RunJudge;
|
|
157
|
+
export {};
|