@parcha/agentrun-dsl 0.1.0-beta.8 → 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/README.md CHANGED
@@ -69,9 +69,10 @@ These are the current beta's validation rules. The numeric knobs below carry no
69
69
  | Choice options / route branches | At most 240; `pick.allowNone` reserves one option |
70
70
  | Score rubric | 2–10 levels, indexed from 0 |
71
71
  | Questions per judgment request | Default 256; override with host-owned `WorkflowDeps.maxQuestionsPerRequest` |
72
+ | Judge state bytes per request | No default; host-owned `WorkflowDeps.maxStateBytesPerRequest` (UTF-8 JSON bytes) |
72
73
  | Jev context | Selected provider's token limits; an adapter host may configure an additional byte guard |
73
74
 
74
- The question-count guard applies after collection expansion, including `sift` items multiplied by their questions. It is a host budget guard, not a claim about a provider's service limit.
75
+ The question-count guard applies after collection expansion, including `sift` items multiplied by their questions. It is a host budget guard, not a claim about a provider's service limit. A `sift` over either limit is split, in item order, into requests that each fit, run up to four at a time. Each request carries the sift's `state` and only its own items.
75
76
 
76
77
  `System One` names TypeSafe's typed-question interface used by the judgment types. A `noul` answer is a truth probability from 0 to 1; `answersToValue` turns values at least 0.5 into `true`. Choice and score confidence comes from the adapter response; Noul confidence is `2 × |probability − 0.5|`. Neither is a calibration guarantee.
77
78
 
package/dist/author.js CHANGED
@@ -77,7 +77,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
77
77
  - 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.
