fascicle 0.17.3 → 0.17.5

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,36 @@
1
1
  # Changelog
2
2
 
3
+ ## v0.17.5 — 2026-10-31
4
+
5
+ ### Changed
6
+
7
+ - **A 4xx on the `ai_sdk` transport throws the typed error that the native transport throws, and says what to do.** A 401, a 403, a 404, or a 400 reached you as the AI SDK's own `APICallError`, with no Fascicle wording, because the engine's classifier read only a 429, a 5xx, or a network code. So a wrong key or a wrong model id, the first error a new user meets, was the one that said least, and the two transports disagreed on what to catch, since the native one already threw `provider_auth_error` and `provider_error`. Now a 401 throws `provider_auth_error`, and any other 4xx throws `provider_error` with `status` and `body`. Each has the SDK's error as its `cause` and the message that the native transport builds for the status, such as `anthropic authentication failed (401): invalid x-api-key: check providers.anthropic.api_key`. The message takes the provider's text from the response body, so a Bedrock 403 no longer starts with `undefined:`. The `ollama` adapter lifts the status that its package keeps on the error's `cause`, so a missing model says `run ollama pull nope` on this transport too. `provider_auth_error` gains `cause`. A 429, a 5xx, and a network failure retry as they did. Code that read `statusCode` or `responseBody` off the raw error reads `status` and `body` off the typed one now, or the same fields off its `cause`.
8
+
9
+ ### Fixed
10
+
11
+ - **A native 401, 403, or 404 says what to check.** The native transport put the provider's text after the status and stopped there, so `anthropic authentication failed (401): invalid x-api-key` never said which key to look at, and `ollama API error 404: model 'nope' not found` never said how to get the model. A 401 now names the key, as in `anthropic authentication failed (401): invalid x-api-key: check providers.anthropic.api_key`. The `ollama` and `lmstudio` providers send no credentials, so a 401 from either says to check that `base_url` reaches the server without a proxy that asks for them. A 403 says that the credentials lack access to this model or endpoint. A 404 says to check the model id against the provider's model list and that `base_url` points at its API, and when Ollama names the model it doesn't have, it says `run ollama pull nope` instead. The provider's text keeps its place and loses only the period it ended on, and any other 4xx reads as it did. Code that matched the old message text has to match the new one.
12
+ - **A provider that can't be reached is named with its URL, and the message says what to check.** A refused or failed connection on the native transport read `ollama native: network failure: fetch failed`, which named neither the address nor the fix, and Node's `fetch failed` doesn't even say whether the host refused, timed out, or doesn't resolve. It reads `ollama could not be reached at http://localhost:11434/api/chat: fetch failed (ECONNREFUSED): check base_url, and that the server is running (ollama serve)` now, with the code that the failure carried and the command to start the server for Ollama alone. The URL keeps only its origin and path, in the lead and wherever the failure's own text repeats it, so credentials or a key in its query never reach a log. On the `ai_sdk` transport the same failure names the same URL, from the SDK's error. A connection that drops after the response began says `ollama connection dropped while reading the response: terminated`, since the request reached the server. Both still retry, and an exhausted one keeps its lead, as in `network after 4 attempts: ollama could not be reached at ...`. Code that matched the old message text has to match the new one.
13
+ - **An empty `api_key`, `base_url`, or `region` names the config key to pass and where its value usually comes from.** A provider built without one threw `anthropic provider requires a non-empty api_key`, which said what was missing but not where it goes, or where its value is usually kept. It reads `anthropic provider requires a non-empty api_key: pass providers.anthropic.api_key to create_engine, usually process.env.ANTHROPIC_API_KEY` now, and `ollama provider requires a non-empty base_url: pass providers.ollama.base_url to create_engine, usually http://localhost:11434`, and the same for `openai`, `google`, `openrouter`, `lmstudio`, and the `region` that `bedrock` needs. The engine still reads no environment variable, so the message says to pass the value, and names the variable only as where it usually lives. Code that matched the old message text has to match the new one.
14
+ - **`claude_cli` start-up failures say what to do.** A missing Claude Code failed with Node's own `spawn claude ENOENT`, an auth failure named its `refresh_command` only in the field, so the message never said to log in, and a timeout said `no stdout within 120000ms` without naming the option that sets it. A missing binary now reads `failed to spawn 'claude': spawn claude ENOENT: install Claude Code, or set providers.claude_cli.binary to where it is`, and a missing sandbox wrapper gets the same lead without that advice. An auth failure ends `: run claude auth login`, and the two timeouts name `providers.claude_cli.startup_timeout_ms` and `providers.claude_cli.stall_timeout_ms`. Code that matched the old message text has to match the new one.
15
+ - **A response that isn't the provider's protocol points at `base_url`.** A body of the wrong shape, such as a payload that isn't a JSON object, a chat completion with no choices or no message, a stream frame or event that isn't JSON, or a stream event with no block index, threw a `provider_error` that said what was wrong and stopped, though the usual cause is a `base_url` that points at something else. Each one ends `: check that base_url points at the <provider> API` now, as the error for a body that isn't JSON already did. A hosted OpenAI or OpenRouter response with no usage adds `or use the lmstudio provider for a self-hosted server`, since a local server that speaks the same API often leaves usage out. A malformed tool call reads as it did, since the model wrote it. Code that matched the old message text has to match the new one.
16
+ - **An Ollama failure on the `ai_sdk` transport retries, and names its address, as it does on the native one.** `ai-sdk-ollama` wraps the `ollama` client's error, which keeps the status on its `cause` and names no URL, and fetch's own error, whose code sits a level further down, so the engine read neither. An Ollama 429 or 5xx failed at once with the daemon's text, and a daemon that wasn't running failed at once as `fetch failed`. The adapter now gives a failure before the stream the URL and the status that the AI SDK's own errors carry, and the engine looks for a network code anywhere down an error's chain of causes. All three retry now, and a daemon that isn't running reads `ollama could not be reached at http://localhost:11434/api/chat: fetch failed (ECONNREFUSED): check base_url, and that the server is running (ollama serve)` on both transports. A connection that drops mid-stream retries as it did, and isn't named as a server that couldn't be reached.
17
+ - **A `base_url` that holds a user name or password is refused when the engine is built, without repeating it.** Node's fetch won't send a request to a URL with credentials in it, and its error names the whole URL, so `http://user:sk-secret@gateway/v1` failed at the first call with the secret in the message, as the AI SDK's raw `TypeError` on the `ai_sdk` transport and inside the network failure's detail on the native one, which retried it as well. No built-in adapter could ever send it, so `create_engine` now throws `engine_config_error` for one, with a scheme or without, before any request: `openai provider's base_url holds a user name or password, which fetch refuses to send: take them out of base_url, and pass the key as providers.openai.api_key`, or for `ollama` and `lmstudio`, which send no credentials, a message that says so. An `@` in a path or a query is left alone, and so is a custom provider's `base_url`.
18
+
19
+ ### Internal
20
+
21
+ - **Lesson 6's error table says what the next release prints, and the docs quote the new messages.** The lesson claimed that every message in its table but the last said what to do, which wasn't true of the 401, the network failure, or `spawn claude ENOENT`. Each of those rows now quotes what releases after 0.17.4 print, and the closing paragraph says which messages name the fix and why a 400 passes on the provider's own reason. [troubleshooting.md](./docs/troubleshooting.md#a-provider-could-not-be-reached) gains an entry for a provider that can't be reached, and the auth, `claude_cli`, provider, configuration, and primer pages describe the messages as they read now. The roadmap's Known Issues bullet keeps only the errors that still don't say what to do.
22
+ - **Releases go through the shared `version` plugin, and the roadmap is current to 0.17.4.** The repo's own `/version` skill and `scripts/bump-version.mjs` repeated what the `version` plugin does, and the skill said to draft the release notes from commits, though fix and feature commits here write their entries under `## Unreleased` as they land, so an agent that followed it would have written them twice. `.claude/version.json` now holds the conventions that the script and the skill hard-coded, and `.claude/version.md` keeps what config can't say, such as the `npm-publish` approval that a tag waits on. The roadmap's Shipped list covers 0.17.3 and 0.17.4.
23
+
24
+ ## v0.17.4 — 2026-10-30
25
+
26
+ ### Changed
27
+
28
+ - **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.
29
+
30
+ ### Fixed
31
+
32
+ - **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.
33
+
3
34
  ## v0.17.3 — 2026-10-30
