@providerkit/core 0.1.0

package/src/transport.ts

@@ -0,0 +1,162 @@
+// The wire. One `fetch`, one SSE reader, one error envelope — no vendor SDK,
+// no Node built-ins, so the same build runs in Bun, Node, Workers, Deno and an
+// MV3 service worker.
+//
+// Adapters keep only their per-event mapping; everything about being an HTTP
+// client lives here once.
+import { classify, isTransportFailure, ProviderError } from "./errors.ts";
+
+export interface RequestInit_ {
+  url: string;
+  headers?: Record<string, string>;
+  body: unknown;
+  /** Names the provider in the error envelope. */
+  provider: string;
+  signal?: AbortSignal;
+  /** Swapped in tests, or to route through a proxy. Defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+/** Join a base URL and a path without doubling or dropping the slash. */
+export function apiUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+}
+
+/**
+ * How long the provider says to wait, read from the RESPONSE rather than from
+ * a thrown error. Headers are authoritative — `Retry-After` first, then the
+ * vendor reset headers that name a subscription window rather than a
+ * per-minute throttle, because "try again in a moment" is a lie for those.
+ */
+export function retryAfterFromHeaders(headers: Headers, now = Date.now()): number | undefined {
+  const retryAfter = headers.get("retry-after");
+  if (retryAfter) {
+    if (/^\d+$/.test(retryAfter)) return Number(retryAfter) * 1000;
+    const date = Date.parse(retryAfter);
+    if (!Number.isNaN(date)) return Math.max(0, date - now);
+  }
+  // Anthropic and several gateways publish an epoch-seconds reset instead.
+  for (const name of [
+    "anthropic-ratelimit-unified-reset",
+    "anthropic-ratelimit-requests-reset",
+    "anthropic-ratelimit-tokens-reset",
+    "x-ratelimit-reset-requests",
+    "x-ratelimit-reset-tokens",
+    "x-ratelimit-reset",
+  ]) {
+    const value = headers.get(name);
+    if (!value) continue;
+    if (/^\d+$/.test(value)) {
+      const seconds = Number(value);
+      // Epoch seconds (a big number) or a relative count — tell them apart by
+      // magnitude rather than by trusting one vendor's convention.
+      const ms = seconds > 1_000_000_000 ? seconds * 1000 - now : seconds * 1000;
+      if (ms > 0) return ms;
+    }
+    const date = Date.parse(value);
+    if (!Number.isNaN(date)) return Math.max(0, date - now);
+  }
+  return undefined;
+}
+
+/** Turn a non-2xx response into the classified error every caller branches on. */
+async function errorFor(provider: string, res: Response): Promise<ProviderError> {
+  const text = await res.text().catch(() => "");
+  const kind = classify({ status: res.status, error: text }, res.status, text);
+  const message = text
+    ? `${provider} ${res.status}: ${text.slice(0, 500)}`
+    : `${provider} ${res.status} ${res.statusText}`;
+  return new ProviderError(provider, kind, message, {
+    status: res.status,
+    retryAfterMs: retryAfterFromHeaders(res.headers),
+    body: text.slice(0, 2_000) || undefined,
+  });
+}
+
+async function send(opts: RequestInit_): Promise<Response> {
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  try {
+    return await doFetch(opts.url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...opts.headers },
+      body: typeof opts.body === "string" ? opts.body : JSON.stringify(opts.body),
+      signal: opts.signal,
+    });
+  } catch (err) {
+    // A stopped run rejects here too, and that is not a failure — let it pass
+    // through untouched. Anything that is not a recognizable transport
+    // rejection is a bug of ours and keeps its own loud shape.
+    if (opts.signal?.aborted || !isTransportFailure(err)) throw err;
+    throw new ProviderError(opts.provider, "network", `no response from ${opts.url}`, {
+      cause: err,
+    });
+  }
+}
+
+/** POST and parse one JSON response. For the endpoints that do not stream. */
+export async function postJson<T = unknown>(opts: RequestInit_): Promise<T> {
+  const res = await send(opts);
+  if (!res.ok) throw await errorFor(opts.provider, res);
+  return (await res.json()) as T;
+}
+
+/**
+ * POST an SSE request and yield each `data:` payload, trimmed.
+ *
+ * Frames are split on the blank line the spec requires, so a payload
+ * containing a bare newline survives; `[DONE]` is swallowed here rather than in
+ * every adapter. CRLF is normalized — some gateways send it, and a `\r` left on
+ * the end of a JSON payload is a parse error nobody enjoys debugging.
+ */
+export async function* streamSse(opts: RequestInit_): AsyncGenerator<string> {
+  const res = await send(opts);
+  if (!res.ok) throw await errorFor(opts.provider, res);
+  // A 2xx with no body at all is an upstream anomaly, not a request we got
+  // wrong — worth the same retry a 5xx gets.
+  if (!res.body) {
+    throw new ProviderError(opts.provider, "overload", `${opts.provider}: empty response body`, {
+      status: res.status,
+    });
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  /** Pull the `data:` payload out of one SSE frame, joining continuation
+   *  lines the way the spec says to. Returns null for a comment or a frame
+   *  carrying only an `event:` name. */
+  function payloadOf(frame: string): string | null {
+    const parts: string[] = [];
+    for (const line of frame.split("\n")) {
+      if (!line.startsWith("data:")) continue;
+      parts.push(line.slice(5).replace(/^ /, ""));
+    }
+    if (parts.length === 0) return null;
+    const payload = parts.join("\n").trim();
+    return payload.length > 0 ? payload : null;
+  }
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true }).replace(/\r\n/g, "\n");
+
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const frame = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        const payload = payloadOf(frame);
+        if (payload !== null && payload !== "[DONE]") yield payload;
+        boundary = buffer.indexOf("\n\n");
+      }
+    }
+    // A stream that ends without its final blank line still has an event in
+    // hand — dropping it loses the last delta, or the usage record.
+    const tail = payloadOf(buffer);
+    if (tail !== null && tail !== "[DONE]") yield tail;
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/types.ts

