@parcha/agentrun-dsl 0.1.0-beta.3 → 0.1.0-beta.31
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +165 -21
- package/dist/author-references.d.ts +8 -0
- package/dist/author-references.js +8 -0
- package/dist/author.d.ts +16 -3
- package/dist/author.js +40 -16
- package/dist/authoring.js +2 -2
- package/dist/cli.js +17 -12
- package/dist/code-exec.d.ts +6 -0
- package/dist/code-exec.js +126 -0
- package/dist/decision-provider.d.ts +157 -0
- package/dist/decision-provider.js +230 -0
- package/dist/decision-receipts.d.ts +143 -0
- package/dist/decision-receipts.js +93 -0
- package/dist/dry-run.d.ts +14 -1
- package/dist/dry-run.js +58 -15
- package/dist/graph.d.ts +169 -0
- package/dist/graph.js +433 -0
- package/dist/index.d.ts +15 -8
- package/dist/index.js +8 -4
- package/dist/inspection.d.ts +5 -0
- package/dist/inspection.js +16 -3
- 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 +10 -0
- package/dist/predicates.js +18 -0
- 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 +238 -0
- package/dist/recovery/driver.js +1337 -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 +274 -0
- package/dist/recovery/frozen-snapshot.js +187 -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 +19 -0
- package/dist/recovery/index.js +17 -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 +50 -0
- package/dist/recovery/with-recovery.js +142 -0
- package/dist/submit-envelope.d.ts +9 -0
- package/dist/submit-envelope.js +40 -0
- package/dist/system-one.d.ts +40 -1
- package/dist/system-one.js +141 -5
- package/dist/testing/decision-provider.d.ts +32 -0
- package/dist/testing/decision-provider.js +183 -0
- package/dist/testing/index.d.ts +1 -0
- package/dist/testing/index.js +2 -0
- package/dist/vocabulary.d.ts +22 -3
- package/dist/vocabulary.js +33 -10
- package/dist/workflow-shape.d.ts +7 -0
- package/dist/workflow-shape.js +115 -67
- package/dist/workflow.d.ts +269 -20
- package/dist/workflow.js +1251 -341
- package/package.json +25 -2
- package/schema/workflow.schema.json +506 -12
- package/skills/author/SKILL.md +6 -1
- package/skills/author/references/jev-decisions.md +58 -6
- package/skills/author/references/language.md +28 -19
- package/skills/author/references/sdk-authoring.md +2 -0
package/dist/workflow.d.ts
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
1
|
import { type AcceptPredicate } from "./predicates.js";
|
|
2
|
-
import {
|
|
2
|
+
import { EFFECT_FAILURE_CODES } from "./vocabulary.js";
|
|
3
|
+
import { type ConfidenceSource, type SystemOneAnswer, type SystemOneQuestion } from "./system-one.js";
|
|
4
|
+
import { type CostBasis, type DecisionEvidence, type DecisionProvider } from "./decision-provider.js";
|
|
5
|
+
import { type DecisionImageDigest, type DecisionReceipt } from "./decision-receipts.js";
|
|
3
6
|
export { resolveSchemaForWorkflow } from "./schema-references.js";
|
|
4
7
|
/** The model tier a node asks for: `fast` (the cheap tier), `strong` (the host's stronger model),
|
|
5
8
|
* or the kind's default. A router that sends the few thin cases to `strong` buys depth only where the
|
|
6
9
|
* decision is on the edge. */
|
|
7
10
|
export type ModelTier = "fast" | "default" | "strong";
|
|
11
|
+
/** An `agent` node's context (`AGENT_CONTEXTS`). */
|
|
12
|
+
export type AgentContext = "fresh" | "fork";
|
|
8
13
|
export type VerifyClause = {
|
|
9
14
|
out: string;
|
|
10
15
|
state?: Record<string, unknown>;
|
|
@@ -13,6 +18,12 @@ export type VerifyClause = {
|
|
|
13
18
|
below: number;
|
|
14
19
|
};
|
|
15
20
|
};
|
|
21
|
+
/** What a decision node asks of its provider's evidence: none, whatever it gives, or some (a provider that gives none is refused before the run). */
|
|
22
|
+
export type DecisionEvidenceMode = "off" | "if_supported" | "required";
|
|
23
|
+
/** The images a decision node sends with its request: each key is a token (such as `"<page1>"`) that appears literally in
|
|
24
|
+
* the node's `state` or in a question's text, and each value is a reference to the image, written as a `state` value is
|
|
25
|
+
* (`"{item.pages.0.image}"`, or a literal path), that resolves to a string the host loads (a run-relative file path). */
|
|
26
|
+
export type DecisionImages = Record<string, string>;
|
|
16
27
|
export type AskPredicate = {
|
|
17
28
|
predicate: "ask";
|
|
18
29
|
instructions: string;
|
|
@@ -22,20 +33,32 @@ export type AskPredicate = {
|
|
|
22
33
|
false?: string;
|
|
23
34
|
};
|
|
24
35
|
gte?: number;
|
|
36
|
+
provider?: string;
|
|
37
|
+
model?: string;
|
|
38
|
+
evidence?: DecisionEvidenceMode;
|
|
39
|
+
timeoutMs?: number;
|
|
40
|
+
images?: DecisionImages;
|
|
25
41
|
};
|
|
26
42
|
export type MechanicalPredicate = AcceptPredicate;
|
|
27
43
|
export type Predicate = MechanicalPredicate | AskPredicate;
|
|
28
44
|
export type WorkflowEffort = "minimal" | "low" | "medium" | "high";
|
|
29
45
|
/** The author's thinking dial. There is deliberately no "off": thinking is never off. */
|
|
30
46
|
export type WorkflowThinking = "low" | "medium" | "high";
|
|
47
|
+
/** Host-owned markers on a node: any JSON object. The engine admits, carries and hashes it with the
|
|
48
|
+
* document and never reads it; it never reaches state, events, prompts or effect identities. */
|
|
49
|
+
export type NodeMetadata = {
|
|
50
|
+
[key: string]: unknown;
|
|
51
|
+
};
|
|
31
52
|
export type WorkflowNode = {
|
|
32
53
|
node: "chain";
|
|
33
54
|
steps: WorkflowNode[];
|
|
55
|
+
metadata?: NodeMetadata;
|
|
34
56
|
} | {
|
|
35
57
|
node: "code";
|
|
36
58
|
label: string;
|
|
37
59
|
code: string;
|
|
38
60
|
as?: string;
|
|
61
|
+
metadata?: NodeMetadata;
|
|
39
62
|
} | {
|
|
40
63
|
node: "agent";
|
|
41
64
|
label: string;
|
|
@@ -50,6 +73,13 @@ export type WorkflowNode = {
|
|
|
50
73
|
thinking?: WorkflowThinking;
|
|
51
74
|
verify?: VerifyClause;
|
|
52
75
|
tier?: ModelTier;
|
|
76
|
+
/** The most the node asks to spend, in dollars. @exclusiveMinimum 0 */
|
|
77
|
+
budget_usd?: number;
|
|
78
|
+
/** The most turns the node asks its host for, per attempt. The host applies it within its own cap; the engine
|
|
79
|
+
* enforces nothing. @minimum 1 @TJS-type integer */
|
|
80
|
+
max_turns?: number;
|
|
81
|
+
context?: AgentContext;
|
|
82
|
+
metadata?: NodeMetadata;
|
|
53
83
|
} | {
|
|
54
84
|
node: "decide";
|
|
55
85
|
label: string;
|
|
@@ -64,6 +94,7 @@ export type WorkflowNode = {
|
|
|
64
94
|
thinking?: WorkflowThinking;
|
|
65
95
|
verify?: VerifyClause;
|
|
66
96
|
tier?: ModelTier;
|
|
97
|
+
metadata?: NodeMetadata;
|
|
67
98
|
} | {
|
|
68
99
|
node: "extract";
|
|
69
100
|
label: string;
|
|
@@ -78,6 +109,7 @@ export type WorkflowNode = {
|
|
|
78
109
|
thinking?: WorkflowThinking;
|
|
79
110
|
verify?: VerifyClause;
|
|
80
111
|
tier?: ModelTier;
|
|
112
|
+
metadata?: NodeMetadata;
|
|
81
113
|
} | {
|
|
82
114
|
node: "report";
|
|
83
115
|
label: string;
|
|
@@ -88,6 +120,7 @@ export type WorkflowNode = {
|
|
|
88
120
|
tools?: string[];
|
|
89
121
|
effort?: WorkflowEffort;
|
|
90
122
|
thinking?: WorkflowThinking;
|
|
123
|
+
metadata?: NodeMetadata;
|
|
91
124
|
} | ArtifactNode | {
|
|
92
125
|
node: "map";
|
|
93
126
|
label: string;
|
|
@@ -96,16 +129,26 @@ export type WorkflowNode = {
|
|
|
96
129
|
as: string;
|
|
97
130
|
resultPath?: string;
|
|
98
131
|
maxConcurrency?: number;
|
|
132
|
+
/** What an item's failure does: `stop` (the default) stops the map and the run; `collect` ends the item as a row
|
|
133
|
+
* of `failedAs` when its failure is an item failure (`isItemFailure`), and the other items finish. */
|
|
134
|
+
onItemFailure?: "stop" | "collect";
|
|
135
|
+
/** With `onItemFailure: "collect"`, the state key the map writes its failed items under, one row each in item order:
|
|
136
|
+
* `{ item_index, label, code, message }`. `as` stays aligned with the items, `null` in a failed item's slot. */
|
|
137
|
+
failedAs?: string;
|
|
138
|
+
metadata?: NodeMetadata;
|
|
99
139
|
} | {
|
|
100
140
|
node: "parallel";
|
|
101
141
|
label: string;
|
|
102
142
|
branches: WorkflowNode[];
|
|
143
|
+
metadata?: NodeMetadata;
|
|
103
144
|
} | {
|
|
104
145
|
node: "loop";
|
|
105
146
|
label: string;
|
|
106
147
|
body: WorkflowNode;
|
|
107
148
|
until: Predicate;
|
|
108
149
|
maxIters: number;
|
|
150
|
+
expect_iters?: number;
|
|
151
|
+
metadata?: NodeMetadata;
|
|
109
152
|
} | {
|
|
110
153
|
node: "escalate";
|
|
111
154
|
label: string;
|
|
@@ -113,6 +156,7 @@ export type WorkflowNode = {
|
|
|
113
156
|
kind: string;
|
|
114
157
|
stage: string;
|
|
115
158
|
summary: string;
|
|
159
|
+
metadata?: NodeMetadata;
|
|
116
160
|
} | JudgeNode | PickNode | SiftNode | RouteNode | CallNode | WorkflowInvocation;
|
|
117
161
|
/** A judgment as typed questions. `state` is what the questions see, interpolated by value from the
|
|
118
162
|
* workflow state (a whole-string placeholder keeps its type); `out` is a flat schema of enums,
|
|
@@ -125,6 +169,12 @@ export type JudgeNode = {
|
|
|
125
169
|
out: string;
|
|
126
170
|
as: string;
|
|
127
171
|
requires?: string[];
|
|
172
|
+
provider?: string;
|
|
173
|
+
model?: string;
|
|
174
|
+
evidence?: DecisionEvidenceMode;
|
|
175
|
+
timeoutMs?: number;
|
|
176
|
+
images?: DecisionImages;
|
|
177
|
+
metadata?: NodeMetadata;
|
|
128
178
|
};
|
|
129
179
|
/** One choice whose options are the items of a list. `describe` renders each item as its option
|
|
130
180
|
* text (`{item.field}`); `allowNone` adds a none-of-these option. The result at `as` is
|
|
@@ -140,6 +190,12 @@ export type PickNode = {
|
|
|
140
190
|
allowNone?: boolean;
|
|
141
191
|
as: string;
|
|
142
192
|
requires?: string[];
|
|
193
|
+
provider?: string;
|
|
194
|
+
model?: string;
|
|
195
|
+
evidence?: DecisionEvidenceMode;
|
|
196
|
+
timeoutMs?: number;
|
|
197
|
+
images?: DecisionImages;
|
|
198
|
+
metadata?: NodeMetadata;
|
|
143
199
|
};
|
|
144
200
|
/** The same question set (`out`, a judge schema) asked of every item of a list in ONE request: item i's
|
|
145
201
|
* questions are prefixed `i.`; every answer lands in `as.answers[i]` and `as.values[i]`. `keep`
|
|
@@ -158,11 +214,20 @@ export type SiftNode = {
|
|
|
158
214
|
gte?: number;
|
|
159
215
|
};
|
|
160
216
|
requires?: string[];
|
|
217
|
+
provider?: string;
|
|
218
|
+
model?: string;
|
|
219
|
+
evidence?: DecisionEvidenceMode;
|
|
220
|
+
timeoutMs?: number;
|
|
221
|
+
images?: DecisionImages;
|
|
222
|
+
metadata?: NodeMetadata;
|
|
161
223
|
};
|
|
162
|
-
/**
|
|
224
|
+
/** Run one of several named branches. Jev chooses it from `instructions` and `state`, or the workflow
|
|
225
|
+
* already holds the choice as a string at `valuePath` and no model is asked. */
|
|
226
|
+
export type RouteNode = RouteByJudgmentNode | RouteByValueNode;
|
|
227
|
+
/** A choice among subgraphs that Jev makes. The options are the branch names, their criteria the branch
|
|
163
228
|
* descriptions; the chosen branch runs on the state. `as` (optional) records the choice and its
|
|
164
229
|
* distribution; `unsure` names the branch taken when confidence is below `gte`. */
|
|
165
|
-
export type
|
|
230
|
+
export type RouteByJudgmentNode = {
|
|
166
231
|
node: "route";
|
|
167
232
|
label: string;
|
|
168
233
|
state: Record<string, unknown>;
|
|
@@ -177,9 +242,38 @@ export type RouteNode = {
|
|
|
177
242
|
branch: string;
|
|
178
243
|
gte: number;
|
|
179
244
|
};
|
|
245
|
+
valuePath?: never;
|
|
246
|
+
otherwise?: never;
|
|
180
247
|
as?: string;
|
|
181
248
|
requires?: string[];
|
|
249
|
+
provider?: string;
|
|
250
|
+
model?: string;
|
|
251
|
+
evidence?: DecisionEvidenceMode;
|
|
252
|
+
timeoutMs?: number;
|
|
253
|
+
images?: DecisionImages;
|
|
254
|
+
metadata?: NodeMetadata;
|
|
182
255
|
};
|
|
256
|
+
/** A route by a value already in state: the string at `valuePath` names the branch. A missing value or
|
|
257
|
+
* an unknown name takes `otherwise` when declared and fails before any branch otherwise; a value that is
|
|
258
|
+
* not a string always fails. `as` records `{value, taken, fallback}`. */
|
|
259
|
+
export type RouteByValueNode = {
|
|
260
|
+
node: "route";
|
|
261
|
+
label: string;
|
|
262
|
+
valuePath: string;
|
|
263
|
+
branches: {
|
|
264
|
+
[branch: string]: {
|
|
265
|
+
body: WorkflowNode;
|
|
266
|
+
};
|
|
267
|
+
};
|
|
268
|
+
otherwise?: string;
|
|
269
|
+
state?: never;
|
|
270
|
+
instructions?: never;
|
|
271
|
+
unsure?: never;
|
|
272
|
+
as?: string;
|
|
273
|
+
requires?: string[];
|
|
274
|
+
metadata?: NodeMetadata;
|
|
275
|
+
};
|
|
276
|
+
export declare const routesByValue: (node: RouteNode) => node is RouteByValueNode;
|
|
183
277
|
/** A child workflow invoked as one step of its parent. The child is embedded whole, so the parent
|
|
184
278
|
* digest covers every child byte; `input` is interpolated by value and is the child's ENTIRE initial
|
|
185
279
|
* state (no parent state leaks in); the child's validated output is checked against the parent's
|
|
@@ -192,10 +286,13 @@ export type WorkflowInvocation = {
|
|
|
192
286
|
input: Record<string, unknown>;
|
|
193
287
|
out: string;
|
|
194
288
|
as: string;
|
|
289
|
+
metadata?: NodeMetadata;
|
|
195
290
|
};
|
|
196
291
|
/** `exit` is a shell command that ended with a non-zero status: retried only when the author
|
|
197
292
|
* declared retry, since re-running a command is the author's call. */
|
|
198
293
|
export type CallRetryClass = "timeout" | "http_5xx" | "http_429" | "connection" | "exit";
|
|
294
|
+
/** A failed effect's closed code (EFFECT_FAILURE_CODES). */
|
|
295
|
+
export type EffectFailureCode = typeof EFFECT_FAILURE_CODES[number];
|
|
199
296
|
/** The workflow's terminal deliverable. Types "markdown" and "report" use the report
|
|
200
297
|
* writer; other non-empty types name a workspace file produced by an earlier call.
|
|
201
298
|
* File existence and delivery are the host's responsibility. */
|
|
@@ -214,6 +311,7 @@ export type ArtifactNode = {
|
|
|
214
311
|
effort?: WorkflowEffort;
|
|
215
312
|
thinking?: WorkflowThinking;
|
|
216
313
|
requires?: string[];
|
|
314
|
+
metadata?: NodeMetadata;
|
|
217
315
|
};
|
|
218
316
|
export type ArtifactState = {
|
|
219
317
|
path: string;
|
|
@@ -263,19 +361,24 @@ export type CallNode = {
|
|
|
263
361
|
produces?: string[];
|
|
264
362
|
/** Wall bound in seconds for one execution. Required: an unbounded effect is how a stalled provider becomes a stalled job. */
|
|
265
363
|
deadline_s: number;
|
|
364
|
+
/** `on` names retry classes or effect failure codes; absent, the transient retry classes. */
|
|
266
365
|
retry?: {
|
|
267
366
|
attempts: number;
|
|
268
367
|
backoff_s?: number;
|
|
269
|
-
on?: CallRetryClass[];
|
|
368
|
+
on?: (CallRetryClass | EffectFailureCode)[];
|
|
270
369
|
};
|
|
271
370
|
/** Repeat the call until its result settles (a queued job, an eventually consistent read). */
|
|
272
371
|
poll?: PollClause;
|
|
273
372
|
requires?: string[];
|
|
373
|
+
metadata?: NodeMetadata;
|
|
274
374
|
};
|
|
275
375
|
export declare const SHELL_RESULT_SCHEMA: Record<string, unknown>;
|
|
276
376
|
export type LlmNode = Extract<WorkflowNode, {
|
|
277
377
|
node: "agent" | "decide" | "extract" | "report";
|
|
278
378
|
}>;
|
|
379
|
+
export type CodeNode = Extract<WorkflowNode, {
|
|
380
|
+
node: "code";
|
|
381
|
+
}>;
|
|
279
382
|
export declare const REPORT_SCHEMA: Record<string, unknown>;
|
|
280
383
|
export type Workflow = {
|
|
281
384
|
v: 2;
|
|
@@ -366,6 +469,10 @@ export type HostPolicy = {
|
|
|
366
469
|
};
|
|
367
470
|
export type WorkflowDeps = {
|
|
368
471
|
maxQuestionsPerRequest?: number;
|
|
472
|
+
/** Most UTF-8 bytes of JSON state one judge request may carry (the Jev adapter's `maxStateBytes`
|
|
473
|
+
* measure). A `sift` that would exceed it, or `maxQuestionsPerRequest`, is split into several
|
|
474
|
+
* requests. Absent = no byte limit. */
|
|
475
|
+
maxStateBytesPerRequest?: number;
|
|
369
476
|
/** Host application policy; see `HostPolicy`. Absent = the engine's own behavior, unchanged. */
|
|
370
477
|
hostPolicy?: HostPolicy;
|
|
371
478
|
runNode?: (params: {
|
|
@@ -390,6 +497,15 @@ export type WorkflowDeps = {
|
|
|
390
497
|
message: string;
|
|
391
498
|
}>;
|
|
392
499
|
tier?: ModelTier;
|
|
500
|
+
/** An `agent` node's `budget_usd`: the most the node asks to spend, recorded; enforcement belongs to the host.
|
|
501
|
+
* No runner stops a run on money. A host may cap it by what it has left. */
|
|
502
|
+
budgetUsd?: number;
|
|
503
|
+
/** An `agent` node's `max_turns`: the most turns it asks for, per attempt. The host applies it within its own cap
|
|
504
|
+
* and refuses a node that asks for more; the engine enforces nothing. */
|
|
505
|
+
maxTurns?: number;
|
|
506
|
+
/** An `agent` node's `context`. `fork` asks the host to start the session from the caller's transcript;
|
|
507
|
+
* a host that has none to fork refuses it. */
|
|
508
|
+
context?: AgentContext;
|
|
393
509
|
}) => Promise<unknown>;
|
|
394
510
|
runEffect?: (params: {
|
|
395
511
|
node: CallNode;
|
|
@@ -399,9 +515,32 @@ export type WorkflowDeps = {
|
|
|
399
515
|
attempt: number;
|
|
400
516
|
idempotencyKey: string;
|
|
401
517
|
signal: AbortSignal;
|
|
518
|
+
/** The attempt's deadline instant on this process's `performance.now()` clock, exactly as the
|
|
519
|
+
* interpreter armed its deadline timer, so the host measures its own kill and duration against
|
|
520
|
+
* the instant the timer fires. Absent when the call has no deadline. */
|
|
521
|
+
deadlineAt?: number;
|
|
402
522
|
item?: MapItem;
|
|
403
523
|
executionPath?: string;
|
|
404
524
|
}) => Promise<unknown>;
|
|
525
|
+
/** The host's executor for `code` nodes. Present, the interpreter hands it the node, the state and
|
|
526
|
+
* the context the transform would receive and uses what it resolves to as the transform's result
|
|
527
|
+
* (the same patch rules and state checks apply); a rejection fails the node as the host typed it.
|
|
528
|
+
* Absent, the interpreter compiles and runs the transform in this process (`compileTransform`),
|
|
529
|
+
* which is not a sandbox: a host that runs code from an untrusted author supplies this. */
|
|
530
|
+
runCode?: (node: CodeNode, state: Record<string, unknown>, ctx: {
|
|
531
|
+
sop: string;
|
|
532
|
+
label: string;
|
|
533
|
+
executionPath: string;
|
|
534
|
+
item?: MapItem;
|
|
535
|
+
signal?: AbortSignal;
|
|
536
|
+
}) => Promise<unknown>;
|
|
537
|
+
/** The host's decision providers by id, and the one a node that names none gets. A run checks every decision node
|
|
538
|
+
* against them before any node runs: a provider the host lacks, evidence it cannot give, a model it does not serve, a
|
|
539
|
+
* question type it does not answer. Without them, a node that names a provider or sets timeoutMs is refused. */
|
|
540
|
+
decisionProviders?: {
|
|
541
|
+
providers: Readonly<Record<string, DecisionProvider>>;
|
|
542
|
+
default: string;
|
|
543
|
+
};
|
|
405
544
|
runJudge?: (params: {
|
|
406
545
|
label: string;
|
|
407
546
|
kind: "judge" | "pick" | "sift" | "route" | "ask";
|
|
@@ -410,6 +549,20 @@ export type WorkflowDeps = {
|
|
|
410
549
|
signal?: AbortSignal;
|
|
411
550
|
state: unknown;
|
|
412
551
|
questions: Record<string, SystemOneQuestion>;
|
|
552
|
+
/** The id of this request's decision receipt (`DecisionReceipt.id`): the same request asked again
|
|
553
|
+
* carries the same id. */
|
|
554
|
+
decisionId?: string;
|
|
555
|
+
/** The node's provider, by id; absent, the host's default answers. */
|
|
556
|
+
provider?: string;
|
|
557
|
+
/** The model the node pins, when it pins one. */
|
|
558
|
+
model?: string;
|
|
559
|
+
/** What the node asks of the provider's evidence. */
|
|
560
|
+
evidence?: DecisionEvidenceMode;
|
|
561
|
+
/** The node's own time bound, in milliseconds: it only ever shortens the provider's deadline. */
|
|
562
|
+
timeoutMs?: number;
|
|
563
|
+
/** The images the node sends, token -> resolved image reference (a run-relative path). The host loads them
|
|
564
|
+
* (`judgeFromProvider`'s `loadImage`); each token appears literally in `state` or a question's text. */
|
|
565
|
+
images?: Record<string, string>;
|
|
413
566
|
}) => Promise<{
|
|
414
567
|
answers: Record<string, SystemOneAnswer>;
|
|
415
568
|
model?: string | null;
|
|
@@ -419,7 +572,25 @@ export type WorkflowDeps = {
|
|
|
419
572
|
} | null;
|
|
420
573
|
cost_usd?: number | null;
|
|
421
574
|
request_sha256?: string;
|
|
575
|
+
/** Whether each choice and score answer's confidence is the provider's own or derived from its probabilities. */
|
|
576
|
+
confidence_source?: Record<string, ConfidenceSource>;
|
|
577
|
+
/** The sources the provider grounded its answers in (a DecisionProvider's, through judgeFromProvider). */
|
|
578
|
+
evidence?: DecisionEvidence[];
|
|
579
|
+
/** The provider's own id for the request, when it gives one. */
|
|
580
|
+
provider_request_id?: string | null;
|
|
581
|
+
/** How `cost_usd` was reached: reported by the provider, estimated by the host, or unknown (null). */
|
|
582
|
+
cost_basis?: CostBasis;
|
|
583
|
+
/** The provider that answered, by id. */
|
|
584
|
+
provider?: string;
|
|
585
|
+
/** The images the request carried, by digest (never the bytes), as the host loaded them. */
|
|
586
|
+
images?: DecisionImageDigest[];
|
|
422
587
|
}>;
|
|
588
|
+
/** Records one typed-question request and what its answers decide. It is awaited before the answers
|
|
589
|
+
* reach state, an event or a branch, so a durable recorder holds every decision the run acted on; a
|
|
590
|
+
* rejection fails the node. A request the judge could not answer, or one cancelled in flight, is
|
|
591
|
+
* recorded too, before its failure is thrown. A decision answered from `recovery.decision` was
|
|
592
|
+
* recorded by the run that asked it and is not recorded again. */
|
|
593
|
+
recordDecision?: (receipt: DecisionReceipt, exchange: DecisionExchange) => Promise<void>;
|
|
423
594
|
syntheticEffects?: boolean;
|
|
424
595
|
checkpoint?: (state: Record<string, unknown>, label: string, executionPath?: string) => Promise<void>;
|
|
425
596
|
/** Critical recovery stores stop execution on write failure; omitted retains legacy best effort. */
|
|
@@ -432,6 +603,17 @@ export type WorkflowDeps = {
|
|
|
432
603
|
pollStartedAt: (node: CallNode, item?: MapItem, executionPath?: string) => number;
|
|
433
604
|
wait: (node: CallNode, ms: number, item?: MapItem, executionPath?: string) => Promise<void>;
|
|
434
605
|
fail?: (node: WorkflowNode, results: unknown[], error: unknown, executionPath?: string) => Promise<void>;
|
|
606
|
+
/** A map with `onItemFailure: "collect"` commits an item that ended on its failure here, at the item's body path,
|
|
607
|
+
* once, before the map goes on; `node` is the map. A store without both hooks cannot hold such a map: it is refused
|
|
608
|
+
* before any step runs. */
|
|
609
|
+
failItem?: (node: WorkflowNode, failure: MapItemFailure, executionPath?: string) => Promise<void>;
|
|
610
|
+
/** The failure an earlier process committed for the item whose body path this is, if any: the item ends on it again,
|
|
611
|
+
* and its body never runs again. */
|
|
612
|
+
itemFailure?: (node: WorkflowNode, executionPath?: string) => Promise<MapItemFailure | undefined>;
|
|
613
|
+
/** The receipt an earlier run recorded under this id, if any. An `answered` one answers the request:
|
|
614
|
+
* the judge is not asked again, so a resumed run decides what the interrupted run decided. Any
|
|
615
|
+
* other receipt, or none, means the request is asked. */
|
|
616
|
+
decision?: (id: string) => Promise<DecisionReceipt | undefined>;
|
|
435
617
|
};
|
|
436
618
|
/** A completed-effect memo keyed by the call's idempotency key. A hit skips the effect and
|
|
437
619
|
* reuses its result; polled calls are never memoized (their result is a moment in time). */
|
|
@@ -444,18 +626,39 @@ export type WorkflowDeps = {
|
|
|
444
626
|
signal?: AbortSignal;
|
|
445
627
|
/** Best-effort observation only: thrown errors and rejected promises are ignored.
|
|
446
628
|
* Observers are never awaited. Use required checkpoints for durable lifecycle gates. */
|
|
447
|
-
onEvent?: (event:
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
629
|
+
onEvent?: (event: WorkflowEvent) => void;
|
|
630
|
+
/** Trusted host boundary: return a detached snapshot without mutating the input.
|
|
631
|
+
* Runs before generic copying; undefined or thrown errors omit the event.
|
|
632
|
+
* Required trace validation cancels through the host signal, preserving execution cleanup. */
|
|
633
|
+
prepareEvent?: (event: WorkflowEvent) => WorkflowEvent | undefined;
|
|
634
|
+
};
|
|
635
|
+
export type WorkflowEvent = {
|
|
636
|
+
type: string;
|
|
637
|
+
label: string;
|
|
638
|
+
detail?: unknown;
|
|
639
|
+
executionPath?: string;
|
|
640
|
+
};
|
|
641
|
+
type JudgeRequest = Parameters<NonNullable<WorkflowDeps["runJudge"]>>[0];
|
|
642
|
+
type JudgeResult = Awaited<ReturnType<NonNullable<WorkflowDeps["runJudge"]>>>;
|
|
643
|
+
/** What a decision recorder gets beside the receipt: the request as the host's `runJudge` received it,
|
|
644
|
+
* and, when the judge returned, the very object it returned, so a host reads back what it put there. */
|
|
645
|
+
export type DecisionExchange = {
|
|
646
|
+
request: JudgeRequest;
|
|
647
|
+
result?: JudgeResult;
|
|
453
648
|
};
|
|
454
649
|
export declare const declaredWrites: (node: WorkflowNode | undefined) => Set<string>;
|
|
455
650
|
export declare const childSteps: (child: Workflow | undefined) => WorkflowNode[] | null;
|
|
651
|
+
/** A failed effect: its retry class (null when the failure is not transient by nature), its closed code,
|
|
652
|
+
* and what the host observed (`detail`, written onto the attempt's `effect.failed` event). */
|
|
456
653
|
export declare class EffectFailure extends Error {
|
|
457
654
|
readonly retryClass: CallRetryClass | null;
|
|
458
|
-
|
|
655
|
+
readonly code: EffectFailureCode | null;
|
|
656
|
+
readonly detail?: Record<string, unknown>;
|
|
657
|
+
constructor(message: string, retryClass?: CallRetryClass | null, options?: {
|
|
658
|
+
code?: EffectFailureCode | null;
|
|
659
|
+
detail?: Record<string, unknown>;
|
|
660
|
+
cause?: unknown;
|
|
661
|
+
});
|
|
459
662
|
}
|
|
460
663
|
export declare function parseCsvRows(text: string): string[][];
|
|
461
664
|
export declare function buildReferenceContext(files: Record<string, string>): {
|
|
@@ -465,15 +668,28 @@ export declare function buildReferenceContext(files: Record<string, string>): {
|
|
|
465
668
|
rows: string[][];
|
|
466
669
|
}>;
|
|
467
670
|
};
|
|
468
|
-
export declare function normalizeStringNullsForSchema(value: unknown, schema: Record<string, unknown> | undefined, depth?: number): unknown;
|
|
671
|
+
export declare function normalizeStringNullsForSchema(value: unknown, schema: Record<string, unknown> | undefined, depth?: number, root?: Record<string, unknown> | undefined): unknown;
|
|
469
672
|
export declare function workflowSha256(workflow: Workflow): string;
|
|
470
673
|
/** Bound the complete document before any recursive schema or semantic traversal. Shared
|
|
471
674
|
* objects are valid, but each occurrence consumes the budget; cycles are never JSON. */
|
|
472
675
|
export declare function workflowDocumentError(value: unknown): string | undefined;
|
|
473
|
-
/**
|
|
474
|
-
*
|
|
475
|
-
|
|
476
|
-
|
|
676
|
+
/** The rule a validation issue breaks. A closed set: a new code widens it, so a consumer keeps a default branch; renaming
|
|
677
|
+
* one is a breaking change. `docs/guide.md` lists each with an example. */
|
|
678
|
+
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";
|
|
679
|
+
/** One validation error. `message` is the matching entry of `errors`, unchanged. `path` is a JSON Pointer (RFC 6901)
|
|
680
|
+
* into the workflow as written, naming what the rule is about: a node (the same path `inspectWorkflow` gives it), a
|
|
681
|
+
* schema (`/schemas/<id>`), a value the shape check refused, or `""` for the document's own fields and for the input
|
|
682
|
+
* supplied to validation. It never names a key that is missing. */
|
|
683
|
+
export type ValidationIssue = {
|
|
684
|
+
path: string;
|
|
685
|
+
code: ValidationCode;
|
|
686
|
+
message: string;
|
|
687
|
+
};
|
|
688
|
+
/** Whether a workflow can run, checked without running it: `errors` refuse it, `warnings` advise and never refuse.
|
|
689
|
+
* Set `executeCode: false` for untrusted author feedback: check syntax and mechanical contracts without evaluating
|
|
690
|
+
* authored expressions or probing transforms. That is not execution admission; trusted/default validation and runtime
|
|
691
|
+
* output checks remain authoritative. */
|
|
692
|
+
export type ValidateWorkflowOptions = {
|
|
477
693
|
executeCode?: boolean;
|
|
478
694
|
input?: Record<string, unknown>;
|
|
479
695
|
inputKeys?: string[];
|
|
@@ -484,11 +700,18 @@ export declare function validateWorkflow(workflow: Workflow, opts?: {
|
|
|
484
700
|
rows: string[][];
|
|
485
701
|
}>;
|
|
486
702
|
};
|
|
487
|
-
|
|
703
|
+
/** The host's tool names. Given, a node that names a tool outside them (a model or artifact node's `tools`, a call
|
|
704
|
+
* node's `tool`) is refused here. Absent, tool names are not checked until a node runs. */
|
|
705
|
+
tools?: readonly string[];
|
|
706
|
+
};
|
|
707
|
+
export declare function validateWorkflow(workflow: Workflow, opts?: ValidateWorkflowOptions): {
|
|
488
708
|
ok: true;
|
|
709
|
+
warnings?: string[];
|
|
489
710
|
} | {
|
|
490
711
|
ok: false;
|
|
491
712
|
errors: string[];
|
|
713
|
+
issues: ValidationIssue[];
|
|
714
|
+
warnings?: string[];
|
|
492
715
|
};
|
|
493
716
|
export declare class EscalationSignal extends Error {
|
|
494
717
|
readonly escalation: Escalation;
|
|
@@ -500,9 +723,11 @@ export declare function schemaProblems(validator: {
|
|
|
500
723
|
export declare class WorkflowInvalidError extends Error {
|
|
501
724
|
readonly workflowName: string;
|
|
502
725
|
readonly problems: string[];
|
|
726
|
+
readonly issues: ValidationIssue[];
|
|
503
727
|
readonly code = "workflow_invalid";
|
|
504
728
|
readonly stage = "validate";
|
|
505
|
-
|
|
729
|
+
/** `problems` are validateWorkflow's `errors`; `issues` its issues, one per problem in the same order. */
|
|
730
|
+
constructor(workflowName: string, problems: string[], issues?: ValidationIssue[]);
|
|
506
731
|
}
|
|
507
732
|
export declare class WorkflowInputInvalidError extends Error {
|
|
508
733
|
readonly workflowName: string;
|
|
@@ -557,13 +782,37 @@ export declare class WorkflowCodeError extends Error {
|
|
|
557
782
|
export declare class WorkflowStateError extends Error {
|
|
558
783
|
readonly stage: string;
|
|
559
784
|
readonly path: string;
|
|
560
|
-
readonly reason: "required_nonempty" | "missing_interpolation" | "expected_list" | "empty_selection" | "missing_map_result" | "parallel_write_conflict" | "reserved_state_key";
|
|
785
|
+
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
786
|
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");
|
|
787
|
+
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
788
|
}
|
|
789
|
+
/** A map item that ended on its failure (`onItemFailure: "collect"`), as `failedAs` holds it: the item's index, the
|
|
790
|
+
* label of the node that failed, the failure's code and its message (at most 300 characters). `needs_review` marks an
|
|
791
|
+
* item whose decision went to a person instead of failing: one sent whose outcome was lost (`decision_interrupted`,
|
|
792
|
+
* never asked again) or one its provider refused (`decision_refused`); its code is that escalation's kind. */
|
|
793
|
+
export type MapItemFailure = {
|
|
794
|
+
item_index: number;
|
|
795
|
+
label: string;
|
|
796
|
+
code: string;
|
|
797
|
+
message: string;
|
|
798
|
+
needs_review?: true;
|
|
799
|
+
};
|
|
800
|
+
/** Whether an item's failure is one a map with `onItemFailure: "collect"` ends the item on: one of the interpreter's own
|
|
801
|
+
* typed node failures (a call that failed after its retries, output that does not match its schema, a state contract, a
|
|
802
|
+
* code transform, a failed verification), or a host's failure that declares itself one, with a string `code` and
|
|
803
|
+
* `itemFailure: true`. Never one whose cause chain holds an effect whose outcome is unknown, a recovery failure, an
|
|
804
|
+
* escalation or an abort, never several failures at once, and nothing else: a new error class is never collected by
|
|
805
|
+
* accident. */
|
|
806
|
+
export declare function isItemFailure(error: unknown): boolean;
|
|
564
807
|
export declare function stageSchemaForNode(workflow: Workflow, node: LlmNode): Record<string, unknown>;
|
|
565
808
|
export declare const submissionSchemaForNode: typeof stageSchemaForNode;
|
|
566
809
|
export declare function mergeStageDelta(state: Record<string, unknown>, node: LlmNode, result: Record<string, unknown>, schema: Record<string, unknown>): Record<string, unknown>;
|
|
810
|
+
/** A persistence failure of a decision receipt. It fails the node: the answers were never applied. */
|
|
811
|
+
export declare class WorkflowDecisionRecordError extends Error {
|
|
812
|
+
readonly label: string;
|
|
813
|
+
readonly decisionId: string;
|
|
814
|
+
constructor(label: string, decisionId: string, cause: unknown);
|
|
815
|
+
}
|
|
567
816
|
/** The reserved state key host policy writes under. Engine-owned like every `$`-prefixed key: no node may name it. */
|
|
568
817
|
export declare const HOST_STATE_KEY = "$host";
|
|
569
818
|
export declare class WorkflowVerificationError extends Error {
|