@providerkit/core 0.34.0 → 0.35.1

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 (66) hide show
  1. package/README.md +18 -0
  2. package/dist/decisions.js +1 -1
  3. package/dist/decisions.js.map +1 -1
  4. package/dist/errors.d.ts +2 -7
  5. package/dist/errors.d.ts.map +1 -1
  6. package/dist/errors.js +114 -69
  7. package/dist/errors.js.map +1 -1
  8. package/dist/hosted/anthropic.d.ts +4 -2
  9. package/dist/hosted/anthropic.d.ts.map +1 -1
  10. package/dist/hosted/anthropic.js +7 -6
  11. package/dist/hosted/anthropic.js.map +1 -1
  12. package/dist/index.d.ts +3 -2
  13. package/dist/index.d.ts.map +1 -1
  14. package/dist/index.js +3 -2
  15. package/dist/index.js.map +1 -1
  16. package/dist/providers/anthropic.d.ts.map +1 -1
  17. package/dist/providers/anthropic.js +113 -12
  18. package/dist/providers/anthropic.js.map +1 -1
  19. package/dist/providers/gemini.d.ts.map +1 -1
  20. package/dist/providers/gemini.js +5 -4
  21. package/dist/providers/gemini.js.map +1 -1
  22. package/dist/providers/openai.d.ts +3 -34
  23. package/dist/providers/openai.d.ts.map +1 -1
  24. package/dist/providers/openai.js +10 -40
  25. package/dist/providers/openai.js.map +1 -1
  26. package/dist/providers/openrouter-billing.d.ts +27 -0
  27. package/dist/providers/openrouter-billing.d.ts.map +1 -0
  28. package/dist/providers/openrouter-billing.js +37 -0
  29. package/dist/providers/openrouter-billing.js.map +1 -0
  30. package/dist/providers/responses.d.ts +2 -1
  31. package/dist/providers/responses.d.ts.map +1 -1
  32. package/dist/providers/responses.js +26 -13
  33. package/dist/providers/responses.js.map +1 -1
  34. package/dist/rate-limit.d.ts +11 -8
  35. package/dist/rate-limit.d.ts.map +1 -1
  36. package/dist/rate-limit.js +123 -77
  37. package/dist/rate-limit.js.map +1 -1
  38. package/dist/tools.d.ts +2 -0
  39. package/dist/tools.d.ts.map +1 -1
  40. package/dist/tools.js.map +1 -1
  41. package/dist/transport.d.ts +6 -0
  42. package/dist/transport.d.ts.map +1 -1
  43. package/dist/transport.js +12 -9
  44. package/dist/transport.js.map +1 -1
  45. package/dist/watchdog.d.ts.map +1 -1
  46. package/dist/watchdog.js +4 -1
  47. package/dist/watchdog.js.map +1 -1
  48. package/dist/zod.d.ts +17 -0
  49. package/dist/zod.d.ts.map +1 -1
  50. package/dist/zod.js +34 -14
  51. package/dist/zod.js.map +1 -1
  52. package/package.json +1 -1
  53. package/src/decisions.ts +1 -1
  54. package/src/errors.ts +128 -70
  55. package/src/hosted/anthropic.ts +7 -6
  56. package/src/index.ts +9 -2
  57. package/src/providers/anthropic.ts +124 -12
  58. package/src/providers/gemini.ts +5 -4
  59. package/src/providers/openai.ts +29 -63
  60. package/src/providers/openrouter-billing.ts +42 -0
  61. package/src/providers/responses.ts +29 -15
  62. package/src/rate-limit.ts +132 -79
  63. package/src/tools.ts +2 -0
  64. package/src/transport.ts +14 -13
  65. package/src/watchdog.ts +4 -0
  66. package/src/zod.ts +48 -10
package/src/rate-limit.ts CHANGED
@@ -253,13 +253,6 @@ function windowForMs(ms: number): RateLimitWindow {
253
253
  return "monthly";
254
254
  }
255
255
 