@@ -0,0 +1,231 @@
+// The seam — provider-neutral messages, tools and chunks. Every adapter
+// (OpenAI-compatible, Anthropic, Responses, Gemini) translates to and from
+// exactly these shapes, so a caller never sees a vendor's dialect.
+//
+// Deliberately NOT OpenAI's parameter types. Using one vendor's wire shape as
+// the lingua franca forces the other adapters to round-trip through a dialect
+// that isn't theirs, and every quirk of that dialect then leaks into callers
+// who never asked for it.
+
+/**
+ * How hard the model thinks before answering. Absent = the provider's own
+ * default (never sent). Passed through verbatim on OpenAI-shape
+ * (`reasoning_effort`); mapped to thinking budgets on Anthropic-shape.
+ * Support varies per model — an unsupported level comes back as a clean 400.
+ *
+ * Ordered least → most; the type derives from the array so the runtime guard
+ * and the union can never drift apart.
+ */
+export const EFFORTS = ["none", "low", "medium", "high", "max"] as const;
+export type Effort = (typeof EFFORTS)[number];
+
+/** The one place the effort union meets raw input (pickers, CLI flags). */
+export function isEffort(value: string): value is Effort {
+  return EFFORTS.some((effort) => effort === value);
+}
+
+export type ImageMimeType = "image/jpeg" | "image/png" | "image/webp" | "image/gif";
+
+export interface TextPart {
+  type: "text";
+  text: string;
+}
+
+/** An image the model looks at (vision) — bytes as base64, never a URL the
+ *  provider would have to fetch on our behalf. */
+export interface ImagePart {
+  type: "image";
+  mimeType: ImageMimeType;
+  data: string;
+}
+
+export type ContentPart = TextPart | ImagePart;
+
+/**
+ * A tool the model asked to run. `arguments` is the RAW JSON string, not a
+ * parsed object: it arrives in fragments and can be truncated mid-stream, so
+ * assembly and validation are the consumer's job (see tools/define).
+ */
+export interface ToolCall {
+  id: string;
+  name: string;
+  arguments: string;
+  /** Gemini's opaque reasoning token. It must ride back on the next turn
+   *  verbatim or the model loses its own chain of thought. */
+  thoughtSignature?: string;
+}
+
+export type ChatMessage =
+  | { role: "system"; content: string }
+  | { role: "user"; content: string | ContentPart[] }
+  | {
+      role: "assistant";
+      content: string;
+      /**
+       * The model's chain-of-thought. Thinking-mode providers require it
+       * replayed on a turn that made a tool call (DeepSeek 400s without it).
+       * OpenAI-shape serializes it as `reasoning_content`; Anthropic-shape
+       * drops it, since its thinking blocks carry signatures we never capture.
+       *
+       * A turn that DISABLES thinking must not carry it — mixing the two is
+       * unsupported. `stripReasoning` below is that rule, once.
+       */
+      reasoning?: string;
+      toolCalls?: ToolCall[];
+    }
+  | {
+      role: "tool";
+      toolCallId: string;
+      name: string;
+      content: string;
+      /** Images a tool hands back (a screenshot, a rendered chart). */
+      images?: ImagePart[];
+    };
+
+/** JSON Schema for an object — what every provider's tool contract wants. */
+export interface JsonObjectSchema {
+  type: "object";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  additionalProperties?: boolean;
+  [key: string]: unknown;
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: JsonObjectSchema;
+}
+
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter";
+
+/** Incremental tool-call fragment, assembled by `index` by the consumer. */
+export interface ToolCallDelta {
+  index: number;
+  id?: string;
+  name?: string;
+  arguments?: string;
+  thoughtSignature?: string;
+}
+
+export interface TokenUsage {
+  inputTokens: number;
+  /** Cache-HIT subset of `inputTokens` — providers auto-cache repeated
+   *  prefixes and bill the hit portion far cheaper, so it must be tracked
+   *  separately to cost a turn correctly. 0 when the provider reports none. */
+  cachedInputTokens: number;
+  /** Tokens WRITTEN to cache. Anthropic bills these above the input rate;
+   *  the OpenAI-shape auto-cachers bill them at it. 0 when not reported. */
+  cacheWriteTokens?: number;
+  outputTokens: number;
+}
+
+export const EMPTY_USAGE: TokenUsage = {
+  inputTokens: 0,
+  cachedInputTokens: 0,
+  outputTokens: 0,
+};
+
+/** Normalized streaming chunk — every provider's shape collapses into this. */
+export interface ProviderChunk {
+  type: "delta" | "usage" | "finish";
+  content?: string;
+  reasoning?: string;
+  toolCalls?: ToolCallDelta[];
+  usage?: TokenUsage;
+  finishReason?: FinishReason;
+}
+
+/** Pin or deny tool use. `{ name }` forces one specific tool — how a run is
+ *  made to commit an answer at its step budget's edge. */
+export type ToolChoice = "auto" | "none" | "required" | { name: string };
+
+/**
+ * Ask for a JSON object matching `schema`. Providers that enforce schemas get
+ * it verbatim; the rest get JSON mode plus the schema in the prompt. Either
+ * way the CALLER validates — a provider's "guaranteed" JSON is not one.
+ */
+export interface JsonOutput {
+  name: string;
+  schema: JsonObjectSchema;
+}
+
+export interface StreamOptions {
+  /** Override the provider's bound model for this call. */
+  model?: string;
+  effort?: Effort;
+  /** Output ceiling. On most providers thinking and answer SHARE it, so a
+   *  task emitting a large artifact must raise it or the tool-call JSON is
+   *  silently truncated mid-argument. */
+  maxTokens?: number;
+  temperature?: number;
+  signal?: AbortSignal;
+  toolChoice?: ToolChoice;
+  json?: JsonOutput;
+}
+
+export interface Provider {
+  readonly id: string;
+  readonly model: string;
+  createStream(
+    messages: ChatMessage[],
+    tools: ToolDefinition[],
+    opts?: StreamOptions,
+  ): AsyncIterable<ProviderChunk>;
+}
+
+export interface Completion {
+  text: string;
+  reasoning: string;
+  usage: TokenUsage;
+  finishReason: FinishReason | null;
+  model: string;
+}
+
+/** Drain a no-tools stream into a Completion. Usage chunks are cumulative on
+ *  some providers and final-only on others: the LAST one wins. */
+export async function drainStream(
+  stream: AsyncIterable<ProviderChunk>,
+  model: string,
+): Promise<Completion> {
+  let text = "";
+  let reasoning = "";
+  let usage: TokenUsage = EMPTY_USAGE;
+  let finishReason: FinishReason | null = null;
+  for await (const chunk of stream) {
+    if (chunk.type === "delta") {
+      if (chunk.content) text += chunk.content;
+      if (chunk.reasoning) reasoning += chunk.reasoning;
+    } else if (chunk.type === "usage" && chunk.usage) {
+      usage = chunk.usage;
+    } else if (chunk.type === "finish" && chunk.finishReason) {
+      finishReason = chunk.finishReason;
+    }
+  }
+  return { text, reasoning, usage, finishReason, model };
+}
+
+/**
+ * Prepare a history for a thinking-DISABLED turn: strip `reasoning` from every
+ * assistant message.
+ *
+ * The chain-of-thought belongs only to thinking turns. A provider that
+ * requires it replayed while thinking is ON (DeepSeek) rejects it when
+ * thinking is OFF — which is exactly the shape of a forced-submit salvage
+ * turn, where a run reasons through its whole investigation and then drops
+ * thinking to serialize what it already found.
+ *
+ * Returns a shallow-cleaned copy; the caller's array is left untouched.
+ */
+export function stripReasoning(messages: readonly ChatMessage[]): ChatMessage[] {
+  return messages.map((message) => {
+    if (message.role !== "assistant" || message.reasoning === undefined) return message;
+    const { reasoning: _dropped, ...rest } = message;
+    return rest;
+  });
+}
+
+/** `data:` URI for an image part — what the OpenAI dialect wants inline. */
+export function toDataUri(part: ImagePart): string {
+  return `data:${part.mimeType};base64,${part.data}`;
+}

