@parcha/agentrun-dsl 0.1.0-beta.5 → 0.1.0-beta.9

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/dist/workflow.js CHANGED
@@ -1,13 +1,15 @@
1
+ import { observerSnapshot } from "./observer-snapshot.js";
1
2
  import { createHash } from "node:crypto";
2
3
  import { isDeepStrictEqual, types as utilTypes } from "node:util";
3
4
  import { predicateMatches, getPath, MECHANICAL_PREDICATE_NAMES } from "./predicates.js";
4
- import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
5
+ import { WORKFLOW_NODE_KINDS, NODE_FIELDS, HOST_NODE_FIELDS, IGNORED_NODE_FIELDS, WORKFLOW_PREDICATES, THINKING_LEVELS, MODEL_TIERS, AGENT_CONTEXTS, CALL_TRANSPORTS, CALL_RETRY_CLASSES, EFFECT_FAILURE_CODES, PROSE_ARTIFACT_TYPES } from "./vocabulary.js";
5
6
  import { validateAnswers, answerConfidence, answersSidecar, answersToValue, compileQuestions, SYSTEM_ONE_LIMITS } from "./system-one.js";
6
7
  import { Compile } from "typebox/compile";
7
8
  import { compileTransform, compileTransformSyntax } from "./code-exec.js";
8
9
  import { workflowShapeErrors } from "./workflow-shape.js";
9
10
  import { resolveSchemaForWorkflow } from "./schema-references.js";
10
11
  export { resolveSchemaForWorkflow } from "./schema-references.js";
12
+ import { setLongTimeout } from "./long-timer.js";
11
13
  export function artifactNodeIsProse(node) {
12
14
  return PROSE_ARTIFACT_TYPES.includes(node.type);
13
15
  }
@@ -130,12 +132,21 @@ export const childSteps = (child) => {
130
132
  return null;
131
133
  return root.node === "chain" ? (Array.isArray(root.steps) ? root.steps : null) : [root];
132
134
  };
135
+ /** The code a retry class implies when the failure names none. */
136
+ const codeOfRetryClass = (retryClass) => retryClass === null ? null : retryClass === "timeout" ? "effect_timeout" : retryClass === "exit" ? "effect_exit" : "effect_transport";
137
+ /** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
138
+ * and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
133
139
  export class EffectFailure extends Error {
134
140
  retryClass;
135
- constructor(message, retryClass = null) {
136
- super(message);
141
+ code;
142
+ detail;
143
+ constructor(message, retryClass = null, options = {}) {
144
+ super(message, options.cause === undefined ? undefined : { cause: options.cause });
137
145
  this.retryClass = retryClass;
138
146
  this.name = "EffectFailure";
147
+ this.code = options.code === undefined ? codeOfRetryClass(retryClass) : options.code;
148
+ if (options.detail)
149
+ this.detail = options.detail;
139
150
  }
140
151
  }
141
152
  function containsReportNode(node) {
@@ -317,6 +328,7 @@ export function workflowDocumentError(value) {
317
328
  /** Set executeCode:false for untrusted author feedback: check syntax and mechanical contracts
318
329
  * without evaluating authored expressions or probing transforms. This is not execution admission;
319
330
  * trusted/default validation and runtime output checks remain authoritative. */
