fascicle 0.17.4 → 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,26 @@
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
+
3
24
  ## v0.17.4 — 2026-10-30
4
25
 
5
26
  ### 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.4/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.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
+ - [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.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
+ - [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.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.
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.
@@ -1,6 +1,6 @@
1
1
  import { C as validate_schema, D as wait_with_abort, E as compute_backoff, S as format_schema_issues, T as failure_meta, j as aborted_error } from "./core-Bfzt55Fl.js";
2
2
  import { n as is_record$1 } from "./records-1HU7mWXf.js";
3
- import { A as schema_validation_error, C as on_chunk_error, D as provider_not_configured_error, E as provider_error, M as tool_error, N as turn_timeout_error, O as provider_required_error, S as model_required_error, T as provider_capability_error, _ as translate_effort_to_sdk_reasoning, a as invoke_http_turn, b as engine_disposed_error, c as network_failure, d as split_assistant_parts, f as default_normalize_usage, g as resolve_transport, h as normalize_local_usage, i as error_body_message, j as tool_approval_denied_error, k as rate_limit_error, l as parse_tool_call_arguments, m as missing_peer_error, n as consume_framed_stream, p as load_optional_peer, r as create_line_splitter, s as map_messages_by_role, t as split_leading_system_run, u as read_dialect_init, v as claude_cli_error, w as provider_auth_error, x as incomplete_generation_error, y as engine_config_error } from "./leading_system-C23TJ9OQ.js";
3
+ import { A as provider_auth_error, C as translate_effort_to_sdk_reasoning, D as incomplete_generation_error, E as engine_disposed_error, F as rate_limit_error, I as schema_validation_error, L as tool_approval_denied_error, M as provider_error, N as provider_not_configured_error, O as model_required_error, P as provider_required_error, R as tool_error, S as resolve_transport, T as engine_config_error, _ as load_optional_peer, a as invoke_http_turn, b as normalize_local_usage, c as network_detail, d as parse_tool_call_arguments, f as protocol_error, g as default_normalize_usage, h as unreachable_message, i as error_body_message, j as provider_capability_error, k as on_chunk_error, l as network_failure, m as split_assistant_parts, n as consume_framed_stream, p as read_dialect_init, r as create_line_splitter, s as map_messages_by_role, t as split_leading_system_run, u as non_retryable_status_error, v as missing_config_error, w as claude_cli_error, x as refuse_credentials_in_base_url, y as missing_peer_error, z as turn_timeout_error } from "./leading_system-CHSYz0h9.js";
4
4
  import { join } from "node:path";
5
5
  import { mkdtempSync, writeFileSync } from "node:fs";
6
6
  import { tmpdir } from "node:os";
@@ -622,7 +622,7 @@ async function retry_with_policy(fn, policy = DEFAULT_RETRY, abort, on_retry) {
622
622
  try {
623
623
  return await fn(attempt);
624
624
  } catch (err) {
625
- const retryable = classify_retryable(err);
625
+ const retryable = classify_retryable$1(err);
626
626
  if (retryable === void 0) throw err;
627
627
  attempt += 1;
628
628
  if (!is_retryable(retryable.kind, policy)) throw build_left_out_error(err, retryable, attempt, last_rate_limit_after);
@@ -717,7 +717,7 @@ function read_retryable(err) {
717
717
  * record names as its `cause`, or the thrown value itself when it is already
718
718
  * an `Error`, such as `turn_timeout_error`.
719
719
  */
720
- function classify_retryable(err) {
720
+ function classify_retryable$1(err) {
721
721
  if (err === null || typeof err !== "object") return void 0;
722
722
  const retryable = read_retryable(err);
723
723
  if (retryable === void 0) return void 0;
@@ -1159,7 +1159,7 @@ function carries_provider_data(parts) {
1159
1159
  * `'stop'` finish, so the loop continues the turn.
1160
1160
  */
1161
1161
  function parse_messages_response(payload) {
1162
- if (payload === null || typeof payload !== "object") throw new provider_error("anthropic native: response payload is not a JSON object");
1162
+ if (payload === null || typeof payload !== "object") throw protocol_error("anthropic", "response payload is not a JSON object");
1163
1163
  const { text_parts, tool_calls, parts } = collect_content_blocks(Reflect.get(payload, "content"));
1164
1164
  const stop_reason = Reflect.get(payload, "stop_reason");
1165
1165
  const result = {
@@ -1206,7 +1206,7 @@ function stream_event_error(event) {
1206
1206
  */
1207
1207
  function read_block_index(event) {
1208
1208
  const index = Reflect.get(event, "index");
1209
- if (typeof index !== "number") throw new provider_error("anthropic native: stream event is missing its block index");
1209
+ if (typeof index !== "number") throw protocol_error("anthropic", "stream event is missing its block index");
1210
1210
  return index;
1211
1211
  }
1212
1212
  /**
@@ -1221,7 +1221,7 @@ function parse_stream_event(data) {
1221
1221
  try {
1222
1222
  return JSON.parse(data);
1223
1223
  } catch {
1224
- throw new provider_error("anthropic native: stream event is not valid JSON");
1224
+ throw protocol_error("anthropic", "stream event is not valid JSON");
1225
1225
  }
1226
1226
  }
1227
1227
  /**
@@ -1475,7 +1475,7 @@ const SUPPORTED$10 = /* @__PURE__ */ new Set([
1475
1475
  */
1476
1476
  const create_anthropic_native_adapter = (init) => {
1477
1477
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
1478
- if (api_key.length === 0) throw new engine_config_error("anthropic provider requires a non-empty api_key", "anthropic");
1478
+ if (api_key.length === 0) throw missing_config_error("anthropic", "api_key", "process.env.ANTHROPIC_API_KEY");
1479
1479
  const base_url = (typeof init.base_url === "string" && init.base_url.length > 0 ? init.base_url : DEFAULT_BASE_URL$2).replace(/\/+$/, "");
1480
1480
  return {
1481
1481
  kind: "native",
@@ -1570,7 +1570,7 @@ const create_anthropic_adapter = (init) => {
1570
1570
  */
1571
1571
  const create_anthropic_ai_sdk_adapter = (init) => {
1572
1572
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
1573
- if (api_key.length === 0) throw new engine_config_error("anthropic provider requires a non-empty api_key", "anthropic");
1573
+ if (api_key.length === 0) throw missing_config_error("anthropic", "api_key", "process.env.ANTHROPIC_API_KEY");
1574
1574
  const base_url = typeof init.base_url === "string" ? init.base_url : void 0;
1575
1575
  return {
1576
1576
  kind: "ai_sdk",
@@ -1833,7 +1833,7 @@ function map_chat_usage(raw, dialect) {
1833
1833
  input_tokens: 0,
1834
1834
  output_tokens: 0
1835
1835
  };
1836
- throw new provider_error(`${dialect.name} native: response is missing its usage object`);
1836
+ throw protocol_error(dialect.name, "response is missing its usage object", "use the lmstudio provider for a self-hosted server");
1837
1837
  }
1838
1838
  const totals = {
1839
1839
  input_tokens: read_number(raw, "prompt_tokens") ?? 0,
@@ -1897,12 +1897,12 @@ function parse_tool_call(raw, provider) {
1897
1897
  * rebuilds this same payload shape from deltas before calling it.
1898
1898
  */
1899
1899
  function parse_chat_completion(payload, dialect) {
1900
- if (payload === null || typeof payload !== "object") throw new provider_error(`${dialect.name} native: response payload is not a JSON object`);
1900
+ if (payload === null || typeof payload !== "object") throw protocol_error(dialect.name, "response payload is not a JSON object");
1901
1901
  const choices = Reflect.get(payload, "choices");
1902
1902
  const choice = Array.isArray(choices) ? choices[0] : void 0;
1903
- if (choice === null || choice === void 0 || typeof choice !== "object") throw new provider_error(`${dialect.name} native: response has no choices`);
1903
+ if (choice === null || choice === void 0 || typeof choice !== "object") throw protocol_error(dialect.name, "response has no choices");
1904
1904
  const message = Reflect.get(choice, "message");
1905
- if (message === null || typeof message !== "object") throw new provider_error(`${dialect.name} native: response choice has no message`);
1905
+ if (message === null || typeof message !== "object") throw protocol_error(dialect.name, "response choice has no message");
1906
1906
  const content = Reflect.get(message, "content");
1907
1907
  const raw_tool_calls = Reflect.get(message, "tool_calls");
1908
1908
  const tool_calls = Array.isArray(raw_tool_calls) ? raw_tool_calls.map((entry) => parse_tool_call(entry, dialect.name)) : [];
@@ -2156,7 +2156,7 @@ function create_chat_stream_aggregator(dialect, step_index, dispatch) {
2156
2156
  try {
2157
2157
  frame = JSON.parse(data);
2158
2158
  } catch {
2159
- throw new provider_error(`${dialect.name} native: stream frame is not valid JSON`);
2159
+ throw protocol_error(dialect.name, "stream frame is not valid JSON");
2160
2160
  }
2161
2161
  if (frame === null || typeof frame !== "object") return;
2162
2162
  const error = Reflect.get(frame, "error");
@@ -2224,7 +2224,7 @@ const SUPPORTED$8 = /* @__PURE__ */ new Set([
2224
2224
  * the mappers above.
2225
2225
  */
2226
2226
  const create_openai_compatible_adapter = (dialect) => {
2227
- if (dialect.auth.kind === "bearer" && dialect.auth.api_key.length === 0) throw new engine_config_error(`${dialect.name} provider requires a non-empty api_key`, dialect.name);
2227
+ if (dialect.auth.kind === "bearer" && dialect.auth.api_key.length === 0) throw missing_config_error(dialect.name, "api_key", `process.env.${dialect.name.toUpperCase()}_API_KEY`);
2228
2228
  const base_url = dialect.base_url.replace(/\/+$/, "");
2229
2229
  const headers = {
2230
2230
  "content-type": "application/json",
@@ -2285,7 +2285,7 @@ const create_openai_adapter = (init) => {
2285
2285
  * `max_completion_tokens` token-limit field, and strict usage (a hosted API
2286
2286
  * omitting usage is a broken response, not a local-runtime quirk). The
2287
2287
  * empty-api_key guard rides on the core, which throws the same
2288
- * `openai provider requires a non-empty api_key` engine_config_error.
2288
+ * engine_config_error as the ai_sdk branch, naming `OPENAI_API_KEY`.
2289
2289
  */
2290
2290
  const create_openai_native_adapter = (init) => {
2291
2291
  const { api_key, base_url } = read_dialect_init(init, DEFAULT_BASE_URL$1);
@@ -2312,7 +2312,7 @@ const create_openai_native_adapter = (init) => {
2312
2312
  */
2313
2313
  const create_openai_ai_sdk_adapter = (init) => {
2314
2314
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2315
- if (api_key.length === 0) throw new engine_config_error("openai provider requires a non-empty api_key", "openai");
2315
+ if (api_key.length === 0) throw missing_config_error("openai", "api_key", "process.env.OPENAI_API_KEY");
2316
2316
  const base_url = typeof init.base_url === "string" ? init.base_url : void 0;
2317
2317
  const organization = typeof init["organization"] === "string" ? init["organization"] : void 0;
2318
2318
  return {
@@ -2353,7 +2353,7 @@ const SUPPORTED$6 = /* @__PURE__ */ new Set([
2353
2353
  */
2354
2354
  const create_google_adapter = (init) => {
2355
2355
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2356
- if (api_key.length === 0) throw new engine_config_error("google provider requires a non-empty api_key", "google");
2356
+ if (api_key.length === 0) throw missing_config_error("google", "api_key", "process.env.GOOGLE_API_KEY");
2357
2357
  const base_url = typeof init.base_url === "string" ? init.base_url : void 0;
2358
2358
  return {
2359
2359
  kind: "ai_sdk",
@@ -2541,9 +2541,9 @@ function parse_ollama_tool_call(raw, ordinal, step_index) {
2541
2541
  * its frames before calling it.
2542
2542
  */
2543
2543
  function parse_ollama_chat(payload, step_index) {
2544
- if (payload === null || typeof payload !== "object") throw new provider_error("ollama native: response payload is not a JSON object");
2544
+ if (payload === null || typeof payload !== "object") throw protocol_error("ollama", "response payload is not a JSON object");
2545
2545
  const message = Reflect.get(payload, "message");
2546
- if (message === null || message === void 0 || typeof message !== "object") throw new provider_error("ollama native: response has no message");
2546
+ if (message === null || message === void 0 || typeof message !== "object") throw protocol_error("ollama", "response has no message");
2547
2547
  const content = Reflect.get(message, "content");
2548
2548
  const raw_tool_calls = Reflect.get(message, "tool_calls");
2549
2549
  const tool_calls = Array.isArray(raw_tool_calls) ? raw_tool_calls.map((entry, ordinal) => parse_ollama_tool_call(entry, ordinal, step_index)) : [];
@@ -2636,7 +2636,7 @@ function create_ollama_stream_aggregator(step_index, dispatch) {
2636
2636
  try {
2637
2637
  frame = JSON.parse(line);
2638
2638
  } catch {
2639
- throw new provider_error("ollama native: stream frame is not valid JSON");
2639
+ throw protocol_error("ollama", "stream frame is not valid JSON");
2640
2640
  }
2641
2641
  if (frame === null || typeof frame !== "object") return;
2642
2642
  const error = Reflect.get(frame, "error");
@@ -2701,7 +2701,7 @@ const SUPPORTED$5 = /* @__PURE__ */ new Set([
2701
2701
  */
2702
2702
  const create_ollama_native_adapter = (init) => {
2703
2703
  const raw_base_url = typeof init.base_url === "string" ? init.base_url : "";
2704
- if (raw_base_url.length === 0) throw new engine_config_error("ollama provider requires a non-empty base_url", "ollama");
2704
+ if (raw_base_url.length === 0) throw missing_config_error("ollama", "base_url", "http://localhost:11434");
2705
2705
  const base_url = raw_base_url.replace(/\/+$/, "");
2706
2706
  return {
2707
2707
  kind: "native",
@@ -2723,6 +2723,44 @@ const create_ollama_native_adapter = (init) => {
2723
2723
  //#endregion
2724
2724
  //#region src/engine/providers/ollama.ts
2725
2725
  /**
2726
+ * Give a failure that `ai-sdk-ollama` raised the `url` and `statusCode` that
2727
+ * the AI SDK's own errors carry. The package wraps the `ollama` client's
2728
+ * error, which keeps the status as `status_code` on the `cause`, and names
2729
+ * no URL, so without these the engine can't retry a 429 or a 5xx, and can't
2730
+ * say which address didn't answer.
2731
+ */
2732
+ function add_request_facts(err, url) {
2733
+ if (err === null || typeof err !== "object") return;
2734
+ const cause = Reflect.get(err, "cause");
2735
+ const status = cause !== null && typeof cause === "object" ? Reflect.get(cause, "status_code") : void 0;
2736
+ Object.assign(err, typeof status === "number" ? {
2737
+ url,
2738
+ statusCode: status
2739
+ } : { url });
2740
+ }
2741
+ /**
2742
+ * The package's model, with a `doStream` whose failures carry the request's
2743
+ * URL and status (see add_request_facts), and everything else read through
2744
+ * to the model itself. Only `doStream` is wrapped, since every engine turn
2745
+ * streams, and only its own rejection, which is a failure before the stream
2746
+ * began. A connection that drops mid-stream reaches the stream as it is, so
2747
+ * it's never named as a server that couldn't be reached.
2748
+ */
2749
+ function with_request_facts(model, url) {
2750
+ if (model === null || typeof model !== "object") return model;
2751
+ const do_stream = Reflect.get(model, "doStream");
2752
+ if (typeof do_stream !== "function") return model;
2753
+ const stream = async (...args) => {
2754
+ try {
2755
+ return await Reflect.apply(do_stream, model, args);
2756
+ } catch (err) {
2757
+ add_request_facts(err, url);
2758
+ throw err;
2759
+ }
2760
+ };
2761
+ return Object.create(model, { doStream: { value: stream } });
2762
+ }
2763
+ /**
2726
2764
  * Ollama has no reasoning-effort control on this transport, so every
2727
2765
  * non-`none` level is reported as ignored and no provider option is emitted.
2728
2766
  */
@@ -2755,16 +2793,18 @@ const create_ollama_adapter = (init) => {
2755
2793
  };
2756
2794
  /**
2757
2795
  * Build the Ollama ai_sdk adapter: validates the required base_url and
2758
- * lazily loads ai-sdk-ollama to build models.
2796
+ * lazily loads ai-sdk-ollama to build models, whose failures before a stream
2797
+ * begins carry the chat URL and the status (see with_request_facts).
2759
2798
  */
2760
2799
  const create_ollama_ai_sdk_adapter = (init) => {
2761
2800
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
2762
- if (base_url.length === 0) throw new engine_config_error("ollama provider requires a non-empty base_url", "ollama");
2801
+ if (base_url.length === 0) throw missing_config_error("ollama", "base_url", "http://localhost:11434");
2802
+ const chat_url = `${base_url.replace(/\/+$/, "")}/api/chat`;
2763
2803
  return {
2764
2804
  kind: "ai_sdk",
2765
2805
  name: "ollama",
2766
2806
  async build_model(model_id) {
2767
- return (await load_optional_peer("ai-sdk-ollama")).createOllama({ baseURL: base_url })(model_id);
2807
+ return with_request_facts((await load_optional_peer("ai-sdk-ollama")).createOllama({ baseURL: base_url })(model_id), chat_url);
2768
2808
  },
2769
2809
  translate_effort: translate_ollama_effort,
2770
2810
  normalize_usage: normalize_ollama_usage,
@@ -2812,7 +2852,7 @@ const create_lmstudio_adapter = (init) => {
2812
2852
  */
2813
2853
  const create_lmstudio_native_adapter = (init) => {
2814
2854
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
2815
- if (base_url.length === 0) throw new engine_config_error("lmstudio provider requires a non-empty base_url", "lmstudio");
2855
+ if (base_url.length === 0) throw missing_config_error("lmstudio", "base_url", "http://localhost:1234/v1");
2816
2856
  return create_openai_compatible_adapter({
2817
2857
  name: "lmstudio",
2818
2858
  base_url,
@@ -2830,7 +2870,7 @@ const create_lmstudio_native_adapter = (init) => {
2830
2870
  */
2831
2871
  const create_lmstudio_ai_sdk_adapter = (init) => {
2832
2872
  const base_url = typeof init.base_url === "string" ? init.base_url : "";
2833
- if (base_url.length === 0) throw new engine_config_error("lmstudio provider requires a non-empty base_url", "lmstudio");
2873
+ if (base_url.length === 0) throw missing_config_error("lmstudio", "base_url", "http://localhost:1234/v1");
2834
2874
  return {
2835
2875
  kind: "ai_sdk",
2836
2876
  name: "lmstudio",
@@ -2902,7 +2942,7 @@ const create_openrouter_adapter = (init) => {
2902
2942
  * the cost OpenRouter reports on every response, and caching only when the
2903
2943
  * call or the engine asks for it, since only Claude models take the field.
2904
2944
  * The empty-api_key guard rides on the core, which throws the same
2905
- * `openrouter provider requires a non-empty api_key` engine_config_error.
2945
+ * engine_config_error as the ai_sdk branch, naming `OPENROUTER_API_KEY`.
2906
2946
  */
2907
2947
  const create_openrouter_native_adapter = (init) => {
2908
2948
  const { api_key, base_url } = read_dialect_init(init, DEFAULT_BASE_URL);
@@ -2935,7 +2975,7 @@ const create_openrouter_native_adapter = (init) => {
2935
2975
  */
2936
2976
  const create_openrouter_ai_sdk_adapter = (init) => {
2937
2977
  const api_key = typeof init.api_key === "string" ? init.api_key : "";
2938
- if (api_key.length === 0) throw new engine_config_error("openrouter provider requires a non-empty api_key", "openrouter");
2978
+ if (api_key.length === 0) throw missing_config_error("openrouter", "api_key", "process.env.OPENROUTER_API_KEY");
2939
2979
  const base_url = typeof init.base_url === "string" ? init.base_url : void 0;
2940
2980
  const http_referer = typeof init["http_referer"] === "string" ? init["http_referer"] : void 0;
2941
2981
  const x_title = typeof init["x_title"] === "string" ? init["x_title"] : void 0;
@@ -2981,7 +3021,7 @@ function read_string(init, key) {
2981
3021
  /** Pull the static fields off init, rejecting a missing or non-string region. */
2982
3022
  function read_static_credentials(init) {
2983
3023
  const region = read_string(init, "region") ?? "";
2984
- if (region.length === 0) throw new engine_config_error("bedrock provider requires a non-empty region", "bedrock");
3024
+ if (region.length === 0) throw missing_config_error("bedrock", "region", "process.env.AWS_REGION");
2985
3025
  return {
2986
3026
  region,
2987
3027
  api_key: read_string(init, "api_key"),
@@ -3076,6 +3116,11 @@ const CLI_AUTH_ERROR_PATTERNS = Object.freeze([
3076
3116
  "oauth token has expired",
3077
3117
  "invalid_api_key"
3078
3118
  ]);
3119
+ /**
3120
+ * The command that logs the CLI in again, which an auth failure's message
3121
+ * names and its `refresh_command` carries.
3122
+ */
3123
+ const CLI_REFRESH_COMMAND = "claude auth login";
3079
3124
  const DEFAULT_SETTING_SOURCES = Object.freeze(["project", "local"]);
3080
3125
  //#endregion
3081
3126
  //#region src/engine/providers/claude_cli/auth.ts
@@ -3392,6 +3437,15 @@ function write_greywall_settings(sandbox) {
3392
3437
  * `shell: false` via argv array form; no value is string-interpolated into
3393
3438
  * argv.
3394
3439
  */
3440
+ /**
3441
+ * The message for a command that couldn't be started: the command, Node's
3442
+ * reason, and, when the claude binary itself is missing, how to install it
3443
+ * or point at it. A sandbox wrapper that's missing gets no such advice,
3444
+ * since installing Claude Code won't help it.
3445
+ */
3446
+ function spawn_failure_message(cmd, reason, detail) {
3447
+ return `failed to spawn '${cmd}': ${detail}${reason === "binary_not_found" ? ": install Claude Code, or set providers.claude_cli.binary to where it is" : ""}`;
3448
+ }
3395
3449
  const ALL_REGISTRIES = /* @__PURE__ */ new Set();
3396
3450
  let exit_handler_installed = false;
3397
3451
  /**
@@ -3450,7 +3504,7 @@ function create_spawn_runtime() {
3450
3504
  child = spawn(args.cmd, [...args.argv], spawn_opts);
3451
3505
  } catch (err) {
3452
3506
  const message = err instanceof Error ? err.message : String(err);
3453
- throw new claude_cli_error(spawn_failure_reason, `failed to spawn '${args.cmd}': ${message}`);
3507
+ throw new claude_cli_error(spawn_failure_reason, spawn_failure_message(args.cmd, spawn_failure_reason, message));
3454
3508
  }
3455
3509
  live_children.add(child);
3456
3510
  let spawn_error;
@@ -3492,14 +3546,14 @@ function create_spawn_runtime() {
3492
3546
  };
3493
3547
  if (args.startup_timeout_ms > 0) startup_timer = setTimeout(() => {
3494
3548
  if (first_stdout_byte_seen) return;
3495
- startup_error = new claude_cli_error("startup_timeout", `no stdout within ${String(args.startup_timeout_ms)}ms`);
3549
+ startup_error = new claude_cli_error("startup_timeout", `no stdout within ${String(args.startup_timeout_ms)}ms: raise providers.claude_cli.startup_timeout_ms if Claude Code needs longer to start`);
3496
3550
  escalate("timeout");
3497
3551
  }, args.startup_timeout_ms);
3498
3552
  const arm_stall_timer = () => {
3499
3553
  if (args.stall_timeout_ms <= 0) return;
3500
3554
  clearTimeout(stall_timer);
3501
3555
  stall_timer = setTimeout(() => {
3502
- stall_error = new claude_cli_error("stall_timeout", `no stdout for ${String(args.stall_timeout_ms)}ms`);
3556
+ stall_error = new claude_cli_error("stall_timeout", `no stdout for ${String(args.stall_timeout_ms)}ms: raise providers.claude_cli.stall_timeout_ms if the model's pauses run longer`);
3503
3557
  escalate("timeout");
3504
3558
  }, args.stall_timeout_ms);
3505
3559
  };
@@ -3543,10 +3597,7 @@ function create_spawn_runtime() {
3543
3597
  stdout_lines,
3544
3598
  wait_close: async () => {
3545
3599
  const outcome = await close_promise;
3546
- if (spawn_error !== void 0) {
3547
- const message = spawn_error.message;
3548
- throw new claude_cli_error(spawn_failure_reason, message);
3549
- }
3600
+ if (spawn_error !== void 0) throw new claude_cli_error(spawn_failure_reason, spawn_failure_message(args.cmd, spawn_failure_reason, spawn_error.message));
3550
3601
  if (startup_error !== void 0) throw startup_error;
3551
3602
  if (stall_error !== void 0) throw stall_error;
3552
3603
  if (terminate_reason === "abort") throw new aborted_error("aborted", { reason: args.abort?.reason });
@@ -5073,7 +5124,10 @@ function classify_close_error(code, signal, stderr, parsed) {
5073
5124
  const snippet = stderr.slice(0, 512);
5074
5125
  const reported = parsed?.is_error === true ? parsed.final_text.slice(0, 512) : "";
5075
5126
  const detail = snippet.length > 0 ? snippet : reported;
5076
- if (stderr_is_auth_failure(stderr) || parsed?.api_error === "authentication_failed") return new provider_auth_error(PROVIDER_NAME, `claude CLI reported an auth failure: ${detail}`, { refresh_command: "claude auth login" });
5127
+ if (stderr_is_auth_failure(stderr) || parsed?.api_error === "authentication_failed") {
5128
+ const reason = detail.length > 0 ? `${detail}: ` : "";
5129
+ return new provider_auth_error(PROVIDER_NAME, `claude CLI reported an auth failure: ${reason}run ${CLI_REFRESH_COMMAND}`, { refresh_command: CLI_REFRESH_COMMAND });
5130
+ }
5077
5131
  const sandboxed_binary = BWRAP_EXEC_MISSING.exec(stderr)?.[1];
5078
5132
  if (sandboxed_binary !== void 0) return new claude_cli_error("binary_not_found", `bwrap ran but found no claude binary at '${sandboxed_binary}' inside its sandbox, which binds only /usr, /bin, /lib, /lib64, and additional_write_paths: ${snippet}`, { stderr_snippet: snippet });
5079
5133
  if (/bwrap|greywall|sandbox/i.test(stderr) && /not found|no such file|enoent/i.test(stderr)) return new claude_cli_error("sandbox_unavailable", `sandbox binary unavailable: ${snippet}`, { stderr_snippet: snippet });
@@ -7370,12 +7424,29 @@ function has_network_code(value) {
7370
7424
  return typeof code === "string" && NETWORK_ERROR_CODES.has(code);
7371
7425
  }
7372
7426
  /**
7373
- * Build the `network` classification when the error or its `cause` carries a
7374
- * known network error code, or `undefined` when neither does. The AI SDK
7375
- * wraps a failed fetch in an `APICallError` whose `cause` holds undici's code.
7427
+ * True when `err`, or any error down its chain of `cause`s, carries a known
7428
+ * network error code. The AI SDK wraps a failed fetch in an `APICallError`
7429
+ * whose `cause` holds undici's code, and `ai-sdk-ollama` wraps fetch's own
7430
+ * `TypeError`, whose `cause` holds it, one level further down. A chain that
7431
+ * leads back to an error already seen ends there.
7432
+ */
7433
+ function has_network_code_in_chain(err) {
7434
+ const seen = /* @__PURE__ */ new Set();
7435
+ let value = err;
7436
+ while (value !== null && typeof value === "object" && !seen.has(value)) {
7437
+ if (has_network_code(value)) return true;
7438
+ seen.add(value);
7439
+ value = Reflect.get(value, "cause");
7440
+ }
7441
+ return false;
7442
+ }
7443
+ /**
7444
+ * Build the `network` classification when the error or an error down its
7445
+ * chain of `cause`s carries a known network error code, or `undefined` when
7446
+ * none does.
7376
7447
  */
7377
7448
  function classify_network_error(err) {
7378
- if (!has_network_code(err) && !has_network_code(Reflect.get(err, "cause"))) return void 0;
7449
+ if (!has_network_code_in_chain(err)) return void 0;
7379
7450
  return with_error_source(err, { kind: "network" });
7380
7451
  }
7381
7452
  /**
@@ -7388,17 +7459,81 @@ function classify_network_error(err) {
7388
7459
  * and the body off `responseBody` or `body` when present, and a known network
7389
7460
  * error code (`ECONNRESET`, `ETIMEDOUT`,
7390
7461
  * `ENOTFOUND`, `ECONNREFUSED`, or undici's `UND_ERR_HEADERS_TIMEOUT`,
7391
- * `UND_ERR_BODY_TIMEOUT`, and `UND_ERR_SOCKET`), on the error or on its
7392
- * `cause`, becomes `network`. Anything else passes through unclassified,
7393
- * which `retry_with_policy` treats as non-retryable.
7462
+ * `UND_ERR_BODY_TIMEOUT`, and `UND_ERR_SOCKET`), on the error or anywhere
7463
+ * down its chain of `cause`s, becomes `network`. Anything else passes through unclassified,
7464
+ * which `retry_with_policy` treats as non-retryable. The ai_sdk transport
7465
+ * runs it inside classify_ai_sdk_error, which also types any other 4xx.
7394
7466
  */
7395
7467
  function classify_provider_error(err) {
7396
7468
  if (err === null || typeof err !== "object") return err;
7397
7469
  if (has_retry_kind(err)) return err;
7470
+ return classify_retryable(err) ?? err;
7471
+ }
7472
+ /**
7473
+ * The record for a failure that retries, a 429, a 5xx, or a known network
7474
+ * code, or `undefined` for any other.
7475
+ */
7476
+ function classify_retryable(err) {
7398
7477
  const status = resolve_error_status(err);
7399
7478
  if (status === 429) return classify_status(err, "rate_limit", status);
7400
7479
  if (status !== void 0 && status >= 500 && status < 600) return classify_status(err, "provider_5xx", status);
7401
- return classify_network_error(err) ?? err;
7480
+ return classify_network_error(err);
7481
+ }
7482
+ /**
7483
+ * True when `err` carries any string `kind`, the mark of a Fascicle typed
7484
+ * error and of every record classify_provider_error builds.
7485
+ */
7486
+ function has_kind(err) {
7487
+ return typeof Reflect.get(err, "kind") === "string";
7488
+ }
7489
+ /**
7490
+ * The typed error for an AI SDK failure whose status says a retry won't
7491
+ * help, any 4xx but the 429 that classify_provider_error claims first, or
7492
+ * `undefined` when the failure carries no such status. It's the error the
7493
+ * native transport throws for the same status, with the SDK's error as its
7494
+ * `cause` and the provider's own message read off the body when the SDK
7495
+ * attached one.
7496
+ */
7497
+ function classify_client_status(provider, err) {
7498
+ const status = resolve_error_status(err);
7499
+ if (status === void 0 || status < 400 || status > 499) return void 0;
7500
+ return non_retryable_status_error(provider, status, provider_message(err) ?? "(no detail)", {
7501
+ body: response_body(err),
7502
+ cause: err
7503
+ });
7504
+ }
7505
+ /**
7506
+ * A network record whose message names the URL that the SDK couldn't reach,
7507
+ * in the words the native transport uses, when the SDK's error carries its
7508
+ * `url`, and the record as it is otherwise. The detail comes from the SDK
7509
+ * error's `cause`, the failure that fetch threw, when it has one, since the
7510
+ * SDK's own message only puts `Cannot connect to API:` in front of it.
7511
+ */
7512
+ function name_unreachable_url(provider, err, record) {
7513
+ const url = Reflect.get(err, "url");
7514
+ if (record["kind"] !== "network" || typeof url !== "string") return record;
7515
+ const detail = network_detail(Reflect.get(err, "cause") ?? err);
7516
+ return {
7517
+ ...record,
7518
+ message: unreachable_message(provider, url, detail)
7519
+ };
7520
+ }
7521
+ /**
7522
+ * Build the classifier for one ai_sdk provider. A 429, a 5xx, or a network
7523
+ * failure becomes the record classify_provider_error builds for it, with a
7524
+ * network failure's message naming the URL, and any other 4xx becomes the
7525
+ * typed error the native transport throws, closed over `provider` so that
7526
+ * its message can name the config key to check. Anything already classified
7527
+ * or typed, and anything with no status, passes through as it is.
7528
+ */
7529
+ function classify_ai_sdk_error(provider) {
7530
+ return (err) => {
7531
+ if (err === null || typeof err !== "object" || has_retry_kind(err)) return err;
7532
+ const record = classify_retryable(err);
7533
+ if (record !== void 0) return name_unreachable_url(provider, err, record);
7534
+ if (has_kind(err)) return err;
7535
+ return classify_client_status(provider, err) ?? err;
7536
+ };
7402
7537
  }
7403
7538
  /**
7404
7539
  * Compose the per-attempt turn signal: the user's abort OR'd with a fresh
@@ -7510,9 +7645,11 @@ function build_step_timing(started_at, stamp) {
7510
7645
  * turn streams; this builder owns only retry and the first-chunk stamp, which
7511
7646
  * it clears as each attempt starts, and which both makes a failure after a
7512
7647
  * chunk reached a consumer a non-retryable interruption and doubles as
7513
- * StepTiming.first_chunk_ms.
7648
+ * StepTiming.first_chunk_ms. Its classifier is classify_ai_sdk_error, closed
7649
+ * over the call's provider.
7514
7650
  */
7515
7651
  function build_ai_sdk_invoke(cfg) {
7652
+ const classify = classify_ai_sdk_error(cfg.provider);
7516
7653
  return async (args) => {
7517
7654
  const stamp = create_first_chunk_stamp();
7518
7655
  const call_once = (turn_abort) => {
@@ -7524,7 +7661,7 @@ function build_ai_sdk_invoke(cfg) {
7524
7661
  observe_chunk: stamp.observe
7525
7662
  });
7526
7663
  };
7527
- return await retry_turn(call_once, args, stamp, cfg.retry_policy, classify_provider_error, cfg.turn_timeout_ms, cfg.trajectory, cfg.on_chunk_provided);
7664
+ return await retry_turn(call_once, args, stamp, cfg.retry_policy, classify, cfg.turn_timeout_ms, cfg.trajectory, cfg.on_chunk_provided);
7528
7665
  };
7529
7666
  }
7530
7667
  /**
@@ -7820,12 +7957,13 @@ async function build_ai_sdk_transport(cfg) {
7820
7957
  const provider_options = combined_provider_options !== void 0 && Object.keys(combined_provider_options).length > 0 ? combined_provider_options : void 0;
7821
7958
  let ai_sdk_invoke_mod;
7822
7959
  try {
7823
- ai_sdk_invoke_mod = await import("./invoke-x5SNh9DV.js");
7960
+ ai_sdk_invoke_mod = await import("./invoke-DnmWf8gE.js");
7824
7961
  } catch (err) {
7825
7962
  throw missing_peer_error("ai", err);
7826
7963
  }
7827
7964
  const { create_ai_sdk_turn } = ai_sdk_invoke_mod;
7828
7965
  return build_ai_sdk_invoke({
7966
+ provider: cfg.target.provider,
7829
7967
  invoke_turn: create_ai_sdk_turn({
7830
7968
  adapter,
7831
7969
  model_id: cfg.target.model_id,
@@ -8290,7 +8428,9 @@ function aggregate_cost(steps, provider) {
8290
8428
  * Each factory validates its init value synchronously, so a bad credential
8291
8429
  * throws here at construction time rather than later; loading the
8292
8430
  * underlying SDK is deferred until the first `generate` call. Throws if
8293
- * `custom_providers` tries to shadow a built-in provider name.
8431
+ * `custom_providers` tries to shadow a built-in provider name, or if a
8432
+ * built-in provider's `base_url` holds credentials, which no built-in
8433
+ * adapter could send.
8294
8434
  */
8295
8435
  function build_provider_adapters(providers, custom_providers) {
8296
8436
  if (custom_providers !== void 0) {
@@ -8300,7 +8440,10 @@ function build_provider_adapters(providers, custom_providers) {
8300
8440
  const adapters = /* @__PURE__ */ new Map();
8301
8441
  for (const [name, init] of Object.entries(providers)) {
8302
8442
  if (init === void 0) continue;
8303
- const adapter = ((custom_providers !== void 0 && Object.hasOwn(custom_providers, name) ? custom_providers[name] : void 0) ?? get_provider_factory(name))(init);
8443
+ const custom = custom_providers !== void 0 && Object.hasOwn(custom_providers, name) ? custom_providers[name] : void 0;
8444
+ const factory = custom ?? get_provider_factory(name);
8445
+ if (custom === void 0) refuse_credentials_in_base_url(name, init);
8446
+ const adapter = factory(init);
8304
8447
  adapters.set(name, adapter);
8305
8448
  }
8306
8449
  return adapters;
@@ -8457,4 +8600,4 @@ function create_engine(config) {
8457
8600
  //#endregion
8458
8601
  export { to_json_schema as n, create_engine as t };
8459
8602
 
8460
- //# sourceMappingURL=engine-CbVdzplI.js.map
8603
+ //# sourceMappingURL=engine-BTijBDlY.js.map