fascicle 0.17.2 → 0.17.4

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,25 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.17.4 — 2026-10-30
4
+
5
+ ### Changed
6
+
7
+ - **The default retry policy waits 7 to 10 s before it gives up, not 1.5 to 2.5 s.** `DEFAULT_RETRY` made 3 attempts from a 500 ms base, so a provider that answered 503 for five seconds, which Bedrock does, outlasted it and failed the call that the next try would have answered. It makes 4 attempts from a 1 s base now, with `max_delay_ms` and `retry_on` as they were, so a turn that keeps failing waits 1 to 2 s, 2 to 3 s, and 4 to 5 s before it throws. A call that fails for good takes that much longer to fail, and a call with its own `abort` is still cut off mid-wait. Set `defaults.retry_policy` to keep the old window, or to wait longer still, and see `RetryPolicy` and [configuration.md](./docs/configuration.md#retry-policy) for how the numbers add up.
8
+
9
+ ### Fixed
10
+
11
+ - **A provider failure that runs out of retries says what happened, and keeps its status, its body, and the error it came from.** An exhausted 5xx or 429 threw a `provider_error` or `rate_limit_error` whose message was the provider SDK's alone, so it never said how many attempts it took, and `@ai-sdk/amazon-bedrock` renders a Bedrock 503 as `undefined: Bedrock is unable to process your request.`, since the body has no `type`. The body never reached `provider_error.body` on the `ai_sdk` transport or on a native 429 or 5xx, and neither error had a `cause`, so the SDK's `statusCode` and `responseBody` were gone by the time the error reached you. The message leads with what the retry did now, then the status, then the provider's own message, which comes from the response body's JSON when the AI SDK attached one: `provider_5xx after 4 attempts (status 503): Bedrock is unable to process your request.`, or `provider_5xx left out of retry_on (status 503): ...` for a kind that `retry_on` leaves out. `body` holds the response body, `provider_error.attempts` counts the attempts the way `rate_limit_error.attempts` does, and `cause` is the error the last attempt threw. A failed run's `run_end`, and the `span_end` of each span the error crossed, `engine.generate` and `engine.generate.step` among them, carry `error_status`, `error_attempts`, `error_cause_kind`, and `error_retry_after_ms` beside `error`, so a dashboard can count the 503s that outlasted their retries without parsing a message. The names keep the `error_` prefix so that the error's status stays apart from `run_end`'s own. Code that matched the old message text has to match the new one.
12
+
13
+ ## v0.17.3 — 2026-10-30
14
+
15
+ ### Added
16
+
17
+ - **`fascicle-diagram --outline` prints the plain `describe` outline.** The plain outline that `describe(step)` prints, with each node's kind, id, and config, was only reachable from code, so seeing it meant writing a script. `--outline` prints it from the terminal in place of the diagram, from the same module and export. It takes `--prefix`, and `--width`, `--replays`, and `--internals` with it are usage errors, since only the diagram reads them.
18
+
19
+ ### Internal
20
+
21
+ - **Lesson 7 says why the solver needs a `diagram.ts`, and the roadmap is current to 0.17.2.** The lesson explains that `fascicle-diagram` can't build the solver from `flow.ts`, which wants an engine, or from `main.ts`, which would run it. The roadmap's Shipped list and near-term plans catch up with 0.17.2.
22
+
3
23
  ## v0.17.2 — 2026-10-28
4
24
 
5
25
  ### Changed
package/dist/AGENTS.md CHANGED
@@ -3,7 +3,7 @@
3
3
  This file is for a coding agent (Claude Code, Codex, Cursor, or another) that's
4
4
  working in a project which uses the published `fascicle` package. A person who
5
5
  is learning Fascicle will usually import it from their `CLAUDE.md`, as
6
- [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
6
+ [lesson 0](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/learn/00-set-up.md) shows. Every shape, rule, and error message below
7
7
  was checked against `fascicle` 0.16.3, and against 0.15.0 where the two differ,
8
8
  except what's marked 0.17.0 and later, which was checked against 0.17.0. A rule
9
9
  that a later release changes says what changed.
@@ -79,7 +79,8 @@ Two commands ship in the package: `fascicle-viewer <trajectory.jsonl>` and
79
79
  `fascicle-diagram <module.ts>`, both run with `pnpm exec`. `fascicle-diagram`
80
80
  reads the module's `flow` export, which is either a Step or a function with no
81
81
  arguments that builds one, and it takes `--prefix ' * '`, `--width <n>`, and
82
- `--export <name>`, plus `--internals` after 0.16.3.
82
+ `--export <name>`, plus `--internals` after 0.16.3 and `--outline` after
83
+ 0.17.2, which prints the plain `describe` outline instead of the diagram.
83
84
 
84
85
  ## The Core Vocabulary
85
86
 
@@ -396,11 +397,11 @@ describe('the calculator', () => {
396
397
 
397
398
  ## Where to Look Next
398
399
 
399
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/blueprint.md) for the layout of a growing app.
400
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/leaf-arm-spine.md) for choosing a primitive at each
400
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/blueprint.md) for the layout of a growing app.
401
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/leaf-arm-spine.md) for choosing a primitive at each
401
402
  layer.