78
78
  - ${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")}.
79
79
  - ${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}.
80
- - ${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")}.
80
+ - ${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")}.
81
81
  - ${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
82
  - 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.
83
83
 
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { defineWorkflow, runTypedWorkflow, WorkflowSchemaConversionError } from "./authoring.js";
2
2
  export type { StandardJSONSchema, AuthoringSchema, TypedWorkflow, TypedWorkflowRunResult, WorkflowInput, WorkflowOutput, } from "./authoring.js";
3
3
  export { runWorkflow, validateWorkflow, workflowSha256, WorkflowInvalidError, WorkflowInputInvalidError, WorkflowOutputInvalidError, WorkflowCodeError, WorkflowStateError, WorkflowVerificationError, EffectFailure, EffectDeadlineExceededError, EffectOutcomeUnknownError, EscalationSignal, } from "./workflow.js";
4
- export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CodeNode, CallRetryClass, EffectFailureCode, CallPredicate, PollClause, ModelTier, AgentContext, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, MechanicalPredicate, Predicate, } from "./workflow.js";
4
+ export type { Workflow, WorkflowNode, NodeMetadata, WorkflowDeps, WorkflowEvent, WorkflowRunResult, HostPolicy, HostPolicyContext, Escalation, EffectSettlement, MapItem, LlmNode, JudgeNode, PickNode, SiftNode, RouteNode, WorkflowInvocation, ArtifactNode, ArtifactState, CallNode, CodeNode, CallRetryClass, EffectFailureCode, CallPredicate, PollClause, ModelTier, AgentContext, WorkflowEffort, WorkflowThinking, VerifyClause, AskPredicate, MechanicalPredicate, Predicate, } from "./workflow.js";
5
5
  export { dryRunWorkflow, synthesizeInstance } from "./dry-run.js";
6
6
  export type { DryRunOptions, DryRunResult } from "./dry-run.js";
7
7
  export { compileQuestions, validateAnswers, answersToValue, answersSidecar, answerConfidence, synthesizeAnswers, SYSTEM_ONE_LIMITS, SystemOneError, isSystemOneResponseReason, } from "./system-one.js";
@@ -0,0 +1,3 @@
1
+ /** Copy observation data without reading accessors or sharing mutable data objects.
2
+ * Keep invalid JSON shapes visible so required host trace validation can reject them. */
3
+ export declare function observerSnapshot<T>(value: T): T;
@@ -0,0 +1,46 @@
1
+ import { isProxy } from "node:util/types";
2
+ /** Copy observation data without reading accessors or sharing mutable data objects.
3
+ * Keep invalid JSON shapes visible so required host trace validation can reject them. */
4
+ export function observerSnapshot(value) {
5
+ const seen = new Map();
6
+ const pending = [];
7
+ const copy = (item) => {
8
+ // A proxy can execute code even when its property descriptors are inspected.
9
+ if (isProxy(item))
10
+ return function unavailable() { };
11
+ if (item === null || typeof item !== "object") {
12
+ // Functions are invalid observation data; an inert function preserves that
13
+ // fact without giving an observer the original callable or its properties.
14
+ return typeof item === "function" ? function unavailable() { } : item;
15
+ }
16
+ const known = seen.get(item);
17
+ if (known)
18
+ return known;
19
+ const prototype = Object.getPrototypeOf(item);
20
+ if (prototype !== Object.prototype && prototype !== Array.prototype && prototype !== null)
21
+ return function unavailable() { };
22
+ const target = Array.isArray(item) ? [] : Object.create(prototype);
23
+ seen.set(item, target);
24
+ pending.push([item, target]);
25
+ return target;
26
+ };
27
+ const result = copy(value);
28
+ while (pending.length) {
29
+ const [source, target] = pending.pop();
30
+ for (const key of Reflect.ownKeys(source)) {
31
+ const descriptor = Object.getOwnPropertyDescriptor(source, key);
32
+ if ("value" in descriptor)
33
+ descriptor.value = copy(descriptor.value);
34
+ else {
35
+ // Never invoke authored getters, including during cloning. Their shape
36
+ // remains an accessor so a JSON-validating host still fails closed.
37
+ if (descriptor.get)
38
+ descriptor.get = () => undefined;
39
+ if (descriptor.set)
40
+ descriptor.set = () => { };
41
+ }
42
+ Object.defineProperty(target, key, descriptor);
43
+ }
44
+ }
45
+ return result;
46
+ }
@@ -166,6 +166,33 @@ function roundedFromUnitMass(probabilities) {
166
166
  }
167
167
  return low <= 1 + 1e-5 && high >= 1 - 1e-5;
168
168
  }
169
+ // A Score's weighted level drifts the same way. The unrounded probabilities lie within their rounding
170
+ // intervals and sum to 1, so Σ level·p lies between two bounds: start every level at its interval's
171
+ // low end, then give the rest of the unit mass to the lowest levels (the minimum) or the highest (the
172
+ // maximum), each up to its interval's high end. A score on the grid is itself off by up to 0.005. The
173
+ // score is accepted when its interval meets [min, max]; with no grid values this is
174
+ // |score − Σ level·p| ≤ 1e-5. A score that is not a number contradicts nothing here and is left to
175
+ // the range check, as before.
176
+ function scoreContradictsDistribution(score, probabilities) {
177
+ const levels = Object.entries(probabilities).map(([level, p]) => {
178
+ const step = onTwoPlaceGrid(p) ? ROUNDING_HALF_STEP : 0;
179
+ return { level: Number(level), low: Math.max(0, p - step), high: Math.min(1, p + step) };
180
+ }).sort((a, b) => a.level - b.level);
181
+ const floor = levels.reduce((sum, l) => sum + l.level * l.low, 0);
182
+ const spare = Math.max(0, 1 - levels.reduce((sum, l) => sum + l.low, 0));
183
+ const fill = (order) => {
184
+ let rest = spare, weighted = floor;
185
+ for (const l of order) {
186
+ const add = Math.min(rest, l.high - l.low);
187
+ weighted += l.level * add;
188
+ rest -= add;
189
+ }
190
+ return weighted;
191
+ };
192
+ const min = fill(levels), max = fill([...levels].reverse());
193
+ const step = onTwoPlaceGrid(score) ? ROUNDING_HALF_STEP : 0;
194
+ return score - step > max + 1e-5 || score + step < min - 1e-5;
195
+ }
169
196
  export function validateAnswers(questions, answers) {
170
197
  if (!answers || typeof answers !== "object" || Array.isArray(answers))
171
198
  throw new SystemOneError("System One response carries no answers", null, undefined, "answers_shape");
@@ -196,8 +223,7 @@ export function validateAnswers(questions, answers) {
196
223
  if (q.type === "score") {
197
224
  if (!a.legend || typeof a.legend !== "object" || Array.isArray(a.legend) || Object.keys(a.legend).length !== expectedKeys.length || q.criteria.some((text, index) => a.legend[String(index)] !== text))
198
225
  throw new SystemOneError("System One answer: legend must match the score criteria", null, undefined, "score_legend");
199
- const weighted = expectedKeys.reduce((sum, key) => sum + Number(key) * a.probabilities[key], 0);
200
- if (Math.abs(weighted - a.score) > 1e-5)
226
+ if (scoreContradictsDistribution(a.score, a.probabilities))
201
227
  throw new SystemOneError("System One answer: score must match its weighted distribution", null, undefined, "score_consistency");
202
228
  }
203
229
  if (q.type === "choice" && !(typeof a.choice === "string" && Object.prototype.hasOwnProperty.call(q.criteria, a.choice)))
@@ -401,6 +401,10 @@ export type HostPolicy = {
401
401
  };
402
402
  export type WorkflowDeps = {
403
403
  maxQuestionsPerRequest?: number;
404
+ /** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
405
+ * measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
406
+ * requests. Absent = no byte limit. */
407
+ maxStateBytesPerRequest?: number;
404
408
  /** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
405
409
  hostPolicy?: HostPolicy;
406
410
  runNode?: (params: {
@@ -440,6 +444,10 @@ export type WorkflowDeps = {
440
444
  attempt: number;
441
445
  idempotencyKey: string;
442
446
  signal: AbortSignal;
447
+ /** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
448
+ * interpreter armed its deadline timer, so the host measures its own kill and duration against
449
+ * the instant the timer fires. Absent when the call has no deadline. */
450
+ deadlineAt?: number;
443
451
  item?: MapItem;
444
452
  executionPath?: string;
445
453
  }) => Promise<unknown>;
@@ -497,12 +505,17 @@ export type WorkflowDeps = {
497
505
  signal?: AbortSignal;
498
506
  /** Best-effort observation only: thrown errors and rejected promises are ignored.
499
507
  * Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
500
- onEvent?: (event: {
501
- type: string;
502
- label: string;
503
- detail?: unknown;
504
- executionPath?: string;
505
- }) => void;
508
+ onEvent?: (event: WorkflowEvent) => void;
509
+ /** Trusted host boundary: return a detached snapshot without mutating the input.
510
+ * Runs before generic copying; undefined or thrown errors omit the event.
511
+ * Required trace validation cancels through the host signal, preserving execution cleanup. */
512
+ prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
513
+ };
514
+ export type WorkflowEvent = {
515
+ type: string;
516
+ label: string;
517
+ detail?: unknown;
518
+ executionPath?: string;
506
519
  };
507
520
  export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
508
521
  export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
package/dist/workflow.js CHANGED
@@ -1,3 +1,4 @@
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";
@@ -1615,7 +1616,7 @@ async function runCallNode(node, state, workflow, deps) {
1615
1616
  if (controller.signal.aborted || performance.now() >= attemptDeadlineMs) {
1616
1617
  throw new EffectFailure(`call node "${node.label}" deadline elapsed before effect admission`, "timeout");
1617
1618
  }
1618
- 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 } : {}) });
1619
1620
  }).then(value => finish({ status: "fulfilled", value }), reason => finish({ status: "rejected", reason }));