331
+ const RETRY_ON_NAMES = [...CALL_RETRY_CLASSES, ...EFFECT_FAILURE_CODES];
320
332
  export function validateWorkflow(workflow, opts) {
321
333
  const bounded = workflowDocumentError(workflow);
322
334
  if (bounded)
@@ -695,6 +707,13 @@ export function validateWorkflow(workflow, opts) {
695
707
  };
696
708
  const checkPredicate = (pred, label, path, field, mechanicalOnly = false) => {
697
709
  const name = pred?.predicate;
710
+ // A predicate with no `predicate` field is the shape mistaken, not an unknown name: say the shape
711
+ // (GRE-2809), naming a predicate the object used as a key when it did.
712
+ if (pred && typeof pred === "object" && !Array.isArray(pred) && name === undefined) {
713
+ const keyed = Object.keys(pred).find((key) => PREDICATES.has(key));
714
+ errors.push(`${path} (${label}): ${field}: a predicate names itself in its "predicate" field beside its own fields, e.g. {"predicate": "${keyed ?? "field_true"}", "path": "..."}${keyed ? `, not {"${keyed}": {...}}` : ""}`);
715
+ return false;
716
+ }
698
717
  if (!pred || !PREDICATES.has(name) || (mechanicalOnly && !MECHANICAL_PREDICATE_NAMES.has(name))) {
699
718
  errors.push(`${path} (${label}): ${field}: unknown predicate "${name}"${mechanicalOnly && name === "ask" ? " (a poll reads a value, never asks a question)" : ""}`);
700
719
  return false;
@@ -777,6 +796,10 @@ export function validateWorkflow(workflow, opts) {
777
796
  checkRequires(node, path);
778
797
  if (node.tier !== undefined && !MODEL_TIERS.includes(String(node.tier)))
779
798
  errors.push(`${path} (${node.label}): tier must be fast|default|strong`);
799
+ if (node.node === "agent" && node.budget_usd !== undefined && !(typeof node.budget_usd === "number" && Number.isFinite(node.budget_usd) && node.budget_usd > 0))
800
+ errors.push(`${path} (${node.label}): budget_usd must be a number of dollars greater than 0`);
801
+ if (node.node === "agent" && node.context !== undefined && !AGENT_CONTEXTS.includes(String(node.context)))
802
+ errors.push(`${path} (${node.label}): context must be ${AGENT_CONTEXTS.join("|")}`);
780
803
  if (node.node !== "report" && node.verify !== undefined) {
781
804
  const v = node.verify;
782
805
  if (!v || typeof v !== "object" || typeof v.out !== "string")
@@ -787,8 +810,8 @@ export function validateWorkflow(workflow, opts) {
787
810
  errors.push(`${path} (${node.label}): verify.out "${v.out}" carries no yes/no question — a verifier decides by yes/no (a boolean named after a submission field verifies it; any other boolean is a requirement)`);
788
811
  if (v.state !== undefined)
789
812
  checkStateMap(v.state, node.label, path, "verify.state");
790
- if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1 || v.maxDrives > 4))
791
- errors.push(`${path} (${node.label}): verify.maxDrives must be an integer 1..4`);
813
+ if (v.maxDrives !== undefined && (!Number.isInteger(v.maxDrives) || v.maxDrives < 1))
814
+ errors.push(`${path} (${node.label}): verify.maxDrives must be an integer >= 1`);
792
815
  if (v.override !== undefined && (typeof v.override?.below !== "number" || v.override.below <= 0 || v.override.below >= 1))
793
816
  errors.push(`${path} (${node.label}): verify.override.below must be in (0, 1)`);
794
817
  }
@@ -856,8 +879,10 @@ export function validateWorkflow(workflow, opts) {
856
879
  }
857
880
  return;
858
881
  case "loop":
859
- if (!Number.isInteger(node.maxIters) || node.maxIters < 1 || node.maxIters > 20)
860
- errors.push(`${path} (${node.label}): maxIters must be 1..20`);
882
+ if (!Number.isInteger(node.maxIters) || node.maxIters < 1)
883
+ errors.push(`${path} (${node.label}): maxIters must be an integer >= 1`);
884
+ if (node.expect_iters !== undefined && (!Number.isInteger(node.expect_iters) || node.expect_iters < 1))
885
+ errors.push(`${path} (${node.label}): expect_iters must be an integer >= 1`);
861
886
  if (containsReportNode(node.body))
862
887
  errors.push(`${path} (${node.label}): a report node cannot live inside a loop body — the report is rendered once, after the record is final`);
863
888
  checkPredicate(node.until, node.label, path, "until");
@@ -1104,8 +1129,8 @@ export function validateWorkflow(workflow, opts) {
1104
1129
  errors.push(`${path} (${label}): as required`);
1105
1130
  if (node.where !== undefined && node.where !== "sandbox")
1106
1131
  errors.push(`${path} (${label}): where accepts only "sandbox"`);
1107
- if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0 && node.deadline_s <= 3600))
1108
- errors.push(`${path} (${label}): deadline_s must be greater than 0 and at most 3600 seconds`);
1132
+ if (!(Number.isFinite(node.deadline_s) && node.deadline_s > 0))
1133
+ errors.push(`${path} (${label}): deadline_s is required and must be a finite number greater than 0 seconds`);
1109
1134
  if (node.produces !== undefined && (!Array.isArray(node.produces) || !node.produces.length || node.produces.some((f) => typeof f !== "string" || !f.trim() || f.startsWith("/") || f.split("/").includes(".."))))
1110
1135
  errors.push(`${path} (${label}): produces must be non-empty workspace-relative paths`);
1111
1136
  else
@@ -1113,12 +1138,12 @@ export function validateWorkflow(workflow, opts) {
1113
1138
  producedFiles.add(f);
1114
1139
  if (node.retry !== undefined) {
1115
1140
  const r = node.retry;
1116
- if (!r || !Number.isInteger(r.attempts) || r.attempts < 1 || r.attempts > 5)
1117
- errors.push(`${path} (${label}): retry.attempts must be 1..5`);
1118
- if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0 && r.backoff_s <= 60))
1119
- errors.push(`${path} (${label}): retry.backoff_s must be 0..60`);
1120
- if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !CALL_RETRY_CLASSES.includes(String(c)))))
1121
- errors.push(`${path} (${label}): retry.on may name only timeout|http_5xx|http_429|connection|exit`);
1141
+ if (!r || !Number.isInteger(r.attempts) || r.attempts < 1)
1142
+ errors.push(`${path} (${label}): retry.attempts must be an integer >= 1`);
1143
+ if (r?.backoff_s !== undefined && !(Number.isFinite(r.backoff_s) && r.backoff_s >= 0))
1144
+ errors.push(`${path} (${label}): retry.backoff_s must be a finite number >= 0`);
1145
+ if (r?.on !== undefined && (!Array.isArray(r.on) || r.on.some((c) => !RETRY_ON_NAMES.includes(String(c)))))
1146
+ errors.push(`${path} (${label}): retry.on may name only ${RETRY_ON_NAMES.join("|")}`);
1122
1147
  }
