@providerkit/core 0.33.1 → 0.35.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 (75) hide show
  1. package/README.md +82 -4
  2. package/dist/errors.d.ts.map +1 -1
  3. package/dist/errors.js +16 -1
  4. package/dist/errors.js.map +1 -1
  5. package/dist/fallback.d.ts +5 -2
  6. package/dist/fallback.d.ts.map +1 -1
  7. package/dist/fallback.js +8 -4
  8. package/dist/fallback.js.map +1 -1
  9. package/dist/hosted/anthropic.d.ts +4 -2
  10. package/dist/hosted/anthropic.d.ts.map +1 -1
  11. package/dist/hosted/anthropic.js +7 -6
  12. package/dist/hosted/anthropic.js.map +1 -1
  13. package/dist/image.d.ts +16 -1
  14. package/dist/image.d.ts.map +1 -1
  15. package/dist/image.js +16 -4
  16. package/dist/image.js.map +1 -1
  17. package/dist/index.d.ts +1 -0
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +1 -0
  20. package/dist/index.js.map +1 -1
  21. package/dist/presets.d.ts +5 -3
  22. package/dist/presets.d.ts.map +1 -1
  23. package/dist/presets.js +22 -3
  24. package/dist/presets.js.map +1 -1
  25. package/dist/providers/anthropic.d.ts +2 -0
  26. package/dist/providers/anthropic.d.ts.map +1 -1
  27. package/dist/providers/anthropic.js +110 -10
  28. package/dist/providers/anthropic.js.map +1 -1
  29. package/dist/providers/factory.d.ts +10 -0
  30. package/dist/providers/factory.d.ts.map +1 -1
  31. package/dist/providers/factory.js.map +1 -1
  32. package/dist/providers/gemini.d.ts +2 -0
  33. package/dist/providers/gemini.d.ts.map +1 -1
  34. package/dist/providers/gemini.js +2 -2
  35. package/dist/providers/gemini.js.map +1 -1
  36. package/dist/providers/openai.d.ts +2 -0
  37. package/dist/providers/openai.d.ts.map +1 -1
  38. package/dist/providers/openai.js +2 -2
  39. package/dist/providers/openai.js.map +1 -1
  40. package/dist/providers/responses.d.ts +2 -0
  41. package/dist/providers/responses.d.ts.map +1 -1
  42. package/dist/providers/responses.js +47 -8
  43. package/dist/providers/responses.js.map +1 -1
  44. package/dist/tool-markup.d.ts +38 -0
  45. package/dist/tool-markup.d.ts.map +1 -0
  46. package/dist/tool-markup.js +177 -0
  47. package/dist/tool-markup.js.map +1 -0
  48. package/dist/tools.d.ts +12 -2
  49. package/dist/tools.d.ts.map +1 -1
  50. package/dist/tools.js +15 -1
  51. package/dist/tools.js.map +1 -1
  52. package/dist/transport.d.ts +22 -0
  53. package/dist/transport.d.ts.map +1 -1
  54. package/dist/transport.js +65 -1
  55. package/dist/transport.js.map +1 -1
  56. package/dist/zod.d.ts +35 -2
  57. package/dist/zod.d.ts.map +1 -1
  58. package/dist/zod.js +170 -14
  59. package/dist/zod.js.map +1 -1
  60. package/package.json +1 -1
  61. package/src/errors.ts +16 -1
  62. package/src/fallback.ts +16 -4
  63. package/src/hosted/anthropic.ts +7 -6
  64. package/src/image.ts +35 -4
  65. package/src/index.ts +1 -0
  66. package/src/presets.ts +22 -3
  67. package/src/providers/anthropic.ts +127 -10
  68. package/src/providers/factory.ts +10 -0
  69. package/src/providers/gemini.ts +8 -2
  70. package/src/providers/openai.ts +8 -2
  71. package/src/providers/responses.ts +55 -8
  72. package/src/tool-markup.ts +205 -0
  73. package/src/tools.ts +28 -3
  74. package/src/transport.ts +86 -1
  75. package/src/zod.ts +219 -17
@@ -17,7 +17,7 @@ import type { HostedToolType } from "../hosted/types.ts";
17
17
  import { refuseHostedTools, type HostedCodecs } from "./hosted-codecs.ts";
18
18
  import { schemaPrompt, toAnthropicToolSchema } from "../schema.ts";
