@providerkit/core 0.33.0 → 0.34.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 (70) hide show
  1. package/README.md +64 -4
  2. package/dist/fallback.d.ts +5 -2
  3. package/dist/fallback.d.ts.map +1 -1
  4. package/dist/fallback.js +8 -4
  5. package/dist/fallback.js.map +1 -1
  6. package/dist/image.d.ts +16 -1
  7. package/dist/image.d.ts.map +1 -1
  8. package/dist/image.js +16 -4
  9. package/dist/image.js.map +1 -1
  10. package/dist/index.d.ts +1 -0
  11. package/dist/index.d.ts.map +1 -1
  12. package/dist/index.js +1 -0
  13. package/dist/index.js.map +1 -1
  14. package/dist/presets.d.ts +5 -3
  15. package/dist/presets.d.ts.map +1 -1
  16. package/dist/presets.js +22 -3
  17. package/dist/presets.js.map +1 -1
  18. package/dist/providers/anthropic.d.ts +2 -0
  19. package/dist/providers/anthropic.d.ts.map +1 -1
  20. package/dist/providers/anthropic.js +2 -2
  21. package/dist/providers/anthropic.js.map +1 -1
  22. package/dist/providers/factory.d.ts +10 -0
  23. package/dist/providers/factory.d.ts.map +1 -1
  24. package/dist/providers/factory.js.map +1 -1
  25. package/dist/providers/gemini.d.ts +2 -0
  26. package/dist/providers/gemini.d.ts.map +1 -1
  27. package/dist/providers/gemini.js +2 -2
  28. package/dist/providers/gemini.js.map +1 -1
  29. package/dist/providers/openai.d.ts +2 -0
  30. package/dist/providers/openai.d.ts.map +1 -1
  31. package/dist/providers/openai.js +2 -2
  32. package/dist/providers/openai.js.map +1 -1
  33. package/dist/providers/responses.d.ts +2 -0
  34. package/dist/providers/responses.d.ts.map +1 -1
  35. package/dist/providers/responses.js +47 -8
  36. package/dist/providers/responses.js.map +1 -1
  37. package/dist/tool-args.d.ts.map +1 -1
  38. package/dist/tool-args.js +6 -8
  39. package/dist/tool-args.js.map +1 -1
  40. package/dist/tool-markup.d.ts +38 -0
  41. package/dist/tool-markup.d.ts.map +1 -0
  42. package/dist/tool-markup.js +177 -0
  43. package/dist/tool-markup.js.map +1 -0
  44. package/dist/tools.d.ts +10 -2
  45. package/dist/tools.d.ts.map +1 -1
  46. package/dist/tools.js +15 -1
  47. package/dist/tools.js.map +1 -1
  48. package/dist/transport.d.ts +22 -0
  49. package/dist/transport.d.ts.map +1 -1
  50. package/dist/transport.js +65 -1
  51. package/dist/transport.js.map +1 -1
  52. package/dist/zod.d.ts +18 -2
  53. package/dist/zod.d.ts.map +1 -1
  54. package/dist/zod.js +150 -14
  55. package/dist/zod.js.map +1 -1
  56. package/package.json +1 -1
  57. package/src/fallback.ts +16 -4
  58. package/src/image.ts +35 -4
  59. package/src/index.ts +1 -0
  60. package/src/presets.ts +22 -3
  61. package/src/providers/anthropic.ts +8 -2
  62. package/src/providers/factory.ts +10 -0
  63. package/src/providers/gemini.ts +8 -2
  64. package/src/providers/openai.ts +8 -2
  65. package/src/providers/responses.ts +55 -8
  66. package/src/tool-args.ts +6 -7
  67. package/src/tool-markup.ts +205 -0
  68. package/src/tools.ts +26 -3
  69. package/src/transport.ts +86 -1
  70. package/src/zod.ts +181 -17
@@ -100,6 +100,16 @@ export interface PresetProviderConfig extends ProviderFallbackConfig {
100
100
  * each adapter decides by host. See `StreamOptions.hostedTools`. */
101
101
  servesHostedTools?: readonly HostedToolType[];
102
102
  fetchImpl?: FetchLike;
103
+ /**
104
+ * Leave the provider's words out of every error this provider throws. A vendor's error can
105
+ * quote what you sent, and `message`, `body` and `cause` carry it into your logs and into
106
+ * every run an agent saves. With this on, an error keeps its `kind`, `status`, a `code` that
107
+ * is one short word, and the retry hints, so retries and fallbacks make the same choices. A
108
+ * context overflow keeps its token counts too, for `parseContextOverflow`. Off by default,
109
+ * because the words usually name the fix. A `models` chain and `fallbacks` specs inherit it; a
110
+ * provider you built yourself keeps its own setting.
111
+ */
112
+ redactErrors?: boolean;
103
113
  }
