fascicle 0.12.7 → 0.12.9
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 +48 -0
- package/dist/agents.d.ts +1 -1
- package/dist/agents.js +1 -1
- package/dist/{core-CFdEjtiT.js → core-BClsJ3h0.js} +89 -32
- package/dist/core-BClsJ3h0.js.map +1 -0
- package/dist/{engine-DQiQHiy8.js → engine-M0fpGDol.js} +71 -16
- package/dist/engine-M0fpGDol.js.map +1 -0
- package/dist/index.d.ts +98 -10
- package/dist/index.js +40 -7
- package/dist/index.js.map +1 -1
- package/dist/{invoke-eEYMZmWg.js → invoke-ulsp4Oke.js} +3 -3
- package/dist/{invoke-eEYMZmWg.js.map → invoke-ulsp4Oke.js.map} +1 -1
- package/dist/{leading_system-DQmlA6Fs.js → leading_system-B6hsYN90.js} +2 -2
- package/dist/{leading_system-DQmlA6Fs.js.map → leading_system-B6hsYN90.js.map} +1 -1
- package/dist/mcp.d.ts +1 -1
- package/dist/mcp.js +1 -1
- package/dist/stdio.js +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +3 -3
- package/dist/{types-CLigYA62.d.ts → types-B46o3nHw.d.ts} +37 -4
- package/dist/viewer-app/assets/index-BBEYkjnQ.js +2 -0
- package/dist/viewer-app/assets/index-Cev83tcH.css +1 -0
- package/dist/viewer-app/index.html +2 -2
- package/dist/viewer.js +1 -1
- package/package.json +1 -1
- package/dist/core-CFdEjtiT.js.map +0 -1
- package/dist/engine-DQiQHiy8.js.map +0 -1
- package/dist/viewer-app/assets/index-BGb1-MwM.js +0 -2
- package/dist/viewer-app/assets/index-D7kvKs40.css +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,53 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## v0.12.9 — 2026-09-24
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- **`retry` and `fallback` can choose which errors they handle.** A new `when` predicate narrows either composer to the errors worth handling, and an error it rejects propagates untouched, the way a suspend or an abort already did. `retry` doesn't spend another attempt or fire `on_error` on it, and `fallback` never calls its handoff or its backup. That's what a schema failure needs, since a second attempt fails the same way, and it's what a paid provider needs, since every retry costs money.
|
|
8
|
+
|
|
9
|
+
- **`retry` and `fallback` can say how they got their result.** The optional `project` that the envelope composites gained in v0.12.0 now reaches both. `retry` hands it `{ value, attempts, errors }` and `fallback` hands it `{ value, source, primary_error }`, so a flow can archive how many retries a value took, or mark a backup's answer as degraded, without keeping a mutable closure or reading the trajectory back. Leave `project` off and the output is the plain value, as before. It lives in its own `RetryProjection` and `FallbackProjection` types rather than on `RetryConfig` and `FallbackOptions`, so a config annotated with the named type still infers its output from the inner steps.
|
|
10
|
+
|
|
11
|
+
- **`model_call` and `model_step` take an `on_chunk` observer.** It streams the call under a plain `run` and hands the caller that call's chunks, which is what a live terminal renderer wants. The alternative was to drive the whole run through `run.stream`, which tees every token into the trajectory logger (and so into `trajectory.jsonl`) and leaves the consumer to sort chunks back out by `step_id`. Under `run.stream` the observer runs after the `model_chunk` record, never in its place, so abort and the trajectory still belong to the composition layer.
|
|
12
|
+
|
|
13
|
+
- **Every `GenerateResult` reports how long the whole call took.** `StepTiming` brackets one turn's provider round-trip and leaves tools out, so nothing measured a call from end to end, and `claude_cli` steps carried no timing at all. The new `timing` field (`GenerateTiming`, with `started_at` and `duration_ms`) covers every turn, the tools that ran between them, absorbed retries, and schema repair, and the engine stamps it for every adapter, external ones included.
|
|
14
|
+
|
|
15
|
+
- **`throughput()` has a rate for `claude_cli`.** The adapter now reads `duration_api_ms` off the CLI's result event, reports it beside `duration_ms`, and splits it across the run's steps by output tokens (the same split it already used for cost). Each step gets a blended `StepTiming`, so a local model and Claude can be compared in tokens per second on the same terms.
|
|
16
|
+
|
|
17
|
+
- **`claude_cli_reported(result)` reads the CLI's report back typed.** It narrows `provider_reported['claude_cli']` to a `ClaudeCliProviderReported` with a runtime shape check, or returns `undefined`. `ClaudeCliProviderReported` and `GenerateTiming` are exported from the package root now too, so an app that imports from `fascicle` no longer hand-writes either shape.
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
|
|
21
|
+
- **The `run.stream` buffer lost new events once it overflowed.** Past the high-water mark the channel dropped the oldest buffered event and then returned without buffering the new one, so each overflow lost two events while `events_dropped` counted one. Seven events into a buffer of three delivered 3, 5, and 7 with a count of 2. They now deliver 5, 6, and 7 with a count of 4, which is what the documentation always described.
|
|
22
|
+
|
|
23
|
+
### Internal
|
|
24
|
+
|
|
25
|
+
- The docs cover all of the above, with a type-checked retry-then-fallback ladder in the cookbook and a per-call streaming recipe. The `branch` entry in `composition.md` now explains that `unicorn/no-thenable` flags its `then` key as a false positive (the config is never awaited) and how to turn the rule off.
|
|
26
|
+
|
|
27
|
+
- `.gitignore` covers volley's per-run state and the timestamped backups it takes of that state, both of which night-shift runs write into the main checkout.
|
|
28
|
+
|
|
29
|
+
## v0.12.8 — 2026-09-04
|
|
30
|
+
|
|
31
|
+
### Added
|
|
32
|
+
|
|
33
|
+
- **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.
|
|
34
|
+
|
|
35
|
+
### Changed
|
|
36
|
+
|
|
37
|
+
- **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.
|
|
38
|
+
|
|
39
|
+
- **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.
|
|
40
|
+
|
|
41
|
+
### Fixed
|
|
42
|
+
|
|
43
|
+
- **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.
|
|
44
|
+
|
|
45
|
+
### Internal
|
|
46
|
+
|
|
47
|
+
- 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.
|
|
48
|
+
|
|
49
|
+
- 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.
|
|
50
|
+
|
|
3
51
|
## v0.12.7 — 2026-09-01
|
|
4
52
|
|
|
5
53
|
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.
|
package/dist/agents.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { a as Step } from "./types-DBpU27sQ.js";
|
|
2
2
|
import { r as ToolSchema } from "./types-BK0UW28o.js";
|
|
3
|
-
import { a as Engine, i as EffortLevel } from "./types-
|
|
3
|
+
import { a as Engine, i as EffortLevel } from "./types-B46o3nHw.js";
|
|
4
4
|
|
|
5
5
|
//#region src/agents/define_agent.d.ts
|
|
6
6
|
type AgentBuiltPrompt = string | {
|
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-BClsJ3h0.js";
|
|
2
2
|
import { readFileSync } from "node:fs";
|
|
3
3
|
import { fileURLToPath } from "node:url";
|
|
4
4
|
//#region src/agents/define_agent.ts
|
|
@@ -447,7 +447,6 @@ function create_streaming_channel(base, high_water_mark = STREAMING_HIGH_WATER_M
|
|
|
447
447
|
if (buffer.length >= high_water_mark) {
|
|
448
448
|
buffer.shift();
|
|
449
449
|
dropped += 1;
|
|
450
|
-
return;
|
|
451
450
|
}
|
|
452
451
|
buffer.push(event);
|
|
453
452
|
}
|
|
@@ -1469,14 +1468,20 @@ function wait_with_abort(ms, signal, to_error) {
|
|
|
1469
1468
|
/**
|
|
1470
1469
|
* retry: re-run on failure.
|
|
1471
1470
|
*
|
|
1472
|
-
* `retry(inner, { max_attempts, backoff_ms?, max_delay_ms?, jitter?, on_error? })`
|
|
1471
|
+
* `retry(inner, { max_attempts, backoff_ms?, max_delay_ms?, jitter?, when?, on_error?, project? })`
|
|
1473
1472
|
* runs `inner`. If it throws an application error, retries up to
|
|
1474
1473
|
* `max_attempts - 1` more times with exponential backoff
|
|
1475
1474
|
* (`backoff_ms * 2^(attempt-1)`), jittered by up to one `backoff_ms` and
|
|
1476
1475
|
* clamped to `max_delay_ms` (default 30s) through the shared `#policy`
|
|
1477
1476
|
* algebra. `jitter` defaults on: un-jittered concurrent retries stampede in
|
|
1478
|
-
* lockstep. `
|
|
1479
|
-
*
|
|
1477
|
+
* lockstep. `when` decides which application errors are retryable: one it
|
|
1478
|
+
* rejects propagates at once, untouched, without consuming an attempt or
|
|
1479
|
+
* firing `on_error`. `on_error` is called on every retryable failure. The
|
|
1480
|
+
* last error is rethrown if all attempts fail.
|
|
1481
|
+
*
|
|
1482
|
+
* `project` maps the `{ value, attempts, errors }` envelope into the step's
|
|
1483
|
+
* output, so a caller can record how the value was reached without a
|
|
1484
|
+
* mutable closure or a trajectory read. Omitted, the value is the output.
|
|
1480
1485
|
*
|
|
1481
1486
|
* Control-flow signals (`suspended_error`, `aborted_error`) are not failures:
|
|
1482
1487
|
* they propagate immediately without consuming an attempt, firing `on_error`,
|
|
@@ -1516,11 +1521,29 @@ function to_abort_error(reason) {
|
|
|
1516
1521
|
return reason instanceof Error ? reason : new aborted_error("aborted", { reason });
|
|
1517
1522
|
}
|
|
1518
1523
|
/**
|
|
1524
|
+
* Settle one attempt into a value or the error it threw, so the attempt loop
|
|
1525
|
+
* reads as a sequence of decisions instead of a nest of try/catch arms.
|
|
1526
|
+
*/
|
|
1527
|
+
async function settle(attempt) {
|
|
1528
|
+
try {
|
|
1529
|
+
return {
|
|
1530
|
+
ok: true,
|
|
1531
|
+
value: await attempt
|
|
1532
|
+
};
|
|
1533
|
+
} catch (error) {
|
|
1534
|
+
return {
|
|
1535
|
+
ok: false,
|
|
1536
|
+
error
|
|
1537
|
+
};
|
|
1538
|
+
}
|
|
1539
|
+
}
|
|
1540
|
+
/**
|
|
1519
1541
|
* Build a retrying step around `inner`.
|
|
1520
1542
|
*
|
|
1521
1543
|
* Runs `inner` up to `max_attempts` times with exponential backoff between
|
|
1522
|
-
* failures.
|
|
1523
|
-
* control-flow signals propagate
|
|
1544
|
+
* failures. Retryable application errors consume an attempt and fire
|
|
1545
|
+
* `on_error`; control-flow signals and errors `when` rejects propagate
|
|
1546
|
+
* untouched. `project` maps the outcome envelope into the output.
|
|
1524
1547
|
*/
|
|
1525
1548
|
function retry(inner, config) {
|
|
1526
1549
|
if (!Number.isFinite(config.max_attempts)) throw new TypeError(`retry: max_attempts must be a finite number, got ${config.max_attempts}`);
|
|
@@ -1529,27 +1552,32 @@ function retry(inner, config) {
|
|
|
1529
1552
|
const backoff_ms = config.backoff_ms ?? DEFAULT_BACKOFF_MS;
|
|
1530
1553
|
const max_delay_ms = config.max_delay_ms ?? DEFAULT_MAX_DELAY_MS;
|
|
1531
1554
|
const jitter = config.jitter ?? true;
|
|
1555
|
+
const when = config.when;
|
|
1532
1556
|
const on_error = config.on_error;
|
|
1557
|
+
const project = config.project ?? ((r) => r.value);
|
|
1533
1558
|
const backoff_policy = {
|
|
1534
1559
|
initial_delay_ms: backoff_ms,
|
|
1535
1560
|
max_delay_ms,
|
|
1536
1561
|
jitter
|
|
1537
1562
|
};
|
|
1563
|
+
const is_retryable = (err, attempt) => !is_control_flow_error(err) && (when === void 0 || when(err, attempt));
|
|
1538
1564
|
const run_fn = async (input, ctx) => {
|
|
1539
|
-
|
|
1565
|
+
const errors = [];
|
|
1540
1566
|
for (let attempt = 1; attempt <= max_attempts; attempt += 1) {
|
|
1541
1567
|
if (ctx.abort.aborted) throw to_abort_error(ctx.abort.reason);
|
|
1542
|
-
|
|
1543
|
-
|
|
1544
|
-
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1548
|
-
|
|
1549
|
-
|
|
1550
|
-
|
|
1568
|
+
const settled = await settle(dispatch_step(inner, input, ctx));
|
|
1569
|
+
if (settled.ok) return project({
|
|
1570
|
+
value: settled.value,
|
|
1571
|
+
attempts: attempt,
|
|
1572
|
+
errors
|
|
1573
|
+
});
|
|
1574
|
+
if (!is_retryable(settled.error, attempt)) throw settled.error;
|
|
1575
|
+
errors.push(settled.error);
|
|
1576
|
+
if (on_error) on_error(settled.error, attempt);
|
|
1577
|
+
if (attempt >= max_attempts) break;
|
|
1578
|
+
await wait_with_abort(compute_backoff(backoff_policy, attempt - 1), ctx.abort, to_abort_error);
|
|
1551
1579
|
}
|
|
1552
|
-
throw
|
|
1580
|
+
throw errors.at(-1) ?? /* @__PURE__ */ new Error("retry: no attempts executed");
|
|
1553
1581
|
};
|
|
1554
1582
|
const config_meta = {
|
|
1555
1583
|
max_attempts,
|
|
@@ -1557,7 +1585,9 @@ function retry(inner, config) {
|
|
|
1557
1585
|
max_delay_ms,
|
|
1558
1586
|
jitter
|
|
1559
1587
|
};
|
|
1588
|
+
if (when) config_meta["when"] = when;
|
|
1560
1589
|
if (on_error) config_meta["on_error"] = on_error;
|
|
1590
|
+
if (config.project) config_meta["project"] = config.project;
|
|
1561
1591
|
if (config.name !== void 0) config_meta["display_name"] = config.name;
|
|
1562
1592
|
return {
|
|
1563
1593
|
id,
|
|
@@ -1582,7 +1612,13 @@ register_traced_kind("retry");
|
|
|
1582
1612
|
* Control-flow signals (`suspended_error`, `aborted_error`) are not
|
|
1583
1613
|
* failures: they propagate instead of triggering the backup, so a
|
|
1584
1614
|
* human-approval gate is never silently bypassed and the backup never runs
|
|
1585
|
-
* under an aborted context. `handoff` is never called for them.
|
|
1615
|
+
* under an aborted context. `handoff` is never called for them. The `when`
|
|
1616
|
+
* option narrows the set further: a primary error it rejects propagates the
|
|
1617
|
+
* same way, untouched.
|
|
1618
|
+
*
|
|
1619
|
+
* `project` maps the `{ value, source, primary_error }` envelope into the
|
|
1620
|
+
* step's output, so a caller can tell a backup's value from the primary's
|
|
1621
|
+
* without a mutable closure. Omitted, the value is the output.
|
|
1586
1622
|
*/
|
|
1587
1623
|
let fallback_counter = 0;
|
|
1588
1624
|
/**
|
|
@@ -1595,33 +1631,54 @@ function next_id$4() {
|
|
|
1595
1631
|
/**
|
|
1596
1632
|
* Build a primary-or-backup step.
|
|
1597
1633
|
*
|
|
1598
|
-
* Runs `primary`; on an application error runs `backup` with
|
|
1599
|
-
* or with `handoff(input, err)` when the option is set.
|
|
1600
|
-
*
|
|
1634
|
+
* Runs `primary`; on an application error `when` accepts, runs `backup` with
|
|
1635
|
+
* the same input, or with `handoff(input, err)` when the option is set.
|
|
1636
|
+
* Control-flow signals and errors `when` rejects propagate without
|
|
1637
|
+
* triggering the backup or the handoff. `project` maps the outcome envelope
|
|
1638
|
+
* into the output.
|
|
1601
1639
|
*/
|
|
1602
1640
|
function fallback(primary, backup, options) {
|
|
1603
1641
|
const id = next_id$4();
|
|
1642
|
+
const when = options?.when;
|
|
1604
1643
|
const handoff = options?.handoff;
|
|
1644
|
+
const project = options?.project ?? ((r) => r.value);
|
|
1645
|
+
const run_backup = async (input, primary_error, ctx) => {
|
|
1646
|
+
const backup_input = handoff === void 0 ? input : handoff(input, primary_error);
|
|
1647
|
+
try {
|
|
1648
|
+
return await dispatch_step(backup, backup_input, ctx);
|
|
1649
|
+
} catch (backup_err) {
|
|
1650
|
+
if (!is_control_flow_error(backup_err) && backup_err instanceof Error && !("cause" in backup_err)) backup_err.cause = primary_error;
|
|
1651
|
+
throw backup_err;
|
|
1652
|
+
}
|
|
1653
|
+
};
|
|
1605
1654
|
const run_fn = async (input, ctx) => {
|
|
1655
|
+
let value;
|
|
1606
1656
|
try {
|
|
1607
|
-
|
|
1657
|
+
value = await dispatch_step(primary, input, ctx);
|
|
1608
1658
|
} catch (err) {
|
|
1609
1659
|
if (is_control_flow_error(err)) throw err;
|
|
1610
|
-
|
|
1611
|
-
|
|
1612
|
-
|
|
1613
|
-
|
|
1614
|
-
|
|
1615
|
-
|
|
1616
|
-
}
|
|
1660
|
+
if (when !== void 0 && !when(err)) throw err;
|
|
1661
|
+
const backup_value = await run_backup(input, err, ctx);
|
|
1662
|
+
return project({
|
|
1663
|
+
value: backup_value,
|
|
1664
|
+
source: "backup",
|
|
1665
|
+
primary_error: err
|
|
1666
|
+
});
|
|
1617
1667
|
}
|
|
1668
|
+
return project({
|
|
1669
|
+
value,
|
|
1670
|
+
source: "primary"
|
|
1671
|
+
});
|
|
1618
1672
|
};
|
|
1619
|
-
const config_meta =
|
|
1673
|
+
const config_meta = {};
|
|
1674
|
+
if (when) config_meta["when"] = when;
|
|
1675
|
+
if (options?.project) config_meta["project"] = options.project;
|
|
1676
|
+
if (options?.name !== void 0) config_meta["display_name"] = options.name;
|
|
1620
1677
|
return {
|
|
1621
1678
|
id,
|
|
1622
1679
|
kind: "fallback",
|
|
1623
1680
|
children: [primary, backup],
|
|
1624
|
-
...config_meta ? { config: config_meta } : {},
|
|
1681
|
+
...Object.keys(config_meta).length > 0 ? { config: config_meta } : {},
|
|
1625
1682
|
run: run_fn
|
|
1626
1683
|
};
|
|
1627
1684
|
}
|
|
@@ -2394,4 +2451,4 @@ register_traced_kind("chain");
|
|
|
2394
2451
|
//#endregion
|
|
2395
2452
|
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 };
|
|
2396
2453
|
|
|
2397
|
-
//# sourceMappingURL=core-
|
|
2454
|
+
//# sourceMappingURL=core-BClsJ3h0.js.map
|