@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/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. */
package/src/zod.ts CHANGED
@@ -6,8 +6,20 @@
6
6
  import { z } from "zod";
7
7
  import { defineTool, type Tool, type ToolContext } from "./tools.ts";
8
8
  import { clampToSchema } from "./schema.ts";
9
+ import { messageOf } from "./errors.ts";
9
10
  import type { JsonObjectSchema } from "./types.ts";
10
11
 
12
+ type Issues = readonly z.core.$ZodIssue[];
13
+
14
+ /** zod's JSON Schema without the dialect URI it puts at the root. */
15
+ function jsonSchemaOf(
16
+ schema: z.ZodType,
17
+ params: z.core.ToJSONSchemaParams,
18
+ ): Record<string, unknown> {
19
+ const { $schema: _dialect, ...json } = z.toJSONSchema(schema, params) as Record<string, unknown>;
20
+ return json;
21
+ }
22
+
11
23
  /**
12
24
  * A zod schema as the JSON Schema every provider's tool contract wants.
13
25
  *
@@ -17,10 +29,7 @@ import type { JsonObjectSchema } from "./types.ts";
17
29
  * tool over that one key, with a message that names neither zod nor the field.
18
30
  */
19
31
  export function toJsonObjectSchema(schema: z.ZodType, label = "schema"): JsonObjectSchema {
20
- const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { io: "input" }) as Record<
21
- string,
22
- unknown
23
- >;
32
+ const json = jsonSchemaOf(schema, { io: "input" });
24
33
  if (json.type !== "object") {
25
34
  // Every provider requires an object at the top level of a tool's
26
35
  // parameters; a bare string or array is rejected at the wire, far from
@@ -30,11 +39,20 @@ export function toJsonObjectSchema(schema: z.ZodType, label = "schema"): JsonObj
30
39
  return json as JsonObjectSchema;
31
40
  }
32
41
 
