fascicle 0.12.5 → 0.12.8

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 CHANGED
@@ -1,5 +1,53 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.12.8 — 2026-09-04
4
+
5
+ ### Added
6
+
7
+ - **Step mode walks a run one beat at a time.** Play mode performs a run on a clock, which is the wrong instrument for reading one. A `STEP` dial now parks the clock and lets you walk the run yourself: engaging it opens the walk at T+0 and relabels the leading chip from `PLAY` to `NEXT`, and every press of that chip or the space bar advances one beat and stops there. A beat is one moment of run time, meaning every event that shares a timestamp, and the walk lands on exactly the positions a performance passes through, so stepping and playing show the same canvas at the same place and a parallel fan-out lights its branches in a single press. Turning the dial back off leaves the playhead where the walk stopped, so you can step into an interesting moment and then play the rest.
8
+
9
+ ### Changed
10
+
11
+ - **Play mode paces a fast run into beats you can read.** A run whose steps finish in tens of milliseconds used to flash past in well under a second, because the schedule played every gap at its real length divided by the speed and capped only the long ones. A floor now lifts every gap between two distinct moments to a second of wall time at 1x (500ms at 2x, 333ms at 3x), so a 200ms demo run performs over a dozen seconds instead of vanishing. Events sharing a timestamp still fire together, which is what keeps a parallel fan-out lighting at once, and inside a floored gap the header `T+` visibly slows, the mirror of the acceleration compression already shows in the other direction.
12
+
13
+ - **The playback controls are big enough to hit.** The dials move from a 10px face with 3px padding to the 11px meta register with a 28px target, and the leading chip holds a fixed width, so relabeling between `PLAY`, `PAUSE`, and `NEXT` no longer shifts the cluster under your pointer. The header's `RETURN TO LIVE` control shares the one chip recipe and grows with it.
14
+
15
+ ### Fixed
16
+
17
+ - **Two dependency pins lifted past fresh advisories, taking the audit to zero findings at every severity.** Three high advisories landed against `fast-uri` 4.1.2, among them host confusion on scheme-relative references and request forgery via malformed IPv6 normalization. The existing override pinned `>=3.1.2`, which 4.1.2 satisfies, so `ajv` resolved straight onto the vulnerable version. A second pin takes `qs` to 6.16.0, past three moderate advisories the `security` slot never demanded, because it fails at high. Neither package reaches anyone who installs this one: the published tarball has no runtime dependencies, and both paths run through the dev tree or through the optional MCP SDK peer.
18
+
19
+ ### Internal
20
+
21
+ - The viewer quickstart writes `.trajectory.jsonl` at the repo root and nothing ignored it, so following the documented demo left the working tree dirty and this release's version bump refused to run. The file is ignored now, alongside the red-green-refactor example's trajectory output.
22
+
23
+ - The comment above the overrides block now records what a `>=` pin cannot do. It is a floor, not a ceiling, so it clears the advisory in front of it and says nothing about the next one inside the same major, which is how the `fast-uri` pin above sat on a vulnerable version until the advisory landed.
24
+
25
+ ## v0.12.7 — 2026-09-01
26
+
27
+ 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.
28
+
29
+ ### Internal
30
+
31
+ - **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.
32
+
33
+ ## v0.12.6 — 2026-09-01
34
+
35
+ ### Changed
36
+
37
+ - **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).
38
+
39
+ ### Added
40
+
41
+ - **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.
42
+
43
+ - **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.
44
+
45
+ - **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.
46
+
47
+ ### Internal
48
+
49
+ - 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.
50
+
3
51
  ## v0.12.5 — 2026-08-21
4
52
 
5
53
  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 { C as step, O as aborted_error, w as assert_valid_step_id } from "./core-DdJEhyQc.js";
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
- * and the settle-time teardown ordering (cleanup handlers first, then
525
- * unlinking and stream close).
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) and
1999
- * throws `suspended_error` carrying the run state. On resume (re-invocation
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 { 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 };
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-DdJEhyQc.js.map
2397
+ //# sourceMappingURL=core-CFdEjtiT.js.map