402
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/composition.md) for one line on every composer.
403
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/cookbook.md) for worked patterns, including tool loops with
403
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/composition.md) for one line on every composer.
404
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/cookbook.md) for worked patterns, including tool loops with
404
405
  `define_tool`.
405
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/testing.md) for the stand-in engines.
406
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.2/docs/troubleshooting.md) for errors and their causes.
406
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/testing.md) for the stand-in engines.
407
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.4/docs/troubleshooting.md) for errors and their causes.
package/dist/acp.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent } from "./types-CPqLZOEr.js";
2
- import { M as Tool, N as ToolApprovalHandler } from "./types-C7pO0jLq.js";
2
+ import { M as Tool, N as ToolApprovalHandler } from "./types-C23S11Kk.js";
3
3
  import { AgentApp, ClientCapabilities, ContentBlock, SessionUpdate } from "@agentclientprotocol/sdk";
4
4
  //#region src/acp/types.d.ts
5
5
  /**
package/dist/acp.js CHANGED
@@ -1,4 +1,4 @@
1
- import { A as aborted_error, E as run } from "./core-Dwir3pkb.js";
1
+ import { j as aborted_error, w as run } from "./core-Bfzt55Fl.js";
2
2
  import { n as is_record, t as as_record } from "./records-1HU7mWXf.js";
3
3
  import { t as json_schema_to_standard } from "./json_schema_to_standard-C4F4lXHE.js";
4
4
  import { a as read_file_tool, c as resolve_roots, i as is_binary, l as shown_path, n as search_tool, o as contain_writable, r as list_files_tool, s as error_code } from "./search-DjhdMsJ8.js";
package/dist/agents.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { c as Step } from "./types-CPqLZOEr.js";
2
2
  import { r as ToolSchema } from "./types-BK0UW28o.js";
3
- import { l as EffortLevel, u as Engine } from "./types-C7pO0jLq.js";
3
+ import { l as EffortLevel, u as Engine } from "./types-C23S11Kk.js";
4
4
  //#region src/agents/define_agent.d.ts
5
5
  type AgentBuiltPrompt = string | {
6
6
  readonly user: string;
package/dist/agents.js CHANGED
@@ -1,4 +1,4 @@
1
- import { A as aborted_error, b as assert_valid_step_id, y as step } from "./core-Dwir3pkb.js";
1
+ import { _ as step, j as aborted_error, v as assert_valid_step_id } from "./core-Bfzt55Fl.js";
2
2
  import { readFileSync } from "node:fs";
3
3
  import { fileURLToPath } from "node:url";
4
4
  //#region src/agents/define_agent.ts
@@ -1175,6 +1175,65 @@ function same_input_as(first) {
1175
1175
  return (next) => stable_json(next) === snapshot;
1176
1176
  }
1177
1177
  //#endregion
1178
+ //#region src/policy/backoff.ts
1179
+ /**
1180
+ * Compute the delay before retry attempt `attempt`, counted from zero.
1181
+ *
1182
+ * Exponential (`initial_delay_ms * 2^attempt`) plus up to one
1183
+ * `initial_delay_ms` of random jitter when `policy.jitter` is set, clamped to
1184
+ * `max_delay_ms`. The jitter spreads retries from concurrent callers apart so
1185
+ * they don't stampede in lockstep; a `max_delay_ms` of `Infinity` is uncapped.
1186
+ */
1187
+ function compute_backoff(policy, attempt) {
1188
+ const base = policy.initial_delay_ms * 2 ** attempt;
1189
+ const jitter = policy.jitter ? Math.random() * policy.initial_delay_ms : 0;
1190
+ return Math.min(base + jitter, policy.max_delay_ms);
1191
+ }
1192
+ /**
1193
+ * Sleep `ms`, rejecting the moment `signal` fires instead of serving out the
1194
+ * delay, so a pending abort never waits out a backoff.
1195
+ *
1196
+ * A non-positive `ms` resolves without arming a timer or consulting `signal`.
1197
+ * The rejection value is `to_error` applied to `signal.reason`.
1198
+ */
1199
+ function wait_with_abort(ms, signal, to_error) {
1200
+ if (ms <= 0) return Promise.resolve();
1201
+ return new Promise((resolve, reject) => {
1202
+ if (signal.aborted) {
1203
+ reject(to_error(signal.reason));
1204
+ return;
1205
+ }
1206
+ const timer = setTimeout(() => {
1207
+ signal.removeEventListener("abort", on_abort);
1208
+ resolve();
1209
+ }, ms);
1210
+ const on_abort = () => {
1211
+ clearTimeout(timer);
1212
+ reject(to_error(signal.reason));
1213
+ };
1214
+ signal.addEventListener("abort", on_abort, { once: true });
1215
+ });
1216
+ }
1217
+ //#endregion
1218
+ //#region src/policy/failure_meta.ts
1219
+ /**
1220
+ * Read `status`, `attempts`, `cause_kind`, and `retry_after_ms` off `err`
1221
+ * into their `error_` fields, keeping each only when it is present.
1222
+ */
1223
+ function failure_meta(err) {
1224
+ const meta = {};
1225
+ if (err === null || typeof err !== "object") return meta;
1226
+ const status = Reflect.get(err, "status");
1227
+ if (typeof status === "number") meta.error_status = status;
1228
+ const attempts = Reflect.get(err, "attempts");
1229
+ if (typeof attempts === "number") meta.error_attempts = attempts;
1230
+ const cause_kind = Reflect.get(err, "cause_kind");
1231
+ if (typeof cause_kind === "string") meta.error_cause_kind = cause_kind;
1232
+ const retry_after_ms = Reflect.get(err, "retry_after_ms");
1233
+ if (typeof retry_after_ms === "number") meta.error_retry_after_ms = retry_after_ms;
1234
+ return meta;
1235
+ }
1236
+ //#endregion
1178
1237
  //#region src/core/runner.ts
