fascicle 0.13.0 → 0.13.1
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 +7 -0
- package/dist/agents.js +1 -1
- package/dist/{core-B-M7nAkg.js → core-DK7g1Z40.js} +184 -42
- package/dist/core-DK7g1Z40.js.map +1 -0
- package/dist/diagram_bin.js +5 -2
- package/dist/diagram_bin.js.map +1 -1
- package/dist/{engine-BRzVcTBB.js → engine-BOGuc0X2.js} +3 -3
- package/dist/{engine-BRzVcTBB.js.map → engine-BOGuc0X2.js.map} +1 -1
- package/dist/index.d.ts +18 -2
- package/dist/index.js +2 -2
- package/dist/{invoke-CIdhjChw.js → invoke-Beef3R3X.js} +3 -3
- package/dist/{invoke-CIdhjChw.js.map → invoke-Beef3R3X.js.map} +1 -1
- package/dist/mcp.js +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.js +2 -2
- package/dist/viewer.js +1 -1
- package/package.json +1 -1
- package/dist/core-B-M7nAkg.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.13.1 — 2026-10-09
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`describe.replays(step)` names the steps a resume would pay for twice, before anything runs.** A run that resumes at a `suspend` replays the flow from its input, so a step marked `side_effect` (every `model_call` is) that can run before the gate runs again, unless a `checkpoint` that holds the step and not the gate stored its result. It reads the `describe.json` tree and returns a `ReplayHint` (`{ id, label, gates }`) for each such step, so a test can hold a flow to an empty list, and on `examples/durable-runs` it names the same step that the run's `step_replayed` event reports. Inside a `sequence`, a `chain`, a `fallback`, or one round of a `loop` the children run in order, `parallel` members and a step's arms can start in either order, and the arms of a `branch` never run against each other. A model call that a step's body makes without declaring it as an `arm` is out of its sight.
|
|
8
|
+
- **`describe.diagram` and `fascicle-diagram` can mark those steps.** Pass `replays: true` to `describe.diagram`, or `--replays` to the bin, and each of those rows ends with the gates it runs before, as in `(replays before approve)`. Without the option the diagram is unchanged byte for byte.
|
|
9
|
+
|
|
3
10
|
## v0.13.0 — 2026-10-09
|
|
4
11
|
|
|
5
12
|
### Added
|
package/dist/agents.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-
|
|
1
|
+
import { S as assert_valid_step_id, k as aborted_error, x as step } from "./core-DK7g1Z40.js";
|
|
2
2
|
import { readFileSync } from "node:fs";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
//#region src/agents/define_agent.ts
|
|
@@ -135,6 +135,154 @@ function is_step_kind(value) {
|
|
|
135
135
|
return typeof value === "string" && STEP_KINDS.includes(value);
|
|
136
136
|
}
|
|
137
137
|
//#endregion
|
|
138
|
+
//#region src/core/node_label.ts
|
|
139
|
+
/**
|
|
140
|
+
* What a flow node is called: its display name, an id its author chose, or
|
|
141
|
+
* its kind, in that order. `describe.diagram` labels its rows this way, and
|
|
142
|
+
* `describe.replays` names the steps it finds the same way.
|
|
143
|
+
*
|
|
144
|
+
* A counter-generated id never serves as a label, because its number depends
|
|
145
|
+
* on what else the process built first.
|
|
146
|
+
*/
|
|
147
|
+
const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
|
|
148
|
+
/**
|
|
149
|
+
* Pick a node's label: its display name, else an id its author chose, else
|
|
150
|
+
* its kind. `by_kind` reports the last case, where the kind already shows.
|
|
151
|
+
*/
|
|
152
|
+
function label_of(node) {
|
|
153
|
+
const display = resolve_display_name(node, "");
|
|
154
|
+
if (display !== "") return {
|
|
155
|
+
label: display,
|
|
156
|
+
by_kind: false
|
|
157
|
+
};
|
|
158
|
+
if (has_chosen_id(node)) return {
|
|
159
|
+
label: node.id,
|
|
160
|
+
by_kind: false
|
|
161
|
+
};
|
|
162
|
+
return {
|
|
163
|
+
label: node.kind,
|
|
164
|
+
by_kind: true
|
|
165
|
+
};
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* True when a node's id was chosen by its author. Anonymous steps, cycle
|
|
169
|
+
* markers, and every built-in composer carry generated ids. A kind outside
|
|
170
|
+
* the built-in set belongs to a hand-built step, whose id is its author's.
|
|
171
|
+
*/
|
|
172
|
+
function has_chosen_id(node) {
|
|
173
|
+
if (node.anonymous === true || node.kind === "<cycle>") return false;
|
|
174
|
+
return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
|
|
175
|
+
}
|
|
176
|
+
//#endregion
|
|
177
|
+
//#region src/core/replays.ts
|
|
178
|
+
/**
|
|
179
|
+
* The analysis behind `describe.replays(step)`: which steps marked
|
|
180
|
+
* `side_effect` a resumed run can run again before it reaches a gate.
|
|
181
|
+
*
|
|
182
|
+
* A run that resumes at a `suspend` replays the flow from its input, so a step
|
|
183
|
+
* that ran before the gate runs again, unless a `checkpoint` stored its
|
|
184
|
+
* result. The runtime reports each one as a `step_replayed` event once it has
|
|
185
|
+
* happened. This finds them from the flow's shape alone, before anything runs,
|
|
186
|
+
* so an app can hold its flow to having none in a test.
|
|
187
|
+
*
|
|
188
|
+
* It reads only the `FlowNode` tree that `describe.json` produces. A marked
|
|
189
|
+
* step can replay at a gate when it can start before the gate in one pass and
|
|
190
|
+
* no checkpoint stores its result first. Where the two paths split decides
|
|
191
|
+
* which comes first:
|
|
192
|
+
*
|
|
193
|
+
* - `parallel` members start together, and a step's arms run in whatever
|
|
194
|
+
* order its body calls them, so either one can.
|
|
195
|
+
* - The arms of a `branch` exclude each other within a pass, so neither does.
|
|
196
|
+
* - Anything else runs its children in order: a `sequence`, a `chain`'s plan,
|
|
197
|
+
* a `fallback`'s primary before its backup, a `loop`'s body before its guard
|
|
198
|
+
* within a round, and a kind this module doesn't know.
|
|
199
|
+
* - A step that holds the gate starts before it.
|
|
200
|
+
*
|
|
201
|
+
* A checkpoint protects a step from a gate when it holds the step and not the
|
|
202
|
+
* gate. One around both stores its result only after the gate resumes.
|
|
203
|
+
*
|
|
204
|
+
* What the tree can't show, this can't see: a model call that a step's body
|
|
205
|
+
* makes without declaring it as an arm, a step that a `suspend`'s `combine`
|
|
206
|
+
* hands back, and a gate that a loop reaches only in a later round.
|
|
207
|
+
*/
|
|
208
|
+
/**
|
|
209
|
+
* Append `node` and every node under it to `out`, in reading order.
|
|
210
|
+
*/
|
|
211
|
+
function walk(node, trail, out) {
|
|
212
|
+
out.push({
|
|
213
|
+
node,
|
|
214
|
+
trail
|
|
215
|
+
});
|
|
216
|
+
for (const [index, child] of (node.children ?? []).entries()) walk(child, [...trail, {
|
|
217
|
+
node,
|
|
218
|
+
index
|
|
219
|
+
}], out);
|
|
220
|
+
}
|
|
221
|
+
/**
|
|
222
|
+
* True when, under a node of `kind`, the child at `first` can start before
|
|
223
|
+
* the child at `second` within one pass.
|
|
224
|
+
*/
|
|
225
|
+
function comes_first(kind, first, second) {
|
|
226
|
+
if (kind === "branch") return false;
|
|
227
|
+
if (kind === "parallel" || kind === "step") return true;
|
|
228
|
+
return first < second;
|
|
229
|
+
}
|
|
230
|
+
/**
|
|
231
|
+
* How many turns two trails share before they part, which is the depth of
|
|
232
|
+
* the node where their paths split. A trail that runs out first is shared
|
|
233
|
+
* whole.
|
|
234
|
+
*/
|
|
235
|
+
function shared_depth(a, b) {
|
|
236
|
+
const parted = a.findIndex((turn, i) => turn.index !== b[i]?.index);
|
|
237
|
+
return parted === -1 ? a.length : parted;
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* True when the marked step at `s` can run before the gate at `g` with no
|
|
241
|
+
* checkpoint between them that holds the step and not the gate.
|
|
242
|
+
*/
|
|
243
|
+
function runs_before(s, g) {
|
|
244
|
+
const depth = shared_depth(s.trail, g.trail);
|
|
245
|
+
const split_s = s.trail[depth];
|
|
246
|
+
const split_g = g.trail[depth];
|
|
247
|
+
if (split_g === void 0) return false;
|
|
248
|
+
if (split_s === void 0) return true;
|
|
249
|
+
if (!comes_first(split_s.node.kind, split_s.index, split_g.index)) return false;
|
|
250
|
+
return !s.trail.slice(depth + 1).some(({ node }) => node.kind === "checkpoint");
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* The gates each marked node can run before, by node, for every marked node
|
|
254
|
+
* that has any. A gate that appears twice in the tree is listed once.
|
|
255
|
+
*/
|
|
256
|
+
function replay_gates(root) {
|
|
257
|
+
const visits = [];
|
|
258
|
+
walk(root, [], visits);
|
|
259
|
+
const gates = visits.filter(({ node }) => node.kind === "suspend");
|
|
260
|
+
const found = /* @__PURE__ */ new Map();
|
|
261
|
+
for (const visit of visits) {
|
|
262
|
+
if (visit.node.meta?.side_effect !== true) continue;
|
|
263
|
+
const ids = [...new Set(gates.filter((gate) => runs_before(visit, gate)).map(({ node }) => node.id))];
|
|
264
|
+
if (ids.length > 0) found.set(visit.node, ids);
|
|
265
|
+
}
|
|
266
|
+
return found;
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* Every step marked `side_effect` that a resumed run can run again before one
|
|
270
|
+
* of the flow's gates, in flow order. A step that appears twice in the tree
|
|
271
|
+
* gets one hint, with the gates of both places.
|
|
272
|
+
*/
|
|
273
|
+
function find_replays(root) {
|
|
274
|
+
const by_id = /* @__PURE__ */ new Map();
|
|
275
|
+
for (const [node, gates] of replay_gates(root)) {
|
|
276
|
+
const seen = by_id.get(node.id);
|
|
277
|
+
by_id.set(node.id, {
|
|
278
|
+
id: node.id,
|
|
279
|
+
label: label_of(node).label,
|
|
280
|
+
gates: seen === void 0 ? gates : [.../* @__PURE__ */ new Set([...seen.gates, ...gates])]
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
return [...by_id.values()];
|
|
284
|
+
}
|
|
285
|
+
//#endregion
|
|
138
286
|
//#region src/core/diagram.ts
|
|
139
287
|
/**
|
|
140
288
|
* The renderer behind `describe.diagram(step)`: a flow drawn as an annotated
|
|
@@ -151,8 +299,9 @@ function is_step_kind(value) {
|
|
|
151
299
|
* parallel member's key, a chain's stages), never from a config dump.
|
|
152
300
|
* Descriptions share one column after the widest row. A composer's description
|
|
153
301
|
* follows its kind (`branch: ...`), and a node without one shows its kind.
|
|
302
|
+
* With `replays` set, a step that a resumed run can run again before a gate
|
|
303
|
+
* ends its description with the gates it runs before.
|
|
154
304
|
*/
|
|
155
|
-
const CHOSEN_ID_KINDS = /* @__PURE__ */ new Set(["step", "suspend"]);
|
|
156
305
|
const BRANCH_ROLES = ["then", "else"];
|
|
157
306
|
const STAGE_PREFIX = "stage:";
|
|
158
307
|
const COLUMN_GAP = 2;
|
|
@@ -162,7 +311,7 @@ const COLUMN_GAP = 2;
|
|
|
162
311
|
*/
|
|
163
312
|
function render_diagram(root, options) {
|
|
164
313
|
const rows = [];
|
|
165
|
-
flatten(to_item(root, void 0), "", "", rows);
|
|
314
|
+
flatten(to_item(root, void 0, options?.replays === true ? replay_gates(root) : /* @__PURE__ */ new Map()), "", "", rows);
|
|
166
315
|
const column = Math.max(...rows.map((row) => row.lead.length + row.head.length)) + COLUMN_GAP;
|
|
167
316
|
const prefix = options?.prefix ?? "";
|
|
168
317
|
const limit = options?.width === void 0 ? Number.POSITIVE_INFINITY : options.width - prefix.length - column;
|
|
@@ -212,41 +361,20 @@ function wrap(words, limit) {
|
|
|
212
361
|
* Convert one node into the item the layout draws. `role` is the name the
|
|
213
362
|
* parent gives this child, and it is dropped when it only repeats the label.
|
|
214
363
|
*/
|
|
215
|
-
function to_item(node, role) {
|
|
364
|
+
function to_item(node, role, marks) {
|
|
216
365
|
const { label, by_kind } = label_of(node);
|
|
217
366
|
return {
|
|
218
367
|
head: role === void 0 || role === label ? label : `${role} ${label}`,
|
|
219
|
-
note: note_of(node, by_kind),
|
|
220
|
-
children: child_items(node)
|
|
221
|
-
};
|
|
222
|
-
}
|
|
223
|
-
/**
|
|
224
|
-
* Pick a node's label: its display name, else an id its author chose, else
|
|
225
|
-
* its kind. `by_kind` reports the last case, where the kind already shows.
|
|
226
|
-
*/
|
|
227
|
-
function label_of(node) {
|
|
228
|
-
const display = resolve_display_name(node, "");
|
|
229
|
-
if (display !== "") return {
|
|
230
|
-
label: display,
|
|
231
|
-
by_kind: false
|
|
232
|
-
};
|
|
233
|
-
if (has_chosen_id(node)) return {
|
|
234
|
-
label: node.id,
|
|
235
|
-
by_kind: false
|
|
236
|
-
};
|
|
237
|
-
return {
|
|
238
|
-
label: node.kind,
|
|
239
|
-
by_kind: true
|
|
368
|
+
note: [...note_of(node, by_kind), ...replay_note(marks.get(node))],
|
|
369
|
+
children: child_items(node, marks)
|
|
240
370
|
};
|
|
241
371
|
}
|
|
242
372
|
/**
|
|
243
|
-
*
|
|
244
|
-
*
|
|
245
|
-
* the built-in set belongs to a hand-built step, whose id is its author's.
|
|
373
|
+
* The words that mark a step a resumed run can run again, naming the gates
|
|
374
|
+
* it runs before, or none for a step it can't.
|
|
246
375
|
*/
|
|
247
|
-
function
|
|
248
|
-
|
|
249
|
-
return !is_step_kind(node.kind) || CHOSEN_ID_KINDS.has(node.kind);
|
|
376
|
+
function replay_note(gates) {
|
|
377
|
+
return gates === void 0 ? [] : `(replays before ${gates.join(", ")})`.split(" ");
|
|
250
378
|
}
|
|
251
379
|
/**
|
|
252
380
|
* The words of a row's description column.
|
|
@@ -266,16 +394,16 @@ function note_of(node, by_kind) {
|
|
|
266
394
|
* Convert a node's children, naming each by the role its parent's kind gives
|
|
267
395
|
* it.
|
|
268
396
|
*/
|
|
269
|
-
function child_items(node) {
|
|
397
|
+
function child_items(node, marks) {
|
|
270
398
|
const children = node.children ?? [];
|
|
271
|
-
if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i]));
|
|
272
|
-
if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0));
|
|
399
|
+
if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i], marks));
|
|
400
|
+
if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0, marks));
|
|
273
401
|
if (node.kind === "parallel") {
|
|
274
402
|
const keys = string_list(node.config?.["keys"]);
|
|
275
|
-
return children.map((child, i) => to_item(child, keys[i]));
|
|
403
|
+
return children.map((child, i) => to_item(child, keys[i], marks));
|
|
276
404
|
}
|
|
277
|
-
if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]));
|
|
278
|
-
return children.map((child) => to_item(child, void 0));
|
|
405
|
+
if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]), marks);
|
|
406
|
+
return children.map((child) => to_item(child, void 0, marks));
|
|
279
407
|
}
|
|
280
408
|
/**
|
|
281
409
|
* Convert a chain's children in plan order, nesting the entries after each
|
|
@@ -283,7 +411,7 @@ function child_items(node) {
|
|
|
283
411
|
* encloses them in the trajectory. Children the plan does not account for
|
|
284
412
|
* follow in order, so a node without a plan still draws every child.
|
|
285
413
|
*/
|
|
286
|
-
function staged_items(children, plan) {
|
|
414
|
+
function staged_items(children, plan, marks) {
|
|
287
415
|
const top = [];
|
|
288
416
|
let target = top;
|
|
289
417
|
let next = 0;
|
|
@@ -298,9 +426,9 @@ function staged_items(children, plan) {
|
|
|
298
426
|
} else {
|
|
299
427
|
const child = children[next];
|
|
300
428
|
next += 1;
|
|
301
|
-
if (child !== void 0) target.push(to_item(child, void 0));
|
|
429
|
+
if (child !== void 0) target.push(to_item(child, void 0, marks));
|
|
302
430
|
}
|
|
303
|
-
for (const child of children.slice(next)) target.push(to_item(child, void 0));
|
|
431
|
+
for (const child of children.slice(next)) target.push(to_item(child, void 0, marks));
|
|
304
432
|
return top;
|
|
305
433
|
}
|
|
306
434
|
/**
|
|
@@ -453,6 +581,10 @@ function is_step(value) {
|
|
|
453
581
|
* `describe.diagram(step)` draws the `describe.json` tree as an annotated
|
|
454
582
|
* box-drawing diagram (see diagram.ts).
|
|
455
583
|
*
|
|
584
|
+
* `describe.replays(step)` reads the same tree for the steps marked
|
|
585
|
+
* `side_effect` that a resumed run can run again before it reaches a gate
|
|
586
|
+
* (see replays.ts).
|
|
587
|
+
*
|
|
456
588
|
* Both forms detect cycles. Under the default (loose) mode, back-references
|
|
457
589
|
* render as `<cycle>(id)` in text and `{ kind: '<cycle>', id }` in JSON. Under
|
|
458
590
|
* `{ strict: true }`, cycles throw `describe_cycle_error`.
|
|
@@ -482,12 +614,22 @@ function describe_diagram(root, options) {
|
|
|
482
614
|
return render_diagram(describe_json(root, options), options);
|
|
483
615
|
}
|
|
484
616
|
/**
|
|
617
|
+
* Find the steps marked `side_effect` that a resumed run can run again before
|
|
618
|
+
* it reaches a gate. Like the diagram, it reads the `describe.json` tree, so
|
|
619
|
+
* it judges the flow's shape and runs nothing.
|
|
620
|
+
*/
|
|
621
|
+
function describe_replays(root, options) {
|
|
622
|
+
return find_replays(describe_json(root, options));
|
|
623
|
+
}
|
|
624
|
+
/**
|
|
485
625
|
* Public entry point: `describe(step)` for text, `describe.json(step)` for
|
|
486
|
-
* the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram
|
|
626
|
+
* the `FlowNode` tree, `describe.diagram(step)` for the annotated diagram,
|
|
627
|
+
* and `describe.replays(step)` for the steps a resume would pay for twice.
|
|
487
628
|
*/
|
|
488
629
|
const describe = Object.assign(describe_text, {
|
|
489
630
|
json: describe_json,
|
|
490
|
-
diagram: describe_diagram
|
|
631
|
+
diagram: describe_diagram,
|
|
632
|
+
replays: describe_replays
|
|
491
633
|
});
|
|
492
634
|
/**
|
|
493
635
|
* Append one node (label line, config lines, then children) to `lines`.
|
|
@@ -3389,4 +3531,4 @@ register_traced_kind("chain");
|
|
|
3389
3531
|
//#endregion
|
|
3390
3532
|
export { describe_cycle_error as A, is_valid_step_id as C, describe as D, run as E, suspended_error as F, timeout_error as I, STEP_KINDS as L, flow_changed_error as M, resume_validation_error as N, is_step as O, run_not_found_error as P, is_step_kind as R, assert_valid_step_id as S, durable 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, resolve_display_name as z };
|
|
3391
3533
|
|
|
3392
|
-
//# sourceMappingURL=core-
|
|
3534
|
+
//# sourceMappingURL=core-DK7g1Z40.js.map
|