104
114
 
105
115
  /** What one adapter for one model takes: a `PresetProviderConfig` without the
@@ -22,7 +22,7 @@ import type { HostedToolType } from "../hosted/types.ts";
22
22
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
23
23
  import { schemaPrompt, toAntigravityToolSchema, toGeminiToolSchema } from "../schema.ts";
24
24
  import { parseToolArgs, settleToolCalls } from "../tool-args.ts";
25
- import { streamSse, apiUrl, type FetchLike } from "../transport.ts";
25
+ import { streamSse, apiUrl, withRedactedErrors, type FetchLike } from "../transport.ts";
26
26
  import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
27
27
  import type {
28
28
  ChatMessage,
@@ -72,6 +72,8 @@ export interface GeminiConfig extends ProviderFallbackConfig {
72
72
  jsonWithTools?: JsonWithTools;
73
73
  maxTokens?: number;
74
74
  fetchImpl?: FetchLike;
75
+ /** Leave the provider's words out of every error. See `PresetProviderConfig.redactErrors`. */
76
+ redactErrors?: boolean;
75
77
  headers?: Record<string, string>;
76
78
  /**
77
79
  * For providers imported from `@providerkit/core/hosted`.
@@ -842,5 +844,9 @@ export function geminiProvider(config: GeminiConfig, codecs?: HostedCodecs): Pro
842
844
  },
843
845
  };
844
846
 
845
- return configuredFallbacks(provider, config, codecs);
847
+ return configuredFallbacks(
848
+ config.redactErrors ? withRedactedErrors(provider) : provider,
849
+ config,
850
+ codecs,
851
+ );
846
852
  }
@@ -13,7 +13,7 @@ import {
13
13
  } from "../errors.ts";
14
14
  import type { HostedToolType } from "../hosted/types.ts";
15
15
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
16
- import { streamSse, apiUrl, parseFrame, type FetchLike } from "../transport.ts";
16
+ import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
17
17
  import { settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
18
18
  import { attributionHeaders } from "../attribution.ts";
19
19
  import type {
@@ -86,6 +86,8 @@ export interface OpenAIConfig extends ProviderFallbackConfig {
86
86
  jsonWithTools?: JsonWithTools;
87
87
  maxTokens?: number;
88
88
  fetchImpl?: FetchLike;
89
+ /** Leave the provider's words out of every error. See `PresetProviderConfig.redactErrors`. */
90
+ redactErrors?: boolean;
89
91
  headers?: Record<string, string>;
90
92
  /**
91
93
  * App attribution for OpenRouter's rankings. The site URL rides as
@@ -855,5 +857,9 @@ export function openaiProvider(config: OpenAIConfig, codecs?: HostedCodecs): Pro
855
857
  },
856
858
  };
857
859
 
858
- return configuredFallbacks(provider, config, codecs);
860
+ return configuredFallbacks(
861
+ config.redactErrors ? withRedactedErrors(provider) : provider,
862
+ config,
863
+ codecs,
864
+ );
859
865
  }
@@ -25,7 +25,7 @@ import {
25
25
  } from "../errors.ts";
26
26
  import type { HostedToolType } from "../hosted/types.ts";
27
27
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
28
- import { streamSse, apiUrl, parseFrame, type FetchLike } from "../transport.ts";
28
+ import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
29
29
  import { parseRateLimitReset } from "../rate-limit.ts";
30
30
  import { settleToolCalls } from "../tool-args.ts";
31
31
  import type {
@@ -55,6 +55,8 @@ export interface ResponsesConfig extends ProviderFallbackConfig {
55
55
  effort?: Effort;
56
56
  maxTokens?: number;
57
57
  fetchImpl?: FetchLike;
58
+ /** Leave the provider's words out of every error. See `PresetProviderConfig.redactErrors`. */
59
+ redactErrors?: boolean;
58
60
  /** Extra request headers, where a subscription backend's account id goes
59
61
  * (`ChatGPT-Account-Id`), which those backends reject the request without. */
