@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
package/dist/zod.js CHANGED
@@ -6,6 +6,12 @@
6
6
  import { z } from "zod";
7
7
  import { defineTool } from "./tools.js";
8
8
  import { clampToSchema } from "./schema.js";
9
+ import { messageOf } from "./errors.js";
10
+ /** zod's JSON Schema without the dialect URI it puts at the root. */
11
+ function jsonSchemaOf(schema, params) {
12
+ const { $schema: _dialect, ...json } = z.toJSONSchema(schema, params);
13
+ return json;
14
+ }
9
15
  /**
10
16
  * A zod schema as the JSON Schema every provider's tool contract wants.
11
17
  *
@@ -15,7 +21,7 @@ import { clampToSchema } from "./schema.js";
15
21
  * tool over that one key, with a message that names neither zod nor the field.
16
22
  */
17
23
  export function toJsonObjectSchema(schema, label = "schema") {
18
- const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { io: "input" });
24
+ const json = jsonSchemaOf(schema, { io: "input" });
19
25
  if (json.type !== "object") {
20
26
  // Every provider requires an object at the top level of a tool's
21
27
  // parameters; a bare string or array is rejected at the wire, far from
@@ -24,33 +30,183 @@ export function toJsonObjectSchema(schema, label = "schema") {
24
30
  }
25
31
  return json;
26
32
  }
33
+ /** How many problems the model reads back: a 1,000-row sheet can fail on every cell. */
34
+ const MAX_ISSUES = 5;
35
+ /**
36
+ * Where each problem is and what to change, in zod's words. The message names the fix
37
+ * ("expected array, received string"); the bare code sent a model back to resend the same
38
+ * call. The rest are counted, so a model that fixes five does not take them for all of it.
39
+ * `root` names a problem with the whole value: the model's arguments, or the tool's result.
40
+ */
41
+ function describeIssues({ issues }, root) {
42
+ const lines = issues
43
+ .slice(0, MAX_ISSUES)
44
+ .map((issue) => `${issue.path.map(String).join(".") || root}: ${issue.message}`);
45
+ if (issues.length > MAX_ISSUES)
46
+ lines.push(`and ${issues.length - MAX_ISSUES} more`);
47
+ return lines.join("; ");
48
+ }
49
+ function isRecord(value) {
50
+ return typeof value === "object" && value !== null;
51
+ }
52
+ /** Whether each zod type a JSON string can stand in for is a JSON list (true) or object (false). */
53
+ const JSON_CONTAINERS = new Map([
54
+ ["array", true],
55
+ ["tuple", true],
56
+ ["object", false],
57
+ ["record", false],
58
+ ]);
59
+ /**
60
+ * `text` decoded, only when it is the JSON container the schema `expected`. Anything else fails
61
+ * the second parse too, and that parse's error would tell the model about a value it never
62
+ * sent: `"[3]"` for a number would come back as "received array". `"42"`, `"null"` and prose
63
+ * stay strings.
64
+ */
65
+ function jsonContainer(text, expected) {
66
+ const isList = JSON_CONTAINERS.get(expected);
67
+ if (isList === undefined)
68
+ return undefined;
69
+ try {
70
+ const value = JSON.parse(text);
71
+ const fits = typeof value === "object" && value !== null && Array.isArray(value) === isList;
72
+ return fits ? value : undefined;
73
+ }
74
+ catch {
75
+ return undefined;
76
+ }
77
+ }
78
+ /**
79
+ * The fix for a value the schema rejected for its type, or undefined when there is none.
80
+ * Both slips cost production runs:
81
+ *
82
+ * - An array or object sent as a JSON string, `{"sheets":"[{...}]"}`. 13 of 16 spreadsheet
83
+ * calls in one day failed this way, each resent unchanged.
84
+ * - A string sent as `{ text }`, copying a sibling field whose items are objects. A research
85
+ * run lost its brief this way on its last step. Only an object holding exactly one string
86
+ * `text`: an extra key or a non-string `text` stays the model's error to fix.
87
+ */
88
+ function slipFix(value, expected) {
89
+ if (typeof value === "string")
90
+ return jsonContainer(value, expected);
91
+ const wrapped = expected === "string" &&
92
+ isRecord(value) &&
93
+ Object.keys(value).length === 1 &&
94
+ typeof value.text === "string";
95
+ return wrapped ? value.text : undefined;
96
+ }
27
97
  /**
28
- * A tool whose arguments are validated by zod, with the failure reported to
29
- * the model in words it can act on. `topic: expected string, received number`
30
- * beats a stack trace it cannot read.
98
+ * `raw` with each slip fixed, only where zod rejected a value for its type: a string the
99
+ * schema took is never decoded, however much it looks like JSON. Returns `raw` itself when
100
+ * nothing applies, and never changes the caller's arguments.
31
101
  */
