@parcha/agentrun-dsl 0.1.0-beta.3 → 0.1.0-beta.31

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.
Files changed (103) hide show
  1. package/README.md +165 -21
  2. package/dist/author-references.d.ts +8 -0
  3. package/dist/author-references.js +8 -0
  4. package/dist/author.d.ts +16 -3
  5. package/dist/author.js +40 -16
  6. package/dist/authoring.js +2 -2
  7. package/dist/cli.js +17 -12
  8. package/dist/code-exec.d.ts +6 -0
  9. package/dist/code-exec.js +126 -0
  10. package/dist/decision-provider.d.ts +157 -0
  11. package/dist/decision-provider.js +230 -0
  12. package/dist/decision-receipts.d.ts +143 -0
  13. package/dist/decision-receipts.js +93 -0
  14. package/dist/dry-run.d.ts +14 -1
  15. package/dist/dry-run.js +58 -15
  16. package/dist/graph.d.ts +169 -0
  17. package/dist/graph.js +433 -0
  18. package/dist/index.d.ts +15 -8
  19. package/dist/index.js +8 -4
  20. package/dist/inspection.d.ts +5 -0
  21. package/dist/inspection.js +16 -3
  22. package/dist/job.d.ts +14 -0
  23. package/dist/job.js +5 -0
  24. package/dist/long-timer.d.ts +7 -0
  25. package/dist/long-timer.js +22 -0
  26. package/dist/observer-snapshot.d.ts +3 -0
  27. package/dist/observer-snapshot.js +46 -0
  28. package/dist/predicates.d.ts +10 -0
  29. package/dist/predicates.js +18 -0
  30. package/dist/recovery/binding.d.ts +10 -0
  31. package/dist/recovery/binding.js +43 -0
  32. package/dist/recovery/call-key.d.ts +13 -0
  33. package/dist/recovery/call-key.js +24 -0
  34. package/dist/recovery/canonical-hash.d.ts +7 -0
  35. package/dist/recovery/canonical-hash.js +22 -0
  36. package/dist/recovery/driver.d.ts +238 -0
  37. package/dist/recovery/driver.js +1337 -0
  38. package/dist/recovery/effect-failure.d.ts +34 -0
  39. package/dist/recovery/effect-failure.js +62 -0
  40. package/dist/recovery/errors.d.ts +31 -0
  41. package/dist/recovery/errors.js +51 -0
  42. package/dist/recovery/execution-path.d.ts +53 -0
  43. package/dist/recovery/execution-path.js +167 -0
  44. package/dist/recovery/file-store.d.ts +7 -0
  45. package/dist/recovery/file-store.js +131 -0
  46. package/dist/recovery/frozen-snapshot.d.ts +274 -0
  47. package/dist/recovery/frozen-snapshot.js +187 -0
  48. package/dist/recovery/handoff-block.d.ts +36 -0
  49. package/dist/recovery/handoff-block.js +148 -0
  50. package/dist/recovery/handoff-digest.d.ts +58 -0
  51. package/dist/recovery/handoff-digest.js +195 -0
  52. package/dist/recovery/handoff-files.d.ts +54 -0
  53. package/dist/recovery/handoff-files.js +162 -0
  54. package/dist/recovery/handoff-receipts.d.ts +42 -0
  55. package/dist/recovery/handoff-receipts.js +53 -0
  56. package/dist/recovery/handoff-redact.d.ts +12 -0
  57. package/dist/recovery/handoff-redact.js +44 -0
  58. package/dist/recovery/handoff.d.ts +44 -0
  59. package/dist/recovery/handoff.js +46 -0
  60. package/dist/recovery/index.d.ts +19 -0
  61. package/dist/recovery/index.js +17 -0
  62. package/dist/recovery/item-state.d.ts +48 -0
  63. package/dist/recovery/item-state.js +89 -0
  64. package/dist/recovery/journal.d.ts +28 -0
  65. package/dist/recovery/journal.js +139 -0
  66. package/dist/recovery/memory-store.d.ts +4 -0
  67. package/dist/recovery/memory-store.js +20 -0
  68. package/dist/recovery/store.d.ts +105 -0
  69. package/dist/recovery/store.js +6 -0
  70. package/dist/recovery/testing/conformance.d.ts +4 -0
  71. package/dist/recovery/testing/conformance.js +268 -0
  72. package/dist/recovery/testing/crash-points.d.ts +18 -0
  73. package/dist/recovery/testing/crash-points.js +43 -0
  74. package/dist/recovery/testing/crash-sweep.d.ts +65 -0
  75. package/dist/recovery/testing/crash-sweep.js +146 -0
  76. package/dist/recovery/testing/index.d.ts +3 -0
  77. package/dist/recovery/testing/index.js +4 -0
  78. package/dist/recovery/testing/preload.d.ts +1 -0
  79. package/dist/recovery/testing/preload.js +3 -0
  80. package/dist/recovery/transport-facts.d.ts +23 -0
  81. package/dist/recovery/transport-facts.js +46 -0
  82. package/dist/recovery/with-recovery.d.ts +50 -0
  83. package/dist/recovery/with-recovery.js +142 -0
  84. package/dist/submit-envelope.d.ts +9 -0
  85. package/dist/submit-envelope.js +40 -0
  86. package/dist/system-one.d.ts +40 -1
  87. package/dist/system-one.js +141 -5
  88. package/dist/testing/decision-provider.d.ts +32 -0
  89. package/dist/testing/decision-provider.js +183 -0
  90. package/dist/testing/index.d.ts +1 -0
  91. package/dist/testing/index.js +2 -0
  92. package/dist/vocabulary.d.ts +22 -3
  93. package/dist/vocabulary.js +33 -10
  94. package/dist/workflow-shape.d.ts +7 -0
  95. package/dist/workflow-shape.js +115 -67
  96. package/dist/workflow.d.ts +269 -20
  97. package/dist/workflow.js +1251 -341
  98. package/package.json +25 -2
  99. package/schema/workflow.schema.json +506 -12
  100. package/skills/author/SKILL.md +6 -1
  101. package/skills/author/references/jev-decisions.md +58 -6
  102. package/skills/author/references/language.md +28 -19
  103. 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
- export declare function applyHostOutputTypes(candidate: Workflow, host: AuthorHostAddendum | undefined): Workflow;
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 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")}.
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, and nodes carry no budgets.
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..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.
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 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.
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")} 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.
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, at most 3600) are required.
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..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.
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
- if (sections.length && JUDGMENT_NODE_KINDS.includes(String(kind)))
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
- export function applyHostOutputTypes(candidate, host) {
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
- const verdict = validateWorkflow(applyHostOutputTypes(value, options.host), { inputKeys });
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" || value === null)
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 positional = args.slice(1).filter(arg => arg !== "--trusted");
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, {});
@@ -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 {};