@parcha/agentrun-dsl 0.1.0-beta.2 → 0.1.0-beta.20
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 +46 -16
- package/dist/author.d.ts +96 -0
- package/dist/author.js +320 -0
- package/dist/authoring.js +1 -1
- package/dist/cli.js +8 -3
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/decision-receipts.d.ts +98 -0
- package/dist/decision-receipts.js +51 -0
- package/dist/dry-run.d.ts +14 -1
- package/dist/dry-run.js +39 -13
- package/dist/graph.d.ts +83 -0
- package/dist/graph.js +231 -0
- package/dist/index.d.ts +12 -4
- package/dist/index.js +6 -2
- package/dist/inspection.js +2 -2
- package/dist/job.d.ts +14 -0
- package/dist/job.js +5 -0
- package/dist/long-timer.d.ts +7 -0
- package/dist/long-timer.js +22 -0
- package/dist/observer-snapshot.d.ts +3 -0
- package/dist/observer-snapshot.js +46 -0
- package/dist/predicates.d.ts +4 -0
- package/dist/predicates.js +19 -2
- package/dist/recovery/binding.d.ts +10 -0
- package/dist/recovery/binding.js +43 -0
- package/dist/recovery/call-key.d.ts +13 -0
- package/dist/recovery/call-key.js +24 -0
- package/dist/recovery/canonical-hash.d.ts +7 -0
- package/dist/recovery/canonical-hash.js +22 -0
- package/dist/recovery/driver.d.ts +208 -0
- package/dist/recovery/driver.js +1222 -0
- package/dist/recovery/effect-failure.d.ts +34 -0
- package/dist/recovery/effect-failure.js +62 -0
- package/dist/recovery/errors.d.ts +31 -0
- package/dist/recovery/errors.js +51 -0
- package/dist/recovery/execution-path.d.ts +53 -0
- package/dist/recovery/execution-path.js +167 -0
- package/dist/recovery/file-store.d.ts +7 -0
- package/dist/recovery/file-store.js +131 -0
- package/dist/recovery/frozen-snapshot.d.ts +244 -0
- package/dist/recovery/frozen-snapshot.js +171 -0
- package/dist/recovery/handoff-block.d.ts +36 -0
- package/dist/recovery/handoff-block.js +148 -0
- package/dist/recovery/handoff-digest.d.ts +58 -0
- package/dist/recovery/handoff-digest.js +195 -0
- package/dist/recovery/handoff-files.d.ts +54 -0
- package/dist/recovery/handoff-files.js +162 -0
- package/dist/recovery/handoff-receipts.d.ts +42 -0
- package/dist/recovery/handoff-receipts.js +53 -0
- package/dist/recovery/handoff-redact.d.ts +12 -0
- package/dist/recovery/handoff-redact.js +44 -0
- package/dist/recovery/handoff.d.ts +44 -0
- package/dist/recovery/handoff.js +46 -0
- package/dist/recovery/index.d.ts +18 -0
- package/dist/recovery/index.js +16 -0
- package/dist/recovery/item-state.d.ts +48 -0
- package/dist/recovery/item-state.js +89 -0
- package/dist/recovery/journal.d.ts +28 -0
- package/dist/recovery/journal.js +139 -0
- package/dist/recovery/memory-store.d.ts +4 -0
- package/dist/recovery/memory-store.js +20 -0
- package/dist/recovery/store.d.ts +105 -0
- package/dist/recovery/store.js +6 -0
- package/dist/recovery/testing/conformance.d.ts +4 -0
- package/dist/recovery/testing/conformance.js +268 -0
- package/dist/recovery/testing/crash-points.d.ts +18 -0
- package/dist/recovery/testing/crash-points.js +43 -0
- package/dist/recovery/testing/crash-sweep.d.ts +65 -0
- package/dist/recovery/testing/crash-sweep.js +146 -0
- package/dist/recovery/testing/index.d.ts +3 -0
- package/dist/recovery/testing/index.js +4 -0
- package/dist/recovery/testing/preload.d.ts +1 -0
- package/dist/recovery/testing/preload.js +3 -0
- package/dist/recovery/transport-facts.d.ts +23 -0
- package/dist/recovery/transport-facts.js +46 -0
- package/dist/recovery/with-recovery.d.ts +44 -0
- package/dist/recovery/with-recovery.js +87 -0
- package/dist/system-one.d.ts +17 -1
- package/dist/system-one.js +62 -5
- package/dist/vocabulary.d.ts +42 -0
- package/dist/vocabulary.js +74 -0
- package/dist/workflow-shape.d.ts +7 -0
- package/dist/workflow-shape.js +85 -62
- package/dist/workflow.d.ts +187 -16
- package/dist/workflow.js +967 -324
- package/package.json +18 -2
- package/schema/workflow.schema.json +251 -15
- package/skills/author/SKILL.md +122 -0
- package/skills/author/examples/evidence-gate.input.json +6 -0
- package/skills/author/examples/evidence-gate.json +125 -0
- package/skills/author/examples/read-file.input.json +1 -0
- package/skills/author/examples/read-file.json +44 -0
- package/skills/author/examples/read-source-decision.input.json +4 -0
- package/skills/author/examples/read-source-decision.json +37 -0
- package/skills/author/examples/release-note.txt +10 -0
- package/skills/author/examples/review-release-notes.input.json +6 -0
- package/skills/author/examples/review-release-notes.json +123 -0
- package/skills/author/references/jev-decisions.md +125 -0
- package/skills/author/references/language.md +118 -0
- package/skills/author/references/sdk-authoring.md +11 -0
- package/skills/author/references/workflow-format.md +137 -0
package/dist/workflow.d.ts
CHANGED
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
import { type AcceptPredicate } from "./predicates.js";
|
|
2
|
+
import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
|
|
2
3
|
import { type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
|
|
4
|
+
import { type DecisionReceipt } from "./decision-receipts.js";
|
|
3
5
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
4
6
|
/** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
|
|
5
7
|
* or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
|
|
6
8
|
* decision is on the edge. */
|
|
7
9
|
export type ModelTier = "fast" | "default" | "strong";
|
|
10
|
+
/** An `agent` node's context (`AGENT_CONTEXTS`). */
|
|
11
|
+
export type AgentContext = "fresh" | "fork";
|
|
8
12
|
export type VerifyClause = {
|
|
9
13
|
out: string;
|
|
10
14
|
state?: Record<string, unknown>;
|
|
@@ -28,14 +32,21 @@ export type Predicate = MechanicalPredicate | AskPredicate;
|
|
|
28
32
|
export type WorkflowEffort = "minimal" | "low" | "medium" | "high";
|
|
29
33
|
/** The author's thinking dial. There is deliberately no "off": thinking is never off. */
|
|
30
34
|
export type WorkflowThinking = "low" | "medium" | "high";
|
|
35
|
+
/** Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the
|
|
36
|
+
* document and never reads it; it never reaches state, events, prompts or effect identities. */
|
|
37
|
+
export type NodeMetadata = {
|
|
38
|
+
[key: string]: unknown;
|
|
39
|
+
};
|
|
31
40
|
export type WorkflowNode = {
|
|
32
41
|
node: "chain";
|
|
33
42
|
steps: WorkflowNode[];
|
|
43
|
+
metadata?: NodeMetadata;
|
|
34
44
|
} | {
|
|
35
45
|
node: "code";
|
|
36
46
|
label: string;
|
|
37
47
|
code: string;
|
|
38
48
|
as?: string;
|
|
49
|
+
metadata?: NodeMetadata;
|
|
39
50
|
} | {
|
|
40
51
|
node: "agent";
|
|
41
52
|
label: string;
|
|
@@ -50,6 +61,10 @@ export type WorkflowNode = {
|
|
|
50
61
|
thinking?: WorkflowThinking;
|
|
51
62
|
verify?: VerifyClause;
|
|
52
63
|
tier?: ModelTier;
|
|
64
|
+
/** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
|
|
65
|
+
budget_usd?: number;
|
|
66
|
+
context?: AgentContext;
|
|
67
|
+
metadata?: NodeMetadata;
|
|
53
68
|
} | {
|
|
54
69
|
node: "decide";
|
|
55
70
|
label: string;
|
|
@@ -64,6 +79,7 @@ export type WorkflowNode = {
|
|
|
64
79
|
thinking?: WorkflowThinking;
|
|
65
80
|
verify?: VerifyClause;
|
|
66
81
|
tier?: ModelTier;
|
|
82
|
+
metadata?: NodeMetadata;
|
|
67
83
|
} | {
|
|
68
84
|
node: "extract";
|
|
69
85
|
label: string;
|
|
@@ -78,6 +94,7 @@ export type WorkflowNode = {
|
|
|
78
94
|
thinking?: WorkflowThinking;
|
|
79
95
|
verify?: VerifyClause;
|
|
80
96
|
tier?: ModelTier;
|
|
97
|
+
metadata?: NodeMetadata;
|
|
81
98
|
} | {
|
|
82
99
|
node: "report";
|
|
83
100
|
label: string;
|
|
@@ -88,6 +105,7 @@ export type WorkflowNode = {
|
|
|
88
105
|
tools?: string[];
|
|
89
106
|
effort?: WorkflowEffort;
|
|
90
107
|
thinking?: WorkflowThinking;
|
|
108
|
+
metadata?: NodeMetadata;
|
|
91
109
|
} | ArtifactNode | {
|
|
92
110
|
node: "map";
|
|
93
111
|
label: string;
|
|
@@ -96,16 +114,26 @@ export type WorkflowNode = {
|
|
|
96
114
|
as: string;
|
|
97
115
|
resultPath?: string;
|
|
98
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;
|
|
123
|
+
metadata?: NodeMetadata;
|
|
99
124
|
} | {
|
|
100
125
|
node: "parallel";
|
|
101
126
|
label: string;
|
|
102
127
|
branches: WorkflowNode[];
|
|
128
|
+
metadata?: NodeMetadata;
|
|
103
129
|
} | {
|
|
104
130
|
node: "loop";
|
|
105
131
|
label: string;
|
|
106
132
|
body: WorkflowNode;
|
|
107
133
|
until: Predicate;
|
|
108
134
|
maxIters: number;
|
|
135
|
+
expect_iters?: number;
|
|
136
|
+
metadata?: NodeMetadata;
|
|
109
137
|
} | {
|
|
110
138
|
node: "escalate";
|
|
111
139
|
label: string;
|
|
@@ -113,6 +141,7 @@ export type WorkflowNode = {
|
|
|
113
141
|
kind: string;
|
|
114
142
|
stage: string;
|
|
115
143
|
summary: string;
|
|
144
|
+
metadata?: NodeMetadata;
|
|
116
145
|
} | JudgeNode | PickNode | SiftNode | RouteNode | CallNode | WorkflowInvocation;
|
|
117
146
|
/** A judgment as typed questions. `state` is what the questions see, interpolated by value from the
|
|
118
147
|
* workflow state (a whole-string placeholder keeps its type); `out` is a flat schema of enums,
|
|
@@ -125,6 +154,7 @@ export type JudgeNode = {
|
|
|
125
154
|
out: string;
|
|
126
155
|
as: string;
|
|
127
156
|
requires?: string[];
|
|
157
|
+
metadata?: NodeMetadata;
|
|
128
158
|
};
|
|
129
159
|
/** One choice whose options are the items of a list. `describe` renders each item as its option
|
|
130
160
|
* text (`{item.field}`); `allowNone` adds a none-of-these option. The result at `as` is
|
|
@@ -140,6 +170,7 @@ export type PickNode = {
|
|
|
140
170
|
allowNone?: boolean;
|
|
141
171
|
as: string;
|
|
142
172
|
requires?: string[];
|
|
173
|
+
metadata?: NodeMetadata;
|
|
143
174
|
};
|
|
144
175
|
/** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
|
|
145
176
|
* questions are prefixed `i.`; every answer lands in `as.answers[i]` and `as.values[i]`. `keep`
|
|
@@ -158,11 +189,15 @@ export type SiftNode = {
|
|
|
158
189
|
gte?: number;
|
|
159
190
|
};
|
|
160
191
|
requires?: string[];
|
|
192
|
+
metadata?: NodeMetadata;
|
|
161
193
|
};
|
|
162
|
-
/**
|
|
194
|
+
/** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
|
|
195
|
+
* already holds the choice as a string at `valuePath` and no model is asked. */
|
|
196
|
+
export type RouteNode = RouteByJudgmentNode | RouteByValueNode;
|
|
197
|
+
/** A choice among subgraphs that Jev makes. The options are the branch names, their criteria the branch
|
|
163
198
|
* descriptions; the chosen branch runs on the state. `as` (optional) records the choice and its
|
|
164
199
|
* distribution; `unsure` names the branch taken when confidence is below `gte`. */
|
|
165
|
-
export type
|
|
200
|
+
export type RouteByJudgmentNode = {
|
|
166
201
|
node: "route";
|
|
167
202
|
label: string;
|
|
168
203
|
state: Record<string, unknown>;
|
|
@@ -177,9 +212,33 @@ export type RouteNode = {
|
|
|
177
212
|
branch: string;
|
|
178
213
|
gte: number;
|
|
179
214
|
};
|
|
215
|
+
valuePath?: never;
|
|
216
|
+
otherwise?: never;
|
|
217
|
+
as?: string;
|
|
218
|
+
requires?: string[];
|
|
219
|
+
metadata?: NodeMetadata;
|
|
220
|
+
};
|
|
221
|
+
/** A route by a value already in state: the string at `valuePath` names the branch. A missing value or
|
|
222
|
+
* an unknown name takes `otherwise` when declared and fails before any branch otherwise; a value that is
|
|
223
|
+
* not a string always fails. `as` records `{value, taken, fallback}`. */
|
|
224
|
+
export type RouteByValueNode = {
|
|
225
|
+
node: "route";
|
|
226
|
+
label: string;
|
|
227
|
+
valuePath: string;
|
|
228
|
+
branches: {
|
|
229
|
+
[branch: string]: {
|
|
230
|
+
body: WorkflowNode;
|
|
231
|
+
};
|
|
232
|
+
};
|
|
233
|
+
otherwise?: string;
|
|
234
|
+
state?: never;
|
|
235
|
+
instructions?: never;
|
|
236
|
+
unsure?: never;
|
|
180
237
|
as?: string;
|
|
181
238
|
requires?: string[];
|
|
239
|
+
metadata?: NodeMetadata;
|
|
182
240
|
};
|
|
241
|
+
export declare const routesByValue: (node: RouteNode) => node is RouteByValueNode;
|
|
183
242
|
/** A child workflow invoked as one step of its parent. The child is embedded whole, so the parent
|
|
184
243
|
* digest covers every child byte; `input` is interpolated by value and is the child's ENTIRE initial
|
|
185
244
|
* state (no parent state leaks in); the child's validated output is checked against the parent's
|
|
@@ -192,10 +251,13 @@ export type WorkflowInvocation = {
|
|
|
192
251
|
input: Record<string, unknown>;
|
|
193
252
|
out: string;
|
|
194
253
|
as: string;
|
|
254
|
+
metadata?: NodeMetadata;
|
|
195
255
|
};
|
|
196
256
|
/** `exit` is a shell command that ended with a non-zero status: retried only when the author
|
|
197
257
|
* declared retry, since re-running a command is the author's call. */
|
|
198
258
|
export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
|
|
259
|
+
/** A failed effect's closed code (EFFECT_FAILURE_CODES). */
|
|
260
|
+
export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
|
|
199
261
|
/** The workflow's terminal deliverable. Types "markdown" and "report" use the report
|
|
200
262
|
* writer; other non-empty types name a workspace file produced by an earlier call.
|
|
201
263
|
* File existence and delivery are the host's responsibility. */
|
|
@@ -214,6 +276,7 @@ export type ArtifactNode = {
|
|
|
214
276
|
effort?: WorkflowEffort;
|
|
215
277
|
thinking?: WorkflowThinking;
|
|
216
278
|
requires?: string[];
|
|
279
|
+
metadata?: NodeMetadata;
|
|
217
280
|
};
|
|
218
281
|
export type ArtifactState = {
|
|
219
282
|
path: string;
|
|
@@ -263,19 +326,24 @@ export type CallNode = {
|
|
|
263
326
|
produces?: string[];
|
|
264
327
|
/** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
|
|
265
328
|
deadline_s: number;
|
|
329
|
+
/** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
|
|
266
330
|
retry?: {
|
|
267
331
|
attempts: number;
|
|
268
332
|
backoff_s?: number;
|
|
269
|
-
on?: CallRetryClass[];
|
|
333
|
+
on?: (CallRetryClass | EffectFailureCode)[];
|
|
270
334
|
};
|
|
271
335
|
/** Repeat the call until its result settles (a queued job, an eventually consistent read). */
|
|
272
336
|
poll?: PollClause;
|
|
273
337
|
requires?: string[];
|
|
338
|
+
metadata?: NodeMetadata;
|
|
274
339
|
};
|
|
275
340
|
export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
|
|
276
341
|
export type LlmNode = Extract<WorkflowNode, {
|
|
277
342
|
node: "agent" | "decide" | "extract" | "report";
|
|
278
343
|
}>;
|
|
344
|
+
export type CodeNode = Extract<WorkflowNode, {
|
|
345
|
+
node: "code";
|
|
346
|
+
}>;
|
|
279
347
|
export declare const REPORT_SCHEMA: Record<string, unknown>;
|
|
280
348
|
export type Workflow = {
|
|
281
349
|
v: 2;
|
|
@@ -366,6 +434,10 @@ export type HostPolicy = {
|
|
|
366
434
|
};
|
|
367
435
|
export type WorkflowDeps = {
|
|
368
436
|
maxQuestionsPerRequest?: number;
|
|
437
|
+
/** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
|
|
438
|
+
* measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
|
|
439
|
+
* requests. Absent = no byte limit. */
|
|
440
|
+
maxStateBytesPerRequest?: number;
|
|
369
441
|
/** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
|
|
370
442
|
hostPolicy?: HostPolicy;
|
|
371
443
|
runNode?: (params: {
|
|
@@ -390,6 +462,12 @@ export type WorkflowDeps = {
|
|
|
390
462
|
message: string;
|
|
391
463
|
}>;
|
|
392
464
|
tier?: ModelTier;
|
|
465
|
+
/** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
|
|
466
|
+
* No runner stops a run on money. A host may cap it by what it has left. */
|
|
467
|
+
budgetUsd?: number;
|
|
468
|
+
/** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
|
|
469
|
+
* a host that has none to fork refuses it. */
|
|
470
|
+
context?: AgentContext;
|
|
393
471
|
}) => Promise<unknown>;
|
|
394
472
|
runEffect?: (params: {
|
|
395
473
|
node: CallNode;
|
|
@@ -399,9 +477,25 @@ export type WorkflowDeps = {
|
|
|
399
477
|
attempt: number;
|
|
400
478
|
idempotencyKey: string;
|
|
401
479
|
signal: AbortSignal;
|
|
480
|
+
/** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
|
|
481
|
+
* interpreter armed its deadline timer, so the host measures its own kill and duration against
|
|
482
|
+
* the instant the timer fires. Absent when the call has no deadline. */
|
|
483
|
+
deadlineAt?: number;
|
|
402
484
|
item?: MapItem;
|
|
403
485
|
executionPath?: string;
|
|
404
486
|
}) => Promise<unknown>;
|
|
487
|
+
/** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
|
|
488
|
+
* the context the transform would receive and uses what it resolves to as the transform's result
|
|
489
|
+
* (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
|
|
490
|
+
* Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
|
|
491
|
+
* which is not a sandbox: a host that runs code from an untrusted author supplies this. */
|
|
492
|
+
runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
|
|
493
|
+
sop: string;
|
|
494
|
+
label: string;
|
|
495
|
+
executionPath: string;
|
|
496
|
+
item?: MapItem;
|
|
497
|
+
signal?: AbortSignal;
|
|
498
|
+
}) => Promise<unknown>;
|
|
405
499
|
runJudge?: (params: {
|
|
406
500
|
label: string;
|
|
407
501
|
kind: "judge" | "pick" | "sift" | "route" | "ask";
|
|
@@ -410,6 +504,9 @@ export type WorkflowDeps = {
|
|
|
410
504
|
signal?: AbortSignal;
|
|
411
505
|
state: unknown;
|
|
412
506
|
questions: Record<string, SystemOneQuestion>;
|
|
507
|
+
/** The id of this request's decision receipt (`DecisionReceipt.id`): the same request asked again
|
|
508
|
+
* carries the same id. */
|
|
509
|
+
decisionId?: string;
|
|
413
510
|
}) => Promise<{
|
|
414
511
|
answers: Record<string, SystemOneAnswer>;
|
|
415
512
|
model?: string | null;
|
|
@@ -420,6 +517,12 @@ export type WorkflowDeps = {
|
|
|
420
517
|
cost_usd?: number | null;
|
|
421
518
|
request_sha256?: string;
|
|
422
519
|
}>;
|
|
520
|
+
/** Records one typed-question request and what its answers decide. It is awaited before the answers
|
|
521
|
+
* reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
|
|
522
|
+
* rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
|
|
523
|
+
* recorded too, before its failure is thrown. A decision answered from `recovery.decision` was
|
|
524
|
+
* recorded by the run that asked it and is not recorded again. */
|
|
525
|
+
recordDecision?: (receipt: DecisionReceipt, exchange: DecisionExchange) => Promise<void>;
|
|
423
526
|
syntheticEffects?: boolean;
|
|
424
527
|
checkpoint?: (state: Record<string, unknown>, label: string, executionPath?: string) => Promise<void>;
|
|
425
528
|
/** Critical recovery stores stop execution on write failure; omitted retains legacy best effort. */
|
|
@@ -432,6 +535,17 @@ export type WorkflowDeps = {
|
|
|
432
535
|
pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
|
|
433
536
|
wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
|
|
434
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>;
|
|
545
|
+
/** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
|
|
546
|
+
* the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
|
|
547
|
+
* other receipt, or none, means the request is asked. */
|
|
548
|
+
decision?: (id: string) => Promise<DecisionReceipt | undefined>;
|
|
435
549
|
};
|
|
436
550
|
/** A completed-effect memo keyed by the call's idempotency key. A hit skips the effect and
|
|
437
551
|
* reuses its result; polled calls are never memoized (their result is a moment in time). */
|
|
@@ -444,18 +558,39 @@ export type WorkflowDeps = {
|
|
|
444
558
|
signal?: AbortSignal;
|
|
445
559
|
/** Best-effort observation only: thrown errors and rejected promises are ignored.
|
|
446
560
|
* Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
|
|
447
|
-
onEvent?: (event:
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
561
|
+
onEvent?: (event: WorkflowEvent) => void;
|
|
562
|
+
/** Trusted host boundary: return a detached snapshot without mutating the input.
|
|
563
|
+
* Runs before generic copying; undefined or thrown errors omit the event.
|
|
564
|
+
* Required trace validation cancels through the host signal, preserving execution cleanup. */
|
|
565
|
+
prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
|
|
566
|
+
};
|
|
567
|
+
export type WorkflowEvent = {
|
|
568
|
+
type: string;
|
|
569
|
+
label: string;
|
|
570
|
+
detail?: unknown;
|
|
571
|
+
executionPath?: string;
|
|
572
|
+
};
|
|
573
|
+
type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
|
|
574
|
+
type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
|
|
575
|
+
/** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
|
|
576
|
+
* and, when the judge returned, the very object it returned, so a host reads back what it put there. */
|
|
577
|
+
export type DecisionExchange = {
|
|
578
|
+
request: JudgeRequest;
|
|
579
|
+
result?: JudgeResult;
|
|
453
580
|
};
|
|
454
581
|
export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
|
|
455
582
|
export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
|
|
583
|
+
/** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
|
|
584
|
+
* and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
|
|
456
585
|
export declare class EffectFailure extends Error {
|
|
457
586
|
readonly retryClass: CallRetryClass | null;
|
|
458
|
-
|
|
587
|
+
readonly code: EffectFailureCode | null;
|
|
588
|
+
readonly detail?: Record<string, unknown>;
|
|
589
|
+
constructor(message: string, retryClass?: CallRetryClass | null, options?: {
|
|
590
|
+
code?: EffectFailureCode | null;
|
|
591
|
+
detail?: Record<string, unknown>;
|
|
592
|
+
cause?: unknown;
|
|
593
|
+
});
|
|
459
594
|
}
|
|
460
595
|
export declare function parseCsvRows(text: string): string[][];
|
|
461
596
|
export declare function buildReferenceContext(files: Record<string, string>): {
|
|
@@ -470,9 +605,19 @@ export declare function workflowSha256(workflow: Workflow): string;
|
|
|
470
605
|
/** Bound the complete document before any recursive schema or semantic traversal. Shared
|
|
471
606
|
* objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
|
|
472
607
|
export declare function workflowDocumentError(value: unknown): string | undefined;
|
|
473
|
-
/**
|
|
474
|
-
*
|
|
475
|
-
|
|
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
|
+
};
|
|
620
|
+
/** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse. */
|
|
476
621
|
export declare function validateWorkflow(workflow: Workflow, opts?: {
|
|
477
622
|
executeCode?: boolean;
|
|
478
623
|
input?: Record<string, unknown>;
|
|
@@ -486,9 +631,12 @@ export declare function validateWorkflow(workflow: Workflow, opts?: {
|
|
|
486
631
|
};
|
|
487
632
|
}): {
|
|
488
633
|
ok: true;
|
|
634
|
+
warnings?: string[];
|
|
489
635
|
} | {
|
|
490
636
|
ok: false;
|
|
491
637
|
errors: string[];
|
|
638
|
+
issues: ValidationIssue[];
|
|
639
|
+
warnings?: string[];
|
|
492
640
|
};
|
|
493
641
|
export declare class EscalationSignal extends Error {
|
|
494
642
|
readonly escalation: Escalation;
|
|
@@ -500,9 +648,11 @@ export declare function schemaProblems(validator: {
|
|
|
500
648
|
export declare class WorkflowInvalidError extends Error {
|
|
501
649
|
readonly workflowName: string;
|
|
502
650
|
readonly problems: string[];
|
|
651
|
+
readonly issues: ValidationIssue[];
|
|
503
652
|
readonly code = "workflow_invalid";
|
|
504
653
|
readonly stage = "validate";
|
|
505
|
-
|
|
654
|
+
/** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
|
|
655
|
+
constructor(workflowName: string, problems: string[], issues?: ValidationIssue[]);
|
|
506
656
|
}
|
|
507
657
|
export declare class WorkflowInputInvalidError extends Error {
|
|
508
658
|
readonly workflowName: string;
|
|
@@ -557,13 +707,34 @@ export declare class WorkflowCodeError extends Error {
|
|
|
557
707
|
export declare class WorkflowStateError extends Error {
|
|
558
708
|
readonly stage: string;
|
|
559
709
|
readonly path: string;
|
|
560
|
-
readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key";
|
|
710
|
+
readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key" | "route_missing" | "route_unknown" | "route_type";
|
|
561
711
|
readonly code = "state_invalid";
|
|
562
|
-
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");
|
|
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");
|
|
563
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;
|
|
564
729
|
export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
|
|
565
730
|
export declare const submissionSchemaForNode: typeof stageSchemaForNode;
|
|
566
731
|
export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
|
|
732
|
+
/** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
|
|
733
|
+
export declare class WorkflowDecisionRecordError extends Error {
|
|
734
|
+
readonly label: string;
|
|
735
|
+
readonly decisionId: string;
|
|
736
|
+
constructor(label: string, decisionId: string, cause: unknown);
|
|
737
|
+
}
|
|
567
738
|
/** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
|
|
568
739
|
export declare const HOST_STATE_KEY = "$host";
|
|
569
740
|
export declare class WorkflowVerificationError extends Error {
|