256
- /** A wait read off a body, named as a window once it is long enough to be one. */
257
- function resetAfter(waitMs: number, now: number): RateLimitReset {
258
- const result: RateLimitReset = { retryAfterMs: waitMs, resetAtMs: now + waitMs };
259
- if (waitMs > WINDOW_FLOOR_MS) result.window = windowForMs(waitMs);
260
- return result;
261
- }
262
-
263
256
  /** A finite number off a JSON field, the string form a relay may stringify it
264
257
  * into included. Bare `Number()` is the trap `numeric()` guards against one
265
258
  * layer up: `Number(null)`, `Number("")`, `Number([])` and `Number(false)` are
@@ -279,7 +272,16 @@ const PROSE_RETRY_PATTERNS = [
279
272
  /retry[- ]after[:\s]+(\d+(?:\.\d+)?)\s*(s(?:ec(?:ond)?s?)?|m(?:in(?:ute)?s?)?|h(?:(?:ou)?rs?)?)?/i,
280
273
  ];
281
274
 
275
+ function secondsMs(value: unknown): number | undefined {
276
+ const seconds = jsonSeconds(value);
277
+ if (seconds === undefined || seconds < 0) return undefined;
278
+ const ms = Math.round(seconds * 1000);
279
+ return Number.isFinite(ms) ? ms : undefined;
280
+ }
281
+
282
282
  function parseProseRetryMs(text: string): number | undefined {
283
+ const google = text.match(/\bplease retry in (\d+(?:\.\d+)?)\s*s\b/i);
284
+ if (google) return secondsMs(google[1]);
283
285
  for (const pattern of PROSE_RETRY_PATTERNS) {
284
286
  const match = text.match(pattern);
285
287
  if (!match?.[1]) continue;
@@ -287,76 +289,128 @@ function parseProseRetryMs(text: string): number | undefined {
287
289
  if (!Number.isFinite(val) || val <= 0) continue;
288
290
  const unit = (match[2] ?? "s").toLowerCase();
289
291
  const multiplier = unit.startsWith("h") ? 3_600_000 : unit.startsWith("m") ? 60_000 : 1_000;
290
- return Math.ceil(val * multiplier);
292
+ const ms = Math.ceil(val * multiplier);
293
+ if (Number.isFinite(ms)) return ms;
291
294
  }
292
295
  return undefined;
293
296
  }
294
297
 
295
- /**
296
- * ChatGPT's codex backend puts the reset IN THE 429 BODY, not the headers:
297
- * `{"error":{"type":"usage_limit_reached","resets_at":1788801754,"resets_in_seconds":2501465}}`.
298
- * Other providers and gateways (LiteLLM, Cloudflare, Ollama) report countdowns in prose:
299
- * `Rate limit exceeded. Try again in 20s.`
300
- * The window name is inferred from the wait itself, and only past the floor
301
- * above. A sub-minute retry is a throttle, not a subscription window.
302
- */
303
- export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLimitReset {
304
- let body: unknown;
298
+ /** SDKs may append a serialized reply to a status line. Only the text before it is
299
+ * prose: a partial JSON body cannot tell us which words belong to the provider. */
300
+ function plainMessageDelay(text: string): number | undefined {
301
+ const jsonAt = text.search(/\{|\[/u);
302
+ return parseProseRetryMs(jsonAt < 0 ? text : text.slice(0, jsonAt));
303
+ }
304
+
305
+ function fields(value: unknown): Record<string, unknown> | undefined {
306
+ return value !== null && typeof value === "object" && !Array.isArray(value)
307
+ ? (value as Record<string, unknown>)
308
+ : undefined;
309
+ }
310
+
311
+ interface BodyHints {
312
+ accountAt?: number;
313
+ delay?: number;
314
+ prose?: number;
315
+ }
316
+
317
+ /** A real account reset survives a shorter Retry-After. A guess from prose does not. Keep
318
+ * those sources separate until the headers are known. Never scan a serialized request: a
319
+ * gateway may echo the entire prompt alongside its error. */
320
+ function bodyHints(text: string, now: number): BodyHints {
321
+ let decoded: unknown;
305
322
  try {
306
- body = JSON.parse(bodyText);
323
+ decoded = JSON.parse(text);
307
324
  } catch {
308
- body = undefined;
325
+ return { prose: plainMessageDelay(text) };
309
326
  }
310
-
311
- if (typeof body === "object" && body !== null) {
312
- const source = (body as Record<string, unknown>).error;
313
- const error =
314
- typeof source === "object" && source !== null
315
- ? (source as Record<string, unknown>)
316
- : (body as Record<string, unknown>);
317
-
318
- // OpenCode puts a budget's ISO reset in envelope metadata, or in Google's
319
- // ErrorInfo details. It names the real horizon, not a short retry hint.
320
- const envelopes: unknown[] = [
321
- body,
322
- error,
323
- ...(Array.isArray(error.details) ? error.details : []),
324
- ];
325
- let metadataReset = -Infinity;
326
- for (const envelope of envelopes) {
327
- if (typeof envelope !== "object" || envelope === null || !("metadata" in envelope)) continue;
328
- const metadata = envelope.metadata;
329
- if (
330
- typeof metadata !== "object" ||
331
- metadata === null ||
332
- !("resetsAt" in metadata) ||
333
- typeof metadata.resetsAt !== "string"
334
- )
335
- continue;
336
- const at = Date.parse(metadata.resetsAt);
337
- if (Number.isFinite(at)) metadataReset = Math.max(metadataReset, at);
327
+ if (typeof decoded === "string") return { prose: parseProseRetryMs(decoded) };
328
+ const hints: BodyHints = {};
329
+ for (const row of Array.isArray(decoded) ? decoded : [decoded]) {
330
+ const outer = fields(row);
331
+ if (!outer) continue;
332
+ const error = fields(outer.error) ?? outer;
333
+ const message = typeof outer.error === "string" ? outer.error : error.message;
334
+ if (typeof message === "string") hints.prose ??= parseProseRetryMs(message);
335
+ // Codex's relative reset is authoritative when it also gives an epoch. Gateways
336
+ // can add a later account reset in metadata, including on a Google ErrorInfo detail.
337
+ const relative = secondsMs(error.resets_in_seconds);
338
+ const epoch = secondsMs(error.resets_at);
339
+ const at = relative !== undefined ? now + relative : epoch;
340
+ if (at !== undefined && at > 0) hints.accountAt = Math.max(hints.accountAt ?? now, at);
341
+ hints.delay ??=
342
+ secondsMs(error.retry_after) ??
343
+ secondsMs(error.retry_after_seconds) ??
344
+ secondsMs(outer.retry_after_seconds);
345
+ const details: unknown[] = Array.isArray(error.details) ? error.details : [];
346
+ for (const value of [outer, error, ...details]) {
347
+ const item = fields(value);
348
+ const deadline = fields(item?.metadata)?.resetsAt;
349
+ if (typeof deadline === "string") {
350
+ const ms = Date.parse(deadline);
351
+ if (Number.isFinite(ms)) hints.accountAt = Math.max(hints.accountAt ?? now, ms);
352
+ }
353
+ // RetryInfo spells even whole seconds as a string. A mention of "retryDelay=1s"
354
+ // inside the model's error message is not this field.
355
+ if (typeof item?.retryDelay === "string") {
356
+ hints.delay ??= secondsMs(/^(\d+(?:\.\d+)?)s$/.exec(item.retryDelay)?.[1]);
357
+ }
338
358
  }
359
+ }
360
+ return hints;
361
+ }
339
362
 
340
- const inSeconds = jsonSeconds(error.resets_in_seconds);
341
- const atSeconds = jsonSeconds(error.resets_at);
342
- // The plain wait some gateways put in the error body instead of a header,
343
- // under either name (cc-proxy reads both off the ChatGPT backend's frames).
344
- const afterSeconds =
345
- jsonSeconds(error.retry_after) ??
346
- jsonSeconds(error.retry_after_seconds) ??
347
- jsonSeconds((body as Record<string, unknown>).retry_after_seconds);
348
- let waitMs: number | undefined;
349
- if (inSeconds !== undefined && inSeconds >= 0) waitMs = inSeconds * 1000;
350
- else if (atSeconds !== undefined && atSeconds > 0) waitMs = Math.max(0, atSeconds * 1000 - now);
351
- else if (afterSeconds !== undefined && afterSeconds >= 0) waitMs = afterSeconds * 1000;
352
- if (waitMs !== undefined || Number.isFinite(metadataReset)) {
353
- return resetAfter(Math.max(0, waitMs ?? 0, metadataReset - now), now);
354
- }
363
+ interface HintOptions {
364
+ headers?: Headers;
365
+ accountWindow?: boolean;
366
+ normalizedDelay?: number;
367
+ fallbackMessage?: string;
368
+ }
369
+
370
+ function mergedReset(text: string, options: HintOptions, now: number): RateLimitReset {
371
+ const header = options.headers ? parseRateLimitReset(options.headers, now) : {};
372
+ const body = bodyHints(text, now);
373
+ const aboutWindow = options.accountWindow !== false;
374
+ const explicit = options.normalizedDelay ?? header.retryAfterMs;
375
+ // A Retry-After header alone supplies no independent account horizon. In particular,
376
+ // it cannot restore a longer delay that the caller has already normalized.
377
+ let headerAt = aboutWindow ? header.resetAtMs : undefined;
378
+ if (
379
+ header.retryAfterMs !== undefined &&
380
+ headerAt === now + header.retryAfterMs &&
381
+ !header.window
382
+ ) {
383
+ headerAt = undefined;
384
+ }
385
+ const accountAt = aboutWindow ? body.accountAt : undefined;
386
+ let bodyWait = body.delay;
387
+ if (accountAt !== undefined) bodyWait = Math.max(accountAt - now, bodyWait ?? 0);
388
+ if (explicit === undefined && headerAt === undefined && bodyWait === undefined) {
389
+ bodyWait = body.prose ?? parseProseRetryMs(options.fallbackMessage ?? "");
355
390
  }
391
+ const delay = explicit ?? bodyWait;
392
+ if (!aboutWindow) return delay === undefined ? {} : { retryAfterMs: delay };
393
+ const end = Math.max(headerAt ?? 0, accountAt ?? 0, delay === undefined ? 0 : now + delay);
394
+ const bodySetsEnd =
395
+ end > 0 &&
396
+ (end === accountAt ||
397
+ (explicit === undefined && bodyWait !== undefined && end === now + bodyWait));
398
+ let window: RateLimitWindow | undefined;
399
+ if (header.window && headerAt === end) {
400
+ window = header.window;
401
+ } else if (bodySetsEnd && end - now > WINDOW_FLOOR_MS) {
402
+ window = windowForMs(end - now);
403
+ }
404
+ return {
405
+ ...(end > 0 ? { resetAtMs: end } : {}),
406
+ ...(delay !== undefined ? { retryAfterMs: delay } : {}),
407
+ ...(window ? { window } : {}),
408
+ };
409
+ }
356
410
 
357
- // If structured JSON did not yield a reset, check prose wording
358
- const waitMs = parseProseRetryMs(bodyText);
359
- return waitMs === undefined ? {} : resetAfter(waitMs, now);
411
+ /** Read a usage deadline, RetryInfo field or wait stated in the provider's own message. */
412
+ export function parseUsageLimitBody(bodyText: string, now = Date.now()): RateLimitReset {
413
+ return mergedReset(bodyText, {}, now);
360
414
  }
361
415
 
362
416
  /** Read both places an endpoint can report its reset. A short Retry-After is
@@ -366,17 +420,16 @@ export function parseRateLimitResponse(
366
420
  bodyText: string,
367
421
  now = Date.now(),
368
422
  ): RateLimitReset {
369
- const header = parseRateLimitReset(headers, now);
370
- const body = parseUsageLimitBody(bodyText, now);
371
- const resetAtMs = Math.max(header.resetAtMs ?? 0, body.resetAtMs ?? 0);
372
- const retryAfterMs = header.retryAfterMs ?? body.retryAfterMs;
373
- const window =
374
- body.resetAtMs !== undefined && body.resetAtMs > (header.resetAtMs ?? 0)
375
- ? body.window
376
- : (header.window ?? body.window);
377
- return {
378
- ...(resetAtMs > 0 ? { resetAtMs } : {}),
379
- ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
380
- ...(window ? { window } : {}),
381
- };
423
+ return mergedReset(bodyText, { headers }, now);
424
+ }
425
+
426
+ /** @internal A failed rate-limited call can use a known account deadline as its wait even
427
+ * without Retry-After. Standing account headers say nothing about unrelated failures. */
428
+ export function failureReset(bodyText: string, options: HintOptions): RateLimitReset {
429
+ const now = Date.now();
430
+ const reset = mergedReset(bodyText, options, now);
431
+ if (reset.retryAfterMs === undefined && reset.resetAtMs !== undefined) {
432
+ reset.retryAfterMs = Math.max(0, reset.resetAtMs - now);
433
+ }
434
+ return reset;
382
435
  }
package/src/tools.ts CHANGED
@@ -33,6 +33,8 @@ export type ToolOutcome<O> =
33
33
  * a reader who cannot see our stack trace. */
34
34
  error: string;
35
35
  durationMs: number;
36
+ /** What was thrown, for your logs. When a `zodTool` check fails, its `cause` is zod's
37
+ * error, or what threw in its place: a refine, a transform or `describeIssues`. */
36
38
  cause?: unknown;
37
39
  };
38
40
 
package/src/transport.ts CHANGED
@@ -8,16 +8,11 @@ import {
8
8
  classify,
9
9
  classifyHttp,
10
10
  parseContextOverflow,
11
- parseRetryAfterMs,
12
11
  ProviderError,
13
12
  type ContextOverflowInfo,
14
13
  type ErrorKind,
15
14
  } from "./errors.ts";
16
- import {
17
- parseRateLimitReset,
18
- parseRateLimitResponse,
19
- type RateLimitReading,
20
- } from "./rate-limit.ts";
15
+ import { failureReset, parseRateLimitReset, type RateLimitReading } from "./rate-limit.ts";
21
16
  import type { Provider } from "./types.ts";
22
17
 
23
18
  /**
@@ -159,11 +154,10 @@ async function errorFor(provider: string, res: Response, redact = false): Promis
159
154
  // three days": past every retry budget, and the backup walker benched the
160
155
  // model until the weekly window rolled — the overload that most wants another
161
156
  // attempt got none. A server's own Retry-After is honoured on any status.
162
- const aboutWindow = kind === "rate" || kind === "quota";
163
- const reset = aboutWindow ? parseRateLimitResponse(res.headers, text) : {};
164
- const asked = aboutWindow
165
- ? retryAfterFromHeaders(res.headers)
166
- : parseRateLimitReset(res.headers).retryAfterMs;
157
+ const reset = failureReset(text, {
158
+ headers: res.headers,
159
+ accountWindow: kind === "rate" || kind === "quota",
160
+ });
167
161
  const message = redact
168
162
  ? `${provider} ${res.status}`
169
163
  : text
@@ -176,7 +170,6 @@ async function errorFor(provider: string, res: Response, redact = false): Promis
176
170
  status: res.status,
177
171
  ...reset,
178
172
  shouldRetry,
179
- retryAfterMs: asked ?? parseRetryAfterMs({}, text),
180
173
  ...(redact ? {} : { body: text.slice(0, 2_000) || undefined }),
181
174
  });
182
175
  }
@@ -666,6 +659,14 @@ export function parseFrame<T>(data: string, provider: string): T {
666
659
  * classified error, the retry hints) plus `parseSseStream`.
667
660
  */
668
661
  export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
662
+ yield* (await openSse(opts)).frames;
663
+ }
664
+
665
+ /** @internal A stream can fail after HTTP 200. Its adapter needs the response
666
+ * headers alongside that error frame to recover the server's retry delay. */
667
+ export async function openSse(
668
+ opts: RequestInit_,
669
+ ): Promise<{ headers: Headers; frames: AsyncGenerator<string> }> {
669
670
  const res = await send(opts);
670
671
  // Headers are the first sign of life — the idle clock starts here, not at
671
672
  // the POST: a backend that withholds them until its first output token (the
@@ -689,5 +690,5 @@ export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
689
690
  status: res.status,
690
691
  });
691
692
  }
692
- yield* parseSseStream(res.body, opts);
693
+ return { headers: res.headers, frames: parseSseStream(res.body, opts) };
693
694
  }
