fascicle 0.12.0 → 0.12.3
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/CHANGELOG.md +148 -32
- package/README.md +25 -15
- package/dist/{adapters-hmnJOOgf.js → adapters-CutexJd3.js} +12 -12
- package/dist/adapters-CutexJd3.js.map +1 -0
- package/dist/adapters.d.ts +10 -10
- package/dist/adapters.js +1 -1
- package/dist/agents.d.ts +22 -3
- package/dist/agents.js +74 -24
- package/dist/agents.js.map +1 -1
- package/dist/bin/fascicle-viewer.js +2 -2
- package/dist/{core-BkB2l1-e.js → core-DdJEhyQc.js} +314 -501
- package/dist/core-DdJEhyQc.js.map +1 -0
- package/dist/engine-J4lIxpw5.js +7000 -0
- package/dist/engine-J4lIxpw5.js.map +1 -0
- package/dist/index.d.ts +237 -178
- package/dist/index.js +617 -7771
- package/dist/index.js.map +1 -1
- package/dist/{invoke-JkzNf7-Y.js → invoke-CH_eJZeS.js} +8 -8
- package/dist/{invoke-JkzNf7-Y.js.map → invoke-CH_eJZeS.js.map} +1 -1
- package/dist/{leading_system-BVtGMweY.js → leading_system-BUCT-PwD.js} +31 -8
- package/dist/leading_system-BUCT-PwD.js.map +1 -0
- package/dist/mcp.d.ts +5 -5
- package/dist/mcp.js +10 -9
- package/dist/mcp.js.map +1 -1
- package/dist/otel.d.ts +1 -1
- package/dist/otel.js +4 -4
- package/dist/otel.js.map +1 -1
- package/dist/static/viewer.html +2 -1
- package/dist/stdio.d.ts +2 -2
- package/dist/stdio.js +2 -2
- package/dist/testing.d.ts +66 -15
- package/dist/testing.js +200 -34
- package/dist/testing.js.map +1 -1
- package/dist/trajectory-ByoOQZ6T.d.ts +114 -0
- package/dist/trajectory-D1eq9eue.js +81 -0
- package/dist/trajectory-D1eq9eue.js.map +1 -0
- package/dist/{types-BCtKsxrX.d.ts → types-BK0UW28o.d.ts} +3 -3
- package/dist/{types-CVdTBXE_.d.ts → types-DBpU27sQ.d.ts} +20 -3
- package/dist/{types-4l54cexm.d.ts → types-DU6cvoA4.d.ts} +9 -5
- package/dist/ui.d.ts +2 -2
- package/dist/ui.js +1 -1
- package/dist/ui.js.map +1 -1
- package/dist/viewer.d.ts +117 -0
- package/dist/viewer.js +659 -0
- package/dist/viewer.js.map +1 -0
- package/package.json +26 -12
- package/dist/adapters-hmnJOOgf.js.map +0 -1
- package/dist/core-BkB2l1-e.js.map +0 -1
- package/dist/leading_system-BVtGMweY.js.map +0 -1
|
@@ -1,322 +1,4 @@
|
|
|
1
1
|
import { randomUUID } from "node:crypto";
|
|
2
|
-
//#region src/core/flow-schema.json
|
|
3
|
-
var flow_schema_default = {
|
|
4
|
-
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
5
|
-
$id: "https://robmclarty.dev/schemas/flow-schema.json",
|
|
6
|
-
title: "fascicle Flow DSL",
|
|
7
|
-
description: "YAML/JSON representation of a composition tree. Documentation-only in v1. See spec.md §5.17.",
|
|
8
|
-
type: "array",
|
|
9
|
-
items: { "$ref": "#/$defs/compose_entry" },
|
|
10
|
-
$defs: {
|
|
11
|
-
"compose_entry": {
|
|
12
|
-
"type": "object",
|
|
13
|
-
"required": ["compose"],
|
|
14
|
-
"properties": { "compose": { "type": "string" } },
|
|
15
|
-
"allOf": [{ "$ref": "#/$defs/node" }]
|
|
16
|
-
},
|
|
17
|
-
"node": {
|
|
18
|
-
"type": "object",
|
|
19
|
-
"anyOf": [
|
|
20
|
-
{ "required": ["step"] },
|
|
21
|
-
{ "required": ["sequence"] },
|
|
22
|
-
{ "required": ["parallel"] },
|
|
23
|
-
{ "required": ["branch"] },
|
|
24
|
-
{ "required": ["map"] },
|
|
25
|
-
{ "required": ["pipe"] },
|
|
26
|
-
{ "required": ["retry"] },
|
|
27
|
-
{ "required": ["fallback"] },
|
|
28
|
-
{ "required": ["timeout"] },
|
|
29
|
-
{ "required": ["loop"] },
|
|
30
|
-
{ "required": ["compose_node"] },
|
|
31
|
-
{ "required": ["adversarial"] },
|
|
32
|
-
{ "required": ["ensemble"] },
|
|
33
|
-
{ "required": ["tournament"] },
|
|
34
|
-
{ "required": ["consensus"] },
|
|
35
|
-
{ "required": ["checkpoint"] },
|
|
36
|
-
{ "required": ["suspend"] },
|
|
37
|
-
{ "required": ["scope"] },
|
|
38
|
-
{ "required": ["chain"] },
|
|
39
|
-
{ "required": ["ref"] }
|
|
40
|
-
],
|
|
41
|
-
"properties": {
|
|
42
|
-
"step": { "$ref": "#/$defs/step_config" },
|
|
43
|
-
"sequence": { "$ref": "#/$defs/sequence_config" },
|
|
44
|
-
"parallel": { "$ref": "#/$defs/parallel_config" },
|
|
45
|
-
"branch": { "$ref": "#/$defs/branch_config" },
|
|
46
|
-
"map": { "$ref": "#/$defs/map_config" },
|
|
47
|
-
"pipe": { "$ref": "#/$defs/pipe_config" },
|
|
48
|
-
"retry": { "$ref": "#/$defs/retry_config" },
|
|
49
|
-
"fallback": { "$ref": "#/$defs/fallback_config" },
|
|
50
|
-
"timeout": { "$ref": "#/$defs/timeout_config" },
|
|
51
|
-
"loop": { "$ref": "#/$defs/loop_config" },
|
|
52
|
-
"compose_node": { "$ref": "#/$defs/compose_node_config" },
|
|
53
|
-
"adversarial": { "$ref": "#/$defs/adversarial_config" },
|
|
54
|
-
"ensemble": { "$ref": "#/$defs/ensemble_config" },
|
|
55
|
-
"tournament": { "$ref": "#/$defs/tournament_config" },
|
|
56
|
-
"consensus": { "$ref": "#/$defs/consensus_config" },
|
|
57
|
-
"checkpoint": { "$ref": "#/$defs/checkpoint_config" },
|
|
58
|
-
"suspend": { "$ref": "#/$defs/suspend_config" },
|
|
59
|
-
"scope": { "$ref": "#/$defs/scope_config" },
|
|
60
|
-
"chain": { "$ref": "#/$defs/chain_config" },
|
|
61
|
-
"ref": { "type": "string" }
|
|
62
|
-
}
|
|
63
|
-
},
|
|
64
|
-
"step_config": {
|
|
65
|
-
"type": "object",
|
|
66
|
-
"required": ["fn"],
|
|
67
|
-
"properties": {
|
|
68
|
-
"id": { "type": "string" },
|
|
69
|
-
"fn": { "type": "string" }
|
|
70
|
-
}
|
|
71
|
-
},
|
|
72
|
-
"sequence_config": {
|
|
73
|
-
"type": "array",
|
|
74
|
-
"items": { "$ref": "#/$defs/node" }
|
|
75
|
-
},
|
|
76
|
-
"parallel_config": {
|
|
77
|
-
"type": "object",
|
|
78
|
-
"additionalProperties": { "$ref": "#/$defs/node" }
|
|
79
|
-
},
|
|
80
|
-
"branch_config": {
|
|
81
|
-
"type": "object",
|
|
82
|
-
"required": [
|
|
83
|
-
"when",
|
|
84
|
-
"then",
|
|
85
|
-
"otherwise"
|
|
86
|
-
],
|
|
87
|
-
"properties": {
|
|
88
|
-
"when": { "type": "string" },
|
|
89
|
-
"then": { "$ref": "#/$defs/node" },
|
|
90
|
-
"otherwise": { "$ref": "#/$defs/node" }
|
|
91
|
-
}
|
|
92
|
-
},
|
|
93
|
-
"map_config": {
|
|
94
|
-
"type": "object",
|
|
95
|
-
"required": ["items", "do"],
|
|
96
|
-
"properties": {
|
|
97
|
-
"items": { "type": "string" },
|
|
98
|
-
"do": { "$ref": "#/$defs/node" },
|
|
99
|
-
"concurrency": {
|
|
100
|
-
"type": "integer",
|
|
101
|
-
"minimum": 1
|
|
102
|
-
}
|
|
103
|
-
}
|
|
104
|
-
},
|
|
105
|
-
"pipe_config": {
|
|
106
|
-
"type": "object",
|
|
107
|
-
"required": ["of", "fn"],
|
|
108
|
-
"properties": {
|
|
109
|
-
"of": { "$ref": "#/$defs/node" },
|
|
110
|
-
"fn": { "type": "string" }
|
|
111
|
-
}
|
|
112
|
-
},
|
|
113
|
-
"retry_config": {
|
|
114
|
-
"type": "object",
|
|
115
|
-
"required": ["do", "max_attempts"],
|
|
116
|
-
"properties": {
|
|
117
|
-
"do": { "$ref": "#/$defs/node" },
|
|
118
|
-
"max_attempts": {
|
|
119
|
-
"type": "integer",
|
|
120
|
-
"minimum": 1
|
|
121
|
-
},
|
|
122
|
-
"backoff_ms": {
|
|
123
|
-
"type": "integer",
|
|
124
|
-
"minimum": 0
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
},
|
|
128
|
-
"fallback_config": {
|
|
129
|
-
"type": "object",
|
|
130
|
-
"required": ["primary", "backup"],
|
|
131
|
-
"properties": {
|
|
132
|
-
"primary": { "$ref": "#/$defs/node" },
|
|
133
|
-
"backup": { "$ref": "#/$defs/node" }
|
|
134
|
-
}
|
|
135
|
-
},
|
|
136
|
-
"timeout_config": {
|
|
137
|
-
"type": "object",
|
|
138
|
-
"required": ["do", "ms"],
|
|
139
|
-
"properties": {
|
|
140
|
-
"do": { "$ref": "#/$defs/node" },
|
|
141
|
-
"ms": {
|
|
142
|
-
"type": "integer",
|
|
143
|
-
"minimum": 1
|
|
144
|
-
}
|
|
145
|
-
}
|
|
146
|
-
},
|
|
147
|
-
"compose_node_config": {
|
|
148
|
-
"type": "object",
|
|
149
|
-
"required": ["name", "do"],
|
|
150
|
-
"properties": {
|
|
151
|
-
"name": {
|
|
152
|
-
"type": "string",
|
|
153
|
-
"minLength": 1
|
|
154
|
-
},
|
|
155
|
-
"do": { "$ref": "#/$defs/node" }
|
|
156
|
-
}
|
|
157
|
-
},
|
|
158
|
-
"loop_config": {
|
|
159
|
-
"type": "object",
|
|
160
|
-
"required": ["body", "max_rounds"],
|
|
161
|
-
"properties": {
|
|
162
|
-
"name": {
|
|
163
|
-
"type": "string",
|
|
164
|
-
"minLength": 1
|
|
165
|
-
},
|
|
166
|
-
"init": { "type": "string" },
|
|
167
|
-
"body": { "$ref": "#/$defs/node" },
|
|
168
|
-
"guard": { "$ref": "#/$defs/node" },
|
|
169
|
-
"finish": { "type": "string" },
|
|
170
|
-
"max_rounds": {
|
|
171
|
-
"type": "integer",
|
|
172
|
-
"minimum": 1
|
|
173
|
-
}
|
|
174
|
-
}
|
|
175
|
-
},
|
|
176
|
-
"adversarial_config": {
|
|
177
|
-
"type": "object",
|
|
178
|
-
"required": [
|
|
179
|
-
"build",
|
|
180
|
-
"critique",
|
|
181
|
-
"accept",
|
|
182
|
-
"max_rounds"
|
|
183
|
-
],
|
|
184
|
-
"properties": {
|
|
185
|
-
"build": { "$ref": "#/$defs/node" },
|
|
186
|
-
"critique": { "$ref": "#/$defs/node" },
|
|
187
|
-
"accept": { "type": "string" },
|
|
188
|
-
"max_rounds": {
|
|
189
|
-
"type": "integer",
|
|
190
|
-
"minimum": 1
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
},
|
|
194
|
-
"ensemble_config": {
|
|
195
|
-
"type": "object",
|
|
196
|
-
"required": ["members", "score"],
|
|
197
|
-
"properties": {
|
|
198
|
-
"members": {
|
|
199
|
-
"type": "object",
|
|
200
|
-
"additionalProperties": { "$ref": "#/$defs/node" }
|
|
201
|
-
},
|
|
202
|
-
"score": { "type": "string" },
|
|
203
|
-
"select": {
|
|
204
|
-
"type": "string",
|
|
205
|
-
"enum": ["max", "min"]
|
|
206
|
-
}
|
|
207
|
-
}
|
|
208
|
-
},
|
|
209
|
-
"tournament_config": {
|
|
210
|
-
"type": "object",
|
|
211
|
-
"required": ["members", "compare"],
|
|
212
|
-
"properties": {
|
|
213
|
-
"members": {
|
|
214
|
-
"type": "object",
|
|
215
|
-
"additionalProperties": { "$ref": "#/$defs/node" }
|
|
216
|
-
},
|
|
217
|
-
"compare": { "type": "string" }
|
|
218
|
-
}
|
|
219
|
-
},
|
|
220
|
-
"consensus_config": {
|
|
221
|
-
"type": "object",
|
|
222
|
-
"required": [
|
|
223
|
-
"members",
|
|
224
|
-
"agree",
|
|
225
|
-
"max_rounds"
|
|
226
|
-
],
|
|
227
|
-
"properties": {
|
|
228
|
-
"members": {
|
|
229
|
-
"type": "object",
|
|
230
|
-
"additionalProperties": { "$ref": "#/$defs/node" }
|
|
231
|
-
},
|
|
232
|
-
"agree": { "type": "string" },
|
|
233
|
-
"max_rounds": {
|
|
234
|
-
"type": "integer",
|
|
235
|
-
"minimum": 1
|
|
236
|
-
}
|
|
237
|
-
}
|
|
238
|
-
},
|
|
239
|
-
"checkpoint_config": {
|
|
240
|
-
"type": "object",
|
|
241
|
-
"required": ["do", "key"],
|
|
242
|
-
"properties": {
|
|
243
|
-
"do": { "$ref": "#/$defs/node" },
|
|
244
|
-
"key": { "type": "string" }
|
|
245
|
-
}
|
|
246
|
-
},
|
|
247
|
-
"suspend_config": {
|
|
248
|
-
"type": "object",
|
|
249
|
-
"required": [
|
|
250
|
-
"id",
|
|
251
|
-
"on",
|
|
252
|
-
"resume_schema",
|
|
253
|
-
"combine"
|
|
254
|
-
],
|
|
255
|
-
"properties": {
|
|
256
|
-
"id": { "type": "string" },
|
|
257
|
-
"on": { "type": "string" },
|
|
258
|
-
"resume_schema": { "type": "string" },
|
|
259
|
-
"combine": { "type": "string" }
|
|
260
|
-
}
|
|
261
|
-
},
|
|
262
|
-
"scope_config": {
|
|
263
|
-
"type": "array",
|
|
264
|
-
"items": { "$ref": "#/$defs/scope_entry" }
|
|
265
|
-
},
|
|
266
|
-
"scope_entry": {
|
|
267
|
-
"type": "object",
|
|
268
|
-
"oneOf": [{
|
|
269
|
-
"type": "object",
|
|
270
|
-
"required": ["stash", "do"],
|
|
271
|
-
"properties": {
|
|
272
|
-
"stash": { "type": "string" },
|
|
273
|
-
"do": { "$ref": "#/$defs/node" }
|
|
274
|
-
}
|
|
275
|
-
}, {
|
|
276
|
-
"type": "object",
|
|
277
|
-
"required": ["use", "do"],
|
|
278
|
-
"properties": {
|
|
279
|
-
"use": {
|
|
280
|
-
"type": "array",
|
|
281
|
-
"items": { "type": "string" }
|
|
282
|
-
},
|
|
283
|
-
"do": { "$ref": "#/$defs/node" }
|
|
284
|
-
}
|
|
285
|
-
}]
|
|
286
|
-
},
|
|
287
|
-
"chain_config": {
|
|
288
|
-
"type": "object",
|
|
289
|
-
"required": ["steps", "output"],
|
|
290
|
-
"properties": {
|
|
291
|
-
"input": { "type": "string" },
|
|
292
|
-
"steps": {
|
|
293
|
-
"type": "array",
|
|
294
|
-
"items": { "$ref": "#/$defs/chain_entry" }
|
|
295
|
-
},
|
|
296
|
-
"output": { "type": "string" }
|
|
297
|
-
}
|
|
298
|
-
},
|
|
299
|
-
"chain_entry": {
|
|
300
|
-
"type": "object",
|
|
301
|
-
"oneOf": [{
|
|
302
|
-
"type": "object",
|
|
303
|
-
"required": ["step", "fn"],
|
|
304
|
-
"properties": {
|
|
305
|
-
"step": { "type": "string" },
|
|
306
|
-
"fn": { "type": "string" }
|
|
307
|
-
}
|
|
308
|
-
}, {
|
|
309
|
-
"type": "object",
|
|
310
|
-
"required": ["stage"],
|
|
311
|
-
"properties": {
|
|
312
|
-
"stage": { "type": "string" },
|
|
313
|
-
"project": { "type": "string" }
|
|
314
|
-
}
|
|
315
|
-
}]
|
|
316
|
-
}
|
|
317
|
-
}
|
|
318
|
-
};
|
|
319
|
-
//#endregion
|
|
320
2
|
//#region src/core/cleanup.ts
|
|
321
3
|
const HANDLER_TIMEOUT_MS = 5e3;
|
|
322
4
|
/**
|
|
@@ -388,6 +70,19 @@ async function run_one(fn, trajectory) {
|
|
|
388
70
|
}
|
|
389
71
|
}
|
|
390
72
|
//#endregion
|
|
73
|
+
//#region src/core/display_name.ts
|
|
74
|
+
/**
|
|
75
|
+
* Resolve the human-readable label for `node`, falling back to `fallback`
|
|
76
|
+
* (typically the step's kind) when neither display channel is populated.
|
|
77
|
+
*/
|
|
78
|
+
function resolve_display_name(node, fallback) {
|
|
79
|
+
const display = node.config?.["display_name"];
|
|
80
|
+
if (typeof display === "string" && display.length > 0) return display;
|
|
81
|
+
const name = node.meta?.name;
|
|
82
|
+
if (typeof name === "string" && name.length > 0) return name;
|
|
83
|
+
return fallback;
|
|
84
|
+
}
|
|
85
|
+
//#endregion
|
|
391
86
|
//#region src/core/errors.ts
|
|
392
87
|
var timeout_error = class extends Error {
|
|
393
88
|
kind = "timeout_error";
|
|
@@ -436,7 +131,7 @@ var aborted_error = class extends Error {
|
|
|
436
131
|
super(message);
|
|
437
132
|
this.name = "aborted_error";
|
|
438
133
|
if (metadata.reason !== void 0) this.reason = metadata.reason;
|
|
439
|
-
this.step_index = metadata.step_index
|
|
134
|
+
if (metadata.step_index !== void 0) this.step_index = metadata.step_index;
|
|
440
135
|
if (metadata.tool_call_in_flight !== void 0) this.tool_call_in_flight = metadata.tool_call_in_flight;
|
|
441
136
|
}
|
|
442
137
|
};
|
|
@@ -452,6 +147,23 @@ var aborted_error = class extends Error {
|
|
|
452
147
|
function is_control_flow_error(err) {
|
|
453
148
|
return err instanceof suspended_error || err instanceof aborted_error;
|
|
454
149
|
}
|
|
150
|
+
/**
|
|
151
|
+
* Read the step-id path off any error that crossed the runner's dispatch.
|
|
152
|
+
*
|
|
153
|
+
* The runner attaches `path` to whatever escapes a step, including
|
|
154
|
+
* user-thrown errors the declared class fields cannot type, so a catch block
|
|
155
|
+
* needs a narrowing read rather than a cast. Returns the ids only when the
|
|
156
|
+
* property is present and well-formed (an all-string array); anything else,
|
|
157
|
+
* including non-object inputs, is `undefined`.
|
|
158
|
+
*/
|
|
159
|
+
function error_path(err) {
|
|
160
|
+
if (err === null || typeof err !== "object") return void 0;
|
|
161
|
+
const path = Reflect.get(err, "path");
|
|
162
|
+
if (!Array.isArray(path)) return void 0;
|
|
163
|
+
const entries = path;
|
|
164
|
+
const ids = entries.filter((v) => typeof v === "string");
|
|
165
|
+
return ids.length === entries.length ? ids : void 0;
|
|
166
|
+
}
|
|
455
167
|
//#endregion
|
|
456
168
|
//#region src/core/streaming.ts
|
|
457
169
|
const STREAMING_HIGH_WATER_MARK = 1e4;
|
|
@@ -591,19 +303,6 @@ function register_kind(kind, fn) {
|
|
|
591
303
|
dispatch.set(kind, fn);
|
|
592
304
|
}
|
|
593
305
|
/**
|
|
594
|
-
* Resolve the trajectory span label for a step. Prefers a non-empty
|
|
595
|
-
* `display_name` from `flow.config`; otherwise falls back to the supplied
|
|
596
|
-
* default (typically the step's `kind`).
|
|
597
|
-
*
|
|
598
|
-
* Dispatch handlers use this so that any composer carrying a user-supplied
|
|
599
|
-
* `name` surfaces under that label in the trajectory, while unconfigured
|
|
600
|
-
* composers retain their kind-based label.
|
|
601
|
-
*/
|
|
602
|
-
function resolve_span_label(flow, fallback) {
|
|
603
|
-
const display = flow.config?.["display_name"];
|
|
604
|
-
return typeof display === "string" && display.length > 0 ? display : fallback;
|
|
605
|
-
}
|
|
606
|
-
/**
|
|
607
306
|
* Register the standard span-wrapping dispatch handler for a composer kind.
|
|
608
307
|
*
|
|
609
308
|
* Every composer wraps `flow.run` in a span identically; this centralizes that
|
|
@@ -615,7 +314,7 @@ function resolve_span_label(flow, fallback) {
|
|
|
615
314
|
*/
|
|
616
315
|
function register_traced_kind(kind) {
|
|
617
316
|
register_kind(kind, async (flow, input, ctx) => {
|
|
618
|
-
const label =
|
|
317
|
+
const label = resolve_display_name(flow, kind);
|
|
619
318
|
const span_meta = { id: flow.id };
|
|
620
319
|
if (ctx.parent_span_id !== void 0) span_meta["parent_span_id"] = ctx.parent_span_id;
|
|
621
320
|
const span_id = ctx.trajectory.start_span(label, span_meta);
|
|
@@ -630,12 +329,32 @@ function register_traced_kind(kind) {
|
|
|
630
329
|
} catch (err) {
|
|
631
330
|
ctx.trajectory.end_span(span_id, {
|
|
632
331
|
id: flow.id,
|
|
633
|
-
|
|
332
|
+
...error_meta(err)
|
|
634
333
|
});
|
|
635
334
|
throw err;
|
|
636
335
|
}
|
|
637
336
|
});
|
|
638
337
|
}
|
|
338
|
+
/**
|
|
339
|
+
* Project an escaping error onto trajectory meta fields.
|
|
340
|
+
*
|
|
341
|
+
* `error` is always present (the message); `error_name` and `error_kind`
|
|
342
|
+
* surface the class name and the `kind` discriminant the typed error classes
|
|
343
|
+
* carry, so a consumer can classify a failure without regex-matching the
|
|
344
|
+
* message. `error_path` is the chain of step ids the error crossed below this
|
|
345
|
+
* point, already accumulated on the error by `prepend_path` as it bubbled up.
|
|
346
|
+
*/
|
|
347
|
+
function error_meta(err) {
|
|
348
|
+
const meta = { error: err instanceof Error ? err.message : String(err) };
|
|
349
|
+
if (err instanceof Error && err.name.length > 0) meta["error_name"] = err.name;
|
|
350
|
+
if (err !== null && typeof err === "object") {
|
|
351
|
+
const kind = Reflect.get(err, "kind");
|
|
352
|
+
if (typeof kind === "string") meta["error_kind"] = kind;
|
|
353
|
+
const path = Reflect.get(err, "path");
|
|
354
|
+
if (Array.isArray(path)) meta["error_path"] = path.filter((v) => typeof v === "string");
|
|
355
|
+
}
|
|
356
|
+
return meta;
|
|
357
|
+
}
|
|
639
358
|
const active_runs = /* @__PURE__ */ new Set();
|
|
640
359
|
let signal_handler_installed = false;
|
|
641
360
|
let sigint_handler = null;
|
|
@@ -763,7 +482,7 @@ function throw_if_aborted(ctx) {
|
|
|
763
482
|
* Concurrent composers (`map`, `parallel`) use this to propagate a parent
|
|
764
483
|
* abort into each in-flight child's composed signal. `controllers` is read by
|
|
765
484
|
* reference, so a caller that appends to the array after installing (as
|
|
766
|
-
* `map` does per newly
|
|
485
|
+
* `map` does per newly started item) is still covered by later aborts.
|
|
767
486
|
* Returns the listener so the caller can remove it once its children settle.
|
|
768
487
|
*/
|
|
769
488
|
function install_abort_fan_out(ctx, controllers) {
|
|
@@ -848,19 +567,27 @@ function start_run(flow, input, options, high_water_mark) {
|
|
|
848
567
|
active_runs.add(controller);
|
|
849
568
|
if (install_signal_handlers) ensure_signal_handlers();
|
|
850
569
|
const result = (async () => {
|
|
570
|
+
let terminal = {
|
|
571
|
+
kind: "run_end",
|
|
572
|
+
status: "done"
|
|
573
|
+
};
|
|
851
574
|
try {
|
|
852
575
|
throw_if_aborted(ctx);
|
|
853
576
|
return await dispatch_step(flow, input, ctx);
|
|
854
577
|
} catch (err) {
|
|
578
|
+
let thrown = err;
|
|
855
579
|
if (controller.signal.aborted && !(err instanceof aborted_error)) {
|
|
856
580
|
const reason = controller.signal.reason;
|
|
857
|
-
if (reason instanceof aborted_error)
|
|
581
|
+
if (reason instanceof aborted_error) thrown = reason;
|
|
858
582
|
}
|
|
859
|
-
|
|
583
|
+
const was_aborted = thrown instanceof aborted_error || controller.signal.aborted && thrown === controller.signal.reason;
|
|
584
|
+
terminal = run_end_event(thrown, was_aborted);
|
|
585
|
+
throw thrown;
|
|
860
586
|
} finally {
|
|
861
587
|
try {
|
|
862
588
|
await cleanup.run_all();
|
|
863
589
|
} finally {
|
|
590
|
+
logger.record(terminal);
|
|
864
591
|
unlink_abort();
|
|
865
592
|
active_runs.delete(controller);
|
|
866
593
|
release_signal_handlers();
|
|
@@ -874,6 +601,30 @@ function start_run(flow, input, options, high_water_mark) {
|
|
|
874
601
|
};
|
|
875
602
|
}
|
|
876
603
|
/**
|
|
604
|
+
* Build the terminal `run_end` event for a run that did not complete.
|
|
605
|
+
*
|
|
606
|
+
* Control-flow endings get their own statuses (`aborted`, `suspended`) so a
|
|
607
|
+
* consumer never has to sniff error text to tell a cancellation or a pending
|
|
608
|
+
* approval from a real failure; only `failed` carries the full error meta.
|
|
609
|
+
*/
|
|
610
|
+
function run_end_event(err, was_aborted) {
|
|
611
|
+
if (err instanceof suspended_error) return {
|
|
612
|
+
kind: "run_end",
|
|
613
|
+
status: "suspended",
|
|
614
|
+
suspend_id: err.suspend_id
|
|
615
|
+
};
|
|
616
|
+
if (was_aborted) return {
|
|
617
|
+
kind: "run_end",
|
|
618
|
+
status: "aborted",
|
|
619
|
+
error: err instanceof Error ? err.message : String(err)
|
|
620
|
+
};
|
|
621
|
+
return {
|
|
622
|
+
kind: "run_end",
|
|
623
|
+
status: "failed",
|
|
624
|
+
...error_meta(err)
|
|
625
|
+
};
|
|
626
|
+
}
|
|
627
|
+
/**
|
|
877
628
|
* Build an async iterable that is immediately done.
|
|
878
629
|
*
|
|
879
630
|
* Non-streaming runs hand this to callers so the `events` field always has
|
|
@@ -909,8 +660,9 @@ function run_stream(flow, input, options = {}) {
|
|
|
909
660
|
* thrown `suspended_error`.
|
|
910
661
|
*
|
|
911
662
|
* Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
|
|
912
|
-
* fires, resolves `{ kind: 'suspended', id, resume }` where `id` is
|
|
913
|
-
* gate's suspend id
|
|
663
|
+
* fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
|
|
664
|
+
* the gate's suspend id, `payload` is what the gate raised on its
|
|
665
|
+
* `suspended_error`, and `resume(data)` re-runs the flow from the original
|
|
914
666
|
* input with `resume_data[id] = data` merged over the caller's options: the
|
|
915
667
|
* same full re-run semantics as calling `run` again yourself, so pure
|
|
916
668
|
* prefixes replay and `checkpoint`ed steps are served from the store. The
|
|
@@ -930,6 +682,7 @@ async function run_until_suspended(flow, input, options = {}) {
|
|
|
930
682
|
return {
|
|
931
683
|
kind: "suspended",
|
|
932
684
|
id,
|
|
685
|
+
payload: err.payload,
|
|
933
686
|
resume: (data) => run_until_suspended(flow, input, {
|
|
934
687
|
...options,
|
|
935
688
|
resume_data: {
|
|
@@ -954,36 +707,88 @@ const run = Object.assign(run_impl, {
|
|
|
954
707
|
until_suspended: run_until_suspended
|
|
955
708
|
});
|
|
956
709
|
//#endregion
|
|
710
|
+
//#region src/core/step_id.ts
|
|
711
|
+
/**
|
|
712
|
+
* Step id validation.
|
|
713
|
+
*
|
|
714
|
+
* Every id in the system is constrained to a valid JavaScript identifier
|
|
715
|
+
* rather than an arbitrary string, because ids are read back as property
|
|
716
|
+
* names: `chain` merges each binding into a typed record under its name, and
|
|
717
|
+
* a name you cannot destructure is a name the record cannot offer. Holding
|
|
718
|
+
* one rule across `step`, `chain`, and the agent surface means a user learns
|
|
719
|
+
* it once instead of discovering per-primitive exceptions.
|
|
720
|
+
*
|
|
721
|
+
* Prose is not constrained, because prose has its own channel: `meta.name`
|
|
722
|
+
* on a step, `name` on a chain binding or composer.
|
|
723
|
+
*
|
|
724
|
+
* Nothing normalizes an id on the caller's behalf. A silent transformation
|
|
725
|
+
* would map several distinct names onto one key ('my-id', 'my.id', and
|
|
726
|
+
* 'my_id' all reduce to 'my_id') and would have to stay bug-for-bug in sync
|
|
727
|
+
* with the equivalent type-level transformation. The suggestion in the
|
|
728
|
+
* failure message is a courtesy for the reader, never a contract.
|
|
729
|
+
*/
|
|
730
|
+
const IDENTIFIER = /^[\p{ID_Start}$_][\p{ID_Continue}$]*$/u;
|
|
731
|
+
/**
|
|
732
|
+
* Report whether `id` can be read back as a property name.
|
|
733
|
+
*/
|
|
734
|
+
function is_valid_step_id(id) {
|
|
735
|
+
return IDENTIFIER.test(id);
|
|
736
|
+
}
|
|
737
|
+
/**
|
|
738
|
+
* Render the closest identifier-shaped spelling of `raw`, for failure
|
|
739
|
+
* messages only. Prefixes an underscore when the swap alone still leaves an
|
|
740
|
+
* illegal leading character, so the suggestion is always usable as written.
|
|
741
|
+
*/
|
|
742
|
+
function suggest_step_id(raw) {
|
|
743
|
+
const swapped = raw.replace(/[^\p{ID_Continue}$]/gu, "_");
|
|
744
|
+
return IDENTIFIER.test(swapped) ? swapped : `_${swapped}`;
|
|
745
|
+
}
|
|
746
|
+
/**
|
|
747
|
+
* Throw when `id` is not identifier-shaped. `subject` names the failing
|
|
748
|
+
* surface so the message points at the call the reader actually wrote, and
|
|
749
|
+
* `remedy` says where the prose spelling belongs instead.
|
|
750
|
+
*/
|
|
751
|
+
function assert_valid_step_id(id, subject, remedy) {
|
|
752
|
+
if (is_valid_step_id(id)) return;
|
|
753
|
+
throw new TypeError(`${subject} ${JSON.stringify(id)} is not a valid identifier: ids are read back as property names, so use ${suggest_step_id(id)} and ${remedy}`);
|
|
754
|
+
}
|
|
755
|
+
//#endregion
|
|
957
756
|
//#region src/core/step.ts
|
|
958
757
|
/**
|
|
959
758
|
* step() factory.
|
|
960
759
|
*
|
|
961
760
|
* Three forms:
|
|
962
761
|
* step(id, fn): named step. id is rendered in trajectory spans and describe().
|
|
963
|
-
* step(id, fn, meta): named step
|
|
964
|
-
*
|
|
965
|
-
*
|
|
966
|
-
*
|
|
762
|
+
* step(id, fn, meta): named step carrying descriptive metadata. `meta.name` is the
|
|
763
|
+
* display channel: it labels the step's trajectory span and its
|
|
764
|
+
* describe() line, leaving the id free to stay a stable
|
|
765
|
+
* identifier. Nothing keys off it, so it is safe to reword.
|
|
766
|
+
* step(fn): anonymous step. id is `step_<counter>`; cannot be checkpointed.
|
|
967
767
|
*
|
|
968
768
|
* Anonymous steps carry an internal `anonymous: true` flag so checkpoint can
|
|
969
769
|
* reject them synchronously at flow construction time.
|
|
770
|
+
*
|
|
771
|
+
* An explicit id must be identifier-shaped: ids are read back as property
|
|
772
|
+
* names wherever a step's output is bound (see step_id.ts). Free prose goes
|
|
773
|
+
* in `meta.name`.
|
|
970
774
|
*/
|
|
971
|
-
let
|
|
775
|
+
let step_counter = 0;
|
|
972
776
|
/**
|
|
973
|
-
* Generate a unique id of the form `
|
|
777
|
+
* Generate a unique id of the form `step_<n>` for anonymous steps.
|
|
974
778
|
*/
|
|
975
|
-
function
|
|
976
|
-
|
|
977
|
-
return `
|
|
779
|
+
function next_step_id() {
|
|
780
|
+
step_counter += 1;
|
|
781
|
+
return `step_${step_counter}`;
|
|
978
782
|
}
|
|
979
783
|
function step(id_or_fn, maybe_fn, meta) {
|
|
980
784
|
if (typeof id_or_fn === "function") return {
|
|
981
|
-
id:
|
|
785
|
+
id: next_step_id(),
|
|
982
786
|
kind: "step",
|
|
983
787
|
run: id_or_fn,
|
|
984
788
|
anonymous: true
|
|
985
789
|
};
|
|
986
790
|
if (typeof maybe_fn !== "function") throw new TypeError("step(id, fn): fn must be a function");
|
|
791
|
+
assert_valid_step_id(id_or_fn, "step id", "put the label in meta.name");
|
|
987
792
|
if (meta) return {
|
|
988
793
|
id: id_or_fn,
|
|
989
794
|
kind: "step",
|
|
@@ -1067,9 +872,7 @@ function render_text(node, depth, lines, path, strict) {
|
|
|
1067
872
|
}
|
|
1068
873
|
path.add(node);
|
|
1069
874
|
try {
|
|
1070
|
-
|
|
1071
|
-
const label = typeof display === "string" && display.length > 0 ? display : node.kind;
|
|
1072
|
-
lines.push(`${prefix}${label}(${node.id})`);
|
|
875
|
+
lines.push(`${prefix}${resolve_display_name(node, node.kind)}(${node.id})`);
|
|
1073
876
|
if (node.config) for (const [key, value] of Object.entries(node.config)) {
|
|
1074
877
|
if (key === "display_name") continue;
|
|
1075
878
|
lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
|
|
@@ -1261,9 +1064,14 @@ function is_renderable_object(value) {
|
|
|
1261
1064
|
*
|
|
1262
1065
|
* For a literal tuple of children, every joint is checked at compile time:
|
|
1263
1066
|
* each child after the first must accept its predecessor's output, and a
|
|
1264
|
-
* mismatch
|
|
1265
|
-
*
|
|
1266
|
-
*
|
|
1067
|
+
* mismatch resolves the offending element to a branded SequenceJointMismatch
|
|
1068
|
+
* so the error names the joint and both types. A spread segment inside a
|
|
1069
|
+
* tuple (`sequence([first, ...mids, last])`) is checked as a homogeneous
|
|
1070
|
+
* self-composing segment rather than index-zipped, since its positions are
|
|
1071
|
+
* not statically known. Arrays built at runtime carry no positional types,
|
|
1072
|
+
* so they must be homogeneous `ReadonlyArray<Step<T, T>>` and produce a
|
|
1073
|
+
* `Step<T, T>`; heterogeneous runtime arrays are rejected rather than
|
|
1074
|
+
* silently degrading to `Step<unknown, unknown>`.
|
|
1267
1075
|
*/
|
|
1268
1076
|
let sequence_counter = 0;
|
|
1269
1077
|
/**
|
|
@@ -1273,19 +1081,8 @@ function next_id$10() {
|
|
|
1273
1081
|
sequence_counter += 1;
|
|
1274
1082
|
return `sequence_${sequence_counter}`;
|
|
1275
1083
|
}
|
|
1276
|
-
/**
|
|
1277
|
-
* Build a step that chains children, each feeding the next.
|
|
1278
|
-
*
|
|
1279
|
-
* The children parameter is checked joint by joint for literal tuples via
|
|
1280
|
-
* `CheckedChildren`; the intersection with the bare `children` parameter is
|
|
1281
|
-
* what lets inference read the precise tuple while the checked shape
|
|
1282
|
-
* constrains it. Validates every element up front so a non-Step (usually a
|
|
1283
|
-
* bare function) fails at construction with a pointed message rather than at
|
|
1284
|
-
* run time. Checks `ctx.abort` before each child so aborts land on step
|
|
1285
|
-
* boundaries.
|
|
1286
|
-
*/
|
|
1287
1084
|
function sequence(children, options) {
|
|
1288
|
-
if (!Array.isArray(children)) throw new TypeError(`sequence(children): children must be an array of Steps, got ${typeof children} — sequence takes a single array, e.g
|
|
1085
|
+
if (!Array.isArray(children)) throw new TypeError(`sequence(children): children must be an array of Steps, got ${typeof children} — sequence takes a single array, e.g., sequence([a, b, c])`);
|
|
1289
1086
|
children.forEach((child, index) => {
|
|
1290
1087
|
if (is_step(child)) return;
|
|
1291
1088
|
throw new TypeError(`sequence(children): children[${index}] is not a Step, got ${typeof child}${typeof child === "function" ? " — wrap plain functions with step(fn), or use pipe(inner, fn) to transform output" : ""}`);
|
|
@@ -1721,6 +1518,7 @@ function to_abort_error(reason) {
|
|
|
1721
1518
|
* control-flow signals propagate untouched.
|
|
1722
1519
|
*/
|
|
1723
1520
|
function retry(inner, config) {
|
|
1521
|
+
if (!Number.isFinite(config.max_attempts)) throw new TypeError(`retry: max_attempts must be a finite number, got ${config.max_attempts}`);
|
|
1724
1522
|
const id = next_id$5();
|
|
1725
1523
|
const max_attempts = Math.max(1, Math.floor(config.max_attempts));
|
|
1726
1524
|
const backoff_ms = config.backoff_ms ?? DEFAULT_BACKOFF_MS;
|
|
@@ -1746,7 +1544,7 @@ function retry(inner, config) {
|
|
|
1746
1544
|
await wait_with_abort(compute_backoff(backoff_policy, attempt - 1), ctx.abort, to_abort_error);
|
|
1747
1545
|
}
|
|
1748
1546
|
}
|
|
1749
|
-
throw last_err;
|
|
1547
|
+
throw last_err ?? /* @__PURE__ */ new Error("retry: no attempts executed");
|
|
1750
1548
|
};
|
|
1751
1549
|
const config_meta = {
|
|
1752
1550
|
max_attempts,
|
|
@@ -1773,7 +1571,9 @@ register_traced_kind("retry");
|
|
|
1773
1571
|
* `fallback(primary, backup)` runs `primary`. If it throws an application
|
|
1774
1572
|
* error, runs `backup` with the same input, or with `handoff(input, err)`
|
|
1775
1573
|
* when the `handoff` option is set, so the backup can be told why it is
|
|
1776
|
-
* running. If `backup` also throws, the `backup` error propagates
|
|
1574
|
+
* running. If `backup` also throws, the `backup` error propagates with the
|
|
1575
|
+
* primary's error attached as its `cause` (unless it already carries one),
|
|
1576
|
+
* so the original failure stays diagnosable from the escaping error.
|
|
1777
1577
|
* Control-flow signals (`suspended_error`, `aborted_error`) are not
|
|
1778
1578
|
* failures: they propagate instead of triggering the backup, so a
|
|
1779
1579
|
* human-approval gate is never silently bypassed and the backup never runs
|
|
@@ -1802,7 +1602,13 @@ function fallback(primary, backup, options) {
|
|
|
1802
1602
|
return await dispatch_step(primary, input, ctx);
|
|
1803
1603
|
} catch (err) {
|
|
1804
1604
|
if (is_control_flow_error(err)) throw err;
|
|
1805
|
-
|
|
1605
|
+
const backup_input = handoff === void 0 ? input : handoff(input, err);
|
|
1606
|
+
try {
|
|
1607
|
+
return await dispatch_step(backup, backup_input, ctx);
|
|
1608
|
+
} catch (backup_err) {
|
|
1609
|
+
if (!is_control_flow_error(backup_err) && backup_err instanceof Error && !("cause" in backup_err)) backup_err.cause = err;
|
|
1610
|
+
throw backup_err;
|
|
1611
|
+
}
|
|
1806
1612
|
}
|
|
1807
1613
|
};
|
|
1808
1614
|
const config_meta = options?.name === void 0 ? void 0 : { display_name: options.name };
|
|
@@ -1900,7 +1706,9 @@ register_traced_kind("timeout");
|
|
|
1900
1706
|
* `loop({ init, body, guard?, finish, max_rounds, name? })` runs `body` up to
|
|
1901
1707
|
* `max_rounds` times, threading `state` through each iteration. After every
|
|
1902
1708
|
* `body` call, an optional `guard` step inspects (and may transform) the state
|
|
1903
|
-
* and decides whether to stop
|
|
1709
|
+
* and decides whether to stop; a bare `(state) => boolean` predicate is
|
|
1710
|
+
* accepted as shorthand for a guard that stops without transforming.
|
|
1711
|
+
* When `guard.stop` is true, the loop exits
|
|
1904
1712
|
* "converged"; otherwise it continues until `max_rounds`. `finish` projects
|
|
1905
1713
|
* the final state to the loop's output value, and is the loop's only output
|
|
1906
1714
|
* channel: `loop` returns `Step<i, o>`, not an envelope around `o`.
|
|
@@ -1918,11 +1726,31 @@ register_traced_kind("timeout");
|
|
|
1918
1726
|
*/
|
|
1919
1727
|
let loop_counter = 0;
|
|
1920
1728
|
/**
|
|
1921
|
-
* Generate a unique step id
|
|
1729
|
+
* Generate a unique step id of the form `loop_<n>`.
|
|
1730
|
+
*
|
|
1731
|
+
* The display `name` deliberately stays out of the id. It is free prose, so
|
|
1732
|
+
* folding it in would both make a cosmetic rename move a trajectory id and
|
|
1733
|
+
* put an arbitrary string where an identifier is required.
|
|
1922
1734
|
*/
|
|
1923
|
-
function next_id$2(
|
|
1735
|
+
function next_id$2() {
|
|
1924
1736
|
loop_counter += 1;
|
|
1925
|
-
return
|
|
1737
|
+
return `loop_${loop_counter}`;
|
|
1738
|
+
}
|
|
1739
|
+
/**
|
|
1740
|
+
* Normalize the guard config to its step form.
|
|
1741
|
+
*
|
|
1742
|
+
* A bare predicate is sugar for the state-preserving guard step, wrapped here
|
|
1743
|
+
* (with an id derived from the loop's, so trees with several loops stay
|
|
1744
|
+
* unambiguous) rather than special-cased in the run loop: the predicate form
|
|
1745
|
+
* then dispatches, traces, and terminates identically to a hand-written guard.
|
|
1746
|
+
*/
|
|
1747
|
+
function wrap_guard(guard, loop_id) {
|
|
1748
|
+
if (guard === void 0) return void 0;
|
|
1749
|
+
if (typeof guard !== "function") return guard;
|
|
1750
|
+
return step(`${loop_id}_guard`, async (state) => ({
|
|
1751
|
+
stop: await guard(state),
|
|
1752
|
+
state
|
|
1753
|
+
}));
|
|
1926
1754
|
}
|
|
1927
1755
|
/**
|
|
1928
1756
|
* Build a bounded iteration step with carry-state.
|
|
@@ -1934,9 +1762,10 @@ function next_id$2(name) {
|
|
|
1934
1762
|
* its output.
|
|
1935
1763
|
*/
|
|
1936
1764
|
function loop(config) {
|
|
1937
|
-
const { init, body,
|
|
1765
|
+
const { init, body, finish, name } = config;
|
|
1938
1766
|
const rounds_limit = Math.max(1, Math.floor(config.max_rounds));
|
|
1939
|
-
const id = next_id$2(
|
|
1767
|
+
const id = next_id$2();
|
|
1768
|
+
const guard = wrap_guard(config.guard, id);
|
|
1940
1769
|
const run_fn = async (input, ctx) => {
|
|
1941
1770
|
let state = init(input);
|
|
1942
1771
|
let round = 0;
|
|
@@ -1976,37 +1805,40 @@ register_traced_kind("loop");
|
|
|
1976
1805
|
/**
|
|
1977
1806
|
* compose: name a composite step.
|
|
1978
1807
|
*
|
|
1979
|
-
* `compose(
|
|
1980
|
-
* `name`. The inner step's own span (
|
|
1981
|
-
* the compose span: the implementation tree is preserved while
|
|
1982
|
-
* intent ("this whole thing is an ensemble") is surfaced in
|
|
1808
|
+
* `compose(inner, { name })` wraps any step and labels its trajectory span
|
|
1809
|
+
* with `name`. The inner step's own span (for example, a `sequence`) appears
|
|
1810
|
+
* as a child of the compose span: the implementation tree is preserved while
|
|
1811
|
+
* the user's intent ("this whole thing is an ensemble") is surfaced in
|
|
1812
|
+
* observability.
|
|
1983
1813
|
*
|
|
1984
1814
|
* Used by the composites package to make built-in patterns appear under
|
|
1985
1815
|
* their familiar names, and available to library consumers who want their own
|
|
1986
1816
|
* named composites to show up in logs as first-class components.
|
|
1987
1817
|
*
|
|
1988
|
-
* The primitive's `kind` is always `'compose'
|
|
1989
|
-
* in `config.display_name
|
|
1818
|
+
* The primitive's `kind` is always `'compose'` and its id is `compose_<n>`.
|
|
1819
|
+
* The user-supplied label lives in `config.display_name`, is the span name
|
|
1820
|
+
* the dispatcher opens, and never reaches the id: it is free prose, so
|
|
1821
|
+
* folding it in would let a cosmetic rename move a trajectory id.
|
|
1990
1822
|
*/
|
|
1991
1823
|
let compose_counter = 0;
|
|
1992
1824
|
/**
|
|
1993
|
-
* Generate a unique step id of the form
|
|
1994
|
-
* label so compose ids read naturally in traces.
|
|
1825
|
+
* Generate a unique step id of the form `compose_<n>`.
|
|
1995
1826
|
*/
|
|
1996
|
-
function next_id$1(
|
|
1827
|
+
function next_id$1() {
|
|
1997
1828
|
compose_counter += 1;
|
|
1998
|
-
return
|
|
1829
|
+
return `compose_${compose_counter}`;
|
|
1999
1830
|
}
|
|
2000
1831
|
/**
|
|
2001
1832
|
* Wrap `inner` in a named composite step.
|
|
2002
1833
|
*
|
|
2003
|
-
* The step's `kind` is always `'compose'`; `name` becomes the
|
|
1834
|
+
* The step's `kind` is always `'compose'`; `config.name` becomes the
|
|
2004
1835
|
* `display_name` used as the span label. Throws a `TypeError` when `name`
|
|
2005
1836
|
* is not a non-empty string, catching the mistake at construction time.
|
|
2006
1837
|
*/
|
|
2007
|
-
function compose(
|
|
2008
|
-
|
|
2009
|
-
|
|
1838
|
+
function compose(inner, config) {
|
|
1839
|
+
const name = config?.name;
|
|
1840
|
+
if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(inner, { name }): name must be a non-empty string");
|
|
1841
|
+
const id = next_id$1();
|
|
2010
1842
|
const run_fn = (input, ctx) => dispatch_step(inner, input, ctx);
|
|
2011
1843
|
return {
|
|
2012
1844
|
id,
|
|
@@ -2025,10 +1857,12 @@ register_traced_kind("compose");
|
|
|
2025
1857
|
* `checkpoint(inner, { key })` checks a persistent store for a completed
|
|
2026
1858
|
* result at `key` before running `inner`. On a hit, returns the stored
|
|
2027
1859
|
* value. On a miss, runs `inner`, persists its result at `key`, and returns
|
|
2028
|
-
* it. Corrupted reads (store throws on `get`) are treated as a miss.
|
|
1860
|
+
* it. Corrupted reads (store throws on `get`) are treated as a miss. Every
|
|
1861
|
+
* lookup records a `checkpoint` trajectory event with
|
|
1862
|
+
* `status: 'hit' | 'miss' | 'read_error'`.
|
|
2029
1863
|
*
|
|
2030
1864
|
* Wrapping an anonymous inner step throws synchronously at construction time
|
|
2031
|
-
* with the message `checkpoint requires a named step
|
|
1865
|
+
* with the message `checkpoint requires a named step, got anonymous`, because
|
|
2032
1866
|
* a cached result must map back to a stable, identifiable step.
|
|
2033
1867
|
*/
|
|
2034
1868
|
let checkpoint_counter = 0;
|
|
@@ -2049,7 +1883,7 @@ function next_id() {
|
|
|
2049
1883
|
* is anonymous.
|
|
2050
1884
|
*/
|
|
2051
1885
|
function checkpoint(inner, config) {
|
|
2052
|
-
if (inner.anonymous === true) throw new Error("checkpoint requires a named step
|
|
1886
|
+
if (inner.anonymous === true) throw new Error("checkpoint requires a named step, got anonymous — give the inner step an id with step('id', fn)");
|
|
2053
1887
|
const id = next_id();
|
|
2054
1888
|
const key_spec = config.key;
|
|
2055
1889
|
const run_fn = async (input, ctx) => {
|
|
@@ -2058,11 +1892,27 @@ function checkpoint(inner, config) {
|
|
|
2058
1892
|
if (store) {
|
|
2059
1893
|
let cached = void 0;
|
|
2060
1894
|
let hit = false;
|
|
1895
|
+
const lookup_meta = {
|
|
1896
|
+
id,
|
|
1897
|
+
key
|
|
1898
|
+
};
|
|
1899
|
+
if (ctx.parent_span_id !== void 0) lookup_meta["span_id"] = ctx.parent_span_id;
|
|
2061
1900
|
try {
|
|
2062
1901
|
cached = await store.get(key);
|
|
2063
1902
|
hit = cached !== null && cached !== void 0;
|
|
2064
|
-
|
|
1903
|
+
ctx.trajectory.record({
|
|
1904
|
+
kind: "checkpoint",
|
|
1905
|
+
status: hit ? "hit" : "miss",
|
|
1906
|
+
...lookup_meta
|
|
1907
|
+
});
|
|
1908
|
+
} catch (err) {
|
|
2065
1909
|
hit = false;
|
|
1910
|
+
ctx.trajectory.record({
|
|
1911
|
+
kind: "checkpoint",
|
|
1912
|
+
status: "read_error",
|
|
1913
|
+
error: err instanceof Error ? err.message : String(err),
|
|
1914
|
+
...lookup_meta
|
|
1915
|
+
});
|
|
2066
1916
|
}
|
|
2067
1917
|
if (hit) return cached;
|
|
2068
1918
|
}
|
|
@@ -2088,7 +1938,7 @@ register_traced_kind("checkpoint");
|
|
|
2088
1938
|
*
|
|
2089
1939
|
* Always async, even for a validator that answers synchronously: the spec
|
|
2090
1940
|
* permits `validate` to return either a result or a promise of one, and
|
|
2091
|
-
*
|
|
1941
|
+
* Fascicle cannot know which a given vendor does. Awaiting a non-promise is
|
|
2092
1942
|
* cheap; guessing wrong is a silent bug.
|
|
2093
1943
|
*/
|
|
2094
1944
|
async function validate_schema(schema, value) {
|
|
@@ -2103,7 +1953,7 @@ async function validate_schema(schema, value) {
|
|
|
2103
1953
|
};
|
|
2104
1954
|
}
|
|
2105
1955
|
/**
|
|
2106
|
-
* Flatten one vendor issue into
|
|
1956
|
+
* Flatten one vendor issue into Fascicle's shape.
|
|
2107
1957
|
*
|
|
2108
1958
|
* The spec allows a path segment to be a bare key or a `{ key }` wrapper, and
|
|
2109
1959
|
* allows the path to be absent entirely. Normalizing here means no consumer has
|
|
@@ -2325,21 +2175,26 @@ register_traced_kind("use");
|
|
|
2325
2175
|
* chain: named steps over a growing record.
|
|
2326
2176
|
*
|
|
2327
2177
|
* `chain<i>(input_name?)` opens a builder whose threaded value is a record of
|
|
2328
|
-
* named outputs rather than a single value.
|
|
2329
|
-
* the
|
|
2330
|
-
*
|
|
2331
|
-
*
|
|
2332
|
-
*
|
|
2333
|
-
*
|
|
2178
|
+
* named outputs rather than a single value. The input type must be stated,
|
|
2179
|
+
* either as the type argument or via `.input<t>()` on the freshly opened
|
|
2180
|
+
* chain; an unannotated `chain()` defaults to `never` so the omission fails
|
|
2181
|
+
* at the `run` call site instead of accepting anything. `.step(name, fn)`
|
|
2182
|
+
* runs `fn` over the record and merges its output back in under `name`;
|
|
2183
|
+
* `.stage(name, project?)` concludes a phase: it opens a grouping span in
|
|
2184
|
+
* the trajectory and, when `project` is given, replaces the record with the
|
|
2185
|
+
* projection so earlier bindings go out of scope; `.output(fn)` closes the
|
|
2186
|
+
* builder and returns an ordinary `Step<i, o>`.
|
|
2334
2187
|
*
|
|
2335
2188
|
* Each `.step` entry is a regular `step(name, fn)` whose input happens to be
|
|
2336
2189
|
* the record, so anything true of steps (spans, error paths, abort checks
|
|
2337
2190
|
* between entries) is true of chain entries, and the binding name doubles as
|
|
2338
|
-
* the entry's id in trajectories.
|
|
2339
|
-
*
|
|
2340
|
-
*
|
|
2341
|
-
* binding's child so `describe` renders
|
|
2342
|
-
*
|
|
2191
|
+
* the entry's id in trajectories. A binding whose whole job is to invoke an
|
|
2192
|
+
* arm is `.step(name, arm, select)`: the chain projects the record through
|
|
2193
|
+
* `select`, dispatches the arm via `ctx.call`, and records it as the
|
|
2194
|
+
* binding's child, so what `describe` renders and what runs cannot diverge.
|
|
2195
|
+
* The escape hatch for bodies that need code around the call is
|
|
2196
|
+
* `.step(name, fn, { arm })`: the body does its own `ctx.call` and the arm
|
|
2197
|
+
* is metadata only, recorded for `describe` but never dispatched.
|
|
2343
2198
|
*
|
|
2344
2199
|
* Builder values are immutable: every method returns a new chain, so a
|
|
2345
2200
|
* prefix can be shared and extended in different directions safely.
|
|
@@ -2425,6 +2280,43 @@ function build_chain(input_name, entries, output_node) {
|
|
|
2425
2280
|
};
|
|
2426
2281
|
}
|
|
2427
2282
|
/**
|
|
2283
|
+
* Project a binding's options onto `step`'s trailing metadata argument.
|
|
2284
|
+
*
|
|
2285
|
+
* Returned as a spreadable tuple so a binding with no label calls `step`
|
|
2286
|
+
* with two arguments, leaving `meta` genuinely absent rather than set to an
|
|
2287
|
+
* empty object that `describe` would then echo.
|
|
2288
|
+
*/
|
|
2289
|
+
function binding_meta(options) {
|
|
2290
|
+
return options?.name === void 0 ? [] : [{ name: options.name }];
|
|
2291
|
+
}
|
|
2292
|
+
/**
|
|
2293
|
+
* Build the binding node for the arm-first `.step(name, arm, select)` form.
|
|
2294
|
+
*
|
|
2295
|
+
* The chain owns the dispatch: the synthesized body projects the record
|
|
2296
|
+
* through `select` and hands the result to the arm via `ctx.call`, and the
|
|
2297
|
+
* same arm is recorded as the binding's child, so the subtree `describe`
|
|
2298
|
+
* renders and the step that runs are one value by construction.
|
|
2299
|
+
*/
|
|
2300
|
+
function arm_node(name, arm, select, options) {
|
|
2301
|
+
if (typeof select !== "function") throw new TypeError("chain.step(name, arm, select): select must be a function");
|
|
2302
|
+
return {
|
|
2303
|
+
...step(name, (s, ctx) => ctx.call(arm, select(s)), ...binding_meta(options)),
|
|
2304
|
+
children: [arm]
|
|
2305
|
+
};
|
|
2306
|
+
}
|
|
2307
|
+
/**
|
|
2308
|
+
* Build the binding node for the body form `.step(name, fn, { arm? })`.
|
|
2309
|
+
*/
|
|
2310
|
+
function body_node(name, fn, options) {
|
|
2311
|
+
const settings = typeof options === "function" ? void 0 : options;
|
|
2312
|
+
const base = step(name, fn, ...binding_meta(settings));
|
|
2313
|
+
const arm = settings?.arm;
|
|
2314
|
+
return arm === void 0 ? base : {
|
|
2315
|
+
...base,
|
|
2316
|
+
children: [arm]
|
|
2317
|
+
};
|
|
2318
|
+
}
|
|
2319
|
+
/**
|
|
2428
2320
|
* Internal untyped builder behind `chain`.
|
|
2429
2321
|
*
|
|
2430
2322
|
* `bound` holds the binding names of the current stage segment so duplicate
|
|
@@ -2434,13 +2326,10 @@ function build_chain(input_name, entries, output_node) {
|
|
|
2434
2326
|
*/
|
|
2435
2327
|
function make_chain(input_name, entries, bound) {
|
|
2436
2328
|
return {
|
|
2437
|
-
step: (name,
|
|
2329
|
+
step: (name, fn_or_arm, options_or_select, arm_options) => {
|
|
2330
|
+
assert_valid_step_id(name, "chain.step: binding name", "put the label in the options object as { name }");
|
|
2438
2331
|
if (bound.has(name)) throw new TypeError(`chain.step: binding '${name}' is already defined in this stage; names are single-assignment`);
|
|
2439
|
-
const
|
|
2440
|
-
const node = options?.arm === void 0 ? base : {
|
|
2441
|
-
...base,
|
|
2442
|
-
children: [options.arm]
|
|
2443
|
-
};
|
|
2332
|
+
const node = is_step(fn_or_arm) ? arm_node(name, fn_or_arm, options_or_select, arm_options) : body_node(name, fn_or_arm, options_or_select);
|
|
2444
2333
|
return make_chain(input_name, [...entries, {
|
|
2445
2334
|
kind: "step",
|
|
2446
2335
|
name,
|
|
@@ -2461,101 +2350,25 @@ function make_chain(input_name, entries, bound) {
|
|
|
2461
2350
|
/**
|
|
2462
2351
|
* Open a chain builder whose record starts as `{ [input_name]: input }`.
|
|
2463
2352
|
*
|
|
2464
|
-
* `input_name` defaults to `'input'`. The
|
|
2465
|
-
*
|
|
2353
|
+
* `input_name` defaults to `'input'`. The input type defaults to `never`, so
|
|
2354
|
+
* a chain that never states it produces a `Step<never, o>` that no real
|
|
2355
|
+
* input satisfies at `run`; state it as the type argument or, when the
|
|
2356
|
+
* binding is renamed, once via `.input<t>()` on the fresh builder. Each
|
|
2357
|
+
* `.step` narrows subsequent callbacks to the record accumulated so far, and
|
|
2466
2358
|
* `.stage` with a projection re-types the record to the projection's
|
|
2467
2359
|
* return, so binding names and views are checked at compile time with no
|
|
2468
2360
|
* declared state shape.
|
|
2469
2361
|
*/
|
|
2470
2362
|
function chain(input_name) {
|
|
2471
2363
|
const name = input_name ?? "input";
|
|
2472
|
-
|
|
2473
|
-
|
|
2474
|
-
register_traced_kind("chain");
|
|
2475
|
-
//#endregion
|
|
2476
|
-
//#region src/core/step_kinds.ts
|
|
2477
|
-
/**
|
|
2478
|
-
* Closed registry of every `Step.kind` produced by the composition layer.
|
|
2479
|
-
*
|
|
2480
|
-
* Studio (and any other consumer that needs to enumerate primitives: palette,
|
|
2481
|
-
* docs, code generation) can rely on this being the exhaustive set. New
|
|
2482
|
-
* primitives must add their kind here. The `step_kinds_cover_runner` contract
|
|
2483
|
-
* test in `step_kinds.test.ts` asserts every dispatch handler corresponds to a
|
|
2484
|
-
* kind listed here.
|
|
2485
|
-
*/
|
|
2486
|
-
const STEP_KINDS = [
|
|
2487
|
-
"step",
|
|
2488
|
-
"sequence",
|
|
2489
|
-
"parallel",
|
|
2490
|
-
"branch",
|
|
2491
|
-
"map",
|
|
2492
|
-
"pipe",
|
|
2493
|
-
"retry",
|
|
2494
|
-
"fallback",
|
|
2495
|
-
"timeout",
|
|
2496
|
-
"loop",
|
|
2497
|
-
"compose",
|
|
2498
|
-
"adversarial",
|
|
2499
|
-
"ensemble",
|
|
2500
|
-
"tournament",
|
|
2501
|
-
"consensus",
|
|
2502
|
-
"checkpoint",
|
|
2503
|
-
"suspend",
|
|
2504
|
-
"scope",
|
|
2505
|
-
"stash",
|
|
2506
|
-
"use",
|
|
2507
|
-
"chain"
|
|
2508
|
-
];
|
|
2509
|
-
/**
|
|
2510
|
-
* Check whether a value is one of the registered `Step.kind` strings.
|
|
2511
|
-
*/
|
|
2512
|
-
function is_step_kind(value) {
|
|
2513
|
-
return typeof value === "string" && STEP_KINDS.includes(value);
|
|
2514
|
-
}
|
|
2515
|
-
//#endregion
|
|
2516
|
-
//#region src/core/trajectory.ts
|
|
2517
|
-
/**
|
|
2518
|
-
* The wire gate: a non-array object carrying a string `kind`.
|
|
2519
|
-
*
|
|
2520
|
-
* True for every well-known kind as well, since `custom` is the fallback shape
|
|
2521
|
-
* rather than a disjoint case.
|
|
2522
|
-
*/
|
|
2523
|
-
function is_custom_trajectory_event(value) {
|
|
2524
|
-
if (typeof value !== "object" || value === null) return false;
|
|
2525
|
-
if (Array.isArray(value)) return false;
|
|
2526
|
-
return typeof value.kind === "string";
|
|
2527
|
-
}
|
|
2528
|
-
/** A composer span open: both `span_id` and `name` must be present as strings. */
|
|
2529
|
-
function is_span_start_event(value) {
|
|
2530
|
-
if (!is_custom_trajectory_event(value)) return false;
|
|
2531
|
-
if (value.kind !== "span_start") return false;
|
|
2532
|
-
return typeof value["span_id"] === "string" && typeof value["name"] === "string";
|
|
2533
|
-
}
|
|
2534
|
-
/** A composer span close: `span_id` must be present as a string, `name` need not be. */
|
|
2535
|
-
function is_span_end_event(value) {
|
|
2536
|
-
if (!is_custom_trajectory_event(value)) return false;
|
|
2537
|
-
return value.kind === "span_end" && typeof value["span_id"] === "string";
|
|
2538
|
-
}
|
|
2539
|
-
/** A `ctx.emit` event: the kind alone identifies it, the payload is the caller's. */
|
|
2540
|
-
function is_emit_event(value) {
|
|
2541
|
-
return is_custom_trajectory_event(value) && value.kind === "emit";
|
|
2542
|
-
}
|
|
2543
|
-
/**
|
|
2544
|
-
* Parse one wire value into a trajectory event, `safeParse`-shaped.
|
|
2545
|
-
*
|
|
2546
|
-
* On success `data` is the value itself, not a copy, so nothing on the line is
|
|
2547
|
-
* dropped or reordered on the way through.
|
|
2548
|
-
*/
|
|
2549
|
-
function parse_trajectory_event(value) {
|
|
2550
|
-
if (!is_custom_trajectory_event(value)) return {
|
|
2551
|
-
success: false,
|
|
2552
|
-
error: /* @__PURE__ */ new Error("not a trajectory event: expected an object with a string 'kind'")
|
|
2553
|
-
};
|
|
2364
|
+
assert_valid_step_id(name, "chain: input name", "rename the binding");
|
|
2365
|
+
const open = make_chain(name, [], /* @__PURE__ */ new Set([name]));
|
|
2554
2366
|
return {
|
|
2555
|
-
|
|
2556
|
-
|
|
2367
|
+
...open,
|
|
2368
|
+
input: () => open
|
|
2557
2369
|
};
|
|
2558
2370
|
}
|
|
2371
|
+
register_traced_kind("chain");
|
|
2559
2372
|
//#endregion
|
|
2560
2373
|
//#region src/core/index.ts
|
|
2561
2374
|
/**
|
|
@@ -2568,6 +2381,6 @@ function parse_trajectory_event(value) {
|
|
|
2568
2381
|
* and surface through the umbrella package.
|
|
2569
2382
|
*/
|
|
2570
2383
|
//#endregion
|
|
2571
|
-
export {
|
|
2384
|
+
export { error_path as A, step as C, run as D, suggest_step_id as E, suspended_error as M, timeout_error as N, aborted_error as O, resolve_display_name as P, is_step as S, is_valid_step_id as T, map as _, suspend as a, sequence as b, checkpoint as c, timeout as d, fallback as f, pipe as g, wait_with_abort as h, use as i, resume_validation_error as j, describe_cycle_error as k, compose as l, compute_backoff as m, scope as n, format_schema_issues as o, retry as p, stash as r, validate_schema as s, chain as t, loop as u, branch as v, assert_valid_step_id as w, describe as x, parallel as y };
|
|
2572
2385
|
|
|
2573
|
-
//# sourceMappingURL=core-
|
|
2386
|
+
//# sourceMappingURL=core-DdJEhyQc.js.map
|