1179
1238
  /**
1180
1239
  * Runner.
@@ -1299,6 +1358,9 @@ function track_resumed_gates(run_id, resume_data) {
1299
1358
  * carry, so a consumer can classify a failure without regex-matching the
1300
1359
  * message. `error_path` is the chain of step ids the error crossed below this
1301
1360
  * point, already accumulated on the error by `prepend_path` as it bubbled up.
1361
+ * `error_status`, `error_attempts`, `error_cause_kind`, and
1362
+ * `error_retry_after_ms` copy what a provider error carries (see
1363
+ * `failure_meta`).
1302
1364
  */
1303
1365
  function error_meta(err) {
1304
1366
  const meta = { error: err instanceof Error ? err.message : String(err) };
@@ -1309,7 +1371,10 @@ function error_meta(err) {
1309
1371
  const path = Reflect.get(err, "path");
1310
1372
  if (Array.isArray(path)) meta["error_path"] = path.filter((v) => typeof v === "string");
1311
1373
  }
1312
- return meta;
1374
+ return {
1375
+ ...meta,
1376
+ ...failure_meta(err)
1377
+ };
1313
1378
  }
1314
1379
  const signal_runs = /* @__PURE__ */ new Set();
1315
1380
  let signal_handler_installed = false;
@@ -2813,46 +2878,6 @@ function pipe(inner, fn, options) {
2813
2878
  }
