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 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 { 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