1123
1148
  if (node.poll !== undefined) {
1124
1149
  const p = node.poll;
@@ -1138,10 +1163,10 @@ export function validateWorkflow(workflow, opts) {
1138
1163
  if (resultShape && typeof resultShape === "object" && predPath && resultPathMissing(resultShape, predPath))
1139
1164
  errors.push(`${path} (${label}): poll.${name} path "${predPath}" is not in the declared result shape (${Object.keys(resultShape).join(", ")}); the poll could never settle`);
1140
1165
  }
1141
- if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1 && p.interval_s <= 300))
1142
- errors.push(`${path} (${label}): poll.interval_s must be 0.1..300 seconds`);
1143
- if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0) && p.deadline_s <= 7200))
1144
- errors.push(`${path} (${label}): poll.deadline_s must be at least deadline_s and at most 7200 seconds`);
1166
+ if (!(Number.isFinite(p.interval_s) && p.interval_s >= 0.1))
1167
+ errors.push(`${path} (${label}): poll.interval_s must be a finite number of at least 0.1 seconds`);
1168
+ if (!(Number.isFinite(p.deadline_s) && p.deadline_s >= (Number(node.deadline_s) || 0)))
1169
+ errors.push(`${path} (${label}): poll.deadline_s must be a finite number at least deadline_s`);
1145
1170
  }
1146
1171
  }
1147
1172
  checkRequires({ label, requires: node.requires }, path);
@@ -1493,8 +1518,8 @@ const sleep = (ms, signal) => new Promise((resolve, reject) => {
1493
1518
  reject(signal.reason ?? new Error("workflow aborted"));
1494
1519
  return;
1495
1520
  }
1496
- const aborted = () => { clearTimeout(timer); reject(signal?.reason ?? new Error("workflow aborted")); };
1497
- const timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1521
+ const aborted = () => { timer.clear(); reject(signal?.reason ?? new Error("workflow aborted")); };
1522
+ const timer = setLongTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
1498
1523
  signal?.addEventListener("abort", aborted, { once: true });
1499
1524
  });
1500
1525
  async function runCallNode(node, state, workflow, deps) {
@@ -1533,7 +1558,7 @@ async function runCallNode(node, state, workflow, deps) {
1533
1558
  throw new EffectFailure(`call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline`, "timeout");
1534
1559
  const controller = new AbortController();
1535
1560
  const attemptMs = Math.max(1, Math.min(node.deadline_s * 1000, remainingMs <= 0 && deps.recovery ? Infinity : remainingMs));
1536
- const attemptDeadlineMs = Date.now() + attemptMs;
1561
+ const attemptDeadlineMs = performance.now() + attemptMs;
1537
1562
  let settled;
1538
1563
  let unknownOutcome;
1539
1564
  let interruptionCheck;
@@ -1569,16 +1594,29 @@ async function runCallNode(node, state, workflow, deps) {
1569
1594
  };
1570
1595
  const onAbort = () => interrupt("cancelled", deps.signal?.reason);
1571
1596
  deps.signal?.addEventListener("abort", onAbort, { once: true });
1572
- const timer = setTimeout(() => interrupt("deadline"), attemptMs);
1597
+ // libuv may fire a timer up to 1 ms before the requested instant. Re-read the monotonic
1598
+ // clock and re-arm for the remainder, so the deadline never interrupts an effect early.
1599
+ // setLongTimeout keeps a deadline past Node's 2^31-1 ms timer limit from overflowing.
1600
+ let timer;
1601
+ const armDeadline = (ms) => {
1602
+ timer = setLongTimeout(() => {
1603
+ const remainingMs = attemptDeadlineMs - performance.now();
1604
+ if (remainingMs > 0)
1605
+ armDeadline(Math.ceil(remainingMs));
1606
+ else
1607
+ interrupt("deadline");
1608
+ }, ms);
1609
+ };
1610
+ armDeadline(attemptMs);
1573
1611
  try {
1574
1612
  deps.onEvent?.({ type: "effect.attempt", label: node.label, detail: { via: node.via, attempt, idempotency_key: idempotencyKey } });
1575
1613
  Promise.resolve().then(() => {
1576
1614
  if (deps.signal?.aborted)
1577
1615
  throw deps.signal.reason ?? new Error("workflow aborted");
1578
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs) {
1616
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs) {
1579
1617
  throw new EffectFailure(`call node "${node.label}" deadline elapsed before effect admission`, "timeout");
1580
1618
  }
1581
- return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal });
1619
+ return deps.runEffect({ node: effectNode, schema, input, produces, attempt, idempotencyKey, signal: controller.signal, ...(Number.isFinite(attemptDeadlineMs) ? { deadlineAt: attemptDeadlineMs } : {}) });
1582
1620
  }).then(value => finish({ status: "fulfilled", value }), reason => finish({ status: "rejected", reason }));
