fascicle 0.12.8 → 0.12.10

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,41 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.12.10 — 2026-09-24
4
+
5
+ ### Fixed
6
+
7
+ - **`throughput()` counted prompt prefill as decode time on the ai_sdk transport.** A streamed step's `first_chunk_ms` was stamped on the first part of the AI SDK's stream, which is the `start` framing the SDK sends before the model has produced a token. The window `throughput()` treats as decode time (`duration_ms - first_chunk_ms`) still held the prefill, so a rate labeled `basis: 'decode'` was really a blended one. A local Ollama step with a 32k-token prompt reported a 9ms time to first chunk. The stamp now lands on the first chunk the turn dispatches, which is the rule the native transport already followed, and the `response_received` event and the OpenTelemetry time-to-first-chunk histogram carry the corrected value too. The same stamp decides when a failure counts as a mid-stream interruption, so an ai_sdk error after the stream opens but before the first token is now retried under the call's retry policy, as it already was on native.
8
+
9
+ ### Internal
10
+
11
+ - Markdown linting skips volley's run state (`.volley/` and its `.volley.bak.*/` backups), which night-shift writes into the main checkout. Git already ignored those folders, but the linter keeps its own ignore list.
12
+
13
+ ## v0.12.9 — 2026-09-24
14
+
15
+ ### Added
16
+
17
+ - **`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.
18
+
19
+ - **`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.
20
+
21
+ - **`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.
22
+
23
+ - **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.
24
+
25
+ - **`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.
26
+
27
+ - **`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.
28
+
29
+ ### Fixed
30
+
31
+ - **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.
32
+
33
+ ### Internal
34
+
35
+ - 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.
36
+
37
+ - `.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.
38
+
3
39
  ## v0.12.8 — 2026-09-04
4
40
 
5
41
  ### Added
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-CLigYA62.js";
3
+ import { a as Engine, i as EffortLevel } from "./types-Dp-tNZPY.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-CFdEjtiT.js";
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. `on_error` is called on every such failure. The last error is
1479
- * rethrown if all attempts fail.
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. Application errors consume an attempt and fire `on_error`;
1523
- * control-flow signals propagate untouched.
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
- let last_err = void 0;
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
- try {
1543
- return await dispatch_step(inner, input, ctx);
1544
- } catch (err) {
1545
- if (is_control_flow_error(err)) throw err;
1546
- last_err = err;
1547
- if (on_error) on_error(err, attempt);
1548
- if (attempt >= max_attempts) break;
1549
- await wait_with_abort(compute_backoff(backoff_policy, attempt - 1), ctx.abort, to_abort_error);
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 last_err ?? /* @__PURE__ */ new Error("retry: no attempts executed");
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 the same input,
1599
- * or with `handoff(input, err)` when the option is set. Control-flow signals
1600
- * propagate without triggering the backup or the handoff.
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
- return await dispatch_step(primary, input, ctx);
1657
+ value = await dispatch_step(primary, input, ctx);
1608
1658
  } catch (err) {
1609
1659
  if (is_control_flow_error(err)) throw err;
1610
- const backup_input = handoff === void 0 ? input : handoff(input, err);
1611
- try {
1612
- return await dispatch_step(backup, backup_input, ctx);
1613
- } catch (backup_err) {
1614
- if (!is_control_flow_error(backup_err) && backup_err instanceof Error && !("cause" in backup_err)) backup_err.cause = err;
1615
- throw backup_err;
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 = options?.name === void 0 ? void 0 : { display_name: options.name };
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-CFdEjtiT.js.map
2454
+ //# sourceMappingURL=core-BClsJ3h0.js.map