1620
1621
  const outcome = await Promise.race([settlement, interrupted]);
1621
1622
  if (outcome.status === "unknown")
@@ -1712,13 +1713,62 @@ async function runCallNode(node, state, workflow, deps) {
1712
1713
  }
1713
1714
  return { ...state, [node.as]: result };
1714
1715
  }
1715
- function assertQuestionCount(deps, count, label) {
1716
+ function questionLimit(deps) {
1716
1717
  const limit = deps.maxQuestionsPerRequest ?? 256;
1717
1718
  if (!Number.isSafeInteger(limit) || limit < 1)
1718
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);
1719
1733
  if (count > limit)
1720
1734
  throw new Error(`node "${label}": ${count} questions exceed maxQuestionsPerRequest (${limit}); reduce the collection/question set or raise the host limit`);
1721
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
+ }
1722
1772
  const requireJudge = (deps, kind, label) => {
1723
1773
  if (!deps.runJudge)
1724
1774
  throw new Error(`${kind} node "${label}": this runner has no System One runner (deps.runJudge)`);
@@ -1744,9 +1794,9 @@ function questionSetOf(workflow, node) {
1744
1794
  };
1745
1795
  }
1746
1796
  const describeItem = (template, state, item, index) => interpolate(template, { ...state, item, item_index: index }).replace(/\s+/g, " ").trim();