4
35
 
5
36
  ### Added
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.3/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.5/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.
@@ -213,7 +213,8 @@ messages are the real ones.
213
213
  valid model ID`.
214
214
  13. **The engine never reads `process.env`.** Your code reads keys and passes
215
215
  them in. Keep keys in `.env` and run with `pnpm exec tsx --env-file=.env`.
216
- A bad key throws `provider_auth_error`.
216
+ A bad key throws `provider_auth_error`, whose message names the config key
217
+ to check.
217
218
  14. **`create_engine` belongs in one module**, and everything else receives an
218
219
  `Engine`. Dispose engines in `finally`.
219
220
  15. **Run TypeScript with `tsx`.** Local imports end in `.js` under NodeNext
@@ -397,11 +398,11 @@ describe('the calculator', () => {
397
398
 
398
399
  ## Where to Look Next
399
400
 
400
- - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/blueprint.md) for the layout of a growing app.
401
- - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/leaf-arm-spine.md) for choosing a primitive at each
401
+ - [blueprint.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/blueprint.md) for the layout of a growing app.
402
+ - [leaf-arm-spine.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/leaf-arm-spine.md) for choosing a primitive at each
402
403
  layer.
403
- - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/composition.md) for one line on every composer.
404
- - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/cookbook.md) for worked patterns, including tool loops with
404
+ - [composition.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/composition.md) for one line on every composer.
405
+ - [cookbook.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/cookbook.md) for worked patterns, including tool loops with
405
406
  `define_tool`.
406
- - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/testing.md) for the stand-in engines.
407
- - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.3/docs/troubleshooting.md) for errors and their causes.
407
+ - [testing.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/docs/testing.md) for the stand-in engines.
408
+ - [troubleshooting.md](https://github.com/robmclarty/fascicle/blob/v0.17.5/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