60
62
  headers?: Record<string, string>;
@@ -480,7 +482,32 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
480
482
  const effort = opts.effort ?? config.effort;
481
483
  const model = opts.model ?? config.model;
482
484
  const museContributor = isMuseSparkContributor(model);
483
- const requestTools = museContributor && opts.toolChoice === "none" ? [] : tools;
485
+ const named = typeof opts.toolChoice === "object" ? opts.toolChoice.name : undefined;
486
+ // On Muse Contributor, a choice the tool list can say travels as the tool
487
+ // list, never as tool_choice. See the tool_choice block below for why.
488
+ let requestTools = tools;
489
+ let choiceInTools = false;
490
+ if (museContributor && opts.toolChoice === "none") {
491
+ requestTools = [];
492
+ choiceInTools = true;
493
+ } else if (museContributor && named !== undefined) {
494
+ const alone = tools.filter((tool) => tool.name === named);
495
+ // Sent on, this call would carry no tools at all, and the forced call
496
+ // would quietly become "call nothing". The choice itself is never sent
497
+ // here, so nothing downstream could refuse it.
498
+ if (alone.length === 0) {
499
+ throw new ProviderError(
500
+ id,
501
+ "invalid",
502
+ `${id}: toolChoice names "${named}", which is not one of this call's tools. ` +
503
+ "Pass that tool too, or name one you pass.",
504
+ );
505
+ }
506
+ // When it is already the call's only tool, offering it alone is the
507
+ // request saying nothing sends (invariant 12), so the choice stays explicit.
508
+ choiceInTools = alone.length < tools.length;
509
+ if (choiceInTools) requestTools = alone;
510
+ }
484
511
  // Repaired before the images are gated: an orphaned result becomes a user
485
512
  // note that keeps its images, and those must meet the limits too.
486
513
  const sent = repairHistory(messages).messages;
@@ -552,11 +579,27 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
552
579
  if (opts.sessionId) request.prompt_cache_key = opts.sessionId;
553
580
  const serviceTier = opts.serviceTier ?? config.serviceTier;
554
581
  if (serviceTier) request.service_tier = serviceTier;
555
- // Muse Contributor accepts only `auto`. `none` has an exact wire-level
556
- // equivalent: send no tools. Required/named choices stay explicit and let
557
- // the endpoint refuse a promise it cannot keep.
558
- const omitMuseTools = museContributor && opts.toolChoice === "none";
559
- if (opts.toolChoice && opts.toolChoice !== "auto" && !omitMuseTools) {
582
+ // Muse Contributor accepts no tool_choice but `auto`. Go answers any other
583
+ // with a 400, `only "auto" is supported for tool_choice` (recorded
584
+ // 2026-10-16), so a choice that can be said in the tool list is said there:
585
+ // `none` as no tools, a named tool as the only tool offered. A choice whose
586
+ // list would hold every tool the call carries can't be: that list under
587
+ // `auto` is the request silence sends (invariant 12). So `required` stays
588
+ // explicit, and so does a named tool that is the call's only tool, and the
589
+ // endpoint refuses both.
590
+ //
591
+ // A named choice among other tools stayed explicit too, until that 400 cost
592
+ // an adopter its runs. It classifies as `invalid`, which nothing retries and
593
+ // a fallback chain does not move past by default, so a run that forced its
594
+ // last step on a chain led by Muse lost everything it had read: on
595
+ // 2026-10-16, three of its four research runs ended without the brief that
596
+ // step saves. Offered alone, the named tool is the only call the model can
597
+ // make.
598
+ // ponytail: Muse can still answer in text instead, as can the Claude
599
+ // models that refuse a forced choice (anthropic.ts), so a caller that must
600
+ // have the call says so in the prompt too. The upgrade is Go accepting the
601
+ // choice.
602
+ if (opts.toolChoice && opts.toolChoice !== "auto" && !choiceInTools) {
560
603
  request.tool_choice =
561
604
  typeof opts.toolChoice === "string"
562
605
  ? opts.toolChoice
@@ -833,5 +876,9 @@ export function responsesProvider(config: ResponsesConfig, codecs?: HostedCodecs
833
876
  },
834
877
  };
835
878
 
836
- return configuredFallbacks(provider, config, codecs);
879
+ return configuredFallbacks(
880
+ config.redactErrors ? withRedactedErrors(provider) : provider,
881
+ config,
882
+ codecs,
883
+ );
837
884
  }
