fascicle 0.18.1 → 0.19.0

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +27 -1
  3. package/dist/AGENTS.md +11 -10
  4. package/dist/a2a.d.ts +358 -0
  5. package/dist/a2a.js +2234 -0
  6. package/dist/a2a.js.map +1 -0
  7. package/dist/acp.d.ts +120 -9
  8. package/dist/acp.js +927 -154
  9. package/dist/acp.js.map +1 -1
  10. package/dist/adapters-DYFauXE1.js +1147 -0
  11. package/dist/adapters-DYFauXE1.js.map +1 -0
  12. package/dist/adapters.d.ts +124 -36
  13. package/dist/adapters.js +1 -1
  14. package/dist/agents.d.ts +2 -2
  15. package/dist/agents.js +1 -1
  16. package/dist/{core-BH7sWpEG.js → core-xTtRZqdb.js} +217 -99
  17. package/dist/core-xTtRZqdb.js.map +1 -0
  18. package/dist/diagram_bin.js +1 -1
  19. package/dist/durable-CgU0kO2H.d.ts +144 -0
  20. package/dist/{engine-fOjYHcv6.js → engine-B_Yl7acj.js} +128 -42
  21. package/dist/engine-B_Yl7acj.js.map +1 -0
  22. package/dist/index.d.ts +9 -136
  23. package/dist/index.js +6 -5
  24. package/dist/index.js.map +1 -1
  25. package/dist/{invoke-7iu8db6V.js → invoke-Bbk0RuVL.js} +3 -3
  26. package/dist/{invoke-7iu8db6V.js.map → invoke-Bbk0RuVL.js.map} +1 -1
  27. package/dist/{leading_system-BeQUSAim.js → leading_system-m-x7HzbQ.js} +16 -4
  28. package/dist/leading_system-m-x7HzbQ.js.map +1 -0
  29. package/dist/mcp-D1hN5ywq.js +662 -0
  30. package/dist/mcp-D1hN5ywq.js.map +1 -0
  31. package/dist/mcp.d.ts +115 -5
  32. package/dist/mcp.js +2 -2
  33. package/dist/otel.d.ts +1 -1
  34. package/dist/stdio.d.ts +1 -1
  35. package/dist/stdio.js +2 -2
  36. package/dist/testing.d.ts +7 -5
  37. package/dist/testing.js +618 -318
  38. package/dist/testing.js.map +1 -1
  39. package/dist/{types-BUXt_zgJ.d.ts → types-BtRpSctv.d.ts} +38 -5
  40. package/dist/{types-Dk9tLpUq.d.ts → types-CDTW7XWB.d.ts} +2 -2
  41. package/dist/ui.d.ts +2 -2
  42. package/dist/viewer.js +2 -2
  43. package/dist/web.d.ts +1 -1
  44. package/package.json +17 -5
  45. package/dist/adapters-CpKpDk7r.js +0 -461
  46. package/dist/adapters-CpKpDk7r.js.map +0 -1
  47. package/dist/core-BH7sWpEG.js.map +0 -1
  48. package/dist/engine-fOjYHcv6.js.map +0 -1
  49. package/dist/leading_system-BeQUSAim.js.map +0 -1
  50. package/dist/mcp-CHJ88HiG.js +0 -262
  51. package/dist/mcp-CHJ88HiG.js.map +0 -1
@@ -1,4 +1,4 @@
1
- import { A as is_step, k as describe } from "./core-BH7sWpEG.js";
1
+ import { A as is_step, k as describe } from "./core-xTtRZqdb.js";
2
2
  import { createRequire } from "node:module";
3
3
  import { resolve } from "node:path";
4
4
  import { fileURLToPath, pathToFileURL } from "node:url";
