fascicle 0.12.5 → 0.12.7
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 +26 -0
- package/dist/agents.js +1 -1
- package/dist/{core-DdJEhyQc.js → core-CFdEjtiT.js} +281 -270
- package/dist/core-CFdEjtiT.js.map +1 -0
- package/dist/{engine-CdXegeqC.js → engine-DQiQHiy8.js} +23 -13
- package/dist/{engine-CdXegeqC.js.map → engine-DQiQHiy8.js.map} +1 -1
- package/dist/index.js +3 -3
- package/dist/{invoke-CH_eJZeS.js → invoke-eEYMZmWg.js} +3 -3
- package/dist/{invoke-CH_eJZeS.js.map → invoke-eEYMZmWg.js.map} +1 -1
- package/dist/{leading_system-BUCT-PwD.js → leading_system-DQmlA6Fs.js} +2 -2
- package/dist/{leading_system-BUCT-PwD.js.map → leading_system-DQmlA6Fs.js.map} +1 -1
- package/dist/mcp.js +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.js +3 -3
- package/dist/viewer-app/assets/index-BGb1-MwM.js +2 -0
- package/dist/viewer-app/assets/index-D7kvKs40.css +1 -0
- package/dist/viewer-app/fonts/sora-OFL.txt +93 -0
- package/dist/viewer-app/fonts/sora-latin.woff2 +0 -0
- package/dist/viewer-app/fonts/spline-sans-mono-OFL.txt +93 -0
- package/dist/viewer-app/fonts/spline-sans-mono-latin.woff2 +0 -0
- package/dist/viewer-app/index.html +13 -0
- package/dist/viewer.d.ts +17 -3
- package/dist/viewer.js +210 -50
- package/dist/viewer.js.map +1 -1
- package/package.json +9 -2
- package/dist/core-DdJEhyQc.js.map +0 -1
- package/dist/static/viewer.html +0 -375
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.12.7 — 2026-09-01
|
|
4
|
+
|
|
5
|
+
Everything in v0.12.6 ships here for the first time: that version was tagged but never reached npm, because its publish run failed on the gate described below. Upgrading from v0.12.5 picks up both sections.
|
|
6
|
+
|
|
7
|
+
### Internal
|
|
8
|
+
|
|
9
|
+
- **The release gate reads the release notes now.** The v0.12.6 changelog entry carried a sentence with two semicolons, which the `prose` slot rejects (vale's `Repo.Semicolon` rule). The narrow check the release skill runs before tagging covered `docs`, `links`, and `spell` only, so the sentence passed locally and then failed inside `publish.yaml`, stranding the tag on a commit that could never pass. The sentence is split in two, and the pre-tag gate now runs `prose` and `prose-health` as well, because vale reads `CHANGELOG.md` like any other markdown.
|
|
10
|
+
|
|
11
|
+
## v0.12.6 — 2026-09-01
|
|
12
|
+
|
|
13
|
+
### Changed
|
|
14
|
+
|
|
15
|
+
- **The viewer draws a run canvas now.** The one static HTML page is replaced by a compiled Solid app that ships prebuilt inside the package, so running the viewer is still one command with nothing to build. The canvas is structure first: it computes a metro-line layout from the flow's `describe.json` tree and draws the whole composition dim and dashed before a single step runs, then the run moves through that geometry as amber light. Retry draws as a loop in the line, fallback as a bypass basin that reroutes when the primary fails, a terminal failure as a scarred puck, and map instances as perpendicular ticks that become a ruler comb at scale, with suspended, emitting, and annotation states carrying their own card treatments. Two properties are load-bearing and gated by `pnpm check:all`: the runtime dependency list stays empty, and the bundle is offline (vendored fonts, no CDN, no telemetry).
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **Every run scrubs.** Canvas state is a pure fold of events up to a time, and live mode is that fold pinned to the newest event, so replay is the same fold stopped earlier rather than a second render path. A time spine along the bottom margin carries the playhead. Scrub off the live edge and the LIVE chip becomes REPLAY with a `RETURN TO LIVE` control. Arrow keys step one event, shifted arrows step one second, and Home and End jump to T+0 and the live edge. The server grew `GET /api/trajectory`, which streams the full run history as NDJSON so the client folds the whole run on load and follows SSE from the cursor that route names, never double-counting. An off-by-default DENSITY dial shades the spine where events crowd together, and the choice persists across sessions.
|
|
20
|
+
|
|
21
|
+
- **Play mode performs the run.** Press play at T+0 and the canvas replays the run on its real timestamp deltas: speeds of 1x, 2x, and 3x, a compression dial (on by default) that caps any single inter-event gap at about two seconds so a ten-minute run plays in a minute or two, a loop toggle for booth-style playback, and controls that fade while a performance runs with the cursor idle.
|
|
22
|
+
|
|
23
|
+
- **The trajectory records what a canvas needs.** Every observed run now opens with a `flow_structure` event, the `describe.json` tree embedded verbatim, recorded only when a logger or stream consumer is present so an unobserved run pays nothing for the walk. `suspend`'s gate records a `suspended` event before it throws, carrying `suspend_id` plus the step id that joins it back to its `flow_structure` node, so a consumer sees the pause as its own event ahead of the span-end error. And `cost`, `turn_retry`, and `response_received` carry the enclosing step's `span_id`, so a consumer attributes them to the exact turn rather than an open-span-stack guess, which mis-attributes under parallel. The field is additive and optional, so fixtures without it keep the old fallback.
|
|
24
|
+
|
|
25
|
+
### Internal
|
|
26
|
+
|
|
27
|
+
- Rewrote `docs/viewer.md` around the run canvas, and pinned the viewer server's heartbeat, close, error, and 500 paths plus the tailer's io-error, drain, stop, and coalescing paths in tests.
|
|
28
|
+
|
|
3
29
|
## v0.12.5 — 2026-08-21
|
|
4
30
|
|
|
5
31
|
Everything in v0.12.4 ships here for the first time: that version was tagged but never reached npm, because its publish run failed on the gate described below. Upgrading from v0.12.3 picks up both sections.
|
package/dist/agents.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-CFdEjtiT.js";
|
|
2
2
|
import { readFileSync } from "node:fs";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
//#region src/agents/define_agent.ts
|
|
@@ -70,19 +70,6 @@ async function run_one(fn, trajectory) {
|
|
|
70
70
|
}
|
|
71
71
|
}
|
|
72
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
|
|
86
73
|
//#region src/core/errors.ts
|
|
87
74
|
var timeout_error = class extends Error {
|
|
88
75
|
kind = "timeout_error";
|
|
@@ -165,6 +152,270 @@ function error_path(err) {
|
|
|
165
152
|
return ids.length === entries.length ? ids : void 0;
|
|
166
153
|
}
|
|
167
154
|
//#endregion
|
|
155
|
+
//#region src/core/is_step.ts
|
|
156
|
+
/**
|
|
157
|
+
* Check whether a value is structurally a `Step`.
|
|
158
|
+
*
|
|
159
|
+
* True when the value has a string `id`, a string `kind`, and a callable
|
|
160
|
+
* `run`.
|
|
161
|
+
*/
|
|
162
|
+
function is_step(value) {
|
|
163
|
+
if (typeof value !== "object" || value === null) return false;
|
|
164
|
+
if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
|
|
165
|
+
const { id, kind, run } = value;
|
|
166
|
+
return typeof id === "string" && typeof kind === "string" && typeof run === "function";
|
|
167
|
+
}
|
|
168
|
+
//#endregion
|
|
169
|
+
//#region src/core/display_name.ts
|
|
170
|
+
/**
|
|
171
|
+
* Resolve the human-readable label for `node`, falling back to `fallback`
|
|
172
|
+
* (typically the step's kind) when neither display channel is populated.
|
|
173
|
+
*/
|
|
174
|
+
function resolve_display_name(node, fallback) {
|
|
175
|
+
const display = node.config?.["display_name"];
|
|
176
|
+
if (typeof display === "string" && display.length > 0) return display;
|
|
177
|
+
const name = node.meta?.name;
|
|
178
|
+
if (typeof name === "string" && name.length > 0) return name;
|
|
179
|
+
return fallback;
|
|
180
|
+
}
|
|
181
|
+
//#endregion
|
|
182
|
+
//#region src/core/describe.ts
|
|
183
|
+
/**
|
|
184
|
+
* describe(step) and describe.json(step): composition introspection.
|
|
185
|
+
*
|
|
186
|
+
* `describe(step)` is the text-tree renderer. Multi-line string with
|
|
187
|
+
* hierarchical indentation. Function values render as `<fn>` (or
|
|
188
|
+
* `<fn:name>` when the function has a non-empty `name`); zod schemas
|
|
189
|
+
* render as `<schema>`.
|
|
190
|
+
*
|
|
191
|
+
* `describe.json(step)` returns a `FlowNode` tree (kind, id, config, children)
|
|
192
|
+
* for tooling (Studio UI, Mermaid renderers, diff tools). Function values
|
|
193
|
+
* serialize as `{ kind: '<fn>', name? }` and schemas as `{ kind: '<schema>' }`.
|
|
194
|
+
*
|
|
195
|
+
* Both forms detect cycles. Under the default (loose) mode, back-references
|
|
196
|
+
* render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
|
|
197
|
+
* `{ strict: true }`, cycles throw `describe_cycle_error`.
|
|
198
|
+
*/
|
|
199
|
+
const INDENT = " ";
|
|
200
|
+
/**
|
|
201
|
+
* Render a step tree as an indented multi-line string.
|
|
202
|
+
*/
|
|
203
|
+
function describe_text(root, options) {
|
|
204
|
+
const lines = [];
|
|
205
|
+
const strict = Boolean(options?.strict);
|
|
206
|
+
render_text(root, 0, lines, /* @__PURE__ */ new Set(), strict);
|
|
207
|
+
return lines.join("\n");
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* Render a step tree as a serializable `FlowNode` tree.
|
|
211
|
+
*/
|
|
212
|
+
function describe_json(root, options) {
|
|
213
|
+
const strict = Boolean(options?.strict);
|
|
214
|
+
return render_json(root, /* @__PURE__ */ new Set(), strict);
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Public entry point: `describe(step)` for text, `describe.json(step)` for
|
|
218
|
+
* the `FlowNode` tree.
|
|
219
|
+
*/
|
|
220
|
+
const describe = Object.assign(describe_text, { json: describe_json });
|
|
221
|
+
/**
|
|
222
|
+
* Append one node (label line, config lines, then children) to `lines`.
|
|
223
|
+
*
|
|
224
|
+
* `path` holds the steps on the current root-to-node path for cycle
|
|
225
|
+
* detection; membership is added before recursing and removed in a `finally`
|
|
226
|
+
* so shared (diamond) references are not misreported as cycles.
|
|
227
|
+
*/
|
|
228
|
+
function render_text(node, depth, lines, path, strict) {
|
|
229
|
+
const prefix = INDENT.repeat(depth);
|
|
230
|
+
if (path.has(node)) {
|
|
231
|
+
if (strict) throw new describe_cycle_error(node.id);
|
|
232
|
+
lines.push(`${prefix}<cycle>(${node.id})`);
|
|
233
|
+
return;
|
|
234
|
+
}
|
|
235
|
+
path.add(node);
|
|
236
|
+
try {
|
|
237
|
+
lines.push(`${prefix}${resolve_display_name(node, node.kind)}(${node.id})`);
|
|
238
|
+
if (node.config) for (const [key, value] of Object.entries(node.config)) {
|
|
239
|
+
if (key === "display_name") continue;
|
|
240
|
+
lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
|
|
241
|
+
}
|
|
242
|
+
if (node.children && node.children.length > 0) for (const child of node.children) render_text(child, depth + 1, lines, path, strict);
|
|
243
|
+
} finally {
|
|
244
|
+
path.delete(node);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
/**
|
|
248
|
+
* Render a single config value for the text tree.
|
|
249
|
+
*
|
|
250
|
+
* Functions become `<fn>` or `<fn:name>`, zod schemas `<schema>`, and Step
|
|
251
|
+
* references `kind(id)`; arrays and plain objects recurse. Strings are
|
|
252
|
+
* JSON-quoted so empty and whitespace values stay visible.
|
|
253
|
+
*
|
|
254
|
+
* Steps, arrays, and renderable objects each own a branch; everything else
|
|
255
|
+
* (functions, the empty markers, schemas, primitives) resolves through
|
|
256
|
+
* `render_scalar_text`. The three object-shaped cases are mutually exclusive at
|
|
257
|
+
* runtime, so their order relative to the scalar cases is immaterial.
|
|
258
|
+
*/
|
|
259
|
+
function render_value_text(value, path, strict) {
|
|
260
|
+
if (is_step(value)) return render_step_text(value, path, strict);
|
|
261
|
+
if (Array.isArray(value)) return `[${value.map((item) => render_value_text(item, path, strict)).join(", ")}]`;
|
|
262
|
+
if (is_renderable_object(value)) return `{ ${Object.entries({ ...value }).map(([k, v]) => `${k}: ${render_value_text(v, path, strict)}`).join(", ")} }`;
|
|
263
|
+
return render_scalar_text(value);
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Render a Step reference for the text tree: a back-reference on the current
|
|
267
|
+
* path becomes `<cycle>(id)` (or throws under strict mode); otherwise `kind(id)`.
|
|
268
|
+
*/
|
|
269
|
+
function render_step_text(value, path, strict) {
|
|
270
|
+
if (path.has(value)) {
|
|
271
|
+
if (strict) throw new describe_cycle_error(value.id);
|
|
272
|
+
return `<cycle>(${value.id})`;
|
|
273
|
+
}
|
|
274
|
+
return `${value.kind}(${value.id})`;
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* Render the non-recursive value cases for the text tree: functions (`<fn>` or
|
|
278
|
+
* `<fn:name>`), the empty markers, zod schemas, and (via `render_primitive_text`)
|
|
279
|
+
* raw primitives.
|
|
280
|
+
*/
|
|
281
|
+
function render_scalar_text(value) {
|
|
282
|
+
if (typeof value === "function") {
|
|
283
|
+
const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
|
|
284
|
+
return name ? `<fn:${name}>` : "<fn>";
|
|
285
|
+
}
|
|
286
|
+
if (value === null) return "null";
|
|
287
|
+
if (value === void 0) return "undefined";
|
|
288
|
+
if (is_zod_schema(value)) return "<schema>";
|
|
289
|
+
return render_primitive_text(value);
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Render a primitive (or unrecognized) value for the text tree. Strings are
|
|
293
|
+
* JSON-quoted so empty and whitespace values stay visible; bigints keep an `n`
|
|
294
|
+
* suffix; anything unexpected falls back to JSON.
|
|
295
|
+
*/
|
|
296
|
+
function render_primitive_text(value) {
|
|
297
|
+
if (typeof value === "string") return JSON.stringify(value);
|
|
298
|
+
if (typeof value === "bigint") return `${value.toString()}n`;
|
|
299
|
+
if (typeof value === "symbol") return value.toString();
|
|
300
|
+
if (typeof value === "number" || typeof value === "boolean") return String(value);
|
|
301
|
+
return JSON.stringify(value);
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Convert one step node to a `FlowNode`, recursing into config and children.
|
|
305
|
+
*
|
|
306
|
+
* Uses the same path-based cycle detection as `render_text`: back-references
|
|
307
|
+
* become `{ kind: '<cycle>', id }` in loose mode and throw in strict mode.
|
|
308
|
+
*/
|
|
309
|
+
function render_json(node, path, strict) {
|
|
310
|
+
if (path.has(node)) {
|
|
311
|
+
if (strict) throw new describe_cycle_error(node.id);
|
|
312
|
+
return {
|
|
313
|
+
kind: "<cycle>",
|
|
314
|
+
id: node.id
|
|
315
|
+
};
|
|
316
|
+
}
|
|
317
|
+
path.add(node);
|
|
318
|
+
try {
|
|
319
|
+
const result = {
|
|
320
|
+
kind: node.kind,
|
|
321
|
+
id: node.id
|
|
322
|
+
};
|
|
323
|
+
if (node.config) {
|
|
324
|
+
const config = {};
|
|
325
|
+
for (const [key, value] of Object.entries(node.config)) config[key] = render_value_json(value, path, strict);
|
|
326
|
+
result.config = config;
|
|
327
|
+
}
|
|
328
|
+
if (node.children && node.children.length > 0) result.children = node.children.map((child) => render_json(child, path, strict));
|
|
329
|
+
if (node.meta) result.meta = node.meta;
|
|
330
|
+
return result;
|
|
331
|
+
} finally {
|
|
332
|
+
path.delete(node);
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
/**
|
|
336
|
+
* Convert a single config value to a JSON-safe `FlowValue`.
|
|
337
|
+
*
|
|
338
|
+
* Functions serialize as `{ kind: '<fn>', name? }`, schemas as
|
|
339
|
+
* `{ kind: '<schema>' }`, Step references as `{ kind, id }`. `undefined`
|
|
340
|
+
* maps to `null` and bigints/symbols to strings so the result survives
|
|
341
|
+
* `JSON.stringify` without loss.
|
|
342
|
+
*
|
|
343
|
+
* Mirrors `render_value_text`: steps, arrays, and renderable objects each own a
|
|
344
|
+
* branch, and everything else resolves through `render_scalar_json`.
|
|
345
|
+
*/
|
|
346
|
+
function render_value_json(value, path, strict) {
|
|
347
|
+
if (is_step(value)) return render_step_json(value, path, strict);
|
|
348
|
+
if (Array.isArray(value)) return value.map((item) => render_value_json(item, path, strict));
|
|
349
|
+
if (is_renderable_object(value)) {
|
|
350
|
+
const out = {};
|
|
351
|
+
for (const [k, v] of Object.entries({ ...value })) out[k] = render_value_json(v, path, strict);
|
|
352
|
+
return out;
|
|
353
|
+
}
|
|
354
|
+
return render_scalar_json(value);
|
|
355
|
+
}
|
|
356
|
+
/**
|
|
357
|
+
* Serialize a Step reference: a back-reference on the current path becomes
|
|
358
|
+
* `{ kind: '<cycle>', id }` (or throws under strict mode); otherwise `{ kind, id }`.
|
|
359
|
+
*/
|
|
360
|
+
function render_step_json(value, path, strict) {
|
|
361
|
+
if (path.has(value)) {
|
|
362
|
+
if (strict) throw new describe_cycle_error(value.id);
|
|
363
|
+
return {
|
|
364
|
+
kind: "<cycle>",
|
|
365
|
+
id: value.id
|
|
366
|
+
};
|
|
367
|
+
}
|
|
368
|
+
return {
|
|
369
|
+
kind: value.kind,
|
|
370
|
+
id: value.id
|
|
371
|
+
};
|
|
372
|
+
}
|
|
373
|
+
/**
|
|
374
|
+
* Serialize the non-recursive value cases: functions, the empty markers, zod
|
|
375
|
+
* schemas, and (via `render_primitive_json`) raw primitives.
|
|
376
|
+
*/
|
|
377
|
+
function render_scalar_json(value) {
|
|
378
|
+
if (typeof value === "function") {
|
|
379
|
+
const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
|
|
380
|
+
return name ? {
|
|
381
|
+
kind: "<fn>",
|
|
382
|
+
name
|
|
383
|
+
} : { kind: "<fn>" };
|
|
384
|
+
}
|
|
385
|
+
if (value === null) return null;
|
|
386
|
+
if (value === void 0) return null;
|
|
387
|
+
if (is_zod_schema(value)) return { kind: "<schema>" };
|
|
388
|
+
return render_primitive_json(value);
|
|
389
|
+
}
|
|
390
|
+
/**
|
|
391
|
+
* Serialize a primitive (or unrecognized) value. `undefined` already resolves
|
|
392
|
+
* to `null` in `render_scalar_json`; bigints and symbols become strings so the
|
|
393
|
+
* result survives `JSON.stringify` without loss.
|
|
394
|
+
*/
|
|
395
|
+
function render_primitive_json(value) {
|
|
396
|
+
if (typeof value === "string") return value;
|
|
397
|
+
if (typeof value === "number" || typeof value === "boolean") return value;
|
|
398
|
+
if (typeof value === "bigint") return `${value.toString()}n`;
|
|
399
|
+
if (typeof value === "symbol") return value.toString();
|
|
400
|
+
return JSON.stringify(value);
|
|
401
|
+
}
|
|
402
|
+
/**
|
|
403
|
+
* Detect a zod schema by its internal marker properties (`_zod` in zod 4,
|
|
404
|
+
* `_def` in zod 3) without importing zod.
|
|
405
|
+
*/
|
|
406
|
+
function is_zod_schema(value) {
|
|
407
|
+
if (typeof value !== "object" || value === null) return false;
|
|
408
|
+
return "_zod" in value || "_def" in value;
|
|
409
|
+
}
|
|
410
|
+
/**
|
|
411
|
+
* True for a plain object rendered by recursing into its own entries: an object
|
|
412
|
+
* that is neither null nor a zod schema. The Step and array cases are checked
|
|
413
|
+
* before this at every call site, so they never reach it.
|
|
414
|
+
*/
|
|
415
|
+
function is_renderable_object(value) {
|
|
416
|
+
return typeof value === "object" && value !== null && !is_zod_schema(value);
|
|
417
|
+
}
|
|
418
|
+
//#endregion
|
|
168
419
|
//#region src/core/streaming.ts
|
|
169
420
|
const STREAMING_HIGH_WATER_MARK = 1e4;
|
|
170
421
|
/**
|
|
@@ -521,8 +772,9 @@ function link_external_abort(controller, external) {
|
|
|
521
772
|
* Shared engine behind `run` and `run.stream`; `high_water_mark` selects the
|
|
522
773
|
* mode (null means no streaming channel). Owns the full run lifecycle:
|
|
523
774
|
* abort wiring, logger decoration, cleanup registration, signal handlers,
|
|
524
|
-
*
|
|
525
|
-
* unlinking and
|
|
775
|
+
* the `flow_structure` event that opens an observed run, and the
|
|
776
|
+
* settle-time teardown ordering (cleanup handlers first, then unlinking and
|
|
777
|
+
* stream close).
|
|
526
778
|
*/
|
|
527
779
|
function start_run(flow, input, options, high_water_mark) {
|
|
528
780
|
const install_signal_handlers = options.install_signal_handlers !== false;
|
|
@@ -541,6 +793,10 @@ function start_run(flow, input, options, high_water_mark) {
|
|
|
541
793
|
close_stream = channel.close;
|
|
542
794
|
}
|
|
543
795
|
const logger = decorate_logger(inner, run_id);
|
|
796
|
+
if (options.trajectory !== void 0 || streaming) logger.record({
|
|
797
|
+
kind: "flow_structure",
|
|
798
|
+
structure: describe.json(flow)
|
|
799
|
+
});
|
|
544
800
|
const cleanup = create_cleanup_registry(logger);
|
|
545
801
|
const ctx = {
|
|
546
802
|
run_id,
|
|
@@ -803,257 +1059,6 @@ function step(id_or_fn, maybe_fn, meta) {
|
|
|
803
1059
|
}
|
|
804
1060
|
register_traced_kind("step");
|
|
805
1061
|
//#endregion
|
|
806
|
-
//#region src/core/is_step.ts
|
|
807
|
-
/**
|
|
808
|
-
* Check whether a value is structurally a `Step`.
|
|
809
|
-
*
|
|
810
|
-
* True when the value has a string `id`, a string `kind`, and a callable
|
|
811
|
-
* `run`.
|
|
812
|
-
*/
|
|
813
|
-
function is_step(value) {
|
|
814
|
-
if (typeof value !== "object" || value === null) return false;
|
|
815
|
-
if (!("id" in value) || !("kind" in value) || !("run" in value)) return false;
|
|
816
|
-
const { id, kind, run } = value;
|
|
817
|
-
return typeof id === "string" && typeof kind === "string" && typeof run === "function";
|
|
818
|
-
}
|
|
819
|
-
//#endregion
|
|
820
|
-
//#region src/core/describe.ts
|
|
821
|
-
/**
|
|
822
|
-
* describe(step) and describe.json(step): composition introspection.
|
|
823
|
-
*
|
|
824
|
-
* `describe(step)` is the text-tree renderer. Multi-line string with
|
|
825
|
-
* hierarchical indentation. Function values render as `<fn>` (or
|
|
826
|
-
* `<fn:name>` when the function has a non-empty `name`); zod schemas
|
|
827
|
-
* render as `<schema>`.
|
|
828
|
-
*
|
|
829
|
-
* `describe.json(step)` returns a `FlowNode` tree (kind, id, config, children)
|
|
830
|
-
* for tooling (Studio UI, Mermaid renderers, diff tools). Function values
|
|
831
|
-
* serialize as `{ kind: '<fn>', name? }` and schemas as `{ kind: '<schema>' }`.
|
|
832
|
-
*
|
|
833
|
-
* Both forms detect cycles. Under the default (loose) mode, back-references
|
|
834
|
-
* render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
|
|
835
|
-
* `{ strict: true }`, cycles throw `describe_cycle_error`.
|
|
836
|
-
*/
|
|
837
|
-
const INDENT = " ";
|
|
838
|
-
/**
|
|
839
|
-
* Render a step tree as an indented multi-line string.
|
|
840
|
-
*/
|
|
841
|
-
function describe_text(root, options) {
|
|
842
|
-
const lines = [];
|
|
843
|
-
const strict = Boolean(options?.strict);
|
|
844
|
-
render_text(root, 0, lines, /* @__PURE__ */ new Set(), strict);
|
|
845
|
-
return lines.join("\n");
|
|
846
|
-
}
|
|
847
|
-
/**
|
|
848
|
-
* Render a step tree as a serializable `FlowNode` tree.
|
|
849
|
-
*/
|
|
850
|
-
function describe_json(root, options) {
|
|
851
|
-
const strict = Boolean(options?.strict);
|
|
852
|
-
return render_json(root, /* @__PURE__ */ new Set(), strict);
|
|
853
|
-
}
|
|
854
|
-
/**
|
|
855
|
-
* Public entry point: `describe(step)` for text, `describe.json(step)` for
|
|
856
|
-
* the `FlowNode` tree.
|
|
857
|
-
*/
|
|
858
|
-
const describe = Object.assign(describe_text, { json: describe_json });
|
|
859
|
-
/**
|
|
860
|
-
* Append one node (label line, config lines, then children) to `lines`.
|
|
861
|
-
*
|
|
862
|
-
* `path` holds the steps on the current root-to-node path for cycle
|
|
863
|
-
* detection; membership is added before recursing and removed in a `finally`
|
|
864
|
-
* so shared (diamond) references are not misreported as cycles.
|
|
865
|
-
*/
|
|
866
|
-
function render_text(node, depth, lines, path, strict) {
|
|
867
|
-
const prefix = INDENT.repeat(depth);
|
|
868
|
-
if (path.has(node)) {
|
|
869
|
-
if (strict) throw new describe_cycle_error(node.id);
|
|
870
|
-
lines.push(`${prefix}<cycle>(${node.id})`);
|
|
871
|
-
return;
|
|
872
|
-
}
|
|
873
|
-
path.add(node);
|
|
874
|
-
try {
|
|
875
|
-
lines.push(`${prefix}${resolve_display_name(node, node.kind)}(${node.id})`);
|
|
876
|
-
if (node.config) for (const [key, value] of Object.entries(node.config)) {
|
|
877
|
-
if (key === "display_name") continue;
|
|
878
|
-
lines.push(`${prefix}${INDENT}${key}: ${render_value_text(value, path, strict)}`);
|
|
879
|
-
}
|
|
880
|
-
if (node.children && node.children.length > 0) for (const child of node.children) render_text(child, depth + 1, lines, path, strict);
|
|
881
|
-
} finally {
|
|
882
|
-
path.delete(node);
|
|
883
|
-
}
|
|
884
|
-
}
|
|
885
|
-
/**
|
|
886
|
-
* Render a single config value for the text tree.
|
|
887
|
-
*
|
|
888
|
-
* Functions become `<fn>` or `<fn:name>`, zod schemas `<schema>`, and Step
|
|
889
|
-
* references `kind(id)`; arrays and plain objects recurse. Strings are
|
|
890
|
-
* JSON-quoted so empty and whitespace values stay visible.
|
|
891
|
-
*
|
|
892
|
-
* Steps, arrays, and renderable objects each own a branch; everything else
|
|
893
|
-
* (functions, the empty markers, schemas, primitives) resolves through
|
|
894
|
-
* `render_scalar_text`. The three object-shaped cases are mutually exclusive at
|
|
895
|
-
* runtime, so their order relative to the scalar cases is immaterial.
|
|
896
|
-
*/
|
|
897
|
-
function render_value_text(value, path, strict) {
|
|
898
|
-
if (is_step(value)) return render_step_text(value, path, strict);
|
|
899
|
-
if (Array.isArray(value)) return `[${value.map((item) => render_value_text(item, path, strict)).join(", ")}]`;
|
|
900
|
-
if (is_renderable_object(value)) return `{ ${Object.entries({ ...value }).map(([k, v]) => `${k}: ${render_value_text(v, path, strict)}`).join(", ")} }`;
|
|
901
|
-
return render_scalar_text(value);
|
|
902
|
-
}
|
|
903
|
-
/**
|
|
904
|
-
* Render a Step reference for the text tree: a back-reference on the current
|
|
905
|
-
* path becomes `<cycle>(id)` (or throws under strict mode); otherwise `kind(id)`.
|
|
906
|
-
*/
|
|
907
|
-
function render_step_text(value, path, strict) {
|
|
908
|
-
if (path.has(value)) {
|
|
909
|
-
if (strict) throw new describe_cycle_error(value.id);
|
|
910
|
-
return `<cycle>(${value.id})`;
|
|
911
|
-
}
|
|
912
|
-
return `${value.kind}(${value.id})`;
|
|
913
|
-
}
|
|
914
|
-
/**
|
|
915
|
-
* Render the non-recursive value cases for the text tree: functions (`<fn>` or
|
|
916
|
-
* `<fn:name>`), the empty markers, zod schemas, and (via `render_primitive_text`)
|
|
917
|
-
* raw primitives.
|
|
918
|
-
*/
|
|
919
|
-
function render_scalar_text(value) {
|
|
920
|
-
if (typeof value === "function") {
|
|
921
|
-
const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
|
|
922
|
-
return name ? `<fn:${name}>` : "<fn>";
|
|
923
|
-
}
|
|
924
|
-
if (value === null) return "null";
|
|
925
|
-
if (value === void 0) return "undefined";
|
|
926
|
-
if (is_zod_schema(value)) return "<schema>";
|
|
927
|
-
return render_primitive_text(value);
|
|
928
|
-
}
|
|
929
|
-
/**
|
|
930
|
-
* Render a primitive (or unrecognized) value for the text tree. Strings are
|
|
931
|
-
* JSON-quoted so empty and whitespace values stay visible; bigints keep an `n`
|
|
932
|
-
* suffix; anything unexpected falls back to JSON.
|
|
933
|
-
*/
|
|
934
|
-
function render_primitive_text(value) {
|
|
935
|
-
if (typeof value === "string") return JSON.stringify(value);
|
|
936
|
-
if (typeof value === "bigint") return `${value.toString()}n`;
|
|
937
|
-
if (typeof value === "symbol") return value.toString();
|
|
938
|
-
if (typeof value === "number" || typeof value === "boolean") return String(value);
|
|
939
|
-
return JSON.stringify(value);
|
|
940
|
-
}
|
|
941
|
-
/**
|
|
942
|
-
* Convert one step node to a `FlowNode`, recursing into config and children.
|
|
943
|
-
*
|
|
944
|
-
* Uses the same path-based cycle detection as `render_text`: back-references
|
|
945
|
-
* become `{ kind: '<cycle>', id }` in loose mode and throw in strict mode.
|
|
946
|
-
*/
|
|
947
|
-
function render_json(node, path, strict) {
|
|
948
|
-
if (path.has(node)) {
|
|
949
|
-
if (strict) throw new describe_cycle_error(node.id);
|
|
950
|
-
return {
|
|
951
|
-
kind: "<cycle>",
|
|
952
|
-
id: node.id
|
|
953
|
-
};
|
|
954
|
-
}
|
|
955
|
-
path.add(node);
|
|
956
|
-
try {
|
|
957
|
-
const result = {
|
|
958
|
-
kind: node.kind,
|
|
959
|
-
id: node.id
|
|
960
|
-
};
|
|
961
|
-
if (node.config) {
|
|
962
|
-
const config = {};
|
|
963
|
-
for (const [key, value] of Object.entries(node.config)) config[key] = render_value_json(value, path, strict);
|
|
964
|
-
result.config = config;
|
|
965
|
-
}
|
|
966
|
-
if (node.children && node.children.length > 0) result.children = node.children.map((child) => render_json(child, path, strict));
|
|
967
|
-
if (node.meta) result.meta = node.meta;
|
|
968
|
-
return result;
|
|
969
|
-
} finally {
|
|
970
|
-
path.delete(node);
|
|
971
|
-
}
|
|
972
|
-
}
|
|
973
|
-
/**
|
|
974
|
-
* Convert a single config value to a JSON-safe `FlowValue`.
|
|
975
|
-
*
|
|
976
|
-
* Functions serialize as `{ kind: '<fn>', name? }`, schemas as
|
|
977
|
-
* `{ kind: '<schema>' }`, Step references as `{ kind, id }`. `undefined`
|
|
978
|
-
* maps to `null` and bigints/symbols to strings so the result survives
|
|
979
|
-
* `JSON.stringify` without loss.
|
|
980
|
-
*
|
|
981
|
-
* Mirrors `render_value_text`: steps, arrays, and renderable objects each own a
|
|
982
|
-
* branch, and everything else resolves through `render_scalar_json`.
|
|
983
|
-
*/
|
|
984
|
-
function render_value_json(value, path, strict) {
|
|
985
|
-
if (is_step(value)) return render_step_json(value, path, strict);
|
|
986
|
-
if (Array.isArray(value)) return value.map((item) => render_value_json(item, path, strict));
|
|
987
|
-
if (is_renderable_object(value)) {
|
|
988
|
-
const out = {};
|
|
989
|
-
for (const [k, v] of Object.entries({ ...value })) out[k] = render_value_json(v, path, strict);
|
|
990
|
-
return out;
|
|
991
|
-
}
|
|
992
|
-
return render_scalar_json(value);
|
|
993
|
-
}
|
|
994
|
-
/**
|
|
995
|
-
* Serialize a Step reference: a back-reference on the current path becomes
|
|
996
|
-
* `{ kind: '<cycle>', id }` (or throws under strict mode); otherwise `{ kind, id }`.
|
|
997
|
-
*/
|
|
998
|
-
function render_step_json(value, path, strict) {
|
|
999
|
-
if (path.has(value)) {
|
|
1000
|
-
if (strict) throw new describe_cycle_error(value.id);
|
|
1001
|
-
return {
|
|
1002
|
-
kind: "<cycle>",
|
|
1003
|
-
id: value.id
|
|
1004
|
-
};
|
|
1005
|
-
}
|
|
1006
|
-
return {
|
|
1007
|
-
kind: value.kind,
|
|
1008
|
-
id: value.id
|
|
1009
|
-
};
|
|
1010
|
-
}
|
|
1011
|
-
/**
|
|
1012
|
-
* Serialize the non-recursive value cases: functions, the empty markers, zod
|
|
1013
|
-
* schemas, and (via `render_primitive_json`) raw primitives.
|
|
1014
|
-
*/
|
|
1015
|
-
function render_scalar_json(value) {
|
|
1016
|
-
if (typeof value === "function") {
|
|
1017
|
-
const name = typeof value.name === "string" && value.name.length > 0 ? value.name : "";
|
|
1018
|
-
return name ? {
|
|
1019
|
-
kind: "<fn>",
|
|
1020
|
-
name
|
|
1021
|
-
} : { kind: "<fn>" };
|
|
1022
|
-
}
|
|
1023
|
-
if (value === null) return null;
|
|
1024
|
-
if (value === void 0) return null;
|
|
1025
|
-
if (is_zod_schema(value)) return { kind: "<schema>" };
|
|
1026
|
-
return render_primitive_json(value);
|
|
1027
|
-
}
|
|
1028
|
-
/**
|
|
1029
|
-
* Serialize a primitive (or unrecognized) value. `undefined` already resolves
|
|
1030
|
-
* to `null` in `render_scalar_json`; bigints and symbols become strings so the
|
|
1031
|
-
* result survives `JSON.stringify` without loss.
|
|
1032
|
-
*/
|
|
1033
|
-
function render_primitive_json(value) {
|
|
1034
|
-
if (typeof value === "string") return value;
|
|
1035
|
-
if (typeof value === "number" || typeof value === "boolean") return value;
|
|
1036
|
-
if (typeof value === "bigint") return `${value.toString()}n`;
|
|
1037
|
-
if (typeof value === "symbol") return value.toString();
|
|
1038
|
-
return JSON.stringify(value);
|
|
1039
|
-
}
|
|
1040
|
-
/**
|
|
1041
|
-
* Detect a zod schema by its internal marker properties (`_zod` in zod 4,
|
|
1042
|
-
* `_def` in zod 3) without importing zod.
|
|
1043
|
-
*/
|
|
1044
|
-
function is_zod_schema(value) {
|
|
1045
|
-
if (typeof value !== "object" || value === null) return false;
|
|
1046
|
-
return "_zod" in value || "_def" in value;
|
|
1047
|
-
}
|
|
1048
|
-
/**
|
|
1049
|
-
* True for a plain object rendered by recursing into its own entries: an object
|
|
1050
|
-
* that is neither null nor a zod schema. The Step and array cases are checked
|
|
1051
|
-
* before this at every call site, so they never reach it.
|
|
1052
|
-
*/
|
|
1053
|
-
function is_renderable_object(value) {
|
|
1054
|
-
return typeof value === "object" && value !== null && !is_zod_schema(value);
|
|
1055
|
-
}
|
|
1056
|
-
//#endregion
|
|
1057
1062
|
//#region src/core/sequence.ts
|
|
1058
1063
|
/**
|
|
1059
1064
|
* sequence: chain child outputs.
|
|
@@ -1995,8 +2000,9 @@ function format_issue(issue) {
|
|
|
1995
2000
|
*
|
|
1996
2001
|
* `suspend({ id, on, resume_schema, combine })` pauses a flow waiting on
|
|
1997
2002
|
* external input (a notification, an approval, an uploaded file). On first
|
|
1998
|
-
* encounter with no resume data, it calls `on(input, ctx)` (side effect)
|
|
1999
|
-
*
|
|
2003
|
+
* encounter with no resume data, it calls `on(input, ctx)` (side effect),
|
|
2004
|
+
* records a `suspended` trajectory event, and throws `suspended_error`
|
|
2005
|
+
* carrying the run state. On resume (re-invocation
|
|
2000
2006
|
* with `run_options.resume_data[id]` populated), the provided value is
|
|
2001
2007
|
* validated against `resume_schema` and passed to `combine(input, resume,
|
|
2002
2008
|
* ctx)`; the result is returned. Invalid resume data throws
|
|
@@ -2019,6 +2025,11 @@ function suspend(config) {
|
|
|
2019
2025
|
const resume_value = ctx.resume_data?.[suspend_id];
|
|
2020
2026
|
if (resume_value === void 0) {
|
|
2021
2027
|
await on_fn(input, ctx);
|
|
2028
|
+
ctx.trajectory.record({
|
|
2029
|
+
kind: "suspended",
|
|
2030
|
+
suspend_id,
|
|
2031
|
+
step_id: suspend_id
|
|
2032
|
+
});
|
|
2022
2033
|
throw new suspended_error(suspend_id, { input });
|
|
2023
2034
|
}
|
|
2024
2035
|
const parsed = await validate_schema(resume_schema, resume_value);
|
|
@@ -2381,6 +2392,6 @@ register_traced_kind("chain");
|
|
|
2381
2392
|
* and surface through the umbrella package.
|
|
2382
2393
|
*/
|
|
2383
2394
|
//#endregion
|
|
2384
|
-
export {
|
|
2395
|
+
export { describe_cycle_error as A, is_valid_step_id as C, resolve_display_name as D, describe as E, resume_validation_error as M, suspended_error as N, is_step as O, timeout_error as P, assert_valid_step_id as S, run 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, error_path as j, aborted_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, suggest_step_id as w, step as x, parallel as y };
|
|
2385
2396
|
|
|
2386
|
-
//# sourceMappingURL=core-
|
|
2397
|
+
//# sourceMappingURL=core-CFdEjtiT.js.map
|