package/src/usage.ts

@@ -0,0 +1,106 @@
+// Counting tokens and pricing them.
+//
+// The RATES are not here on purpose. A price table is volatile data about a
+// model catalogue that differs per application, it goes stale on a vendor's
+// schedule rather than this package's, and a wrong number shipped in a library
+// is a wrong number in everyone's ledger. So the arithmetic lives here and the
+// numbers stay with the caller, who can verify them line by line against a
+// price sheet.
+import type { TokenUsage } from "./types.ts";
+import { EMPTY_USAGE } from "./types.ts";
+
+/** USD per MILLION tokens — how every vendor prints its price sheet, so a row
+ *  can be checked against one without arithmetic. */
+export interface ModelRate {
+  /** Cache-MISS input: fresh tokens the provider had to read. */
+  input: number;
+  output: number;
+  /** Cache-HIT input. Providers auto-cache repeated prefixes and bill the hit
+   *  portion far cheaper — 0.1× on Anthropic, ~0.1× on Gemini, 0.5× on some
+   *  OpenAI models. In an agent loop the re-sent context is overwhelmingly
+   *  hits, so billing it at the miss rate overcounts by up to 10×. */
+  cacheRead: number;
+  /** Input WRITTEN to cache. Anthropic bills this ABOVE the input rate
+   *  (1.25×); the OpenAI-shape auto-cachers bill it at the input rate.
+   *  Defaults to `input` when a vendor does not price it separately. */
+  cacheWrite?: number;
+}
+
+/** Add two usage records. */
+export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    cachedInputTokens: a.cachedInputTokens + b.cachedInputTokens,
+    cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0),
+    outputTokens: a.outputTokens + b.outputTokens,
+  };
+}
+
+/**
+ * USD for one call.
+ *
+ * Cached tokens are a SUBSET of input, not an addition to it: the miss part
+ * bills at the full rate and the hit part at the cache rate. `cached` is
+ * clamped to `input` so an over-reporting provider can neither drive the miss
+ * count negative nor bill for more prompt than it was sent.
+ */
+export function costUsd(usage: TokenUsage, rate: ModelRate): number {
+  const input = Math.max(0, usage.inputTokens);
+  const cached = Math.min(Math.max(0, usage.cachedInputTokens), input);
+  const written = Math.max(0, usage.cacheWriteTokens ?? 0);
+  const miss = input - cached;
+  const writeRate = rate.cacheWrite ?? rate.input;
+  return (
+    (miss * rate.input +
+      cached * rate.cacheRead +
+      written * writeRate +
+      Math.max(0, usage.outputTokens) * rate.output) /
+    1_000_000
+  );
+}
+
+/**
+ * Accumulates usage and cost across the calls of one run, pricing each with
+ * the rate in effect for the model that served it — so a run that switches to
+ * a backup model, or spans a time-of-day price boundary, still bills correctly.
+ */
+export class UsageTracker {
+  private usage: TokenUsage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
+  private cost = 0;
+  /** USD the cache hits saved, versus billing them all as misses.
+   *  Observability only — never billed. */
+  private saved = 0;
+
+  add(usage: TokenUsage, rate?: ModelRate): void {
+    this.usage = addUsage(this.usage, usage);
+    if (!rate) return;
+    this.cost += costUsd(usage, rate);
+    const cached = Math.min(Math.max(0, usage.cachedInputTokens), Math.max(0, usage.inputTokens));
+    this.saved += (cached * (rate.input - rate.cacheRead)) / 1_000_000;
+  }
+
+  get totals(): TokenUsage {
+    return { ...this.usage };
+  }
+
+  get costUsd(): number {
+    return this.cost;
+  }
+
+  get cacheSavingsUsd(): number {
+    return this.saved;
+  }
+
+  /** A generous runaway guard, not a quality cap: the loop's step budget is
+   *  the real bound, and a run that trips this should finalize rather than
+   *  fail, so set it well above any legitimate run. */
+  isOverBudget(maxUsd: number): boolean {
+    return this.cost >= maxUsd;
+  }
+
+  reset(): void {
+    this.usage = { ...EMPTY_USAGE, cacheWriteTokens: 0 };
+    this.cost = 0;
+    this.saved = 0;
+  }
+}