@@ -0,0 +1,144 @@
1
+ import { c as Step, h as TrajectoryLogger, m as TrajectoryEvent, n as CheckpointStore, s as ScopedCheckpointStore } from "./types-BtRpSctv.js";
2
+ type RunOptions = {
3
+ readonly install_signal_handlers?: boolean;
4
+ readonly trajectory?: TrajectoryLogger;
5
+ readonly checkpoint_store?: CheckpointStore;
6
+ readonly resume_data?: Readonly<Record<string, unknown>>;
7
+ readonly abort?: AbortSignal;
8
+ /**
9
+ * Record each model call's chunks as `model_chunk` events on the run's
10
+ * trajectory, as `run.stream` does, without the stream. No channel or
11
+ * buffer comes with it, so the chunks reach `trajectory` synchronously and
12
+ * in order. `durable` passes it through; default: false.
13
+ */
14
+ readonly record_chunks?: boolean;
15
+ };
16
+ type StreamingRunHandle<o> = {
17
+ readonly events: AsyncIterable<TrajectoryEvent>;
18
+ readonly result: Promise<o>;
19
+ };
20
+ /**
21
+ * Execute a flow and resolve with its final output.
22
+ */
23
+ declare function run_impl<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): Promise<o>;
24
+ /**
25
+ * Execute a flow while exposing its trajectory events as an async iterable.
26
+ */
27
+ declare function run_stream<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): StreamingRunHandle<o>;
28
+ type RunOutcome<o> = {
29
+ readonly kind: 'done';
30
+ readonly output: o;
31
+ } | {
32
+ readonly kind: 'suspended';
33
+ readonly id: string;
34
+ readonly payload: unknown;
35
+ readonly deadline_ms?: number;
36
+ readonly resume: (data: unknown) => Promise<RunOutcome<o>>;
37
+ };
38
+ /**
39
+ * Execute a flow, reporting suspension as a typed outcome instead of a
40
+ * thrown `suspended_error`.
41
+ *
42
+ * Resolves `{ kind: 'done', output }` on completion. When a `suspend` gate
43
+ * fires, resolves `{ kind: 'suspended', id, payload, resume }` where `id` is
44
+ * the gate's suspend id, `payload` is what the gate raised on its
45
+ * `suspended_error` (plus `deadline_ms`, when the gate set one), and
46
+ * `resume(data)` re-runs the flow from the original
47
+ * input with `resume_data[id] = data` merged over the caller's options: the
48
+ * same full re-run semantics as calling `run` again yourself, so pure
49
+ * prefixes replay and `checkpoint`ed steps are served from the store. The
50
+ * returned promise resolves to the next outcome, so a flow with several
51
+ * gates is driven by awaiting `resume` repeatedly. Real errors still throw,
52
+ * from the initial call and from `resume` alike.
53
+ */
54
+ declare function run_until_suspended<i, o>(flow: Step<i, o>, input: i, options?: RunOptions): Promise<RunOutcome<o>>;
55
+ /**
56
+ * The public entry point for executing a flow.
57
+ *
58
+ * Callable as `run(flow, input, options?)` for a plain result,
59
+ * `run.stream(flow, input, options?)` for `{ events, result }`, or
60
+ * `run.until_suspended(flow, input, options?)` for a `RunOutcome` that
61
+ * carries suspension as data. All share one implementation, so every entry
62
+ * point runs the same graph identically.
63
+ */
64
+ declare const run: typeof run_impl & {
65
+ stream: typeof run_stream;
66
+ until_suspended: typeof run_until_suspended;
67
+ };
68
+ type Claims = Required<Pick<CheckpointStore, 'claim' | 'release'>>;
69
+ type Conditional = Required<Pick<CheckpointStore, 'get_versioned' | 'set_if'>>;
70
+ /**
71
+ * A store `durable` can keep runs in: one that scopes, and whose scopes can
72
+ * claim and can write on a condition (`get_versioned` and `set_if`).
73
+ * `filesystem_store` from `fascicle/adapters` is one for a single machine and
74
+ * `object_store` is one for a fleet. `checkpoint_store_conformance` in
75
+ * `fascicle/testing` checks a store of your own.
76
+ */
77
+ type DurableStore = {
78
+ readonly scope: (prefix: string) => ScopedCheckpointStore & Claims & Conditional;
79
+ };
80
+ type DurableConfig = {
81
+ readonly store: DurableStore;
82
+ /**
83
+ * How long a drive owns its run before another invocation may take it
84
+ * over, in milliseconds. The driver renews the lease every third of this
85
+ * while it drives, so the lease only runs out once a drive stops answering
86
+ * (its process died, or stalled for longer than this). Default 60 seconds.
87
+ */
88
+ readonly lease_ms?: number;
89
+ /**
90
+ * What happens when a run's flow no longer has the shape the run started
91
+ * on. `'fail'` (the default) throws `flow_changed_error`. `'replay'` takes
92
+ * the new shape, records a `flow_changed` event, and drives on.
93
+ */
94
+ readonly on_flow_change?: 'fail' | 'replay';
95
+ };
96
+ /**
97
+ * The `run` options a drive passes through. The driver owns the checkpoint
98
+ * store and the resume data, so it leaves those two out.
99
+ */
100
+ type DurableRunOptions = Omit<RunOptions, 'checkpoint_store' | 'resume_data'>;
101
+ type DurableOutcome<o> = {
102
+ readonly kind: 'done';
103
+ readonly run_id: string;
104
+ readonly output: o;
105
+ } | {
106
+ readonly kind: 'suspended';
107
+ readonly run_id: string;
108
+ readonly id: string;
109
+ readonly payload: unknown;
110
+ readonly deadline_at?: number;
111
+ } | {
112
+ readonly kind: 'busy';
113
+ readonly run_id: string;
114
+ };
115
+ type DurableRunState = Exclude<DurableOutcome<unknown>, {
116
+ readonly kind: 'busy';
117
+ }> | {
118
+ readonly kind: 'running';
119
+ readonly run_id: string;
120
+ } | {
121
+ readonly kind: 'failed';
122
+ readonly run_id: string;
123
+ readonly error: string;
124
+ };
125
+ type DurableRuns = {
126
+ readonly start: <i, o>(run_id: string, flow: Step<i, o>, input: i, options?: DurableRunOptions) => Promise<DurableOutcome<o>>;
127
+ readonly resume: <i, o>(run_id: string, flow: Step<i, o>, resume_data: Readonly<Record<string, unknown>>, options?: DurableRunOptions) => Promise<DurableOutcome<o>>;
128
+ readonly get: (run_id: string) => Promise<DurableRunState | undefined>;
129
+ readonly delete: (run_id: string) => Promise<boolean>;
130
+ };
131
+ /**
132
+ * Keep the runs of flows that suspend in `config.store`, and drive them one
133
+ * event at a time.
134
+ *
135
+ * `start(run_id, flow, input)` begins a run and drives it until it's done or
136
+ * waiting at a gate. `resume(run_id, flow, { [gate]: data })` hands a run
137
+ * the data its gate waits for and drives it on. Both report `busy` instead
138
+ * when another invocation is driving the run, and both are safe to repeat.
139
+ * `get(run_id)` reads where a run stands without driving it, and
140
+ * `delete(run_id)` removes it, resolving false while a drive holds it.
141
+ */
142
+ declare function durable(config: DurableConfig): DurableRuns;
143
+ export { DurableRuns as a, RunOptions as c, run as d, DurableRunState as i, RunOutcome as l, DurableOutcome as n, DurableStore as o, DurableRunOptions as r, durable as s, DurableConfig as t, StreamingRunHandle as u };
144
+ //# sourceMappingURL=durable-CgU0kO2H.d.ts.map
@@ -1,5 +1,5 @@
1
- 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-BeQUSAim.js";
2
- 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-BH7sWpEG.js";
1
+ import { A as on_chunk_error, B as turn_timeout_error, C as resolve_transport, D as engine_disposed_error, E as engine_config_error, F as provider_required_error, I as rate_limit_error, L as schema_validation_error, M as provider_capability_error, N as provider_error, O as incomplete_generation_error, P as provider_not_configured_error, R as tool_approval_denied_error, S as refuse_credentials_in_base_url, T as claude_cli_error, _ as default_normalize_usage, a as image_input_error, b as missing_peer_error, c as map_messages_by_role, d as non_retryable_status_error, f as parse_tool_call_arguments, g as unreachable_message, h as split_assistant_parts, i as error_body_message, j as provider_auth_error, k as model_required_error, l as network_detail, m as read_dialect_init, n as consume_framed_stream, o as invoke_http_turn, p as protocol_error, r as create_line_splitter, t as split_leading_system_run, u as network_failure, v as load_optional_peer, w as translate_effort_to_sdk_reasoning, x as normalize_local_usage, y as missing_config_error, z as tool_error } from "./leading_system-m-x7HzbQ.js";
2
+ 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-xTtRZqdb.js";
3
3
  import { n as is_record$1 } from "./records-Btlmvunj.js";