package/src/tool-args.ts CHANGED
@@ -39,9 +39,8 @@ function healValue(value: unknown): unknown {
39
39
  }
40
40
 
41
41
  function healArgs(args: Record<string, unknown>): Record<string, unknown> {
42
- const out: Record<string, unknown> = {};
43
- for (const [key, value] of Object.entries(args)) out[key] = healValue(value);
44
- return out;
42
+ // JSON keys are data; assignment would invoke the inherited "__proto__" setter.
43
+ return Object.fromEntries(Object.entries(args).map(([key, value]) => [key, healValue(value)]));
45
44
  }
46
45
 
47
46
  /** The cut can land inside an escape (`…aten\u00`, or a lone `\`). That
@@ -66,7 +65,7 @@ function unescapeJson(text: string): string {
66
65
  * half-value is worse than none.
67
66
  */
68
67
  function salvageStringFields(raw: string): Record<string, unknown> {
69
- const out: Record<string, unknown> = {};
68
+ const entries: [string, string][] = [];
70
69
  const text = raw.replace(DANGLING_ESCAPE, "");
71
70
 
72
71
  // A completed `"key": "value",` or `"key": "value"}` pair.
@@ -74,7 +73,7 @@ function salvageStringFields(raw: string): Record<string, unknown> {
74
73
  let match: RegExpExecArray | null;
75
74
  let lastCompleteEnd = 0;
76
75
  while ((match = COMPLETE_FIELD.exec(text)) !== null) {
77
- out[unescapeJson(match[1]!)] = unescapeJson(match[2]!);
76
+ entries.push([unescapeJson(match[1]!), unescapeJson(match[2]!)]);
78
77
  lastCompleteEnd = COMPLETE_FIELD.lastIndex;
79
78
  }
80
79
 
@@ -82,9 +81,9 @@ function salvageStringFields(raw: string): Record<string, unknown> {
82
81
  // never closed, keep its content up to the cut.
83
82
  const OPEN_FIELD = /"((?:[^"\\]|\\.)*)"\s*:\s*"((?:[^"\\]|\\.)*)$/s;
84
83
  const open = OPEN_FIELD.exec(text.slice(lastCompleteEnd));
85
- if (open?.[2]) out[unescapeJson(open[1]!)] = unescapeJson(open[2]!);
84
+ if (open?.[2]) entries.push([unescapeJson(open[1]!), unescapeJson(open[2]!)]);
86
85
 
87
- return out;
86
+ return Object.fromEntries(entries);
88
87
  }
89
88
 
90
89
  /**
@@ -0,0 +1,205 @@
1
+ // A tool call written into the answer's text instead of the tool-call field.
2
+ // It reaches the reader as raw markup, and once it sits in the history the
3
+ // model copies it on later turns. Two shapes reach production:
4
+ //
5
+ // 1. DeepSeek's own special tokens, which open with `<` and a fullwidth
6
+ // vertical line (U+FF5C), as in `<|tool▁calls▁begin|>`. What follows one
7
+ // is the vendor's call syntax, never prose, so the rest of the turn's text
8
+ // goes with it.
9
+ // 2. A call improvised as a tag, like `<suggest_dossie subjectType="company" />`.
10
+ // The signal is a snake_case name, then an attribute (`name=`) or a
11
+ // self-closing slash: real markup almost never puts an underscore in a tag
12
+ // name. Only the tag goes, with its closing tag when it opens a pair, and
13
+ // the prose around it keeps streaming.
14
+ //
15
+ // A false match deletes the reader's words, so a tag needs both halves of the
16
+ // signal. The source app's filter took any space after the name for the start
17
+ // of attributes: `sort <in_file >out_file` lost `<in_file >` and became a
18
+ // different command, and `Promise<user_row | null>` became `Promise`. A closing
19
+ // tag counts only when its opening tag went: alone, `</user_id>` is no more a
20
+ // call than `<user_id>`, and stripping only the closing tags of a call written
21
+ // as plain tags, the way GLM writes one, left the reader its opening tags and
22
+ // arguments.
23
+ import type { Citation } from "./hosted/types.ts";
24
+ import type { ProviderChunk } from "./types.ts";
25
+
26
+ /** How every DeepSeek special token opens: `<` and U+FF5C, written as an
27
+ * escape because it looks like `|` in most fonts. */
28
+ const DEEPSEEK_TOKEN = "<\uFF5C";
29
+ /** A tag name with an underscore in it, like `save_note`. */
30
+ const NAME = "[a-z][a-z0-9]*(?:_[a-z0-9]+)+";
31
+ /** An attribute's name, like `title` or `subjectType`. */
32
+ const ATTR = String.raw`[A-Za-z_][\w.:-]*`;
33
+ /** A whole opening pseudo tag, its name captured: the name, then an attribute
34
+ * or a self-closing slash. */
35
+ const OPENING_TAG = new RegExp(String.raw`^<(${NAME})(?:\s+${ATTR}\s*=[^>]*|\s*/)>`);
36
+ /** A whole closing tag, its name captured. */
37
+ const CLOSING_TAG = new RegExp(String.raw`^</(${NAME})\s*>`);
38
+ /** Text that may still grow into either tag, or a DeepSeek token, on the next chunk. */
39
+ const PARTIAL_TAG = new RegExp(
40
+ String.raw`^<(?:/?[a-z0-9_]*|/${NAME}\s*|${NAME}(?:\s+(?:${ATTR}\s*(?:=[^>]*)?)?|\s*/)?)$`,
41
+ );
42
+ /** Held text that already reads as an opening pseudo tag: markup, even unclosed. */
43
+ const OPENED_TAG = new RegExp(String.raw`^<${NAME}(?:\s+${ATTR}\s*=|\s*/)`);
44
+ /** The longest text held while it waits for its `>` in a later chunk. A real
45
+ * leaked tag closes well within it; a tag that arrives whole is caught at any
46
+ * length. */
47
+ const MAX_HELD = 512;
48
+
49
+ /**
50
+ * Strip tool calls a model wrote into its text, as the stream arrives.
51
+ *
52
+ * ```ts
53
+ * for await (const chunk of stripLeakedToolMarkup(provider.createStream(messages, tools))) {
54
+ * if (chunk.content) write(chunk.content);
55
+ * }
56
+ * ```
57
+ *
58
+ * A tag can arrive split across chunks, so text that could still become one
59
+ * (`<`, `<suggest_`) is held until the next chunk settles it. Held text goes
60
+ * out before the finish chunk, and before the stream's own error. Only
61
+ * `content` changes: every chunk still passes, in order, with its reasoning,
62
+ * tool calls and usage. A citation whose span reaches text that was removed,
63
+ * or is still held, keeps its source and loses its span, as any span that
64
+ * doesn't check out against the text does.
65
+ *
66
+ * A turn that was nothing but markup comes out with no text. Wrap the result
67
+ * in `requireContent` to have it fail like any other empty turn.
68
+ *
69
+ * `onStrip` runs once for each leak removed, with the markup that set it off: a
70
+ * whole tag, or a DeepSeek token and the rest of the text it arrived in. The
71
+ * rest of a leak goes without another call: a pair's closing tag, and text
72
+ * after a DeepSeek token in later chunks.
73
+ *
74
+ * ponytail: a leaked call is dropped, not turned into the tool call it meant.
75
+ * Some get through, whole or in part: a pair of tags with no attributes (GLM's
76
+ * call format) stays whole, the text between a pair's tags stays, a `>` inside
77
+ * an attribute ends the tag early, and a tag split across chunks that runs past
78
+ * 512 characters before it closes leaks. Code is not exempt: a snake_case tag
79
+ * with an attribute, as in an XML sample, is removed from a code block too.
80
+ * Count `onStrip` to learn whether recovering the calls is worth building.
81
+ */
82
+ export async function* stripLeakedToolMarkup(
83
+ chunks: AsyncIterable<ProviderChunk>,
84
+ opts: { onStrip?: (markup: string) => void } = {},
85
+ ): AsyncGenerator<ProviderChunk> {
86
+ // Text that could still become markup, waiting for the next chunk.
87
+ let held = "";
88
+ // A DeepSeek token went by: the rest of the turn's text is its syntax.
89
+ let tripped = false;
90
+ // The names of the pairs whose opening tag went and whose closing tag has not
91
+ // come yet. Only their closing tags are markup.
92
+ const open: string[] = [];
93
+ // Positions in the source's text, the one a citation's span indexes: how
94
+ // much of it is settled (sent on or removed), and where the first removal
95
+ // began.
96
+ let settled = 0;
97
+ let firstCut: number | undefined;
98
+
99
+ function strip(at: number, markup: string): void {
100
+ firstCut ??= at;
101
+ opts.onStrip?.(markup);
102
+ }
103
+
104
+ function push(text: string): string {
105
+ if (tripped) {
106
+ settled += text.length;
107
+ return "";
108
+ }
109
+ const base = settled;
110
+ let buf = held + text;
111
+ const length = buf.length;
112
+ held = "";
113
+ const token = buf.indexOf(DEEPSEEK_TOKEN);
114
+ let afterToken = "";
115
+ if (token >= 0) {
116
+ tripped = true;
117
+ afterToken = buf.slice(token);
118
+ buf = buf.slice(0, token);
119
+ }
120
+ let out = "";
121
+ let i = 0;
122
+ while (i < buf.length) {
123
+ const lt = buf.indexOf("<", i);
124
+ if (lt < 0) {
125
+ out += buf.slice(i);
126
+ break;
127
+ }
128
+ out += buf.slice(i, lt);
129
+ const rest = buf.slice(lt);
130
+ const opening = OPENING_TAG.exec(rest);
131
+ if (opening) {
132
+ strip(base + lt, opening[0]);
133
+ if (!opening[0].endsWith("/>")) open.push(opening[1]!);
134
+ i = lt + opening[0].length;
135
+ continue;
136
+ }
137
+ const closing = CLOSING_TAG.exec(rest);
138
+ const pair = closing ? open.lastIndexOf(closing[1]!) : -1;
139
+ if (closing && pair >= 0) {
140
+ // The end of a leak already reported, so no second report. Its opening
141
+ // tag already marked the first cut the citations are checked against.
142
+ open.splice(pair, 1);
143
+ i = lt + closing[0].length;
144
+ continue;
145
+ }
146
+ if (!tripped && rest.length <= MAX_HELD && PARTIAL_TAG.test(rest)) {
147
+ held = rest;
148
+ break;
149
+ }
150
+ out += "<";
151
+ i = lt + 1;
152
+ }
153
+ // Reported after the loop, so leaks are reported in the order they appear.
154
+ if (afterToken) strip(base + token, afterToken);
155
+ settled = base + length - held.length;
156
+ return out;
157
+ }
158
+
159
+ /** The held text as a chunk of its own, unless it already reads as markup. */
160
+ function flush(): ProviderChunk[] {
161
+ const tail = held;
162
+ if (!tail) return [];
163
+ held = "";
164
+ const at = settled;
165
+ settled += tail.length;
166
+ // A tag the turn ended inside is still markup: never show it.
167
+ if (OPENED_TAG.test(tail)) {
168
+ strip(at, tail);
169
+ return [];
170
+ }
171
+ // Nor the start of the closing tag a removed pair was waiting for.
172
+ if (tail.startsWith("</") && open.some((name) => `</${name}`.startsWith(tail.trimEnd()))) {
173
+ return [];
174
+ }
175
+ return [{ type: "delta", content: tail }];
176
+ }
177
+
178
+ /** A span no removal can have moved stays as it is. One that a removal may
179
+ * have moved is dropped with its anchor, never shifted by a guess. */
180
+ function checked(citation: Citation): Citation {
181
+ const end = citation.end ?? citation.start;
182
+ return end === undefined || end <= (firstCut ?? settled)
183
+ ? citation
184
+ : { source: citation.source };
185
+ }
186
+
187
+ try {
188
+ for await (const chunk of chunks) {
189
+ // A delta after the finish lands in a message the reader already closed.
190
+ if (chunk.type === "finish") yield* flush();
191
+ let out = chunk;
192
+ if (chunk.content) {
193
+ const content = push(chunk.content);
194
+ if (content !== chunk.content) out = { ...out, content };
195
+ }
196
+ if (chunk.citations?.length) out = { ...out, citations: chunk.citations.map(checked) };
197
+ yield out;
198
+ }
199
+ } catch (err) {
200
+ // What arrived before the failure is the reader's, as on every wire.
201
+ yield* flush();
202
+ throw err;
203
+ }
204
+ yield* flush();
205
+ }
package/src/tools.ts CHANGED
@@ -41,7 +41,8 @@ export interface ToolSpec<I, O> {
41
41
  description: string;
42
42
  /** Advertised to the model verbatim. */
43
43
  inputSchema: JsonObjectSchema;
44
- /** JSON Schema for generated result types. Not validated or sent to providers. */
44
+ /** JSON Schema for generated result types. Not validated here or sent to providers;
45
+ * `zodTool`'s `output` checks results and fills this in. */
45
46
  outputSchema?: Record<string, unknown>;
46
47
  /**
47
48
  * Turn raw arguments into `I`, or throw with a message the MODEL can act on.
@@ -72,7 +73,8 @@ export interface Tool<I = unknown, O = unknown> {
72
73
  readonly name: string;
73
74
  readonly description: string;
74
75
  readonly inputSchema: JsonObjectSchema;
75
- /** JSON Schema for generated result types. Not validated or sent to providers. */
76
+ /** JSON Schema for generated result types. Not validated here or sent to providers;
77
+ * `zodTool`'s `output` checks results and fills this in. */
76
78
  readonly outputSchema?: Record<string, unknown>;
77
79
  readonly timeoutMs: number;
78
80
  readonly isReadOnly: boolean;
@@ -80,6 +82,12 @@ export interface Tool<I = unknown, O = unknown> {
80
82
  readonly isConcurrencySafe: boolean;
81
83
  readonly isTerminal: boolean;
82
84
  definition(): ToolDefinition;
85
+ /**
86
+ * Whether `invoke` would take these raw arguments, by the same `validate`, without running
87
+ * the tool. Ask before opening an approval, so nobody is asked to approve a call that cannot
88
+ * run: it would come back `invalid_input` after they said yes.
89
+ */
90
+ accepts(rawArgs: unknown): boolean;
83
91
  /** Validate, run, and report the outcome. Never throws except on abort. */
84
92
  invoke(rawArgs: unknown, ctx?: ToolContext): Promise<ToolOutcome<O>>;
85
93
  /** The typed path for internal callers: throws on failure. */
@@ -149,6 +157,12 @@ export function defineTool<I = unknown, O = unknown>(spec: ToolSpec<I, O>): Tool
149
157
  return name === "AbortError" ? "aborted" : "failed";
150
158
  }
151
159
 
160
+ /** The one parse `invoke` and `accepts` share, so a host asking first gets the answer
161
+ * `invoke` would give. Throws with the message the model reads. */
162
+ function parse(rawArgs: unknown): I {
163
+ return spec.validate ? spec.validate(rawArgs) : (rawArgs as I);
164
+ }
165
+
152
166
  return {
153
167
  name: spec.name,
154
168
  description: spec.description,
@@ -173,13 +187,22 @@ export function defineTool<I = unknown, O = unknown>(spec: ToolSpec<I, O>): Tool
173
187
  return (await execute(input, ctx)).output;
174
188
  },
175
189
 
190
+ accepts(rawArgs) {
191
+ try {
192
+ parse(rawArgs);
193
+ return true;
194
+ } catch {
195
+ return false;
196
+ }
197
+ },
198
+
176
199
  async invoke(rawArgs, ctx = {}) {
177
200
  const callId = ctx.callId ?? newId();
178
201
  const started = Date.now();
179
202
 
180
203
  let input: I;
181
204
  try {
182
- input = spec.validate ? spec.validate(rawArgs) : (rawArgs as I);
205
+ input = parse(rawArgs);
183
206
  } catch (err) {
184
207
  return {
185
208
  ok: false,
package/src/transport.ts CHANGED
@@ -4,12 +4,21 @@
4
4
  //
5
5
  // Adapters keep only their per-event mapping; everything about being an HTTP
6
6
  // client lives here once.
7
- import { classifyHttp, parseRetryAfterMs, ProviderError, type ErrorKind } from "./errors.ts";
7
+ import {
8
+ classify,
9
+ classifyHttp,
10
+ parseContextOverflow,
11
+ parseRetryAfterMs,
12
+ ProviderError,
13
+ type ContextOverflowInfo,
14
+ type ErrorKind,
15
+ } from "./errors.ts";
8
16
  import {
9
17
  parseRateLimitReset,
10
18
  parseRateLimitResponse,
11
19
  type RateLimitReading,
12
20
  } from "./rate-limit.ts";
21
+ import type { Provider } from "./types.ts";
13
22
 
14
23
  /**
15
24
  * What a `fetchImpl` option takes: anything called like `fetch` that answers with a `Response`.
@@ -435,6 +444,82 @@ export async function callOnce<T>(
435
444
  }
436
445
  }
437
446
 
447
+ /** A vendor code short enough to be a name, not a sentence. */
448
+ const CODE_SLUG = /^[A-Za-z0-9_.-]{1,64}$/;
449
+
450
+ /**
451
+ * @internal What `redactErrors` turns on for chat: the speech rule of invariant 18. A vendor's
452
+ * error can quote what was sent, and its message, `body` and `cause` carry that into logs and
453
+ * into every run an agent saves. Each `ProviderError` the adapter throws comes back as a copy
454
+ * that keeps what retries, pools and logs read: the kind, the status, a `code` that is one
455
+ * short word, the retry hints, and a context overflow's token counts. So a retry or a fallback
456
+ * decides exactly as it would have on the original, and an app trims by the same numbers.
457
+ * Anything else passes through as thrown: a socket that died mid-read is the runtime's error,
458
+ * not the vendor's, and an abort reason (the caller's Stop, or the deadline a watchdog outside
459
+ * this layer aborted with) stays itself.
460
+ *
461
+ * Applied once, where each adapter hands out its provider, so a new failure path inside an
462
+ * adapter cannot forget it. The same reason `noReplay` lives in one place.
463
+ *
464
+ * ponytail: every error loses its words, ours too (a refused option, a stream cut short), so a
465
+ * redacted log says only the kind, the status, the code and an overflow's counts. And a code
466
+ * that is one word stays, so a vendor that put one of the caller's words in its code would
467
+ * still show it. Upgrade: mark the errors that carry vendor text where they are built, and keep
468
+ * our own words.
469
+ */
470
+ export function withRedactedErrors(provider: Provider): Provider {
471
+ return {
472
+ ...provider,
473
+ async *createStream(messages, tools, opts = {}) {
474
+ try {
475
+ yield* provider.createStream(messages, tools, opts);
476
+ } catch (error) {
477
+ if (!(error instanceof ProviderError) || error === opts.signal?.reason) throw error;
478
+ throw withoutVendorWords(error);
479
+ }
480
+ },
481
+ };
482
+ }
483
+
484
+ function withoutVendorWords(error: ProviderError): ProviderError {
485
+ const { provider, kind, status, retryAfterMs, resetAtMs, window, shouldRetry } = error;
486
+ const code = error.code !== undefined && CODE_SLUG.test(error.code) ? error.code : undefined;
487
+ const overflow = parseContextOverflow(error);
488
+ const facts = [
489
+ kind,
490
+ ...(status === undefined ? [] : [`HTTP ${status}`]),
491
+ ...(code === undefined ? [] : [`code ${code}`]),
492
+ // `parseContextOverflow` reads the token counts out of the message, and an app lowers
493
+ // `maxTokens` or compacts by them. Counts are not the person's words, so they stay.
494
+ ...(overflow === undefined ? [] : [overflowFact(overflow)]),
495
+ // `isRetryable` reads a cancel phrase in the message as the caller's Stop and never retries
496
+ // it. That one fact stays, or the copy would be retried where the original was not.
497
+ ...(classify({ message: error.message }) === "aborted" ? ["client closed request"] : []),
498
+ ];
499
+ return new ProviderError(
500
+ provider,
501
+ kind,
502
+ `${provider}: the model call failed (${facts.join(", ")}). ` +
503
+ "The error text is left out because redactErrors is on.",
504
+ { status, code, retryAfterMs, resetAtMs, window, shouldRetry },
505
+ );
506
+ }
507
+
508
+ /** An overflow in the wording `parseContextOverflow` reads for its shape, so the copy parses to
509
+ * the same numbers as the original. */
510
+ function overflowFact({
511
+ inputTokens,
512
+ maxTokens,
513
+ contextLimit,
514
+ excessTokens,
515
+ }: ContextOverflowInfo): string {
516
+ // The excess is counted from the input, so it gives the input back if a wording ever lacks it.
517
+ const input = inputTokens ?? contextLimit + excessTokens - (maxTokens ?? 0);
518
+ return maxTokens === undefined
519
+ ? `prompt is too long: ${input} tokens > ${contextLimit}`
520
+ : `input length and max_tokens exceed context limit: ${input} + ${maxTokens} > ${contextLimit}`;
521
+ }
522
+
438
523
  /** Pull the `data:` payload out of one SSE frame, joining continuation lines
439
524
  * the way the spec says to. Returns null for a comment or a frame carrying
440
525
  * only an `event:` name. */