package/src/watchdog.ts

@@ -0,0 +1,119 @@
+// The stream-idle watchdog.
+//
+// A provider that stops sending bytes is indistinguishable from a long prefill
+// — except that it never ends, and every SDK's default is to wait forever. A
+// queued route or a wedged prefill upstream hangs the caller indefinitely, and
+// the symptom is the worst kind: nothing. No error, no log, no timeout.
+//
+// So the seam gives itself a deadline. Any byte of any kind re-arms it
+// (reasoning models emit thinking deltas continuously, so silence really is
+// silence). When it fires, the watchdog aborts ITS OWN controller and the
+// caller's signal is only bridged in — which is what keeps a person's Stop
+// distinguishable from our timeout. One is their cancel and is never retried;
+// the other is ours, is transient, and fires while nothing has streamed yet,
+// so the retry is always safe.
+import { ProviderError } from "./errors.ts";
+
+/** No byte at all for this long and the stream is considered wedged. */
+export const STREAM_IDLE_MS = 60_000;
+
+export interface StreamWatch {
+  /** Hand this to the provider in place of the caller's signal. */
+  readonly signal: AbortSignal;
+  /** A byte arrived: re-arm the deadline, and mark TTFT if it was the first. */
+  sawByte(): void;
+  /**
+   * Milliseconds from the call opening to its first byte of any kind — the
+   * wait a person actually experiences, and the number a prompt-cache pin
+   * exists to shrink. Null until something arrives.
+   */
+  firstChunkMs(): number | null;
+  /**
+   * Re-issue a provider failure as the idle timeout when — and only when — it
+   * was our deadline that aborted. A caller's Stop passes through untouched.
+   */
+  classify(err: unknown): unknown;
+  /** Clear the deadline timer. Safe to call more than once. */
+  dispose(): void;
+}
+
+export interface StreamWatchOptions {
+  provider?: string;
+  idleMs?: number;
+  signal?: AbortSignal;
+}
+
+export function streamWatch(opts: StreamWatchOptions = {}): StreamWatch {
+  const provider = opts.provider ?? "provider";
+  const idleMs = opts.idleMs ?? STREAM_IDLE_MS;
+  const callerSignal = opts.signal;
+  const started = Date.now();
+  const timeout = new AbortController();
+
+  let firstChunk: number | null = null;
+  let idle = false;
+  let disposed = false;
+
+  // The bridge is structural rather than an event listener: AbortSignal.any
+  // aborts synchronously when an input is ALREADY aborted, which is the race
+  // no listener can catch (the event fired before we subscribed).
+  const signal = callerSignal ? AbortSignal.any([callerSignal, timeout.signal]) : timeout.signal;
+
+  const idleError = (cause?: unknown) =>
+    new ProviderError(provider, "timeout", `stream went ${idleMs / 1000}s without a byte`, {
+      cause,
+    });
+
+  function arm(): ReturnType<typeof setTimeout> {
+    const timer = setTimeout(() => {
+      idle = true;
+      timeout.abort(idleError());
+    }, idleMs);
+    // An orphaned watch — its consumer gone, dispose never called — must not
+    // hold a Node event loop open for a full deadline.
+    (timer as { unref?: () => void }).unref?.();
+    return timer;
+  }
+
+  let timer = arm();
+
+  return {
+    signal,
+    sawByte() {
+      firstChunk ??= Date.now() - started;
+      clearTimeout(timer);
+      if (!disposed && !signal.aborted) timer = arm();
+    },
+    firstChunkMs: () => firstChunk,
+    classify(err: unknown) {
+      // Our deadline, not theirs — and not the caller's Stop.
+      if (idle && !(callerSignal?.aborted ?? false)) return idleError(err);
+      return err;
+    },
+    dispose() {
+      disposed = true;
+      clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * Wrap a stream so every chunk re-arms `watch`, and a failure is re-classified
+ * through it. Disposes on any exit — completion, throw, or the consumer
+ * breaking out of the loop.
+ */
+export async function* watchChunks<T>(
+  watch: StreamWatch,
+  chunks: AsyncIterable<T>,
+): AsyncGenerator<T> {
+  try {
+    for await (const chunk of chunks) {
+      watch.sawByte();
+      yield chunk;
+    }
+  } catch (err) {
+    throw watch.classify(err);
+  } finally {
+    watch.dispose();
+  }
+}

package/src/zod.ts

@@ -0,0 +1,74 @@
+// The optional zod ergonomics — `@providerkit/core/zod`.
+//
+// Kept behind its own entry point so the core stays dependency-free for
+// consumers that have no zod (a browser extension counting every byte, for
+// one). Import this and tools become typed end to end.
+import { z } from "zod";
+import { defineTool, type Tool, type ToolContext } from "./tools.ts";
+import { clampToSchema } from "./schema.ts";
+import type { JsonObjectSchema } from "./types.ts";
+
+/** A zod schema as the JSON Schema every provider's tool contract wants. */
+export function toJsonObjectSchema(schema: z.ZodType, label = "schema"): JsonObjectSchema {
+  const json = z.toJSONSchema(schema, { io: "input" }) as Record<string, unknown>;
+  if (json.type !== "object") {
+    // Every provider requires an object at the top level of a tool's
+    // parameters; a bare string or array is rejected at the wire, far from
+    // here, with a message that names none of this.
+    throw new Error(`providerkit: ${label} must be an object schema, got ${String(json.type)}`);
+  }
+  return json as JsonObjectSchema;
+}
+
+export interface ZodToolSpec<I, O> {
+  name: string;
+  description: string;
+  input: z.ZodType<I>;
+  run: (input: I, ctx: ToolContext) => Promise<O>;
+  summarize?: (output: O) => string;
+  timeoutMs?: number;
+  isReadOnly?: boolean;
+  needsApproval?: boolean;
+  isConcurrencySafe?: boolean;
+  isTerminal?: boolean;
+  /**
+   * Clamp overflow to the bounds the schema already advertised instead of
+   * rejecting the call. Worth it for a TERMINAL tool, which gets no second
+   * chance: a forced-submit salvage turn runs exactly once, and discarding an
+   * otherwise-valid answer over a few extra characters loses the whole run.
+   * Off by default — an ordinary tool can simply be called again.
+   */
+  clampOverflow?: boolean;
+}
+
+/**
+ * A tool whose arguments are validated by zod, with the failure reported to
+ * the MODEL in words it can act on — `topic: expected string, received number`
+ * beats a stack trace it cannot read.
+ */
+export function zodTool<I, O>(spec: ZodToolSpec<I, O>): Tool<I, O> {
+  const inputSchema = toJsonObjectSchema(spec.input, `Tool "${spec.name}" input`);
+
+  return defineTool<I, O>({
+    name: spec.name,
+    description: spec.description,
+    inputSchema,
+    ...(spec.summarize ? { summarize: spec.summarize } : {}),
+    ...(spec.timeoutMs !== undefined ? { timeoutMs: spec.timeoutMs } : {}),
+    ...(spec.isReadOnly !== undefined ? { isReadOnly: spec.isReadOnly } : {}),
+    ...(spec.needsApproval !== undefined ? { needsApproval: spec.needsApproval } : {}),
+    ...(spec.isConcurrencySafe !== undefined ? { isConcurrencySafe: spec.isConcurrencySafe } : {}),
+    ...(spec.isTerminal !== undefined ? { isTerminal: spec.isTerminal } : {}),
+    validate: (raw) => {
+      const candidate = spec.clampOverflow ? clampToSchema(raw, inputSchema) : raw;
+      const parsed = spec.input.safeParse(candidate);
+      if (parsed.success) return parsed.data;
+      throw new Error(
+        parsed.error.issues
+          .map((issue) => `${issue.path.join(".") || "input"}: ${issue.message}`)
+          .join("; "),
+      );
+    },
+    run: spec.run,
+  });
+}