4
4
  import { join } from "node:path";
5
5
  import { mkdtempSync, writeFileSync } from "node:fs";
@@ -466,10 +466,11 @@ function to_abort_error(reason) {
466
466
  * then the status when the failure had one, then the provider's own message
467
467
  * when it had one, as in `provider_5xx after 4 attempts (status 503): Service
468
468
  * Unavailable`. The lead comes first so the message reads the same whether
469
- * or not the provider said anything.
469
+ * or not the provider said anything. `action`, when the caller has one to
470
+ * offer, closes the message, after whatever the provider said.
470
471
  */
471
- function compose_message(lead, status, message) {
472
- return `${lead}${status === void 0 ? "" : ` (status ${status})`}${message === void 0 ? "" : `: ${message}`}`;
472
+ function compose_message(lead, status, message, action) {
473
+ return `${lead}${status === void 0 ? "" : ` (status ${status})`}${message === void 0 ? "" : `: ${message}`}${action === void 0 ? "" : `: ${action}`}`;
473
474
  }
474
475
  /**
475
476
  * Build the `rate_limit_error` for a 429 that this layer won't retry again.
@@ -477,7 +478,7 @@ function compose_message(lead, status, message) {
477
478
  * recent one a prior attempt carried (`last_rate_limit_after`), and keeps the
478
479
  * failure's original error as its `cause`.
479
480
  */
480
- function build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead) {
481
+ function build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead, action) {
481
482
  const metadata = {
482
483
  attempts: attempt,
483
484
  cause: retryable.cause
@@ -485,7 +486,7 @@ function build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead)
485
486
  if (retryable.retry_after_ms !== void 0) metadata.retry_after_ms = retryable.retry_after_ms;
486
487
  else if (last_rate_limit_after !== void 0) metadata.retry_after_ms = last_rate_limit_after;
487
488
  if (retryable.status !== void 0) metadata.status = retryable.status;
488
- return new rate_limit_error(compose_message(lead, retryable.status, retryable.message), metadata);
489
+ return new rate_limit_error(compose_message(lead, retryable.status, retryable.message, action), metadata);
489
490
  }
490
491
  /**
491
492
  * Build the `provider_error` for a 5xx, network, or timeout failure that this
@@ -493,7 +494,7 @@ function build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead)
493
494
  * onto the `network` cause; only 5xx carries status/body. The failure's
494
495
  * original error is its `cause`.
495
496
  */
496
- function build_provider_error(retryable, attempt, lead) {
497
+ function build_provider_error(retryable, attempt, lead, action) {
497
498
  const metadata = {
498
499
  cause_kind: retryable.kind === "provider_5xx" ? "provider_5xx" : "network",
499
500
  attempts: attempt,
@@ -505,17 +506,18 @@ function build_provider_error(retryable, attempt, lead) {
505
506
  if (status !== void 0) metadata.status = status;
506
507
  if (retryable.body !== void 0) metadata.body = retryable.body;
507
508
  }
508
- return new provider_error(compose_message(lead, status, retryable.message), metadata);
509
+ return new provider_error(compose_message(lead, status, retryable.message, action), metadata);
509
510
  }
510
511
  /**
511
512
  * Map a classified failure that this layer won't retry again onto the error
512
513
  * it rejects with: `rate_limit_error` for 429s, `provider_error` for
513
514
  * everything else, after `attempt` failures in all. `lead` opens the message
514
- * and says why this layer stopped.
515
+ * and says why this layer stopped, and `action`, when given, closes it with
516
+ * what the caller can do.
515
517
  */
516
- function build_typed_error(retryable, attempt, last_rate_limit_after, lead) {
517
- if (retryable.kind === "rate_limit") return build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead);
518
- return build_provider_error(retryable, attempt, lead);
518
+ function build_typed_error(retryable, attempt, last_rate_limit_after, lead, action) {
519
+ if (retryable.kind === "rate_limit") return build_rate_limit_error(retryable, attempt, last_rate_limit_after, lead, action);
520
+ return build_provider_error(retryable, attempt, lead, action);
519
521
  }
520
522
  /**
521
523
  * The error for a failure whose kind `retry_on` leaves out. One that's
@@ -523,11 +525,12 @@ function build_typed_error(retryable, attempt, last_rate_limit_after, lead) {
523
525
  * network failure, is rethrown as it is, so a caller that catches its class
524
526
  * still gets it. A plain record that `classify_provider_error` built becomes
525
527
  * the typed error that exhaustion would have thrown for its kind, so a
526
- * caller never gets a value that prints as `[object Object]`.
528
+ * caller never gets a value that prints as `[object Object]`, and its
529
+ * message closes by naming the kind to add to `retry_on`.
527
530
  */
528
531
  function build_left_out_error(err, retryable, attempt, last_rate_limit_after) {
529
532
  if (err instanceof Error) return err;
530
- return build_typed_error(retryable, attempt, last_rate_limit_after, `${retryable.kind} left out of retry_on`);
533
+ return build_typed_error(retryable, attempt, last_rate_limit_after, `${retryable.kind} left out of retry_on`, `add '${retryable.kind}' to retry.retry_on to retry it`);
531
534
  }
532
535
  /**
533
536
  * The lead of an exhausted failure's message, which counts its attempts.
@@ -822,7 +825,7 @@ function to_user_blocks(content) {
822
825
  if (typeof content === "string") return text_blocks(content);
823
826
  const blocks = [];
824
827
  for (const part of content) {
825
- if (part.type === "image") throw new provider_capability_error("anthropic", "image_input", "image parts are not mapped on the native transport; use transport: 'ai_sdk'");
828
+ if (part.type === "image") throw image_input_error("anthropic");
826
829
  blocks.push(...text_blocks(part.text));
827
830
  }
828
831
  return blocks;
@@ -918,7 +921,7 @@ function to_anthropic_messages(messages) {
918
921
  };
919
922
  for (const message of messages) switch (message.role) {
920
923
  case "system":
921
- if (out.length > 0) throw new provider_capability_error("anthropic", "mid_conversation_system_messages", "the Messages API accepts system text only before the first user/assistant turn");
924
+ if (out.length > 0) throw new provider_capability_error("anthropic", "mid_conversation_system_messages", "the Messages API accepts system text only before the first user/assistant turn: move it to the front of the messages, or send it as a user message");
922
925
  system_parts.push(message.content);
923
926
  break;
924
927
  case "user":
@@ -1644,7 +1647,7 @@ function to_user_content$1(content, provider) {
1644
1647
  if (typeof content === "string") return content;
1645
1648
  const parts = [];
1646
1649
  for (const part of content) {
1647
- if (part.type === "image") throw new provider_capability_error(provider, "image_input", "image parts are not mapped on the native transport; use transport: 'ai_sdk'");
1650
+ if (part.type === "image") throw image_input_error(provider);
1648
1651
  if (part.text.trim().length > 0) parts.push({
1649
1652
  type: "text",
1650
1653
  text: part.text
@@ -2371,7 +2374,7 @@ function to_user_content(content) {
2371
2374
  if (typeof content === "string") return content;
2372
2375
  const parts = [];
2373
2376
  for (const part of content) {
2374
- if (part.type === "image") throw new provider_capability_error("ollama", "image_input", "image parts are not mapped on the native transport; use transport: 'ai_sdk'");
2377
+ if (part.type === "image") throw image_input_error("ollama");
2375
2378
  if (part.text.trim().length > 0) parts.push(part.text);
2376
2379
  }
2377
2380
  return parts.join("\n");
@@ -2770,7 +2773,8 @@ const SUPPORTED$4 = /* @__PURE__ */ new Set([
2770
2773
  "tools",
2771
2774
  "schema",
2772
2775
  "streaming",
2773
- "structured_output"
2776
+ "structured_output",
2777
+ "image_input"
2774
2778
  ]);
2775
2779
  /**
2776
2780
  * Build the Ollama adapter, picking the native or ai_sdk backend per the
@@ -2822,7 +2826,8 @@ const SUPPORTED$3 = /* @__PURE__ */ new Set([
2822
2826
  "tools",
2823
2827
  "schema",
2824
2828
  "streaming",
2825
- "structured_output"
2829
+ "structured_output",
2830
+ "image_input"
2826
2831
  ]);
2827
2832
  /**
2828
2833
  * Build the LM Studio adapter, picking the native or ai_sdk backend per the
@@ -3159,7 +3164,7 @@ const STANDARD_ENV_KEYS = [
3159
3164
  */
3160
3165
  function validate_auth_config(config) {
3161
3166
  if ((config.auth_mode ?? "auto") === "api_key") {
3162
- if ((typeof config.api_key === "string" ? config.api_key : "").length === 0) throw new engine_config_error("api_key is required for auth_mode: api_key", "claude_cli");
3167
+ if ((typeof config.api_key === "string" ? config.api_key : "").length === 0) throw new engine_config_error("claude_cli auth_mode 'api_key' requires a non-empty api_key: pass providers.claude_cli.api_key to create_engine, usually process.env.ANTHROPIC_API_KEY, or set auth_mode to 'oauth' to use the CLI's own login", "claude_cli");
3163
3168
  }
3164
3169
  }
3165
3170
  /**
@@ -4591,6 +4596,17 @@ function blended_step_timings(parsed, turn_usages, now) {
4591
4596
  });
4592
4597
  }
4593
4598
  /**
4599
+ * The message for a run that the CLI itself reported as failed. The CLI's
4600
+ * text is the reason, and it's the CLI's wording, so the lead says who is
4601
+ * speaking. Either way it points at the trajectory, which holds the turns
4602
+ * the CLI ran before it gave up.
4603
+ */
4604
+ function error_result_message(final_text) {
4605
+ const said = final_text.trim();
4606
+ if (said.length > 0) return `claude CLI returned an error result: ${said}: the reason is the CLI's own, and a trajectory on the call shows the turns that led to it`;
4607
+ return "claude CLI returned an error result with no text: retry the call with a trajectory set to see the turns that lead to it";
4608
+ }
4609
+ /**
4594
4610
  * Assemble a `GenerateResult<T>` from a parsed CLI stream.
4595
4611
  *
4596
4612
  * Throws a `claude_cli_error` instead of returning when the CLI reported
@@ -4600,7 +4616,7 @@ function blended_step_timings(parsed, turn_usages, now) {
4600
4616
  */
4601
4617
  function build_generate_result(input) {
4602
4618
  const { parsed, resolved } = input;
4603
- if (parsed.is_error) throw new claude_cli_error("result_error", parsed.final_text.length > 0 ? parsed.final_text : "claude_cli returned an error result");
4619
+ if (parsed.is_error) throw new claude_cli_error("result_error", error_result_message(parsed.final_text));
4604
4620
  const turns = normalize_turns(parsed);
4605
4621
  const now = Date.now();
4606
4622
  const turn_usages = turns.map((t) => ({
@@ -5303,15 +5319,38 @@ function compile_schema(schema) {
5303
5319
  * the run from going ahead, whether Claude Code's own or a wrapper. Returns
5304
5320
  * `undefined` when neither does.
5305
5321
  *
5322
+ * It reads the text alone and never learns which sandbox kind is configured,
5323
+ * so the missing-binary message tells the reader to install what stderr
5324
+ * names, and offers the switch to `claude_code` only to the wrapper kinds.
5325
+ *
5306
5326
  * The bwrap check has to come before the wrapper check: bwrap's own
5307
5327
  * "execvp <binary>: No such file or directory" names bwrap and says the file
5308
5328
  * is missing, so the wrapper check would blame bwrap for the claude binary.
5309
5329
  */
5310
5330
  function classify_sandbox_failure(stderr, reported, snippet, detail) {
5311
5331
  if (CLI_SANDBOX_START_FAILED.test(stderr) || CLI_SANDBOX_START_FAILED.test(reported)) return new claude_cli_error("sandbox_unavailable", `Claude Code's sandbox couldn't start, so the claude_code sandbox stopped the run: on Linux and WSL2 it needs bubblewrap and socat, and native Windows has no sandbox (${detail})`, { stderr_snippet: snippet });
5332
+ const said = snippet.trim();
5312
5333
  const sandboxed_binary = BWRAP_EXEC_MISSING.exec(stderr)?.[1];
5313
- 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 });
5314
- 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 });
5334
+ 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: ${said}: point providers.claude_cli.binary at a claude under one of those, or switch the sandbox to kind: 'claude_code', which wraps nothing`, { stderr_snippet: snippet });
5335
+ 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: ${said}: install the binary that it names and put it on PATH. A providers.claude_cli.sandbox.kind of 'bwrap' or 'greywall' can switch to kind: 'claude_code' instead, which needs no wrapper on macOS and needs bubblewrap and socat on Linux`, { stderr_snippet: snippet });
5336
+ }
5337
+ /**
5338
+ * What to do about a CLI that exited non-zero for a reason Fascicle doesn't
5339
+ * recognize. Running it by hand is the one check that separates a CLI that
5340
+ * can't run at all from one that this call's options upset.
5341
+ */
5342
+ const CLI_EXIT_ACTION = "run `claude -p hello` in the same directory to see whether the CLI works by itself";
5343
+ /**
5344
+ * The error for a CLI that exited 0 without writing its result event, which
5345
+ * leaves no answer, usage, or cost to return. What it wrote to stderr goes
5346
+ * in the message when it wrote anything, since that's the only reason on
5347
+ * offer. A CLI too old to write the stream-json events is the usual cause
5348
+ * that outlasts a retry.
5349
+ */
5350
+ function no_result_error(stderr_snippet) {
5351
+ const said = stderr_snippet.trim();
5352
+ const detail = said.length > 0 ? `: ${said}` : "";
5353
+ return new claude_cli_error("no_result_event", `claude CLI closed without emitting a terminal result event${detail}: retry the call, and if it happens again, run claude update, since an older CLI may not write one`, { stderr_snippet });
5315
5354
  }
5316
5355
  /**
5317
5356
  * Turn a closed CLI subprocess's exit code, signal, stderr, and what its
@@ -5320,8 +5359,10 @@ function classify_sandbox_failure(stderr, reported, snippet, detail) {
5320
5359
  * Checks for an auth failure first, then for a sandbox that stopped the run
5321
5360
  * (Claude Code's own failing to start, a claude binary that bwrap couldn't
5322
5361
  * find inside its sandbox, or a missing wrapper), then falls back to a
5323
- * generic exit-code error. The stderr snippet attached to each error is
5324
- * truncated to 512 bytes.
5362
+ * generic exit-code error, which says so when the CLI printed no reason and
5363
+ * closes with a check to run by hand. The stderr snippet attached to each
5364
+ * error is truncated to 512 bytes and otherwise raw, and the message quotes
5365
+ * it trimmed, so the action never lands on a line of its own.
5325
5366
  *
5326
5367
  * A logged-out CLI says so on stdout and leaves stderr empty: it writes an
5327
5368
  * assistant message with the `authentication_failed` error code and an error
@@ -5331,8 +5372,9 @@ function classify_sandbox_failure(stderr, reported, snippet, detail) {
5331
5372
  */
5332
5373
  function classify_close_error(code, signal, stderr, parsed) {
5333
5374
  const snippet = stderr.slice(0, 512);
5334
- const reported = parsed?.is_error === true ? parsed.final_text.slice(0, 512) : "";
5335
- const detail = snippet.length > 0 ? snippet : reported;
5375
+ const said = snippet.trim();
5376
+ const reported = parsed?.is_error === true ? parsed.final_text.slice(0, 512).trim() : "";
5377
+ const detail = said.length > 0 ? said : reported;
5336
5378
  if (stderr_is_auth_failure(stderr) || parsed?.api_error === "authentication_failed") {
5337
5379
  const reason = detail.length > 0 ? `${detail}: ` : "";
5338
5380
  return new provider_auth_error(PROVIDER_NAME, `claude CLI reported an auth failure: ${reason}run ${CLI_REFRESH_COMMAND}`, { refresh_command: CLI_REFRESH_COMMAND });
@@ -5341,7 +5383,8 @@ function classify_close_error(code, signal, stderr, parsed) {
5341
5383
  if (sandbox_failure !== void 0) return sandbox_failure;
5342
5384
  const status = typeof code === "number" ? code : void 0;
5343
5385
  const signal_part = signal !== null ? ` (signal ${signal})` : "";
5344
- const message = `claude CLI exited with code ${String(code)}${signal_part}: ${detail}`;
5386
+ const reason = detail.length > 0 ? detail : "it printed no reason";
5387
+ const message = `claude CLI exited with code ${String(code)}${signal_part}: ${reason}: ${CLI_EXIT_ACTION}`;
5345
5388
  const metadata = { stderr_snippet: snippet };
5346
5389
  if (status !== void 0) metadata.status = status;
5347
5390
  return new claude_cli_error("subprocess_exit", message, metadata);
@@ -5395,7 +5438,7 @@ async function run_cli(spawn_runtime, args) {
5395
5438
  }
5396
5439
  const parsed = snapshot(state);
5397
5440
  if (close_outcome.code !== 0) throw classify_close_error(close_outcome.code, close_outcome.signal, close_outcome.stderr, parsed);
5398
- if (!parsed.received_result) throw new claude_cli_error("no_result_event", "claude CLI closed without emitting a terminal result event", { stderr_snippet: close_outcome.stderr.slice(0, 512) });
5441
+ if (!parsed.received_result) throw no_result_error(close_outcome.stderr.slice(0, 512));
5399
5442
  return {
5400
5443
  parsed,
5401
5444
  chunks
@@ -5762,7 +5805,7 @@ function list_builtin_providers() {
5762
5805
  */
5763
5806
  function get_provider_factory(name) {
5764
5807
  const factory = BUILTIN_PROVIDERS.get(name);
5765
- if (factory === void 0) throw new engine_config_error(`unknown provider '${name}'; built-in providers are: ${list_builtin_providers().join(", ")}`, name);
5808
+ if (factory === void 0) throw new engine_config_error(`unknown provider '${name}': use a built-in provider (${list_builtin_providers().join(", ")}), or register a factory for '${name}' in custom_providers`, name);
5766
5809
  return factory;
5767
5810
  }
5768
5811
  // src/engine/first_chunk_stamp.ts
@@ -7727,17 +7770,40 @@ function name_unreachable_url(provider, err, record) {
7727
7770
  message: unreachable_message(provider, url, detail)
7728
7771
  };
7729
7772
  }
7773
+ const REFUSED_IMAGE = /image input is not supported|does not support images?\b/i;
7774
+ /**
7775
+ * The capability error for a response that says the model can't take the
7776
+ * image it was sent, or `undefined` for any other failure.
7777
+ *
7778
+ * Ollama answers this with a 500, which would otherwise retry as a
7779
+ * `provider_5xx` until the attempts run out, though no retry can change what
7780
+ * the model takes.
7781
+ */
7782
+ function refused_image(provider, err) {
7783
+ const message = provider_message(err);
7784
+ if (message === void 0 || !REFUSED_IMAGE.test(message)) return void 0;
7785
+ const refusal = new provider_capability_error(provider, "image_input", `the model refused the image (${message}): send it to a model that takes images, or drop the image part`);
7786
+ Object.defineProperty(refusal, "cause", {
7787
+ value: err,
7788
+ enumerable: false
7789
+ });
7790
+ return refusal;
7791
+ }
7730
7792
  /**
7731
7793
  * Build the classifier for one ai_sdk provider. A 429, a 5xx, or a network
7732
7794
  * failure becomes the record classify_provider_error builds for it, with a
7733
7795
  * network failure's message naming the URL, and any other 4xx becomes the
7734
7796
  * typed error the native transport throws, closed over `provider` so that
7735
- * its message can name the config key to check. Anything already classified
7797
+ * its message can name the config key to check. A response that says the
7798
+ * model can't take an image becomes a `provider_capability_error`, whatever
7799
+ * its status. Anything already classified
7736
7800
  * or typed, and anything with no status, passes through as it is.
7737
7801
  */
7738
7802
  function classify_ai_sdk_error(provider) {
7739
7803
  return (err) => {
7740
7804
  if (err === null || typeof err !== "object" || has_retry_kind(err)) return err;
7805
+ const refused = refused_image(provider, err);
7806
+ if (refused !== void 0) return refused;
7741
7807
  const record = classify_retryable(err);
7742
7808
  if (record !== void 0) return name_unreachable_url(provider, err, record);
7743
7809
  if (has_kind(err)) return err;
@@ -7776,6 +7842,16 @@ function arm_turn_timeout(user_abort, turn_timeout_ms) {
7776
7842
  };
7777
7843
  }
7778
7844
  /**
7845
+ * The message for a turn that failed after `on_chunk` had received output.
7846
+ * It says why the engine didn't retry, since a 5xx or a dropped connection
7847
+ * is retried anywhere else, and that the caller can still retry the call as
7848
+ * a whole, which is theirs to decide because their consumer saw the first
7849
+ * part of an answer.
7850
+ */
7851
+ function stream_interrupted_message(detail) {
7852
+ return `stream interrupted: ${detail}: not retried because on_chunk had already received output, so retry the whole call`;
7853
+ }
7854
+ /**
7779
7855
  * Engine-owned wrapper shared by both transports: one turn attempt inside
7780
7856
  * retry_with_policy. The catch ladder classifies by CAUSE, not
7781
7857
  * by the shape the transport happened to throw: on_chunk_error passes through,
@@ -7818,7 +7894,7 @@ function retry_turn(call_once, args, stamp, retry_policy, classify, turn_timeout
7818
7894
  });
7819
7895
  if (has_streamed()) {
7820
7896
  const message = err instanceof Error ? err.message : String(err);
7821
- throw new provider_error(`stream interrupted: ${message}`, {
7897
+ throw new provider_error(stream_interrupted_message(message), {
7822
7898
  cause_kind: "unknown",
7823
7899
  cause: err
7824
7900
  });
@@ -8044,14 +8120,24 @@ function resolve_target(opts_in, engine) {
8044
8120
  };
8045
8121
  }
8046
8122
  /**
8123
+ * What to do about a call option that the resolved adapter can't honor:
8124
+ * drop the option, or send the call to a provider that can. Only a custom
8125
+ * provider reaches it, since every built-in adapter supports all three
8126
+ * capabilities that assert_capabilities checks.
8127
+ */
8128
+ function capability_action(option, capability) {
8129
+ return `drop \`${option}\` from the call, or route it to a provider that supports '${capability}'`;
8130
+ }
8131
+ /**
8047
8132
  * Reject a call that uses a capability the resolved adapter does not
8048
8133
  * implement. Checked up front, before any transport work, so the failure is a
8049
- * typed capability error rather than a mid-call provider rejection.
8134
+ * typed capability error rather than a mid-call provider rejection. Each
8135
+ * error names the call option that asked for the capability.
8050
8136
  */
8051
8137
  function assert_capabilities(adapter, provider, opts, tools_list, on_chunk_provided) {
8052
- if (opts.schema !== void 0 && !adapter.supports("schema")) throw new provider_capability_error(provider, "schema");
8053
- if (tools_list.length > 0 && !adapter.supports("tools")) throw new provider_capability_error(provider, "tools");
8054
- if (on_chunk_provided && !adapter.supports("streaming")) throw new provider_capability_error(provider, "streaming");
8138
+ if (opts.schema !== void 0 && !adapter.supports("schema")) throw new provider_capability_error(provider, "schema", capability_action("schema", "schema"));
8139
+ if (tools_list.length > 0 && !adapter.supports("tools")) throw new provider_capability_error(provider, "tools", capability_action("tools", "tools"));
8140
+ if (on_chunk_provided && !adapter.supports("streaming")) throw new provider_capability_error(provider, "streaming", capability_action("on_chunk", "streaming"));
8055
8141
  }
8056
8142
  /**
8057
8143
  * Read the caching an adapter declares. An `ai_sdk` adapter that declares
@@ -8166,7 +8252,7 @@ async function build_ai_sdk_transport(cfg) {
8166
8252
  const provider_options = combined_provider_options !== void 0 && Object.keys(combined_provider_options).length > 0 ? combined_provider_options : void 0;
8167
8253
  let ai_sdk_invoke_mod;
8168
8254
  try {
8169
- ai_sdk_invoke_mod = await import("./invoke-7iu8db6V.js");
8255
+ ai_sdk_invoke_mod = await import("./invoke-Bbk0RuVL.js");
8170
8256
  } catch (err) {
8171
8257
  throw missing_peer_error("ai", err);
8172
8258
  }
@@ -8643,7 +8729,7 @@ function aggregate_cost(steps, provider) {
8643
8729
  function build_provider_adapters(providers, custom_providers) {
8644
8730
  if (custom_providers !== void 0) {
8645
8731
  const builtins = new Set(list_builtin_providers());
8646
- for (const name of Object.keys(custom_providers)) if (builtins.has(name)) throw new engine_config_error(`custom_providers must not shadow built-in provider '${name}'`, name);
8732
+ for (const name of Object.keys(custom_providers)) if (builtins.has(name)) throw new engine_config_error(`custom_providers must not shadow built-in provider '${name}': register the custom adapter under another name`, name);
8647
8733
  }
8648
8734
  const adapters = /* @__PURE__ */ new Map();
8649
8735
  for (const [name, init] of Object.entries(providers)) {
@@ -8747,7 +8833,7 @@ function build_internals(base, defaults) {
8747
8833
  * still throws `provider_not_configured_error`, but only at call time.
8748
8834
  */
8749
8835
  function create_engine(config) {
8750
- if (config.providers === null || typeof config.providers !== "object") throw new engine_config_error("EngineConfig.providers is required");
8836
+ if (config.providers === null || typeof config.providers !== "object") throw new engine_config_error("EngineConfig.providers is required: pass create_engine({ providers }) an object keyed by provider name, such as { anthropic: { api_key } }");
8751
8837
  const adapters = build_provider_adapters(config.providers, config.custom_providers);
8752
8838
  const pricing = merge_pricing(config.pricing);
8753
8839
  const { default_retry, default_effort, default_max_steps } = resolve_default_scalars(config);
@@ -8807,4 +8893,4 @@ function create_engine(config) {
8807
8893
  }
8808
8894
  export { to_json_schema as n, create_engine as t };
8809
8895
 
8810
- //# sourceMappingURL=engine-fOjYHcv6.js.map
8896
+ //# sourceMappingURL=engine-B_Yl7acj.js.map