1747
- async function askQuestions(deps, node, asked, questions) {
1797
+ async function askQuestions(deps, node, asked, questions, signal = deps.signal) {
1748
1798
  const runJudge = requireJudge(deps, node.node, node.label);
1749
- 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 });
1750
1800
  validateAnswers(questions, result.answers);
1751
1801
  return { answers: result.answers, sidecar: answersSidecar(result.answers), model: result.model ?? null, cost_usd: result.cost_usd ?? null };
1752
1802
  }
@@ -1797,7 +1847,6 @@ async function runSiftNode(node, state, workflow, deps) {
1797
1847
  throw new WorkflowStateError(`sift node "${node.label}": ${node.itemsPath} is not a list`, node.label, node.itemsPath, "expected_list");
1798
1848
  const set = questionSetOf(workflow, node);
1799
1849
  const ids = Object.keys(set.questions);
1800
- assertQuestionCount(deps, items.length * ids.length, node.label);
1801
1850
  const [keepId, keepTail] = node.keep ? node.keep.path.split(".") : [];
1802
1851
  const values = [];
1803
1852
  const sidecars = [];
@@ -1806,16 +1855,53 @@ async function runSiftNode(node, state, workflow, deps) {
1806
1855
  if (items.length) {
1807
1856
  const base = node.state ? interpolateValue(node.state, state, node.label) : {};
1808
1857
  const named = items.map((item, i) => ({ id: `item_${i}`, ...(node.describe ? { summary: describeItem(node.describe, state, item, i) } : {}), item }));
1809
- const questions = {};
1810
- for (let i = 0; i < items.length; i += 1)
1811
- for (const id of ids)
1812
- questions[`${i}.${id}`] = { ...set.questions[id], instructions: `For \`items[${i}]\` (id item_${i}): ${set.questions[id].instructions}` };
1813
- const { answers, model, cost_usd } = await askQuestions(deps, node, { ...base, items: named }, questions);
1814
- 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}`];
1815
1901
  for (let i = 0; i < items.length; i += 1) {
1816
1902
  const mine = Object.create(null);
1817
1903
  for (const id of ids) {
1818
- const a = answers[`${i}.${id}`];
1904
+ const a = answerOf(i, id);
1819
1905
  if (!a)
1820
1906
  throw new Error(`sift node "${node.label}": no answer for item ${i} question "${id}"`);
1821
1907
  mine[id] = a;
@@ -1885,7 +1971,7 @@ function withExecutionLocation(deps) {
1885
1971
  ...(deps.runNode ? { runNode: params => deps.runNode({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1886
1972
  ...(deps.runEffect ? { runEffect: params => deps.runEffect({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1887
1973
  ...(deps.runJudge ? { runJudge: params => deps.runJudge({ ...params, executionPath: params.executionPath ?? path }) } : {}),
1888
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, executionPath: event.executionPath ?? path }) } : {}),
1974
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, executionPath: event.executionPath ?? path })) } : {}),
1889
1975
  };
1890
1976
  }
1891
1977
  /** Older hosts only support flat child chains outside repeated/branching structure. They must
@@ -1945,21 +2031,37 @@ function scopeDepsToChild(deps, invocation) {
1945
2031
  wait: (node, ms, item, path) => recovery.wait(relabel(node), ms, item, path),
1946
2032
  ...(recovery.fail ? { fail: (node, results, error, path) => recovery.fail(relabel(node), results, error, path) } : {}),
1947
2033
  } } : {}),
1948
- ...(deps.onEvent ? { onEvent: event => deps.onEvent({ ...event, label: `${prefix}/${event.label}` }) } : {}),
2034
+ ...(deps.onEvent ? { onEvent: forwardObserver(deps.onEvent, event => ({ ...event, label: `${prefix}/${event.label}` })) } : {}),
1949
2035
  };
1950
2036
  }
1951
2037
  const STEP_KINDS = new Set(["agent", "decide", "extract", "report", "code", "call", "artifact", "workflow", "judge", "pick", "sift"]);
1952
2038
  const CHECKPOINTED_STRUCTURE_KINDS = new Set(["map", "parallel", "loop", "route"]);
1953
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
+ }
1954
2046
  async function runNodeOnState(node, state, workflow, deps) {
1955
2047
  deps = withExecutionLocation(deps);
1956
2048
  const observer = deps.onEvent;
1957
2049
  if (observer && !guardedObservers.has(observer)) {
1958
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;
1959
2060
  try {
1960
2061
  // TypeScript void callbacks can still return promises. Consume rejection without
1961
2062
  // awaiting telemetry or allowing it to replace an execution or recovery outcome.
1962
- const returned = observer(event);
2063
+ // Observers receive snapshots, never objects shared with execution state.
2064
+ const returned = observer(detached);
1963
2065
  if (returned && typeof returned.then === "function") {
1964
2066
  void Promise.resolve(returned).catch(() => { });
1965
2067
  }
@@ -2518,6 +2620,8 @@ export async function runWorkflow(workflow, input, deps) {
2518
2620
  throw new WorkflowInputInvalidError(workflow.name, [`input must not contain the reserved "${HOST_STATE_KEY}" key`]);
2519
2621
  try {
2520
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");
2521
2625
  const host = hostStateOf(state);
2522
2626
  const output = workflow.output.path
2523
2627
  ? getPath(state, workflow.output.path)
@@ -2563,6 +2667,8 @@ export async function runWorkflowSlice(workflow, input, focus, deps) {
2563
2667
  let out = state;
2564
2668
  for (let i = a; i <= b; i++)
2565
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");
2566
2672
  return { status: "complete", state: out, focus: { from: labels[a], to: labels[b] } };
2567
2673
  }
2568
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.8",
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",
@@ -69,7 +69,7 @@ Typed questions answered by the host's judge in one request each: no tools, no s
69
69
  - A question schema is a flat object. Each property's `description` is its question. A boolean yields a yes-probability; a string enum (at most 240 options, optional per-option `criteria`) yields a choice; an integer with `criteria`: [level descriptions] (2 to 10 levels, minimum 0, maximum the last level index) yields a score. Nothing else is a question.
70
70
  - `judge`: a non-empty `state` map, `out` (a question schema) and `as`. The decoded value lands at `as`, the raw answers at `<as>$answers`.
71
71
  - `pick`: `itemsPath`, `describe` (the option text per item, such as "{item.name}"), `instructions` (the one question) and `as`; `allowNone` adds a none-of-these option. The result is {index, item, none, option}.
72
- - `sift`: `itemsPath`, `out` (a question schema asked of every item in one request) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
72
+ - `sift`: `itemsPath`, `out` (a question schema asked of every item; the host splits the items across requests when they exceed its limits) and `as`. `keep` {path: a question id or <id>.confidence, never a choice, gte?} keeps passing items, in order, at `<as>.items`.
73
73
  - `route`: a non-empty `state` map, `instructions` (the one question) and 2 to 240 named `branches`, each {criteria?, body}. `unsure` {branch: one of the branches, gte: a number in (0, 1]} takes that branch when the choice's confidence is below `gte`. `as` records the choice.
74
74
  - A decoded boolean is true at yes-probability 0.5. To hold a different threshold, read `<as>$answers.answers.<id>.noul` in a code node.
75
75