33
- export interface ZodToolSpec<I, O> {
42
+ /** `R` is what `run` returns. It is `O` unless `output` parses it into something else. */
43
+ export interface ZodToolSpec<I, O, R = O> {
34
44
  name: string;
35
45
  description: string;
36
46
  input: z.ZodType<I>;
37
- run: (input: I, ctx: ToolContext) => Promise<O>;
47
+ /**
48
+ * Checks every result before the model or your code reads it, and fills `outputSchema` for
49
+ * generated result types. `run` returns what the schema takes, `unknown` included, and the
50
+ * tool returns what the schema parses that into, after any transform. A result that fails is
51
+ * a `failed` outcome the model reads, and its value is dropped. A result that passes is the
52
+ * parsed value, so unknown keys are dropped and defaults are filled in before the model sees it.
53
+ */
54
+ output?: z.ZodType<O, R>;
55
+ run: (input: I, ctx: ToolContext) => Promise<R>;
38
56
  summarize?: (output: O) => string;
39
57
  timeoutMs?: number;
40
58
  isReadOnly?: boolean;
@@ -49,36 +67,220 @@ export interface ZodToolSpec<I, O> {
49
67
  * Off by default: an ordinary tool can simply be called again.
50
68
  */
51
69
  clampOverflow?: boolean;
70
+ /**
71
+ * Writes the problems zod found in your words instead of zod's, for the input check and the
72
+ * `output` check. zod's sentence can list every value a field accepts and quote the caller's
73
+ * key names, and an app that saves tool replies keeps that text: an adopter shows each reply
74
+ * again in its studio for a week, so it words a problem from its path and code alone. That
75
+ * tells the model less. A bare `invalid_type` at `sheets` once sent a model back to resend
76
+ * the same call, which is why the default keeps zod's sentence.
77
+ *
78
+ * It gets zod's error, with every issue, and `checked`: `input` for the model's arguments,
79
+ * `result` for what `run` returned. On input it words the same parse `invoke` and `accepts`
80
+ * decide by, after the repairs. Only the default stops at five issues. A check that throws
81
+ * reads as its own message, and so does a `describeIssues` that throws. On both checks, the
82
+ * error the tool throws keeps zod's error as its `cause`, or what was thrown in its place, so
83
+ * your logs find it at `ToolOutcome.cause.cause`. Defaults to zod's message for each issue,
84
+ * after its path.
85
+ */
86
+ describeIssues?: (error: z.ZodError, checked: "input" | "result") => string;
87
+ }
88
+
89
+ /** How many problems the model reads back: a 1,000-row sheet can fail on every cell. */
90
+ const MAX_ISSUES = 5;
91
+
92
+ /**
93
+ * Where each problem is and what to change, in zod's words. The message names the fix
94
+ * ("expected array, received string"); the bare code sent a model back to resend the same
95
+ * call. The rest are counted, so a model that fixes five does not take them for all of it.
96
+ * `root` names a problem with the whole value: the model's arguments, or the tool's result.
97
+ */
98
+ function describeIssues({ issues }: z.ZodError, root: "input" | "result"): string {
99
+ const lines = issues
100
+ .slice(0, MAX_ISSUES)
101
+ .map((issue) => `${issue.path.map(String).join(".") || root}: ${issue.message}`);
102
+ if (issues.length > MAX_ISSUES) lines.push(`and ${issues.length - MAX_ISSUES} more`);
103
+ return lines.join("; ");
104
+ }
105
+
106
+ function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
107
+ return typeof value === "object" && value !== null;
52
108
  }
53
109
 
110
+ /** Whether each zod type a JSON string can stand in for is a JSON list (true) or object (false). */
111
+ const JSON_CONTAINERS = new Map([
112
+ ["array", true],
113
+ ["tuple", true],
114
+ ["object", false],
115
+ ["record", false],
116
+ ]);
117
+
118
+ /**
119
+ * `text` decoded, only when it is the JSON container the schema `expected`. Anything else fails
120
+ * the second parse too, and that parse's error would tell the model about a value it never
121
+ * sent: `"[3]"` for a number would come back as "received array". `"42"`, `"null"` and prose
122
+ * stay strings.
123
+ */
124
+ function jsonContainer(text: string, expected: string): object | undefined {
125
+ const isList = JSON_CONTAINERS.get(expected);
126
+ if (isList === undefined) return undefined;
127
+ try {
128
+ const value: unknown = JSON.parse(text);
129
+ const fits = typeof value === "object" && value !== null && Array.isArray(value) === isList;
130
+ return fits ? value : undefined;
131
+ } catch {
132
+ return undefined;
133
+ }
134
+ }
135
+
136
+ /**
137
+ * The fix for a value the schema rejected for its type, or undefined when there is none.
138
+ * Both slips cost production runs:
139
+ *
140
+ * - An array or object sent as a JSON string, `{"sheets":"[{...}]"}`. 13 of 16 spreadsheet
141
+ * calls in one day failed this way, each resent unchanged.
142
+ * - A string sent as `{ text }`, copying a sibling field whose items are objects. A research
143
+ * run lost its brief this way on its last step. Only an object holding exactly one string
144
+ * `text`: an extra key or a non-string `text` stays the model's error to fix.
145
+ */
146
+ function slipFix(value: unknown, expected: string): unknown {
147
+ if (typeof value === "string") return jsonContainer(value, expected);
148
+ const wrapped =
149
+ expected === "string" &&
150
+ isRecord(value) &&
151
+ Object.keys(value).length === 1 &&
152
+ typeof value.text === "string";
153
+ return wrapped ? value.text : undefined;
154
+ }
155
+
156
+ /**
157
+ * `raw` with each slip fixed, only where zod rejected a value for its type: a string the
158
+ * schema took is never decoded, however much it looks like JSON. Returns `raw` itself when
159
+ * nothing applies, and never changes the caller's arguments.
160
+ */
161
+ function repairSlips(raw: unknown, issues: Issues): unknown {
162
+ const copy = structuredClone(raw);
163
+ let changed = false;
164
+ for (const issue of issues) {
165
+ if (issue.code !== "invalid_type") continue;
166
+ const key = issue.path.at(-1);
167
+ let parent: unknown = copy;
168
+ for (const step of issue.path.slice(0, -1)) parent = isRecord(parent) ? parent[step] : null;
169
+ if (key === undefined || !isRecord(parent)) continue;
170
+ const fixed = slipFix(parent[key], issue.expected);
171
+ if (fixed === undefined) continue;
172
+ parent[key] = fixed;
173
+ changed = true;
174
+ }
175
+ return changed ? copy : raw;
176
+ }
177
+
178
+ /**
179
+ * `spec.run` with each result checked against `output` before the model or your code reads it.
180
+ * The result is read as unknown: `output` decides its type, whatever `run` declared.
181
+ */
182
+ function checkedRun<I, O>(
183
+ spec: ZodToolSpec<I, O, unknown>,
184
+ output: z.ZodType<O>,
185
+ describe: typeof describeIssues,
186
+ ): (input: I, ctx: ToolContext) => Promise<O> {
187
+ return async (input, ctx) => {
188
+ const result = await spec.run(input, ctx);
189
+ let problems: string;
190
+ let cause: unknown;
191
+ try {
192
+ // Async, because the sync parse throws on an async refine or transform.
193
+ const parsed = await output.safeParseAsync(result);
194
+ if (parsed.success) return parsed.data;
195
+ cause = parsed.error;
196
+ // Inside the try, so a wording that throws still tells the model the call ran.
197
+ problems = describe(parsed.error, "result");
198
+ } catch (err) {
199
+ // zod does not catch a refine or transform that throws (`new URL` on a bad link). The
200
+ // call ran all the same, and that is what the model must read.
201
+ cause = err;
202
+ problems = messageOf(err);
203
+ }
204
+ // The call ran, so a write may already have happened. The model decides whether to
205
+ // call again from this, as it does from `repairHistory`'s interrupted-call note.
206
+ const effect = spec.isReadOnly ? "" : " Check its effect before calling it again.";
207
+ throw new Error(
208
+ `${spec.name} ran, but its result does not match its output schema.${effect} Problems: ${problems}`,
209
+ { cause },
210
+ );
211
+ };
212
+ }
213
+
214
+ /**
215
+ * A zod tool that checks its results too. It returns what `output` makes of `run`'s result, so
216
+ * `run` can return `unknown`, or the string a transform turns into a `Date`.
217
+ */
218
+ export function zodTool<I, O, R>(
219
+ spec: ZodToolSpec<I, O, R> & { output: z.ZodType<O, R> },
220
+ ): Tool<I, O>;
54
221
  /**
55
222
  * A tool whose arguments are validated by zod, with the failure reported to
56
223
  * the model in words it can act on. `topic: expected string, received number`
57
224
  * beats a stack trace it cannot read.
58
225
  */
226
+ export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O>;
227
+ // Two signatures, so only a tool with `output` can return a type `run` does not. `output` comes
228
+ // first: the second signature takes an optional one too, for a wrapper that passes it through,
229
+ // and would type a `run` that returns `unknown` as a tool that returns `unknown`. The body is
230
+ // typed as the second. With `output`, `checkedRun` reads the result as unknown, so that holds
231
+ // for any `R`.
59
232
  export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O> {
60
233
  const inputSchema = toJsonObjectSchema(spec.input, `Tool "${spec.name}" input`);
234
+ const { output } = spec;
235
+ const describe = spec.describeIssues ?? describeIssues;
236
+
237
+ function clamp(value: unknown): unknown {
238
+ return spec.clampOverflow ? clampToSchema(value, inputSchema) : value;
239
+ }
240
+
241
+ // One repair, one more parse, and the error is the second parse's: a real mistake inside
242
+ // a decoded string, or beside a fixed wrapper, still reaches the model. The repaired
243
+ // value is clamped too, since a string unwrapped from `{ text }` can be the one too long.
244
+ function parseInput(raw: unknown): I {
245
+ let problems: string;
246
+ let cause: unknown;
247
+ try {
248
+ const candidate = clamp(raw);
249
+ const first = spec.input.safeParse(candidate);
250
+ if (first.success) return first.data;
251
+ const repaired = repairSlips(candidate, first.error.issues);
252
+ const parsed = repaired === candidate ? first : spec.input.safeParse(clamp(repaired));
253
+ if (parsed.success) return parsed.data;
254
+ cause = parsed.error;
255
+ problems = describe(parsed.error, "input");
256
+ } catch (err) {
257
+ // A refine or transform that throws, or a `describeIssues` that does, is wrapped as it is
258
+ // on a result. Thrown bare, it was `ToolOutcome.cause` itself, so a log reading
259
+ // `cause.cause`, where zod's error sits, got `undefined`.
260
+ cause = err;
261
+ problems = messageOf(err);
262
+ }
263
+ // The model reads the message, which may be the app's words. What went wrong stays as the
264
+ // cause, and `invoke` keeps what was thrown, so logs still have all of it.
265
+ throw new Error(problems, { cause });
266
+ }
61
267
 
62
268
  return defineTool<I, O>({
63
269
  name: spec.name,
64
270
  description: spec.description,
65
271
  inputSchema,
272
+ // Metadata only, never sent to a provider. A type JSON Schema cannot express (a Date, a
273
+ // transform) reads as any value here rather than refusing the tool; the check runs on zod.
274
+ ...(output
275
+ ? { outputSchema: jsonSchemaOf(output, { io: "output", unrepresentable: "any" }) }
276
+ : {}),
66
277
  ...(spec.summarize ? { summarize: spec.summarize } : {}),
67
278
  ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
68
279
  ...(spec.isReadOnly !== undefined ? { isReadOnly: spec.isReadOnly } : {}),
69
280
  ...(spec.needsApproval !== undefined ? { needsApproval: spec.needsApproval } : {}),
70
281
  ...(spec.isConcurrencySafe !== undefined ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
71
282
  ...(spec.isTerminal !== undefined ? { isTerminal: spec.isTerminal } : {}),
72
- validate: (raw) => {
73
- const candidate = spec.clampOverflow ? clampToSchema(raw, inputSchema) : raw;
74
- const parsed = spec.input.safeParse(candidate);
75
- if (parsed.success) return parsed.data;
76
- throw new Error(
77
- parsed.error.issues
78
- .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
79
- .join("; "),
80
- );
81
- },
82
- run: spec.run,
283
+ validate: parseInput,
284
+ run: output ? checkedRun(spec, output, describe) : spec.run,
83
285
  });
84
286
  }