package/src/watchdog.ts CHANGED
@@ -261,6 +261,9 @@ export async function* requireContent<T extends ProviderChunk>(
261
261
  return;
262
262
  }
263
263
  if (finish === "length") {
264
+ // This failure is not retried. A caller that handles the cut needs its finish and billed
265
+ // usage even on a provider that streams no reasoning. Other empty failures stay uncommitted.
266
+ yield* held;
264
267
  const spent = usage?.reasoningTokens
265
268
  ? ` (${usage.reasoningTokens} of ${usage.outputTokens} output tokens went to reasoning)`
266
269
  : "";
@@ -268,6 +271,7 @@ export async function* requireContent<T extends ProviderChunk>(
268
271
  provider,
269
272
  "invalid",
270
273
  `${provider}: the output cap ran out before any answer${spent}. Raise maxTokens or lower effort.`,
274
+ { code: "output_cap_before_answer" },
271
275
  );
272
276
  }
273
277
  throw new ProviderError(provider, "overload", `${provider}: completed with no content`);
package/src/zod.ts CHANGED
@@ -67,6 +67,23 @@ export interface ZodToolSpec<I, O, R = O> {
67
67
  * Off by default: an ordinary tool can simply be called again.
68
68
  */
69
69
  clampOverflow?: boolean;
70
+ /**
71
+ * Writes the problems zod found in your words instead of zod's, for the input check and the
72
+ * `output` check. zod's sentence can list every value a field accepts and quote the caller's
73
+ * key names, and an app that saves tool replies keeps that text: an adopter shows each reply
74
+ * again in its studio for a week, so it words a problem from its path and code alone. That
75
+ * tells the model less. A bare `invalid_type` at `sheets` once sent a model back to resend
76
+ * the same call, which is why the default keeps zod's sentence.
77
+ *
78
+ * It gets zod's error, with every issue, and `checked`: `input` for the model's arguments,
79
+ * `result` for what `run` returned. On input it words the same parse `invoke` and `accepts`
80
+ * decide by, after the repairs. Only the default stops at five issues. A check that throws
81
+ * reads as its own message, and so does a `describeIssues` that throws. On both checks, the
82
+ * error the tool throws keeps zod's error as its `cause`, or what was thrown in its place, so
83
+ * your logs find it at `ToolOutcome.cause.cause`. Defaults to zod's message for each issue,
84
+ * after its path.
85
+ */
86
+ describeIssues?: (error: z.ZodError, checked: "input" | "result") => string;
70
87
  }