1583
1621
  const outcome = await Promise.race([settlement, interrupted]);
1584
1622
  if (outcome.status === "unknown")
@@ -1588,7 +1626,7 @@ async function runCallNode(node, state, workflow, deps) {
1588
1626
  result = outcome.value;
1589
1627
  if (deps.signal?.aborted)
1590
1628
  throw deps.signal.reason ?? new Error("workflow aborted");
1591
- if (controller.signal.aborted || Date.now() >= attemptDeadlineMs)
1629
+ if (controller.signal.aborted || performance.now() >= attemptDeadlineMs)
1592
1630
  throw new EffectDeadlineExceededError(node.label, result);
1593
1631
  failed = false;
1594
1632
  lastError = undefined;
@@ -1603,16 +1641,21 @@ async function runCallNode(node, state, workflow, deps) {
1603
1641
  ? new EffectFailure(cutByPoll ? `call node "${node.label}" poll exceeded its ${node.poll?.deadline_s}s deadline` : `call node "${node.label}" exceeded its ${node.deadline_s}s deadline`, "timeout")
1604
1642
  : error;
1605
1643
  const retryClass = lastError instanceof EffectFailure ? lastError.retryClass : null;
1644
+ // The row's `code` is closed: an EffectFailure's code when it is one of EFFECT_FAILURE_CODES, else
1645
+ // null. Any other typed error's own code (an unknown outcome, a host's receipts failure) rides
1646
+ // beside it as `error_code`, never as `code`.
1647
+ const code = lastError instanceof EffectFailure && EFFECT_FAILURE_CODES.includes(lastError.code) ? lastError.code : null;
1648
+ const errorCode = code === null && typeof lastError?.code === "string" ? lastError.code : null;
1606
1649
  // Durable admission is uncertain after failure; only the host can reconcile it.
1607
- const retryable = !deps.signal?.aborted && !deps.recovery && retryClass !== null && retryOn.has(retryClass) && attempt < attempts;
1608
- deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { via: node.via, attempt, retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1650
+ const retryable = !deps.signal?.aborted && !deps.recovery && ((retryClass !== null && retryOn.has(retryClass)) || (code !== null && retryOn.has(code))) && attempt < attempts;
1651
+ deps.onEvent?.({ type: "effect.failed", label: node.label, detail: { ...(lastError instanceof EffectFailure ? lastError.detail : undefined), via: node.via, attempt, code, ...(errorCode !== null ? { error_code: errorCode } : {}), retry_class: retryClass, retrying: retryable, ...(lastError instanceof EffectOutcomeUnknownError ? { outcome: "unknown", interruption: lastError.interruption, idempotency_key: idempotencyKey } : {}), message: String(lastError?.message || lastError).slice(0, 300) } });
1609
1652
  if (!retryable || (budgetUntilMs !== undefined && Date.now() >= budgetUntilMs))
1610
1653
  break;
1611
1654
  const delay = Math.min((node.retry?.backoff_s ?? 1) * 1000 * attempt, budgetUntilMs === undefined ? Infinity : Math.max(0, budgetUntilMs - Date.now()));
1612
1655
  await sleep(delay, deps.signal);
1613
1656
  }
1614
1657
  finally {
1615
- clearTimeout(timer);
1658
+ timer?.clear();
1616
1659
  if (interruptionCheck)
1617
1660
  clearImmediate(interruptionCheck);
1618
1661
  deps.signal?.removeEventListener("abort", onAbort);
@@ -1670,13 +1713,62 @@ async function runCallNode(node, state, workflow, deps) {
1670
1713
  }
1671
1714
  return { ...state, [node.as]: result };
1672
1715
  }
1673
- function assertQuestionCount(deps, count, label) {
1716
+ function questionLimit(deps) {
1674
1717
  const limit = deps.maxQuestionsPerRequest ?? 256;
1675
1718
  if (!Number.isSafeInteger(limit) || limit < 1)
1676
1719
  throw new Error("maxQuestionsPerRequest must be a positive safe integer");
1720
+ return limit;
1721
+ }
1722
+ function stateByteLimit(deps) {
1723
+ const limit = deps.maxStateBytesPerRequest;
1724
+ if (limit === undefined)
1725
+ return null;
1726
+ if (!Number.isSafeInteger(limit) || limit < 1)
1727
+ throw new Error("maxStateBytesPerRequest must be a positive safe integer");
1728
+ return limit;
1729
+ }
1730
+ function assertQuestionCount(deps, count, label) {
1731
+ const limit = questionLimit(deps);
1732
+ stateByteLimit(deps);
1677
1733
  if (count > limit)
1678
1734
  throw new Error(`node "${label}": ${count} questions exceed maxQuestionsPerRequest (${limit}); reduce the collection/question set or raise the host limit`);
1679
1735
  }
1736
+ const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
1737
+ /** A split sift's requests in flight at once: the same default as `map.maxConcurrency`. A host that
1738
+ * needs fewer bounds its own `runJudge`. */
1739
+ const SIFT_REQUESTS_IN_FLIGHT = 4;
1740
+ /** Splits a sift's items, in order, into requests that each fit the host's question limit and, when set,
1741
+ * its state byte limit: the UTF-8 length of the JSON state the judge receives, as the Jev adapter
1742
+ * measures it. Sizes are exact: JSON of `{...base, items: [a, b]}` is JSON of `{...base, items: []}`
1743
+ * plus each item's JSON plus one comma between items. */
1744
+ function siftChunks(deps, label, questionsPerItem, base, named) {
1745
+ const maxQuestions = questionLimit(deps);
1746
+ const maxBytes = stateByteLimit(deps);
1747
+ if (questionsPerItem > maxQuestions)
1748
+ throw new Error(`node "${label}": ${questionsPerItem} questions exceed maxQuestionsPerRequest (${maxQuestions}); reduce the question set or raise the host limit`);
1749
+ const perRequest = Math.floor(maxQuestions / questionsPerItem);
1750
+ const emptyBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify({ ...base, items: [] }));
1751
+ if (maxBytes !== null && emptyBytes > maxBytes)
1752
+ throw new Error(`sift node "${label}": its state alone, before any item, is ${emptyBytes} bytes, over maxStateBytesPerRequest (${maxBytes}); every request carries that state, so make the sift's state smaller or raise the host limit`);
1753
+ const chunks = [];
1754
+ let chunk = [], bytes = emptyBytes;
1755
+ for (let i = 0; i < named.length; i += 1) {
1756
+ const itemBytes = maxBytes === null ? 0 : utf8Bytes(JSON.stringify(named[i]));
1757
+ if (maxBytes !== null && emptyBytes + itemBytes > maxBytes)
1758
+ throw new Error(`sift node "${label}": item ${i} alone makes a ${emptyBytes + itemBytes}-byte judge state, over maxStateBytesPerRequest (${maxBytes}); send less of each item (a code step before the sift) or raise the host limit`);
1759
+ const grown = bytes + itemBytes + (chunk.length ? 1 : 0);
1760
+ if (chunk.length && (chunk.length >= perRequest || (maxBytes !== null && grown > maxBytes))) {
1761
+ chunks.push(chunk);
1762
+ chunk = [];
1763
+ bytes = emptyBytes;
1764
+ }
1765
+ bytes += itemBytes + (chunk.length ? 1 : 0);
1766
+ chunk.push(i);
1767
+ }
1768
+ if (chunk.length)
1769
+ chunks.push(chunk);
1770
+ return chunks;
1771
+ }
1680
1772
  const requireJudge = (deps, kind, label) => {
1681
1773
  if (!deps.runJudge)
1682
1774
  throw new Error(`${kind} node "${label}": this runner has no System One runner (deps.runJudge)`);
@@ -1702,9 +1794,9 @@ function questionSetOf(workflow, node) {
1702
1794
  };
1703
1795
  }
1704
1796
  const describeItem = (template, state, item, index) => interpolate(template, { ...state, item, item_index: index }).replace(/\s+/g, " ").trim();
1705
- async function askQuestions(deps, node, asked, questions) {
1797
+ async function askQuestions(deps, node, asked, questions, signal = deps.signal) {
1706
1798
  const runJudge = requireJudge(deps, node.node, node.label);
1707
- const result = await runJudge({ label: node.label, kind: node.node, state: asked, questions, signal: deps.signal });
1799
+ const result = await runJudge({ label: node.label, kind: node.node, state: asked, questions, signal });
1708
1800
  validateAnswers(questions, result.answers);
1709
1801
  return { answers: result.answers, sidecar: answersSidecar(result.answers), model: result.model ?? null, cost_usd: result.cost_usd ?? null };
1710
1802
  }
@@ -1755,7 +1847,6 @@ async function runSiftNode(node, state, workflow, deps) {
1755
1847
  throw new WorkflowStateError(`sift node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
1756
1848
  const set = questionSetOf(workflow, node);
1757
1849
  const ids = Object.keys(set.questions);
1758
- assertQuestionCount(deps, items.length * ids.length, node.label);
1759
1850
  const [keepId, keepTail] = node.keep ? node.keep.path.split(".") : [];
1760
1851
  const values = [];
1761
1852
  const sidecars = [];
@@ -1764,16 +1855,53 @@ async function runSiftNode(node, state, workflow, deps) {
1764
1855
  if (items.length) {
1765
1856
  const base = node.state ? interpolateValue(node.state, state, node.label) : {};
1766
1857
  const named = items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
1767
- const questions = {};
1768
- for (let i = 0; i < items.length; i += 1)
1769
- for (const id of ids)
1770
- questions[`${i}.${id}`] = { ...set.questions[id], instructions: `For \`items[${i}]\` (id item_${i}): ${set.questions[id].instructions}` };
1771
- const { answers, model, cost_usd } = await askQuestions(deps, node, { ...base, items: named }, questions);
1772
- metering = { model, cost_usd };
1858
+ const chunks = siftChunks(deps, node.label, ids.length, base, named);
1859
+ // Each chunk is its own request: item ids stay global (item_<i>), `items[j]` indexes the chunk.
1860
+ // A sift that fits in one request sends exactly the request it always did. Several requests run at
1861
+ // most SIFT_REQUESTS_IN_FLIGHT at a time; the first failure stops dispatch, cancels the requests in
1862
+ // flight, and is thrown once they settle.
1863
+ const ask = (chunk, signal) => {
1864
+ const questions = {};
1865
+ chunk.forEach((i, j) => { for (const id of ids)
1866
+ questions[`${j}.${id}`] = { ...set.questions[id], instructions: `For \`items[${j}]\` (id item_${i}): ${set.questions[id].instructions}` }; });
1867
+ return askQuestions(deps, node, { ...base, items: chunk.map((i) => named[i]) }, questions, signal);
1868
+ };
1869
+ let results;
1870
+ if (chunks.length === 1)
1871
+ results = [await ask(chunks[0], deps.signal)];
1872
+ else {
1873
+ const stop = new AbortController();
1874
+ const signal = deps.signal ? AbortSignal.any([deps.signal, stop.signal]) : stop.signal;
1875
+ results = new Array(chunks.length);
1876
+ let next = 0, failure;
1877
+ await Promise.all(Array.from({ length: Math.min(SIFT_REQUESTS_IN_FLIGHT, chunks.length) }, async () => {
1878
+ while (!failure && next < chunks.length) {
1879
+ const c = next++;
1880
+ try {
1881
+ results[c] = await ask(chunks[c], signal);
1882
+ }
1883
+ catch (error) {
1884
+ failure ??= { error };
1885
+ stop.abort();
1886
+ }
1887
+ }
1888
+ }));
1889
+ if (failure)
1890
+ throw failure.error;
1891
+ }
1892
+ const models = new Set(results.map((r) => r.model));
1893
+ metering = {
1894
+ model: models.size === 1 ? results[0].model : null,
1895
+ cost_usd: results.every((r) => r.cost_usd !== null) ? results.reduce((sum, r) => sum + r.cost_usd, 0) : null,
1896
+ ...(chunks.length > 1 ? { requests: chunks.length } : {}),
1897
+ };
1898
+ const at = [];
1899
+ chunks.forEach((chunk, c) => chunk.forEach((i, j) => { at[i] = [c, j]; }));
1900
+ const answerOf = (i, id) => results[at[i][0]].answers[`${at[i][1]}.${id}`];
1773
1901
  for (let i = 0; i < items.length; i += 1) {
1774
1902
  const mine = Object.create(null);
1775
1903
  for (const id of ids) {
1776
- const a = answers[`${i}.${id}`];
1904
+ const a = answerOf(i, id);
1777
1905
  if (!a)
1778
1906
  throw new Error(`sift node "${node.label}": no answer for item ${i} question "${id}"`);
1779
1907
  mine[id] = a;
@@ -1843,7 +1971,7 @@ function withExecutionLocation(deps) {
1843
1971
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1844
1972
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1845
1973
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1846
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, executionPath: event.executionPath ?? path }) } : {}),
1974
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, executionPath: event.executionPath ?? path })) } : {}),
1847
1975
  };
