@parcha/agentrun-dsl 0.1.0-beta.17 → 0.1.0-beta.19

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.
@@ -32,6 +32,15 @@ const SHA256 = /^[a-f0-9]{64}$/;
32
32
  /** `value` as an object whose fields can be read, or null. */
33
33
  const fields = (value) => record(value) ? value : null;
34
34
  const entriesOf = (value) => { const object = fields(value); return object ? Object.entries(object) : null; };
35
+ const isStepFailure = (value) => {
36
+ const at = fields(value);
37
+ return Boolean(at && Object.keys(at).length === 2 && typeof at.code === "string" && typeof at.message === "string");
38
+ };
39
+ /** Whether a value is an item's committed failure: three strings, and nothing else. */
40
+ export const isItemOutcome = (value) => {
41
+ const at = fields(value);
42
+ return Boolean(at && Object.keys(at).length === 3 && typeof at.code === "string" && typeof at.label === "string" && typeof at.message === "string");
43
+ };
35
44
  const nonNegativeInt = (value) => Number.isSafeInteger(value) && value >= 0;
36
45
  /** Whether a saved frame is one the driver could have written for its document. */
37
46
  function validFrame(value, resolves) {
@@ -46,7 +55,9 @@ function validFrame(value, resolves) {
46
55
  return false;
47
56
  const [states, chains, loops, routes, inputs, steps] = [frame.states, frame.chains, frame.loops, frame.routes, frame.inputs, frame.steps].map(entriesOf);
48
57
  const partial = frame.partial === undefined ? undefined : fields(frame.partial);
58
+ const failures = frame.failures === undefined ? [] : entriesOf(frame.failures);
49
59
  return Boolean(states && states.every(([path, state]) => done.has(path) && record(state))
60
+ && failures && failures.every(([item, outcome]) => /\/items\/(?:0|[1-9]\d*)$/.test(item) && resolves(`${item}/body`) && isItemOutcome(outcome))
50
61
  && chains && chains.every(([, head]) => { const at = fields(head); return Boolean(at && nonNegativeInt(at.index) && typeof at.path === "string" && done.has(at.path)); })
51
62
  && loops && loops.every(([loop, count]) => resolves(loop) && nonNegativeInt(count))
52
63
  && routes && routes.every(([route, decision]) => {
@@ -60,7 +71,8 @@ function validFrame(value, resolves) {
60
71
  const at = fields(step);
61
72
  return Boolean(at && resolves(path) && typeof at.label === "string"
62
73
  && nonNegativeInt(at.attempt) && Number.isSafeInteger(at.attemptsAllowed) && at.attemptsAllowed >= 1
63
- && ["running", "closed", "failed", "submitted"].includes(String(at.status)));
74
+ && ["running", "closed", "failed", "submitted"].includes(String(at.status))
75
+ && (at.failure === undefined || (at.status === "failed" && isStepFailure(at.failure))));
64
76
  })
65
77
  && (partial === undefined || (partial && typeof partial.path === "string" && resolves(partial.path) && typeof partial.as === "string" && Array.isArray(partial.results))));
66
78
  }
@@ -147,8 +159,10 @@ export function admitFrozenStep(steps, path, label, admission) {
147
159
  }
148
160
  /** The current attempt ended without a submission: `closed` until a retry is admitted, or
149
161
  * `failed` when the failure is final or no attempt remains. */
150
- export function closeFrozenStepAttempt(step, final) {
162
+ export function closeFrozenStepAttempt(step, final, failure) {
151
163
  step.status = final || step.attempt + 1 >= step.attemptsAllowed ? "failed" : "closed";
164
+ if (step.status === "failed" && failure)
165
+ step.failure = { code: failure.code, message: failure.message };
152
166
  }
153
167
  /** The run-wide stop the driver applies: the host's pause or cancel it was handed, or null when it keeps
154
168
  * running. A cancelled snapshot stays cancelled. */
@@ -50,8 +50,11 @@ export function withRecovery(driver, deps, options = {}) {
50
50
  driver.stepAttemptFailed(params.executionPath);
51
51
  admission = admit();
52
52
  }
53
- if (admission.status === "failed")
54
- throw new Error(`${params.label} failed after ${admission.attemptsAllowed} attempts`);
53
+ // A step that failed on an item failure is refused with it, so the item it lies in ends on the same failure.
54
+ if (admission.status === "failed") {
55
+ throw admission.failure ? Object.assign(new Error(admission.failure.message), { code: admission.failure.code, itemFailure: true })
56
+ : new Error(`${params.label} failed after ${admission.attemptsAllowed} attempts`);
57
+ }
55
58
  // The step's record is durable before the attempt runs. A stop or a caller's cancellation that landed
56
59
  // meanwhile ends the step here: the runner is not called, and no attempt is spent. A pause waiting for an
57
60
  // effect in flight holds the step here until it is taken.
@@ -71,7 +74,7 @@ export function withRecovery(driver, deps, options = {}) {
71
74
  // A failure the runner marked final (an attempt that ended on a bound of its own) gets no second attempt: it
72
75
  // would spend the same again.
73
76
  const final = error?.final === true;
74
- driver.stepAttemptFailed(params.executionPath, final);
77
+ driver.stepAttemptFailed(params.executionPath, final, error);
75
78
  if (final)
76
79
  throw error;
77
80
  admission = admit();
@@ -18,7 +18,7 @@ export const NODE_FIELDS = {
18
18
  extract: GENERATIVE_FIELDS,
19
19
  report: ["node", "label", "state", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
20
20
  artifact: ["node", "label", "state", "type", "path", "instructions", "sopSection", "requires", "tools", "effort", "thinking"],
21
- map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency"],
21
+ map: ["node", "label", "itemsPath", "body", "as", "resultPath", "maxConcurrency", "onItemFailure", "failedAs"],
22
22
  parallel: ["node", "label", "branches"],
23
23
  loop: ["node", "label", "body", "until", "maxIters", "expect_iters"],
24
24
  escalate: ["node", "label", "when", "kind", "stage", "summary"],
@@ -1 +1,8 @@
1
+ /** A shape problem: its message, and a JSON Pointer to the value it is about (to the nearest value the document has, when
2
+ * the one the rule names is missing). */
3
+ export type ShapeIssue = {
4
+ path: string;
5
+ message: string;
6
+ };
1
7
  export declare function workflowShapeErrors(value: unknown, complete?: boolean): string[];
8
+ export declare function workflowShapeIssues(value: unknown, complete?: boolean): ShapeIssue[];
@@ -22,7 +22,7 @@ function discriminatedErrors(value) {
22
22
  const validator = diagnosticValidators.get(schema);
23
23
  if (!validator.Check(entry))
24
24
  for (const error of validator.Errors(entry)) {
25
- errors.push(`workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}`);
25
+ errors.push({ path: `${path}${error.instancePath}`, message: `workflow${path}${error.instancePath || (path ? "" : "/")}: ${error.message}` });
26
26
  if (errors.length >= 8)
27
27
  return;
28
28
  }
@@ -58,128 +58,147 @@ function discriminatedErrors(value) {
58
58
  check(documentSchema.definitions.Workflow, value, "");
59
59
  return errors;
60
60
  }
61
+ /** The deepest prefix of `path` that names a value in `document`: a rule about a missing key points at its container. */
62
+ function present(document, path) {
63
+ let cursor = document;
64
+ let reached = "";
65
+ for (const raw of path.split("/").slice(1)) {
66
+ const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
67
+ if (cursor === null || typeof cursor !== "object" || !Object.hasOwn(cursor, key))
68
+ break;
69
+ cursor = cursor[key];
70
+ reached += `/${raw}`;
71
+ }
72
+ return reached;
73
+ }
61
74
  export function workflowShapeErrors(value, complete = false) {
75
+ return workflowShapeIssues(value, complete).map(issue => issue.message);
76
+ }
77
+ export function workflowShapeIssues(value, complete = false) {
78
+ const located = (issues) => issues.map(issue => ({ path: present(value, issue.path), message: issue.message }));
62
79
  if (complete) {
63
80
  if (fullValidator.Check(value))
64
81
  return [];
65
82
  const selected = discriminatedErrors(value);
66
83
  if (selected.length)
67
- return selected;
68
- return [...fullValidator.Errors(value)].slice(0, 8).map(error => `workflow${error.instancePath || "/"}: ${error.message}`);
84
+ return located(selected);
85
+ return located([...fullValidator.Errors(value)].slice(0, 8).map(error => ({ path: error.instancePath, message: `workflow${error.instancePath || "/"}: ${error.message}` })));
69
86
  }
87
+ const at = (loc, key) => ({ text: `${loc.text}.${key}`, ptr: `${loc.ptr}/${pointer(key)}` });
88
+ const index = (loc, i) => ({ text: `${loc.text}[${i}]`, ptr: `${loc.ptr}/${i}` });
70
89
  const errors = [];
71
- const fail = (path, expected) => { errors.push(`${path} must be ${expected}`); };
72
- const record = (entry, path) => {
90
+ const fail = (loc, expected) => { errors.push({ path: loc.ptr, message: `${loc.text} must be ${expected}` }); };
91
+ const record = (entry, loc) => {
73
92
  if (isRecord(entry))
74
93
  return true;
75
- fail(path, "an object");
94
+ fail(loc, "an object");
76
95
  return false;
77
96
  };
78
- const strings = (entry, path, keys) => {
97
+ const strings = (entry, loc, keys) => {
79
98
  for (const key of keys)
80
99
  if (entry[key] !== undefined && typeof entry[key] !== "string")
81
- fail(`${path}.${key}`, "a string");
100
+ fail(at(loc, key), "a string");
82
101
  };
83
- const stringList = (entry, path) => {
102
+ const stringList = (entry, loc) => {
84
103
  if (entry === undefined)
85
104
  return;
86
105
  if (!Array.isArray(entry)) {
87
- fail(path, "an array of strings");
106
+ fail(loc, "an array of strings");
88
107
  return;
89
108
  }
90
- entry.forEach((item, index) => { if (typeof item !== "string")
91
- fail(`${path}[${index}]`, "a string"); });
109
+ entry.forEach((item, i) => { if (typeof item !== "string")
110
+ fail(index(loc, i), "a string"); });
92
111
  };
93
112
  // Preserve existing diagnostics for missing, non-finite and out-of-range numbers, and
94
113
  // primitive strings such as poll.deadline_s="soon". Objects can throw during coercion.
95
- const numeric = (entry, path, keys) => {
114
+ const numeric = (entry, loc, keys) => {
96
115
  for (const key of keys) {
97
116
  const item = entry[key];
98
117
  if (item !== null && item !== undefined && !["number", "string", "boolean"].includes(typeof item))
99
- fail(`${path}.${key}`, "a number");
118
+ fail(at(loc, key), "a number");
100
119
  }
101
120
  };
102
- const objectField = (entry, path, key, visit) => {
121
+ const objectField = (entry, loc, key, visit) => {
103
122
  if (entry[key] === undefined)
104
123
  return;
105
- if (record(entry[key], `${path}.${key}`))
106
- visit?.(entry[key], `${path}.${key}`);
124
+ if (record(entry[key], at(loc, key)))
125
+ visit?.(entry[key], at(loc, key));
107
126
  };
108
- const predicate = (entry, path) => {
109
- strings(entry, path, ["predicate", "path", "key", "instructions"]);
110
- numeric(entry, path, ["n", "gte"]);
111
- objectField(entry, path, "state");
112
- objectField(entry, path, "criteria", (criteria, at) => strings(criteria, at, ["true", "false"]));
127
+ const predicate = (entry, loc) => {
128
+ strings(entry, loc, ["predicate", "path", "key", "instructions"]);
129
+ numeric(entry, loc, ["n", "gte"]);
130
+ objectField(entry, loc, "state");
131
+ objectField(entry, loc, "criteria", (criteria, here) => strings(criteria, here, ["true", "false"]));
113
132
  };
114
- const node = (entry, path) => {
133
+ const node = (entry, loc) => {
115
134
  if (entry === undefined)
116
135
  return; // missing bodies already receive semantic diagnostics
117
- if (!record(entry, path))
136
+ if (!record(entry, loc))
118
137
  return;
119
- strings(entry, path, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier", "valuePath", "otherwise"]);
120
- numeric(entry, path, ["maxConcurrency", "maxIters", "expect_iters", "deadline_s"]);
138
+ strings(entry, loc, ["node", "label", "code", "as", "out", "instructions", "itemsPath", "resultPath", "kind", "stage", "summary", "describe", "type", "path", "tool", "command", "via", "where", "effort", "thinking", "tier", "valuePath", "otherwise", "onItemFailure", "failedAs"]);
139
+ numeric(entry, loc, ["maxConcurrency", "maxIters", "expect_iters", "deadline_s"]);
121
140
  for (const key of ["requires", "tools", "produces"])
122
- stringList(entry[key], `${path}.${key}`);
141
+ stringList(entry[key], at(loc, key));
123
142
  if (entry.sopSection !== undefined && typeof entry.sopSection !== "string")
124
- stringList(entry.sopSection, `${path}.sopSection`);
143
+ stringList(entry.sopSection, at(loc, "sopSection"));
125
144
  for (const key of ["state", "args", "input", "env"])
126
- objectField(entry, path, key);
145
+ objectField(entry, loc, key);
127
146
  // Host-owned and opaque: only its container is checked, never its keys or values.
128
147
  if (entry.metadata !== undefined && !isRecord(entry.metadata)) {
129
- errors.push(`${path} (${typeof entry.label === "string" && entry.label ? entry.label : String(entry.node)}): metadata must be a plain object of host markers`);
148
+ errors.push({ path: at(loc, "metadata").ptr, message: `${loc.text} (${typeof entry.label === "string" && entry.label ? entry.label : String(entry.node)}): metadata must be a plain object of host markers` });
130
149
  }
131
150
  for (const key of ["until", "when"])
132
- objectField(entry, path, key, predicate);
133
- objectField(entry, path, "verify", (verify, at) => {
134
- strings(verify, at, ["out"]);
135
- numeric(verify, at, ["maxDrives"]);
136
- objectField(verify, at, "state");
137
- objectField(verify, at, "override", (override, here) => numeric(override, here, ["below"]));
151
+ objectField(entry, loc, key, predicate);
152
+ objectField(entry, loc, "verify", (verify, here) => {
153
+ strings(verify, here, ["out"]);
154
+ numeric(verify, here, ["maxDrives"]);
155
+ objectField(verify, here, "state");
156
+ objectField(verify, here, "override", (override, inner) => numeric(override, inner, ["below"]));
138
157
  });
139
- objectField(entry, path, "keep", (keep, at) => { strings(keep, at, ["path"]); numeric(keep, at, ["gte"]); });
140
- objectField(entry, path, "unsure", (unsure, at) => { strings(unsure, at, ["branch"]); numeric(unsure, at, ["gte"]); });
141
- objectField(entry, path, "retry", (retry, at) => {
142
- numeric(retry, at, ["attempts", "backoff_s"]);
143
- stringList(retry.on, `${at}.on`);
158
+ objectField(entry, loc, "keep", (keep, here) => { strings(keep, here, ["path"]); numeric(keep, here, ["gte"]); });
159
+ objectField(entry, loc, "unsure", (unsure, here) => { strings(unsure, here, ["branch"]); numeric(unsure, here, ["gte"]); });
160
+ objectField(entry, loc, "retry", (retry, here) => {
161
+ numeric(retry, here, ["attempts", "backoff_s"]);
162
+ stringList(retry.on, at(here, "on"));
144
163
  });
145
- objectField(entry, path, "poll", (poll, at) => {
146
- numeric(poll, at, ["interval_s", "deadline_s"]);
164
+ objectField(entry, loc, "poll", (poll, here) => {
165
+ numeric(poll, here, ["interval_s", "deadline_s"]);
147
166
  for (const key of ["until", "fail_when"])
148
- objectField(poll, at, key, predicate);
167
+ objectField(poll, here, key, predicate);
149
168
  });
150
169
  if (entry.node === "chain" || entry.node === "parallel") {
151
170
  const key = entry.node === "chain" ? "steps" : "branches";
152
171
  if (entry[key] !== undefined) {
153
172
  if (!Array.isArray(entry[key]))
154
- fail(`${path}.${key}`, "an array of nodes");
173
+ fail(at(loc, key), "an array of nodes");
155
174
  else
156
- entry[key].forEach((child, index) => node(child, `${path}.${key}[${index}]`));
175
+ entry[key].forEach((child, i) => node(child, index(at(loc, key), i)));
157
176
  }
158
177
  }
159
178
  if (entry.node === "map" || entry.node === "loop")
160
- node(entry.body, `${path}.body`);
179
+ node(entry.body, at(loc, "body"));
161
180
  if (entry.node === "route")
162
- objectField(entry, path, "branches", (branches, at) => {
181
+ objectField(entry, loc, "branches", (branches, here) => {
163
182
  for (const [name, branch] of Object.entries(branches))
164
- if (record(branch, `${at}.${name}`)) {
165
- strings(branch, `${at}.${name}`, ["criteria"]);
166
- node(branch.body, `${at}.${name}.body`);
183
+ if (record(branch, at(here, name))) {
184
+ strings(branch, at(here, name), ["criteria"]);
185
+ node(branch.body, at(at(here, name), "body"));
167
186
  }
168
187
  });
169
188
  if (entry.node === "workflow")
170
- workflow(entry.workflow, `${path}.workflow`);
189
+ workflow(entry.workflow, at(loc, "workflow"));
171
190
  };
172
- const workflow = (entry, path) => {
173
- if (!record(entry, path))
191
+ const workflow = (entry, loc) => {
192
+ if (!record(entry, loc))
174
193
  return;
175
- strings(entry, path, ["name"]);
176
- record(entry.schemas, `${path}.schemas`);
177
- objectField(entry, path, "input", (input, at) => strings(input, at, ["schemaId"]));
178
- if (record(entry.output, `${path}.output`))
179
- strings(entry.output, `${path}.output`, ["schemaId", "path"]);
180
- if (record(entry.root, `${path}.root`))
181
- node(entry.root, `${path}.root`);
194
+ strings(entry, loc, ["name"]);
195
+ record(entry.schemas, at(loc, "schemas"));
196
+ objectField(entry, loc, "input", (input, here) => strings(input, here, ["schemaId"]));
197
+ if (record(entry.output, at(loc, "output")))
198
+ strings(entry.output, at(loc, "output"), ["schemaId", "path"]);
199
+ if (record(entry.root, at(loc, "root")))
200
+ node(entry.root, at(loc, "root"));
182
201
  };
183
- workflow(value, "workflow");
184
- return errors.slice(0, 8);
202
+ workflow(value, { text: "workflow", ptr: "" });
203
+ return located(errors.slice(0, 8));
185
204
  }
@@ -114,6 +114,12 @@ export type WorkflowNode = {
114
114
  as: string;
115
115
  resultPath?: string;
116
116
  maxConcurrency?: number;
117
+ /** What an item's failure does: `stop` (the default) stops the map and the run; `collect` ends the item as a row
118
+ * of `failedAs` when its failure is an item failure (`isItemFailure`), and the other items finish. */
119
+ onItemFailure?: "stop" | "collect";
120
+ /** With `onItemFailure: "collect"`, the state key the map writes its failed items under, one row each in item order:
121
+ * `{ item_index, label, code, message }`. `as` stays aligned with the items, `null` in a failed item's slot. */
122
+ failedAs?: string;
117
123
  metadata?: NodeMetadata;
118
124
  } | {
119
125
  node: "parallel";
@@ -529,6 +535,13 @@ export type WorkflowDeps = {
529
535
  pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
530
536
  wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
531
537
  fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
538
+ /** A map with `onItemFailure: "collect"` commits an item that ended on its failure here, at the item's body path,
539
+ * once, before the map goes on; `node` is the map. A store without both hooks cannot hold such a map: it is refused
540
+ * before any step runs. */
541
+ failItem?: (node: WorkflowNode, failure: MapItemFailure, executionPath?: string) => Promise<void>;
542
+ /** The failure an earlier process committed for the item whose body path this is, if any: the item ends on it again,
543
+ * and its body never runs again. */
544
+ itemFailure?: (node: WorkflowNode, executionPath?: string) => Promise<MapItemFailure | undefined>;
532
545
  /** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
533
546
  * the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
534
547
  * other receipt, or none, means the request is asked. */
@@ -592,6 +605,18 @@ export declare function workflowSha256(workflow: Workflow): string;
592
605
  /** Bound the complete document before any recursive schema or semantic traversal. Shared
593
606
  * objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
594
607
  export declare function workflowDocumentError(value: unknown): string | undefined;
608
+ /** The rule a validation issue breaks. A closed set: a new code widens it, so a consumer keeps a default branch; renaming
609
+ * one is a breaking change. `docs/guide.md` lists each with an example. */
610
+ export type ValidationCode = "DOCUMENT_INVALID" | "SHAPE_INVALID" | "WORKFLOW_FIELD_INVALID" | "SCHEMA_INVALID" | "SCHEMA_UNKNOWN" | "INPUT_INVALID" | "NODE_KIND_UNKNOWN" | "NODE_KEY_UNKNOWN" | "NODE_FIELD_INVALID" | "STATE_KEY_RESERVED" | "STATE_PATH_UNPRODUCED" | "STATE_PATH_EXCLUDED" | "PARALLEL_WRITE_CONFLICT" | "STRUCTURE_INVALID" | "PREDICATE_INVALID" | "CODE_INVALID";
611
+ /** One validation error. `message` is the matching entry of `errors`, unchanged. `path` is a JSON Pointer (RFC 6901)
612
+ * into the workflow as written, naming what the rule is about: a node (the same path `inspectWorkflow` gives it), a
613
+ * schema (`/schemas/<id>`), a value the shape check refused, or `""` for the document's own fields and for the input
614
+ * supplied to validation. It never names a key that is missing. */
615
+ export type ValidationIssue = {
616
+ path: string;
617
+ code: ValidationCode;
618
+ message: string;
619
+ };
595
620
  /** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
596
621
  export declare function validateWorkflow(workflow: Workflow, opts?: {
597
622
  executeCode?: boolean;
@@ -610,6 +635,7 @@ export declare function validateWorkflow(workflow: Workflow, opts?: {
610
635
  } | {
611
636
  ok: false;
612
637
  errors: string[];
638
+ issues: ValidationIssue[];
613
639
  warnings?: string[];
614
640
  };
615
641
  export declare class EscalationSignal extends Error {
@@ -622,9 +648,11 @@ export declare function schemaProblems(validator: {
622
648
  export declare class WorkflowInvalidError extends Error {
623
649
  readonly workflowName: string;
624
650
  readonly problems: string[];
651
+ readonly issues: ValidationIssue[];
625
652
  readonly code = "workflow_invalid";
626
653
  readonly stage = "validate";
627
- constructor(workflowName: string, problems: string[]);
654
+ /** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
655
+ constructor(workflowName: string, problems: string[], issues?: ValidationIssue[]);
628
656
  }
629
657
  export declare class WorkflowInputInvalidError extends Error {
630
658
  readonly workflowName: string;
@@ -683,6 +711,21 @@ export declare class WorkflowStateError extends Error {
683
711
  readonly code = "state_invalid";
684
712
  constructor(summary: string, stage: string, path: string, reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type");
685
713
  }
714
+ /** A map item that ended on its failure (`onItemFailure: "collect"`), as `failedAs` holds it: the item's index, the
715
+ * label of the node that failed, the failure's code and its message (at most 300 characters). */
716
+ export type MapItemFailure = {
717
+ item_index: number;
718
+ label: string;
719
+ code: string;
720
+ message: string;
721
+ };
722
+ /** Whether an item's failure is one a map with `onItemFailure: "collect"` ends the item on: one of the interpreter's own
723
+ * typed node failures (a call that failed after its retries, output that does not match its schema, a state contract, a
724
+ * code transform, a failed verification), or a host's failure that declares itself one, with a string `code` and
725
+ * `itemFailure: true`. Never one whose cause chain holds an effect whose outcome is unknown, a recovery failure, an
726
+ * escalation or an abort, never several failures at once, and nothing else: a new error class is never collected by
727
+ * accident. */
728
+ export declare function isItemFailure(error: unknown): boolean;
686
729
  export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
687
730
  export declare const submissionSchemaForNode: typeof stageSchemaForNode;
688
731
  export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;