19
19
  import { parseToolArgs, settleToolCalls, type ToolCallIdentity } from "../tool-args.ts";
20
- import { streamSse, apiUrl, parseFrame, type FetchLike } from "../transport.ts";
20
+ import { streamSse, apiUrl, parseFrame, withRedactedErrors, type FetchLike } from "../transport.ts";
21
21
  import { attributionHeaders } from "../attribution.ts";
22
22
  import { configuredFallbacks, type ProviderFallbackConfig } from "../fallback.ts";
23
23
  import type {
@@ -49,6 +49,8 @@ export interface AnthropicConfig extends ProviderFallbackConfig {
49
49
  maxTokens?: number;
50
50
  version?: string;
51
51
  fetchImpl?: FetchLike;
52
+ /** Leave the provider's words out of every error. See `PresetProviderConfig.redactErrors`. */
53
+ redactErrors?: boolean;
52
54
  /** Merged into every request. The subscription backend needs its own beta
53
55
  * headers, and a gateway in front usually wants one of its own. */
54
56
  headers?: Record<string, string>;
@@ -281,7 +283,8 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
281
283
  * tool results are merged into one user turn, which the API requires.
282
284
  */
283
285
  /**
284
- * The system prompt as ONE cached block.
286
+ * The system prompt: one text block per system message, in order, with the
287
+ * cache breakpoint on the last.
285
288
  *
286
289
  * Anthropic's prompt caching is opt-in per block. A plain string system prompt
287
290
  * is never cached, however many times it is re-sent. An agent loop re-sends this
@@ -292,9 +295,116 @@ function partsToAnthropic(content: string | ContentPart[], provider: string): un
292
295
  * Unconditional. Below the model's minimum cacheable length the field is
293
296
  * ignored rather than rejected, and above it the one-time 1.25× write is repaid
294
297
  * by the second turn, which always comes in the loop this package sits under.
298
+ *
299
+ * A block per message, not one joined block, because a decorator over a
300
+ * Provider can only add a system message. A line it puts first then reaches the
301
+ * wire as its own first block, which a gateway that reads the first block finds
302
+ * alone, instead of as the start of a block that holds the whole prompt.
303
+ *
304
+ * A blank message gets no block. Joined, it was a few spaces inside real text;
305
+ * alone, it is a 400 ("system text blocks must contain non-whitespace text",
306
+ * recorded against claude-sonnet-5-5 by PydanticAI, MIT,
307
+ * tests/test_history_properties.py).
295
308
  */
296
- function systemBlocks(text: string): unknown[] | undefined {
297
- return text ? [{ type: "text", text, cache_control: { type: "ephemeral" } }] : undefined;
309
+ function systemBlocks(messages: readonly string[]): unknown[] | undefined {
310
+ const texts = messages.filter((text) => text.trim() !== "");
311
+ if (texts.length === 0) return undefined;
312
+ return texts.map((text, i) =>
313
+ i === texts.length - 1
314
+ ? { type: "text", text, cache_control: { type: "ephemeral" } }
315
+ : { type: "text", text },
316
+ );
317
+ }
318
+
319
+ /**
320
+ * Whether Anthropic takes a cache marker on this block. A list of the blocks
321
+ * that do, rather than of the ones that don't: a marker on a block that refuses
322
+ * one is a 400 that loses the turn, while a block missing from this list only
323
+ * moves the marker back a block.
324
+ *
325
+ * Thinking blocks of both kinds and empty text cannot carry one; text, images,
326
+ * tool use and tool results can, the last two in user and assistant turns alike
327
+ * (Anthropic, Prompt caching, "What can be cached" and "What cannot be cached",
328
+ * read 2026-11-19). A server tool's result takes one too: the API puts its own
329
+ * breakpoint there before its tool loop's next step (Anthropic, Tool use with
330
+ * prompt caching, read 2026-11-19). Blank text counts as empty: the API refuses
331
+ * a text block of only whitespace outright.
332
+ */
333
+ function takesMarker(block: unknown): block is Record<string, unknown> {
334
+ if (typeof block !== "object" || block === null || !("type" in block)) return false;
335
+ const { type } = block;
336
+ if (type === "text") {
337
+ return "text" in block && typeof block.text === "string" && block.text.trim() !== "";
338
+ }
339
+ return (
340
+ type === "image" ||
341
+ type === "tool_use" ||
342
+ type === "tool_result" ||
343
+ type === "server_tool_use" ||
344
+ (typeof type === "string" && type.endsWith("_tool_result"))
345
+ );
346
+ }
347
+
348
+ /** `message` with a marker on its last block that takes one, or as it was when none does. */
349
+ function markLast(message: AnthropicMessage): AnthropicMessage {
350
+ for (let i = message.content.length - 1; i >= 0; i--) {
351
+ const block = message.content[i];
352
+ if (!takesMarker(block)) continue;
353
+ const content = [...message.content];
354
+ content[i] = { ...block, cache_control: { type: "ephemeral" } };
355
+ return { ...message, content };
356
+ }
357
+ return message;
358
+ }
359
+
360
+ /**
361
+ * The conversation's cache breakpoints. The system marker caches the fixed
362
+ * prefix, tools and system; these cache the conversation, which grows every
363
+ * turn while that prefix stays the same size. Without them every turn billed
364
+ * the whole history again at the full input rate, and only tools and system
365
+ * came from cache.
366
+ *
367
+ * Two of them, on the last block that takes one (see takesMarker):
368
+ * - The newest message. Each request writes its entry there.
369
+ * - The message just before the newest assistant message: where the previous
370
+ * request ended, so this one reads that request's entry exactly. A read looks
371
+ * back at most 20 positions from a breakpoint for an entry an earlier request
372
+ * wrote. On the Claude API a run of tool_use blocks counts as one position, and
373
+ * so does a run of tool_result blocks; the docs state that rule for no other
374
+ * platform. A turn that adds more than 20 would read nothing from the newest
375
+ * marker alone, and bill its whole prefix fresh. An adopter ran on the newest
376
+ * marker alone and named this second one as the upgrade.
377
+ *
378
+ * Only on a request another one will follow: one that declares tools, or one
379
+ * whose messages already hold an assistant turn. A one-shot would pay the 1.25×
380
+ * write for an entry nothing reads. A prefix under the model's minimum (512
381
+ * tokens on the newest models, up to 4,096 on older ones) is neither cached
382
+ * nor billed as a write.
383
+ *
384
+ * Block markers only, never the top-level `cache_control` field that turns on
385
+ * automatic caching: the legacy Bedrock integration (bedrock-runtime) answers
386
+ * that field with a 400, and no Anthropic-shape gateway has been checked.
387
+ *
388
+ * With the system's, three markers at most, under the API's cap of four. They
389
+ * depend only on the messages, and a moved marker is not a changed prefix (the
390
+ * docs' own growing conversation moves it every turn and reads the last
391
+ * turn's entry), so a longer history still sends the shorter one's bytes plus
392
+ * what is new (invariant 14).
393
+ *
394
+ * Documented (Anthropic, Prompt caching, read 2026-11-19:
395
+ * platform.claude.com/docs/en/build-with-claude/prompt-caching); not measured
396
+ * live here.
397
+ */
398
+ function markConversation(
399
+ messages: AnthropicMessage[],
400
+ declaresTools: boolean,
401
+ ): AnthropicMessage[] {
402
+ const newestReply = messages.map((message) => message.role).lastIndexOf("assistant");
403
+ if (!declaresTools && newestReply < 0) return messages;
404
+ const previousEnd = newestReply - 1;
405
+ return messages.map((message, i) =>
406
+ i === messages.length - 1 || i === previousEnd ? markLast(message) : message,
407
+ );
298
408
  }
299
409
 
300
410
  /**
@@ -364,10 +474,7 @@ export function anthropicMessages(
364
474
  messages: AnthropicMessage[];
365
475
  } {
366
476
  const wireId = anthropicIds();
367
- const system = messages
368
- .filter((m) => m.role === "system")
369
- .map((m) => m.content)
370
- .join("\n\n");
477
+ const system = messages.flatMap((m) => (m.role === "system" ? [m.content] : []));
371
478
 
372
479
  const toolUse = (call: { id: string; name: string; arguments: string }) => ({
373
480
  type: "tool_use",
@@ -651,7 +758,13 @@ export function anthropicProvider(config: AnthropicConfig, codecs?: HostedCodecs
651
758
  let cached = 0;
652
759
  let written = 0;
653
760
  let output = 0;
654
- const payload = hostedStream?.payload(request, body) ?? request;
761
+ // Marked per pass, because each pass is a request of its own: the one
762
+ // after a pause ends in the paused turn, so that is its newest message.
763
+ const messages = markConversation(
764
+ hostedStream?.messages(body) ?? body,
765
+ request.tools !== undefined,
766
+ );
767
+ const payload = hostedStream?.payload({ ...request, messages }) ?? { ...request, messages };
655
768
 
656
769
  read: for await (const data of streamSse({
657
770
  url: apiUrl(baseUrl, "/v1/messages"),
@@ -783,5 +896,9 @@ export function anthropicProvider(config: AnthropicConfig, codecs?: HostedCodecs
783
896
  }
784
897
  },
785
898
  };
786
- return configuredFallbacks(provider, config, codecs);
899
+ return configuredFallbacks(
900
+ config.redactErrors ? withRedactedErrors(provider) : provider,
901
+ config,
902
+ codecs,
903
+ );
787
904
  }
@@ -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
  }
@@ -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
@@ -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
 
@@ -41,7 +43,8 @@ export interface ToolSpec<I, O> {
41
43
  description: string;
42
44
  /** Advertised to the model verbatim. */
43
45
  inputSchema: JsonObjectSchema;
44
- /** JSON Schema for generated result types. Not validated or sent to providers. */
46
+ /** JSON Schema for generated result types. Not validated here or sent to providers;
47
+ * `zodTool`'s `output` checks results and fills this in. */
45
48
  outputSchema?: Record<string, unknown>;
46
49
  /**
47
50
  * Turn raw arguments into `I`, or throw with a message the MODEL can act on.
@@ -72,7 +75,8 @@ export interface Tool<I = unknown, O = unknown> {
72
75
  readonly name: string;
73
76
  readonly description: string;
74
77
  readonly inputSchema: JsonObjectSchema;
75
- /** JSON Schema for generated result types. Not validated or sent to providers. */
78
+ /** JSON Schema for generated result types. Not validated here or sent to providers;
79
+ * `zodTool`'s `output` checks results and fills this in. */
76
80
  readonly outputSchema?: Record<string, unknown>;
77
81
  readonly timeoutMs: number;
78
82
  readonly isReadOnly: boolean;
@@ -80,6 +84,12 @@ export interface Tool<I = unknown, O = unknown> {
80
84
  readonly isConcurrencySafe: boolean;
81
85
  readonly isTerminal: boolean;
82
86
  definition(): ToolDefinition;
87
+ /**
88
+ * Whether `invoke` would take these raw arguments, by the same `validate`, without running
89
+ * the tool. Ask before opening an approval, so nobody is asked to approve a call that cannot
90
+ * run: it would come back `invalid_input` after they said yes.
91
+ */
92
+ accepts(rawArgs: unknown): boolean;
83
93
  /** Validate, run, and report the outcome. Never throws except on abort. */
84
94
  invoke(rawArgs: unknown, ctx?: ToolContext): Promise<ToolOutcome<O>>;
85
95
  /** The typed path for internal callers: throws on failure. */
@@ -149,6 +159,12 @@ export function defineTool<I = unknown, O = unknown>(spec: ToolSpec<I, O>): Tool
149
159
  return name === "AbortError" ? "aborted" : "failed";
150
160
  }
151
161
 
162
+ /** The one parse `invoke` and `accepts` share, so a host asking first gets the answer
163
+ * `invoke` would give. Throws with the message the model reads. */
164
+ function parse(rawArgs: unknown): I {
165
+ return spec.validate ? spec.validate(rawArgs) : (rawArgs as I);
166
+ }
167
+
152
168
  return {
153
169
  name: spec.name,
154
170
  description: spec.description,
@@ -173,13 +189,22 @@ export function defineTool<I = unknown, O = unknown>(spec: ToolSpec<I, O>): Tool
173
189
  return (await execute(input, ctx)).output;
174
190
  },
175
191
 
192
+ accepts(rawArgs) {
193
+ try {
194
+ parse(rawArgs);
195
+ return true;
196
+ } catch {
197
+ return false;
198
+ }
199
+ },
200
+
176
201
  async invoke(rawArgs, ctx = {}) {
177
202
  const callId = ctx.callId ?? newId();
178
203
  const started = Date.now();
179
204
 
180
205
  let input: I;
181
206
  try {
182
- input = spec.validate ? spec.validate(rawArgs) : (rawArgs as I);
207
+ input = parse(rawArgs);
183
208
  } catch (err) {
184
209
  return {
185
210
  ok: false,