102
+ function repairSlips(raw, issues) {
103
+ const copy = structuredClone(raw);
104
+ let changed = false;
105
+ for (const issue of issues) {
106
+ if (issue.code !== "invalid_type")
107
+ continue;
108
+ const key = issue.path.at(-1);
109
+ let parent = copy;
110
+ for (const step of issue.path.slice(0, -1))
111
+ parent = isRecord(parent) ? parent[step] : null;
112
+ if (key === undefined || !isRecord(parent))
113
+ continue;
114
+ const fixed = slipFix(parent[key], issue.expected);
115
+ if (fixed === undefined)
116
+ continue;
117
+ parent[key] = fixed;
118
+ changed = true;
119
+ }
120
+ return changed ? copy : raw;
121
+ }
122
+ /**
123
+ * `spec.run` with each result checked against `output` before the model or your code reads it.
124
+ * The result is read as unknown: `output` decides its type, whatever `run` declared.
125
+ */
126
+ function checkedRun(spec, output, describe) {
127
+ return async (input, ctx) => {
128
+ const result = await spec.run(input, ctx);
129
+ let problems;
130
+ let cause;
131
+ try {
132
+ // Async, because the sync parse throws on an async refine or transform.
133
+ const parsed = await output.safeParseAsync(result);
134
+ if (parsed.success)
135
+ return parsed.data;
136
+ cause = parsed.error;
137
+ // Inside the try, so a wording that throws still tells the model the call ran.
138
+ problems = describe(parsed.error, "result");
139
+ }
140
+ catch (err) {
141
+ // zod does not catch a refine or transform that throws (`new URL` on a bad link). The
142
+ // call ran all the same, and that is what the model must read.
143
+ cause = err;
144
+ problems = messageOf(err);
145
+ }
146
+ // The call ran, so a write may already have happened. The model decides whether to
147
+ // call again from this, as it does from `repairHistory`'s interrupted-call note.
148
+ const effect = spec.isReadOnly ? "" : " Check its effect before calling it again.";
149
+ throw new Error(`${spec.name} ran, but its result does not match its output schema.${effect} Problems: ${problems}`, { cause });
150
+ };
151
+ }
152
+ // Two signatures, so only a tool with `output` can return a type `run` does not. `output` comes
153
+ // first: the second signature takes an optional one too, for a wrapper that passes it through,
154
+ // and would type a `run` that returns `unknown` as a tool that returns `unknown`. The body is
155
+ // typed as the second. With `output`, `checkedRun` reads the result as unknown, so that holds
156
+ // for any `R`.
32
157
  export function zodTool(spec) {
33
158
  const inputSchema = toJsonObjectSchema(spec.input, `Tool "${spec.name}" input`);
159
+ const { output } = spec;
160
+ const describe = spec.describeIssues ?? describeIssues;
161
+ function clamp(value) {
162
+ return spec.clampOverflow ? clampToSchema(value, inputSchema) : value;
163
+ }
164
+ // One repair, one more parse, and the error is the second parse's: a real mistake inside
165
+ // a decoded string, or beside a fixed wrapper, still reaches the model. The repaired
166
+ // value is clamped too, since a string unwrapped from `{ text }` can be the one too long.
167
+ function parseInput(raw) {
168
+ let problems;
169
+ let cause;
170
+ try {
171
+ const candidate = clamp(raw);
172
+ const first = spec.input.safeParse(candidate);
173
+ if (first.success)
174
+ return first.data;
175
+ const repaired = repairSlips(candidate, first.error.issues);
176
+ const parsed = repaired === candidate ? first : spec.input.safeParse(clamp(repaired));
177
+ if (parsed.success)
178
+ return parsed.data;
179
+ cause = parsed.error;
180
+ problems = describe(parsed.error, "input");
181
+ }
182
+ catch (err) {
183
+ // A refine or transform that throws, or a `describeIssues` that does, is wrapped as it is
184
+ // on a result. Thrown bare, it was `ToolOutcome.cause` itself, so a log reading
185
+ // `cause.cause`, where zod's error sits, got `undefined`.
186
+ cause = err;
187
+ problems = messageOf(err);
188
+ }
189
+ // The model reads the message, which may be the app's words. What went wrong stays as the
190
+ // cause, and `invoke` keeps what was thrown, so logs still have all of it.
191
+ throw new Error(problems, { cause });
192
+ }
34
193
  return defineTool({
35
194
  name: spec.name,
36
195
  description: spec.description,
37
196
  inputSchema,
197
+ // Metadata only, never sent to a provider. A type JSON Schema cannot express (a Date, a
198
+ // transform) reads as any value here rather than refusing the tool; the check runs on zod.
199
+ ...(output
200
+ ? { outputSchema: jsonSchemaOf(output, { io: "output", unrepresentable: "any" }) }
201
+ : {}),
38
202
  ...(spec.summarize ? { summarize: spec.summarize } : {}),
39
203
  ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
40
204
  ...(spec.isReadOnly !== undefined ? { isReadOnly: spec.isReadOnly } : {}),
41
205
  ...(spec.needsApproval !== undefined ? { needsApproval: spec.needsApproval } : {}),
42
206
  ...(spec.isConcurrencySafe !== undefined ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
43
207
  ...(spec.isTerminal !== undefined ? { isTerminal: spec.isTerminal } : {}),
44
- validate: (raw) => {
45
- const candidate = spec.clampOverflow ? clampToSchema(raw, inputSchema) : raw;
46
- const parsed = spec.input.safeParse(candidate);
47
- if (parsed.success)
48
- return parsed.data;
49
- throw new Error(parsed.error.issues
50
- .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
51
- .join("; "));
52
- },
53
- run: spec.run,
208
+ validate: parseInput,
209
+ run: output ? checkedRun(spec, output, describe) : spec.run,
54
210
  });
55
211
  }
56
212
  //# sourceMappingURL=zod.js.map
package/dist/zod.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"zod.js","sourceRoot":"","sources":["../src/zod.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@providerkit/core",
3
- "version": "0.33.1",
3
+ "version": "0.35.0",
4
4
  "description": "The layer under your agent loop: one seam for every LLM provider, plus the failure handling you only learn in production.",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/src/errors.ts CHANGED
@@ -390,6 +390,11 @@ const ENTITLEMENT_PATTERNS: readonly RegExp[] = [
390
390
  // The ChatGPT backend's error code, which arrives with no prose at all.
391
391
  /usage_not_included/i,
392
392
  /usage not included/i,
393
+ // Z.ai's plan gate, code 1311: "[1311][当前订阅套餐暂未开放GLM-5.3-FlashX权限]", the plan does
394
+ // not include this model yet. It comes as a 403, so it read as a wrong key, and a key pool
395
+ // benched a working key for 12 hours. The code is matched with the bracket after it, as Z.ai
396
+ // writes it, because OpenAI's errors name one message of a long history as `messages[1311]`.
397
+ /\[1311\]\[|暂未开放/,
393
398
  ];
394
399
 
395
400
  const OPENCODE_FREE_LIMIT = /\bFreeUsageLimitError\b/i;
@@ -470,6 +475,10 @@ const MODEL_PATTERNS: readonly RegExp[] = [
470
475
  // requested model." On status alone that is a wrong key, but the key is fine: another model is
471
476
  // the fix (its errors page, read 2026-11-11).
472
477
  /does not have access to the requested model/i,
478
+ // Google, for a model that answers one turn only: "Multiturn chat is not enabled for
479
+ // models/antigravity-preview-latest". A 400, so `invalid` on status alone, and a pool stopped on
480
+ // it. Every turn after the first is multiturn, so the fix is another model.
481
+ /multiturn chat is not enabled/i,
473
482
  ];
474
483
 
475
484
  /** An optional model id after the word "model", quoted or not: "model `gpt-4`", "Model mimo-v2.5". */
@@ -497,7 +506,13 @@ const RETIRED_MODEL_PATTERNS: readonly RegExp[] = [
497
506
 
498
507
  const AUTH_PATTERNS: readonly RegExp[] = [
499
508
  /invalid[_\s]?(?:x-api-key|api[ _-]?key|token|credentials?)/i,
500
- /api[ _-]?key (?:is )?(?:not valid|invalid|incorrect)/i,
509
+ // "missing" and "required" come from an adopter's own classifier, with no recorded body: a key
510
+ // that never arrived is fixed the same way as a wrong one.
511
+ /api[ _-]?key (?:is )?(?:not valid|invalid|incorrect|missing|required)/i,
512
+ // Google's OpenAI-compatible endpoint answers a bad key with a 400 that says only "Please pass a
513
+ // valid API key". On status alone that is `invalid`, so a key pool never tried its next key and
514
+ // a fallback chain stopped, though the key is the fix.
515
+ /pass a valid api[ _-]?key/i,
501
516
  /unauthorized|UNAUTHENTICATED|PERMISSION_DENIED/i,
502
517
  /authentication[_\s](?:failed|invalid|error)/i,
503
518
  /account (?:disabled|suspended|deactivated|banned)/i,
package/src/fallback.ts CHANGED
@@ -71,17 +71,26 @@ export type FallbackCandidate = Provider | FallbackSpec;
71
71
  function resolveFallback(
72
72
  candidate: FallbackCandidate,
73
73
  inheritedWatchdog?: WatchdogOptions,
74
+ inheritedRedactErrors?: boolean,
74
75
  codecs?: HostedCodecs,
75
76
  ): Provider {
76
77
  if (typeof candidate === "object" && candidate !== null && "createStream" in candidate) {
78
+ // `redactErrors` is not applied here: a hand-built provider keeps its own errors. We didn't
79
+ // build it, and a rebuild would turn a pool's `NoAvailableProviderError` into a plain error.
77
80
  return inheritedWatchdog ? withWatchdog(candidate, inheritedWatchdog) : candidate;
78
81
  }
79
- const { preset, watchdog = inheritedWatchdog, ...config } = candidate;
82
+ const {
83
+ preset,
84
+ watchdog = inheritedWatchdog,
85
+ redactErrors = inheritedRedactErrors,
86
+ ...config
87
+ } = candidate;
80
88
  return presetProvider(
81
89
  preset,
82
90
  {
83
91
  ...config,
84
92
  ...(watchdog ? { watchdog } : {}),
93
+ ...(redactErrors ? { redactErrors } : {}),
85
94
  },
86
95
  codecs,
87
96
  );
@@ -112,10 +121,11 @@ export function withConfiguredFallbacks(
112
121
  return configuredFallbacks(primary, config);
113
122
  }
114
123
 
115
- /** @internal Keeps opt-in codecs on nested preset fallbacks. */
124
+ /** @internal Keeps opt-in codecs on nested preset fallbacks. `redactErrors` comes in with the
125
+ * adapter's or preset's own config, so its specs inherit it as they inherit the watchdog. */
116
126
  export function configuredFallbacks(
117
127
  primary: Provider,
118
- config?: ProviderFallbackConfig,
128
+ config?: ProviderFallbackConfig & { redactErrors?: boolean },
119
129
  codecs?: HostedCodecs,
120
130
  ): Provider {
121
131
  const watchedPrimary = config?.watchdog ? withWatchdog(primary, config.watchdog) : primary;
@@ -123,7 +133,9 @@ export function configuredFallbacks(
123
133
  return withFallbackProviders(
124
134
  [
125
135
  watchedPrimary,
126
- ...config.fallbacks.map((candidate) => resolveFallback(candidate, config.watchdog, codecs)),
136
+ ...config.fallbacks.map((candidate) =>
137
+ resolveFallback(candidate, config.watchdog, config.redactErrors, codecs),
138
+ ),
127
139
  ],
128
140
  config.fallbackOptions,
129
141
  );
@@ -393,15 +393,16 @@ export const anthropicHosted = {
393
393
  }
394
394
  }
395
395
  return {
396
- payload(request: Record<string, unknown>, body: AnthropicMessage[]) {
396
+ /** The conversation a pass sends: `body`, then what the paused passes
397
+ * wrote, as the turn they continue. */
398
+ messages(body: AnthropicMessage[]): AnthropicMessage[] {
399
+ return resumed.length > 0 ? resumeWith(body, resumed) : body;
400
+ },
401
+ payload(request: Record<string, unknown>) {
397
402
  blocks = [];
398
403
  open = undefined;
399
404
  servers = undefined;
400
- return {
401
- ...request,
402
- ...(resumed.length > 0 ? { messages: resumeWith(body, resumed) } : {}),
403
- ...(container ? { container } : {}),
404
- };
405
+ return { ...request, ...(container ? { container } : {}) };
405
406
  },
406
407
  *event(event: AnthropicEvent): Generator<ProviderChunk> {
407
408
  const usage = event.type === "message_start" ? event.message?.usage : event.usage;
package/src/image.ts CHANGED
@@ -22,6 +22,22 @@ export interface ImageLimits {
22
22
  maxImages: number;
23
23
  }
24
24
 
25
+ /** Which images a gate looks at, and what its notes say. Left out, it gates every image. */
26
+ export interface ImageGateOptions {
27
+ /**
28
+ * Gate only the images in tool results. The person's own images stay as they are and do not
29
+ * count toward `maxImages`: they are what the task is about, so a long run that drops them
30
+ * forgets what it was asked. An old screenshot is the cheapest thing in a run to lose.
31
+ */
32
+ toolResultsOnly?: boolean;
33
+ /**
34
+ * The reason every note gives, in place of each image's own. For a model that reads no
35
+ * images, pass `maxImages: 0` and a reason that says so: the cap's own note,
36
+ * "only the last 0 images are attached per request", tells it nothing true.
37
+ */
38
+ reason?: string;
39
+ }
40
+
25
41
  interface Raster {
26
42
  width: number;
27
43
  height: number;
@@ -155,10 +171,24 @@ function omitted(image: ImagePart, reason: string): string {
155
171
  * joins the result's text. Of the images that pass, only the newest
156
172
  * `maxImages` stay, so the latest screenshot is the one the model sees.
157
173
  */
158
- export function gateImages(messages: readonly ChatMessage[], limits: ImageLimits): ChatMessage[] {
174
+ export function gateImages(
175
+ messages: readonly ChatMessage[],
176
+ limits: ImageLimits,
177
+ options: ImageGateOptions = {},
178
+ ): ChatMessage[] {
179
+ /** With `toolResultsOnly`, a user turn is never read, counted or rewritten. */
180
+ function gated(message: ChatMessage): boolean {
181
+ return !options.toolResultsOnly || message.role !== "user";
182
+ }
183
+ function note(image: ImagePart, reason: string): string {
184
+ return omitted(image, options.reason ?? reason);
185
+ }
159
186
  // One verdict per image, in conversation order: a reason, or undefined to
160
187
  // keep it. Past the cap, the oldest images that pass give way.
161
- const verdicts = messages.flatMap(imagesOf).map((image) => refusal(image, limits));
188
+ const verdicts = messages
189
+ .filter(gated)
190
+ .flatMap(imagesOf)
191
+ .map((image) => refusal(image, limits));
162
192
  let surplus = verdicts.filter((reason) => reason === undefined).length - limits.maxImages;
163
193
  for (let i = 0; surplus > 0; i++) {
164
194
  if (verdicts[i] !== undefined) continue;
@@ -168,11 +198,12 @@ export function gateImages(messages: readonly ChatMessage[], limits: ImageLimits
168
198
 
169
199
  let next = 0;
170
200
  return messages.map((message): ChatMessage => {
201
+ if (!gated(message)) return message;
171
202
  if (message.role === "user" && typeof message.content !== "string") {
172
203
  const content = message.content.map((part): ContentPart => {
173
204
  if (part.type !== "image") return part;
174
205
  const reason = verdicts[next++];
175
- return reason === undefined ? part : { type: "text", text: omitted(part, reason) };
206
+ return reason === undefined ? part : { type: "text", text: note(part, reason) };
176
207
  });
177
208
  return { ...message, content };
178
209
  }
@@ -182,7 +213,7 @@ export function gateImages(messages: readonly ChatMessage[], limits: ImageLimits
182
213
  for (const image of message.images) {
183
214
  const reason = verdicts[next++];
184
215
  if (reason === undefined) images.push(image);
185
- else notes.push(omitted(image, reason));
216
+ else notes.push(note(image, reason));
186
217
  }
187
218
  if (notes.length === 0) return message;
188
219
  const content = [message.content, ...notes].filter(Boolean).join("\n");
package/src/index.ts CHANGED
@@ -38,6 +38,7 @@ export {
38
38
  } from "./transport.ts";
39
39
  export * from "./rate-limit.ts";
40
40
  export * from "./tool-args.ts";
41
+ export * from "./tool-markup.ts";
41
42
  export * from "./tools.ts";
42
43
  export * from "./schema.ts";
43
44
  export * from "./context.ts";
package/src/presets.ts CHANGED
@@ -302,6 +302,24 @@ export const PROVIDER_PRESETS = {
302
302
  "x-ai/grok-4.6",
303
303
  "openai/gpt-5.6-luna-pro",
304
304
  ],
305
+ // An absent `max_tokens` is not "no limit" here. OpenRouter holds each paid call's cost up
306
+ // front, counting "the completion tokens allowed by `max_tokens` up to a fixed per-request
307
+ // cap (the cap is used when `max_tokens` is not set)" (its limits page, read 2026-11-19, which
308
+ // gives the cap no value). On a low balance that hold alone answers 402. An adopter's error
309
+ // watcher got one on 2026-09-10: "You requested up to 131072 tokens", the whole window
310
+ // `z-ai/glm-5.3-flash` had then, for an answer of a few thousand. So this ceiling shrinks the
311
+ // hold only while the cap is above 32,000. It stops a runaway either way. 32,000 is that
312
+ // adopter's chat ceiling, from 60 days of its output: p99 16,389 tokens on GLM 5.3 Flash and
313
+ // 9,565 on DeepSeek V4 Flash, a longest real answer of 33,429 (which this cuts), and one
314
+ // runaway call that returned 131,072. A caller sets its own `maxTokens` in two cases, both as
315
+ // of 2026-11-19. The ceiling has to fit in the window beside the prompt, so a prompt within
316
+ // 32,000 tokens of a model's window fails as `context`; the models above have windows of
317
+ // 500,000 or more. And "if you set `max_tokens`, then OpenRouter will only route to providers
318
+ // that support a response of that length" (its provider routing page): 57 of the 479 models
319
+ // it listed had no host that writes 32,000 (`openai/gpt-4o-mini` stops at 16,384), and every
320
+ // host of every model above writes 65,536 or more. 16,384 would keep gpt-4o-mini, and cut
321
+ // about one in a hundred of those GLM answers.
322
+ maxTokens: 32_000,
305
323
  // Source: OpenRouter's text-to-speech guide, read 2026-11-02. It takes mp3 or pcm
306
324
  // (its own default is pcm), and some models take only one: Gemini TTS and HeyGen
307
325
  // answer 400 to mp3, MiniMax to pcm. This row asks for mp3, so a Gemini TTS model
@@ -530,9 +548,10 @@ export const PROVIDER_PRESETS = {
530
548
  * Muse Contributor, measured 2026-09-28 on /responses: text, images, strict
531
549
  * JSON Schema, parallel tools and tool-result round trips all passed. It
532
550
  * requires reasoning (`none` becomes `minimal`) and accepts only automatic
533
- * tool choice (`none` is encoded by sending no tools). Contributor requests
534
- * may be used to improve Meta products; the workspace must explicitly allow
535
- * those endpoints.
551
+ * tool choice: `none` is sent as no tools and a named tool as that tool alone,
552
+ * while `required`, and a named tool that is the call's only tool, are still
553
+ * sent and refused. Contributor requests may be used to improve Meta products;
554
+ * the workspace must explicitly allow those endpoints.
536
555
  *
537
556
  * Reasoning effort is spelled per model on chat completions (see
538
557
  * `effortParams`): GLM takes only `high` and `max`, DeepSeek V4 and MiMo