2814
2879
  register_traced_kind("pipe");
2815
2880
  //#endregion
2816
- //#region src/policy/backoff.ts
2817
- /**
2818
- * Compute the delay before retry attempt `attempt`, counted from zero.
2819
- *
2820
- * Exponential (`initial_delay_ms * 2^attempt`) plus up to one
2821
- * `initial_delay_ms` of random jitter when `policy.jitter` is set, clamped to
2822
- * `max_delay_ms`. The jitter spreads retries from concurrent callers apart so
2823
- * they don't stampede in lockstep; a `max_delay_ms` of `Infinity` is uncapped.
2824
- */
2825
- function compute_backoff(policy, attempt) {
2826
- const base = policy.initial_delay_ms * 2 ** attempt;
2827
- const jitter = policy.jitter ? Math.random() * policy.initial_delay_ms : 0;
2828
- return Math.min(base + jitter, policy.max_delay_ms);
2829
- }
2830
- /**
2831
- * Sleep `ms`, rejecting the moment `signal` fires instead of serving out the
2832
- * delay, so a pending abort never waits out a backoff.
2833
- *
2834
- * A non-positive `ms` resolves without arming a timer or consulting `signal`.
2835
- * The rejection value is `to_error` applied to `signal.reason`.
2836
- */
2837
- function wait_with_abort(ms, signal, to_error) {
2838
- if (ms <= 0) return Promise.resolve();
2839
- return new Promise((resolve, reject) => {
2840
- if (signal.aborted) {
2841
- reject(to_error(signal.reason));
2842
- return;
2843
- }
2844
- const timer = setTimeout(() => {
2845
- signal.removeEventListener("abort", on_abort);
2846
- resolve();
2847
- }, ms);
2848
- const on_abort = () => {
2849
- clearTimeout(timer);
2850
- reject(to_error(signal.reason));
2851
- };
2852
- signal.addEventListener("abort", on_abort, { once: true });
2853
- });
2854
- }
2855
- //#endregion
2856
2881
  //#region src/core/retry.ts
2857
2882
  /**
2858
2883
  * retry: re-run on failure.
@@ -3920,6 +3945,6 @@ function chain(input_name) {
3920
3945
  }
3921
3946
  register_traced_kind("chain");
3922
3947
  //#endregion
3923
- export { aborted_error as A, STEP_KINDS as B, durable as C, same_input_as as D, run as E, gate_result_error as F, resolve_display_name as H, resume_validation_error as I, run_not_found_error as L, duplicate_suspend_id_error as M, error_path as N, describe as O, flow_changed_error as P, suspended_error as R, suggest_step_id as S, validate_schema as T, is_step_kind as V, parallel as _, suspend as a, assert_valid_step_id as b, loop as c, retry as d, compute_backoff as f, branch as g, map as h, use as i, describe_cycle_error as j, is_step as k, timeout as l, pipe as m, scope as n, checkpoint as o, wait_with_abort as p, stash as r, compose as s, chain as t, fallback as u, sequence as v, format_schema_issues as w, is_valid_step_id as x, step as y, timeout_error as z };
3948
+ export { is_step as A, timeout_error as B, validate_schema as C, wait_with_abort as D, compute_backoff as E, flow_changed_error as F, is_step_kind as H, gate_result_error as I, resume_validation_error as L, describe_cycle_error as M, duplicate_suspend_id_error as N, same_input_as as O, error_path as P, run_not_found_error as R, format_schema_issues as S, failure_meta as T, resolve_display_name as U, STEP_KINDS as V, step as _, suspend as a, suggest_step_id as b, loop as c, retry as d, pipe as f, sequence as g, parallel as h, use as i, aborted_error as j, describe as k, timeout as l, branch as m, scope as n, checkpoint as o, map as p, stash as r, compose as s, chain as t, fallback as u, assert_valid_step_id as v, run as w, durable as x, is_valid_step_id as y, suspended_error as z };
3924
3949
 
3925
- //# sourceMappingURL=core-Dwir3pkb.js.map
3950
+ //# sourceMappingURL=core-Bfzt55Fl.js.map