1848
1976
  }
1849
1977
  /** Older hosts only support flat child chains outside repeated/branching structure. They must
@@ -1894,6 +2022,7 @@ function scopeDepsToChild(deps, invocation) {
1894
2022
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, label: `${prefix}/${params.label}` }) } : {}),
1895
2023
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, node: relabel(params.node) }) } : {}),
1896
2024
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, label: `${prefix}/${params.label}` }) } : {}),
2025
+ ...(deps.runCode ? { runCode: (node, state, ctx) => deps.runCode(relabel(node), state, { ...ctx, label: `${prefix}/${ctx.label}` }) } : {}),
1897
2026
  ...(recovery ? { recovery: {
1898
2027
  supportsExecutionPaths: recovery.supportsExecutionPaths,
1899
2028
  resume: (node, state, item, path) => recovery.resume(relabel(node), state, item, path),
@@ -1902,21 +2031,37 @@ function scopeDepsToChild(deps, invocation) {
1902
2031
  wait: (node, ms, item, path) => recovery.wait(relabel(node), ms, item, path),
1903
2032
  ...(recovery.fail ? { fail: (node, results, error, path) => recovery.fail(relabel(node), results, error, path) } : {}),
1904
2033
  } } : {}),
1905
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, label: `${prefix}/${event.label}` }) } : {}),
2034
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, label: `${prefix}/${event.label}` })) } : {}),
1906
2035
  };
1907
2036
  }
1908
2037
  const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
1909
2038
  const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
1910
2039
  const guardedObservers = new WeakSet();
2040
+ function forwardObserver(observer, transform) {
2041
+ const forwarded = (event) => observer(transform(event));
2042
+ if (guardedObservers.has(observer))
2043
+ guardedObservers.add(forwarded);
2044
+ return forwarded;
2045
+ }
1911
2046
  async function runNodeOnState(node, state, workflow, deps) {
1912
2047
  deps = withExecutionLocation(deps);
1913
2048
  const observer = deps.onEvent;
1914
2049
  if (observer && !guardedObservers.has(observer)) {
1915
2050
  const guarded = event => {
2051
+ let detached;
2052
+ try {
2053
+ detached = deps.prepareEvent ? deps.prepareEvent(event) : observerSnapshot(event);
2054
+ }
2055
+ catch {
2056
+ return;
2057
+ }
2058
+ if (detached === undefined)
2059
+ return;
1916
2060
  try {
1917
2061
  // TypeScript void callbacks can still return promises. Consume rejection without
1918
2062
  // awaiting telemetry or allowing it to replace an execution or recovery outcome.
1919
- const returned = observer(event);
2063
+ // Observers receive snapshots, never objects shared with execution state.
2064
+ const returned = observer(detached);
1920
2065
  if (returned && typeof returned.then === "function") {
1921
2066
  void Promise.resolve(returned).catch(() => { });
1922
2067
  }
@@ -2011,12 +2156,18 @@ async function runNodeBody(node, state, workflow, deps) {
2011
2156
  }
2012
2157
  case "code": {
2013
2158
  let out;
2014
- try {
2015
- const fn = compileTransform(node.code);
2016
- out = fn(state, { sop: deps.sop || "" });
2159
+ if (deps.runCode) {
2160
+ const item = deps[MAP_ITEM];
2161
+ out = await deps.runCode(node, state, { sop: deps.sop || "", label: node.label, executionPath: executionPath(deps), ...(item ? { item } : {}), ...(deps.signal ? { signal: deps.signal } : {}) });
2017
2162
  }
2018
- catch (cause) {
2019
- throw new WorkflowCodeError(node.label, cause);
2163
+ else {
2164
+ try {
2165
+ const fn = compileTransform(node.code);
2166
+ out = fn(state, { sop: deps.sop || "" });
2167
+ }
2168
+ catch (cause) {
2169
+ throw new WorkflowCodeError(node.label, cause);
2170
+ }
2020
2171
  }
2021
2172
  const patch = node.as ? { [node.as]: out } : (out && typeof out === "object" && !Array.isArray(out) ? out : { [node.label]: out });
2022
2173
  if (Object.prototype.hasOwnProperty.call(patch, HOST_STATE_KEY))
@@ -2080,6 +2231,8 @@ async function runNodeBody(node, state, workflow, deps) {
2080
2231
  kind: node.node, label: node.label,
2081
2232
  ...(review ? { review } : {}),
2082
2233
  ...(node.tier ? { tier: node.tier } : {}),
2234
+ ...(node.node === "agent" && node.budget_usd !== undefined ? { budgetUsd: node.budget_usd } : {}),
2235
+ ...(node.node === "agent" && node.context !== undefined ? { context: node.context } : {}),
2083
2236
  system: [sopSlice, deps.skill, node.instructions, ...(policy?.systemBlocks && context ? policy.systemBlocks(context) : [])].filter(Boolean),
2084
2237
  user: JSON.stringify(promptState),
2085
2238
  schema: transportSchema,
@@ -2444,7 +2597,9 @@ export function assertWorkflowCapabilities(node, deps, workflow) {
2444
2597
  export async function runWorkflow(workflow, input, deps) {
2445
2598
  if (!input || typeof input !== "object" || Array.isArray(input))
2446
2599
  throw new WorkflowInputInvalidError(String(workflow?.name), ["input must be a JSON object"]);
2447
- const valid = validateWorkflow(workflow);
2600
+ // A host that executes code nodes itself never has them executed here, not even as validation probes.
2601
+ const executeCode = deps.runCode ? false : undefined;
2602
+ const valid = validateWorkflow(workflow, { executeCode });
2448
2603
  if (!valid.ok)
2449
2604
  throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2450
2605
  workflow = desugarWorkflow(workflow);
@@ -2453,7 +2608,7 @@ export async function runWorkflow(workflow, input, deps) {
2453
2608
  if (!validator.Check(input))
2454
2609
  throw new WorkflowInputInvalidError(workflow.name, schemaProblems(validator, input));
2455
2610
  }
2456
- const reachable = validateWorkflow(workflow, { inputKeys: Object.keys(input) });
2611
+ const reachable = validateWorkflow(workflow, { executeCode, inputKeys: Object.keys(input) });
2457
2612
  if (!reachable.ok)
2458
2613
  throw new WorkflowInvalidError(workflow.name, reachable.errors);
2459
2614
  assertWorkflowCapabilities(workflow.root, deps, workflow);
@@ -2465,6 +2620,8 @@ export async function runWorkflow(workflow, input, deps) {
2465
2620
  throw new WorkflowInputInvalidError(workflow.name, [`input must not contain the reserved "${HOST_STATE_KEY}" key`]);
2466
2621
  try {
2467
2622
  const state = await runNodeOnState(workflow.root, snapshotState(input), workflow, deps);
2623
+ if (deps.signal?.aborted)
2624
+ throw deps.signal.reason ?? new Error("workflow aborted");
2468
2625
  const host = hostStateOf(state);
2469
2626
  const output = workflow.output.path
2470
2627
  ? getPath(state, workflow.output.path)
@@ -2482,7 +2639,7 @@ export async function runWorkflow(workflow, input, deps) {
2482
2639
  }
2483
2640
  }
2484
2641
  export async function runWorkflowSlice(workflow, input, focus, deps) {
2485
- const valid = validateWorkflow(workflow);
2642
+ const valid = validateWorkflow(workflow, { executeCode: deps.runCode ? false : undefined });
2486
2643
  if (!valid.ok)
2487
2644
  throw new WorkflowInvalidError(String(workflow?.name), valid.errors);
2488
2645
  const desugared = desugarWorkflow(workflow);
@@ -2510,6 +2667,8 @@ export async function runWorkflowSlice(workflow, input, focus, deps) {
2510
2667
  let out = state;
2511
2668
  for (let i = a; i <= b; i++)
2512
2669
  out = await runNodeOnState(root[i], out, desugared, desugared.root.node === "chain" ? scopeExecution(deps, "steps", i) : deps);
2670
+ if (deps.signal?.aborted)
2671
+ throw deps.signal.reason ?? new Error("workflow aborted");
2513
2672
  return { status: "complete", state: out, focus: { from: labels[a], to: labels[b] } };
2514
2673
  }
2515
2674
  catch (error) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@parcha/agentrun-dsl",
3
- "version": "0.1.0-beta.5",
3
+ "version": "0.1.0-beta.9",
4
4
  "description": "Composable, typed workflows for agents",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -184,6 +184,21 @@
184
184
  "type": "string",
185
185
  "title": "tier"
186
186
  },
187
+ "budget_usd": {
188
+ "description": "The most the node asks to spend, in dollars.",
189
+ "exclusiveMinimum": 0,
190
+ "type": "number",
191
+ "title": "budget_usd"
192
+ },
193
+ "context": {
194
+ "description": "An `agent` node's context (`AGENT_CONTEXTS`).",
195
+ "enum": [
196
+ "fork",
197
+ "fresh"
198
+ ],
199
+ "type": "string",
200
+ "title": "context"
201
+ },
187
202
  "metadata": {
188
203
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
189
204
  "type": "object",
@@ -743,6 +758,10 @@
743
758
  "type": "number",
744
759
  "title": "maxIters"
745
760
  },
761
+ "expect_iters": {
762
+ "type": "number",
763
+ "title": "expect_iters"
764
+ },
746
765
  "metadata": {
747
766
  "description": "Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the\ndocument and never reads it; it never reaches state, events, prompts or effect identities.",
748
767
  "type": "object",
@@ -1150,6 +1169,7 @@
1150
1169
  "title": "deadline_s"
1151
1170
  },
1152
1171
  "retry": {
1172
+ "description": "`on` names retry classes or effect failure codes; absent, the transient retry classes.",
1153
1173
  "type": "object",
1154
1174
  "properties": {
1155
1175
  "attempts": {
@@ -1163,7 +1183,24 @@
1163
1183
  "on": {
1164
1184
  "type": "array",
1165
1185
  "items": {
1166
- "$ref": "#/definitions/CallRetryClass"
1186
+ "enum": [
1187
+ "connection",
1188
+ "effect_code_unsafe",
1189
+ "effect_exit",
1190
+ "effect_not_granted",
1191
+ "effect_path_escape",
1192
+ "effect_produces_missing",
1193
+ "effect_timeout",
1194
+ "effect_transport",
1195
+ "effect_unknown_transport",
1196
+ "exit",
1197
+ "http_429",
1198
+ "http_5xx",
1199
+ "output_invalid",
1200
+ "state_invalid",
1201
+ "timeout"
1202
+ ],
1203
+ "type": "string"
1167
1204
  },
1168
1205
  "title": "on"
1169
1206
  }
@@ -1681,18 +1718,6 @@
1681
1718
  }
1682
1719
  ]
1683
1720
  },
1684
- "CallRetryClass": {
1685
- "description": "`exit` is a shell command that ended with a non-zero status: retried only when the author\ndeclared retry, since re-running a command is the author's call.",
1686
- "title": "CallRetryClass",
1687
- "enum": [
1688
- "connection",
1689
- "exit",
1690
- "http_429",
1691
- "http_5xx",
1692
- "timeout"
1693
- ],
1694
- "type": "string"
1695
- },
1696
1721
  "AcceptPredicate": {
1697
1722
  "description": "A predicate a `call` evaluates against ITS OWN RESULT: paths are result-relative.",
1698
1723
  "title": "AcceptPredicate",