71
88
 
72
89
  /** How many problems the model reads back: a 1,000-row sheet can fail on every cell. */
@@ -78,7 +95,7 @@ const MAX_ISSUES = 5;
78
95
  * call. The rest are counted, so a model that fixes five does not take them for all of it.
79
96
  * `root` names a problem with the whole value: the model's arguments, or the tool's result.
80
97
  */
81
- function describeIssues(issues: Issues, root: "input" | "result"): string {
98
+ function describeIssues({ issues }: z.ZodError, root: "input" | "result"): string {
82
99
  const lines = issues
83
100
  .slice(0, MAX_ISSUES)
84
101
  .map((issue) => `${issue.path.map(String).join(".") || root}: ${issue.message}`);
@@ -165,18 +182,23 @@ function repairSlips(raw: unknown, issues: Issues): unknown {
165
182
  function checkedRun<I, O>(
166
183
  spec: ZodToolSpec<I, O, unknown>,
167
184
  output: z.ZodType<O>,
185
+ describe: typeof describeIssues,
168
186
  ): (input: I, ctx: ToolContext) => Promise<O> {
169
187
  return async (input, ctx) => {
170
188
  const result = await spec.run(input, ctx);
171
189
  let problems: string;
190
+ let cause: unknown;
172
191
  try {
173
192
  // Async, because the sync parse throws on an async refine or transform.
174
193
  const parsed = await output.safeParseAsync(result);
175
194
  if (parsed.success) return parsed.data;
176
- problems = describeIssues(parsed.error.issues, "result");
195
+ cause = parsed.error;
196
+ // Inside the try, so a wording that throws still tells the model the call ran.
197
+ problems = describe(parsed.error, "result");
177
198
  } catch (err) {
178
199
  // zod does not catch a refine or transform that throws (`new URL` on a bad link). The
179
200
  // call ran all the same, and that is what the model must read.
201
+ cause = err;
180
202
  problems = messageOf(err);
181
203
  }
182
204
  // The call ran, so a write may already have happened. The model decides whether to
@@ -184,6 +206,7 @@ function checkedRun<I, O>(
184
206
  const effect = spec.isReadOnly ? "" : " Check its effect before calling it again.";
185
207
  throw new Error(
186
208
  `${spec.name} ran, but its result does not match its output schema.${effect} Problems: ${problems}`,
209
+ { cause },
187
210
  );
188
211
  };
189
212
  }
@@ -209,6 +232,7 @@ export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O>;
209
232
  export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O> {
210
233
  const inputSchema = toJsonObjectSchema(spec.input, `Tool "${spec.name}" input`);
211
234
  const { output } = spec;
235
+ const describe = spec.describeIssues ?? describeIssues;
212
236
 
213
237
  function clamp(value: unknown): unknown {
214
238
  return spec.clampOverflow ? clampToSchema(value, inputSchema) : value;
@@ -218,13 +242,27 @@ export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O> {
218
242
  // a decoded string, or beside a fixed wrapper, still reaches the model. The repaired
219
243
  // value is clamped too, since a string unwrapped from `{ text }` can be the one too long.
220
244
  function parseInput(raw: unknown): I {
221
- const candidate = clamp(raw);
222
- const first = spec.input.safeParse(candidate);
223
- if (first.success) return first.data;
224
- const repaired = repairSlips(candidate, first.error.issues);
225
- const parsed = repaired === candidate ? first : spec.input.safeParse(clamp(repaired));
226
- if (parsed.success) return parsed.data;
227
- throw new Error(describeIssues(parsed.error.issues, "input"));
245
+ let problems: string;
246
+ let cause: unknown;
247
+ try {
248
+ const candidate = clamp(raw);
249
+ const first = spec.input.safeParse(candidate);
250
+ if (first.success) return first.data;
251
+ const repaired = repairSlips(candidate, first.error.issues);
252
+ const parsed = repaired === candidate ? first : spec.input.safeParse(clamp(repaired));
253
+ if (parsed.success) return parsed.data;
254
+ cause = parsed.error;
255
+ problems = describe(parsed.error, "input");
256
+ } catch (err) {
257
+ // A refine or transform that throws, or a `describeIssues` that does, is wrapped as it is
258
+ // on a result. Thrown bare, it was `ToolOutcome.cause` itself, so a log reading
259
+ // `cause.cause`, where zod's error sits, got `undefined`.
260
+ cause = err;
261
+ problems = messageOf(err);
262
+ }
263
+ // The model reads the message, which may be the app's words. What went wrong stays as the
264
+ // cause, and `invoke` keeps what was thrown, so logs still have all of it.
265
+ throw new Error(problems, { cause });
228
266
  }
229
267
 
230
268
  return defineTool<I, O>({
@@ -243,6 +281,6 @@ export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O> {
243
281
  ...(spec.isConcurrencySafe !== undefined ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
244
282
  ...(spec.isTerminal !== undefined ? { isTerminal: spec.isTerminal } : {}),
245
283
  validate: parseInput,
246
- run: output ? checkedRun(spec, output) : spec.run,
284
+ run: output ? checkedRun(spec, output, describe) : spec.run,
247
285
  });
248
286
  }