@providerkit/core 0.1.0

package/src/retry.ts

@@ -0,0 +1,246 @@
+// Retrying, and knowing when not to.
+//
+// Three rules do most of the work here, and each was learned separately:
+//
+//  1. Retry only what a retry can fix. A deterministic failure (bad key,
+//     invalid request, exhausted balance) hits identically on every attempt,
+//     so retrying it just spends the budget to arrive at the same answer later.
+//
+//  2. For a STREAM, retry only while nothing has been emitted. Once a chunk
+//     has reached the consumer the stream is committed: a retry would replay
+//     tokens the caller already rendered. A mid-output drop is the caller's
+//     problem to handle (or a job-level restart's), never a silent re-run.
+//
+//  3. Honour the provider's own number. When it says `Retry-After: 30`, a
+//     one-second backoff is three wasted attempts before the same wait.
+import { classify, isBackupEligible, isTransient, parseRetryAfterMs } from "./errors.ts";
+
+export interface RetryOptions {
+  /** Total attempts including the first. Default 3. */
+  maxAttempts?: number;
+  baseDelayMs?: number;
+  maxDelayMs?: number;
+  /** Aborts the wait as well as the work, so Stop lands promptly. */
+  signal?: AbortSignal;
+  /** Decide retryability. Default: transient kinds only. */
+  shouldRetry?: (err: unknown, attempt: number) => boolean;
+  onRetry?: (info: { error: unknown; attempt: number; delayMs: number }) => void;
+  /** Injected in tests so a suite never really waits. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+
+/**
+ * Full-jitter exponential backoff: a random delay in
+ * `[0, min(cap, base · 2^(attempt-1))]`.
+ *
+ * The jitter is the point, not the exponent. Without it, every client that
+ * failed against the same overloaded upstream retries in the same instant and
+ * rebuilds the thundering herd that caused the failure.
+ */
+export function backoffMs(
+  attempt: number,
+  base = DEFAULT_BASE_DELAY_MS,
+  cap = DEFAULT_MAX_DELAY_MS,
+): number {
+  const ceiling = Math.min(cap, base * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(Math.random() * ceiling);
+}
+
+/** A sleep that wakes early when the caller aborts, and rejects with the
+ *  abort reason rather than resolving into work nobody wants any more. */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(signal?.reason);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** The delay before the next attempt: the provider's own figure when it gave
+ *  one, capped, else full-jitter backoff. */
+function delayFor(err: unknown, attempt: number, opts: RetryOptions): number {
+  const asked = parseRetryAfterMs(err);
+  const cap = opts.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  if (asked !== undefined) return Math.min(asked, cap);
+  return backoffMs(attempt, opts.baseDelayMs ?? DEFAULT_BASE_DELAY_MS, cap);
+}
+
+const defaultShouldRetry = (err: unknown): boolean => isTransient(classify(err));
+
+/**
+ * Run `fn`, retrying transient failures with backoff. For one-shot calls —
+ * a title, a summary, a compaction pass.
+ */
+export async function withRetry<T>(
+  fn: (attempt: number) => Promise<T>,
+  opts: RetryOptions = {},
+): Promise<T> {
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+  const nap = opts.sleep ?? sleep;
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (opts.signal?.aborted) throw opts.signal.reason;
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+      // A caller's Stop is never a transient failure, whatever it looks like.
+      if (opts.signal?.aborted) throw err;
+      if (attempt >= maxAttempts || !shouldRetry(err, attempt)) throw err;
+      const delayMs = delayFor(err, attempt, opts);
+      opts.onRetry?.({ error: err, attempt, delayMs });
+      await nap(delayMs, opts.signal);
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * The streaming twin — with the rule that makes it safe: a retry happens only
+ * while NOTHING has been yielded yet.
+ *
+ * `factory` is re-invoked per attempt and gets a fresh signal, so an abandoned
+ * attempt's upstream request is cancelled rather than left racing the retry.
+ * Once the first chunk is out, the stream is committed and any later failure
+ * propagates untouched.
+ */
+export async function* withStreamRetry<T>(
+  factory: (signal: AbortSignal, attempt: number) => AsyncIterable<T>,
+  opts: RetryOptions = {},
+): AsyncGenerator<T> {
+  const maxAttempts = opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+  const nap = opts.sleep ?? sleep;
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (opts.signal?.aborted) throw opts.signal.reason;
+
+    // One controller per attempt: abandoning an attempt must cancel its
+    // upstream call, or a retry stacks a second live stream against the same
+    // rate limit.
+    const controller = new AbortController();
+    const onOuterAbort = () => controller.abort(opts.signal?.reason);
+    opts.signal?.addEventListener("abort", onOuterAbort, { once: true });
+
+    let emitted = false;
+    try {
+      for await (const chunk of factory(controller.signal, attempt)) {
+        emitted = true;
+        yield chunk;
+      }
+      return;
+    } catch (err) {
+      lastError = err;
+      if (opts.signal?.aborted) throw err;
+      // Rule 2: past the first chunk there is no going back.
+      if (emitted || attempt >= maxAttempts || !shouldRetry(err, attempt)) throw err;
+      const delayMs = delayFor(err, attempt, opts);
+      opts.onRetry?.({ error: err, attempt, delayMs });
+      await nap(delayMs, opts.signal);
+    } finally {
+      opts.signal?.removeEventListener("abort", onOuterAbort);
+      // Abandoning mid-iteration (the consumer broke out, or we are retrying)
+      // must not leave the upstream request running.
+      if (!controller.signal.aborted) controller.abort();
+    }
+  }
+  throw lastError;
+}
+
+export interface BackupModelOptions {
+  /** Tried in order: `[primary, ...backups]`. The first success wins. */
+  models: string[];
+  /**
+   * Whether a failure may fall through to the remaining models. Default:
+   * overload and rate limits only — those are per-model-endpoint, and nothing
+   * else on the list is. An auth failure or an invalid request would land
+   * identically on every backup.
+   */
+  shouldTryNext?: (err: unknown) => boolean;
+  onModelFailed?: (info: {
+    model: string;
+    error: unknown;
+    position: number;
+    total: number;
+  }) => void;
+  onFallback?: (info: { model: string; position: number; total: number }) => void;
+}
+
+const defaultShouldTryNext = (err: unknown): boolean => isBackupEligible(classify(err));
+
+function requireModels(models: string[]): void {
+  if (models.length === 0) throw new Error("providerkit: `models` must include a primary model");
+}
+
+/** Walk `[primary, ...backups]` until one succeeds. Rethrows the last error. */
+export async function withBackupModels<T>(
+  attempt: (model: string) => Promise<T>,
+  opts: BackupModelOptions,
+): Promise<T> {
+  requireModels(opts.models);
+  const shouldTryNext = opts.shouldTryNext ?? defaultShouldTryNext;
+  const total = opts.models.length;
+
+  let lastError: unknown;
+  for (const [index, model] of opts.models.entries()) {
+    if (index > 0) opts.onFallback?.({ model, position: index + 1, total });
+    try {
+      return await attempt(model);
+    } catch (err) {
+      lastError = err;
+      opts.onModelFailed?.({ model, error: err, position: index + 1, total });
+      if (!shouldTryNext(err)) break;
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * The streaming twin — carrying the same commitment rule as `withStreamRetry`.
+ *
+ * This is the correction worth naming: walking to a backup model AFTER chunks
+ * have already reached the consumer replays the answer from the top, in a
+ * different model's voice, on top of text the caller has already rendered. So
+ * a stream that fails past its first chunk ends the walk, exactly as it ends a
+ * retry.
+ */
+export async function* streamWithBackupModels<T>(
+  attempt: (model: string) => AsyncIterable<T>,
+  opts: BackupModelOptions,
+): AsyncGenerator<T> {
+  requireModels(opts.models);
+  const shouldTryNext = opts.shouldTryNext ?? defaultShouldTryNext;
+  const total = opts.models.length;
+
+  let lastError: unknown;
+  for (const [index, model] of opts.models.entries()) {
+    if (index > 0) opts.onFallback?.({ model, position: index + 1, total });
+    let emitted = false;
+    try {
+      for await (const chunk of attempt(model)) {
+        emitted = true;
+        yield chunk;
+      }
+      return;
+    } catch (err) {
+      lastError = err;
+      opts.onModelFailed?.({ model, error: err, position: index + 1, total });
+      if (emitted || !shouldTryNext(err)) break;
+    }
+  }
+  throw lastError;
+}

package/src/schema.ts

@@ -0,0 +1,67 @@
+// Clamping a model's output to the bounds its own schema advertised.
+//
+// Models treat `maxLength` and `maxItems` as soft hints and routinely overflow
+// them when they have a lot to say. Rejecting the whole submission over a few
+// extra characters is the worst available outcome — the run fails and the
+// person gets nothing, when a perfectly good answer was sitting right there.
+//
+// So OVERFLOW is clamped to the very limit the schema told the model about.
+// Structural problems — a missing required field, the wrong type, a bad enum —
+// are deliberately left alone for the real validator to reject: those are the
+// model misunderstanding the contract, not overrunning it.
+//
+// This walks the generated JSON Schema, a stable public shape, rather than any
+// validator's internals.
+type SchemaNode = Record<string, unknown>;
+
+export function clampToSchema(value: unknown, node: unknown): unknown {
+  if (!node || typeof node !== "object") return value;
+  const schema = node as SchemaNode;
+
+  // Nullable and union fields (`anyOf: [schema, {type: "null"}]`). Fold through
+  // every branch: only the one whose type matches transforms, the rest no-op.
+  const union = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(union)) {
+    return union.reduce<unknown>((current, branch) => clampToSchema(current, branch), value);
+  }
+
+  if (typeof value === "string") {
+    const max = schema.maxLength;
+    // Ends in an ellipsis so the cut is visible rather than silent. "…" is one
+    // UTF-16 unit — the same unit the validators count — so the result lands
+    // at exactly `max`.
+    if (typeof max === "number" && max >= 1 && value.length > max) {
+      return `${value.slice(0, max - 1)}…`;
+    }
+    return value;
+  }
+
+  if (typeof value === "number") {
+    let out = value;
+    if (typeof schema.maximum === "number" && out > schema.maximum) out = schema.maximum;
+    if (typeof schema.minimum === "number" && out < schema.minimum) out = schema.minimum;
+    return out;
+  }
+
+  if (Array.isArray(value)) {
+    const items = value.map((item) => clampToSchema(item, schema.items));
+    const max = schema.maxItems;
+    return typeof max === "number" && items.length > max ? items.slice(0, max) : items;
+  }
+
+  if (
+    value &&
+    typeof value === "object" &&
+    schema.properties &&
+    typeof schema.properties === "object"
+  ) {
+    const properties = schema.properties as Record<string, unknown>;
+    const out: Record<string, unknown> = { ...(value as Record<string, unknown>) };
+    for (const key of Object.keys(out)) {
+      if (key in properties) out[key] = clampToSchema(out[key], properties[key]);
+    }
+    return out;
+  }
+
+  return value;
+}

package/src/tool-args.ts

@@ -0,0 +1,117 @@
+// Reading a model's tool-call arguments, including the ones it broke.
+//
+// Two failure modes cost real answers, and both are invisible — the JSON simply
+// does not parse, and the run reports "no result" while the answer was sitting
+// in the fragments.
+//
+//  1. TRUNCATION. The turn hit its output ceiling mid-argument, so the JSON is
+//     cut off. Everything before the cut is still good, and the field the cut
+//     landed in holds a half-written answer that beats no answer.
+//
+//  2. DOUBLE ESCAPING. Most models write non-ASCII inside tool JSON as
+//     `\uXXXX`, which JSON.parse decodes correctly. Some escape it twice and
+//     emit `\\u00e7`, so even a clean parse leaves six literal characters
+//     standing and a Portuguese answer reaches the user as `atenção`.
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * `\uXXXX` only. An answer that legitimately spells that sequence is
+ * vanishingly rare; one that mentions `\n` while talking about code is not.
+ */
+const UNICODE_ESCAPE = /\\u([0-9a-fA-F]{4})/g;
+
+function healUnicodeEscapes(text: string): string {
+  return text.replace(UNICODE_ESCAPE, (_match, hex: string) =>
+    String.fromCharCode(parseInt(hex, 16)),
+  );
+}
+
+function healValue(value: unknown): unknown {
+  if (typeof value === "string") return healUnicodeEscapes(value);
+  if (Array.isArray(value)) return value.map(healValue);
+  if (isRecord(value)) return healArgs(value);
+  return value;
+}
+
+function healArgs(args: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(args)) out[key] = healValue(value);
+  return out;
+}
+
+/** The cut can land inside an escape (`…aten\u00`, or a lone `\`). That
+ *  fragment is not text, and a trailing backslash also stops the field
+ *  patterns below from matching. */
+const DANGLING_ESCAPE = /\\(?:u[0-9a-fA-F]{0,3})?$/;
+
+function unescapeJson(text: string): string {
+  try {
+    return JSON.parse(`"${text}"`) as string;
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Best-effort recovery of `"key": "value"` string fields from truncated JSON.
+ *
+ * Only strings: they are what a summary field — the one worth rescuing — is
+ * made of, and a closing quote is the single reliable boundary in a partial
+ * stream. Numbers, booleans and objects are dropped, because a salvaged
+ * half-value is worse than none.
+ */
+function salvageStringFields(raw: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const text = raw.replace(DANGLING_ESCAPE, "");
+
+  // A completed `"key": "value",` or `"key": "value"}` pair.
+  const COMPLETE_FIELD = /"((?:[^"\\]|\\.)*)"\s*:\s*"((?:[^"\\]|\\.)*)"\s*[,}]/gs;
+  let match: RegExpExecArray | null;
+  let lastCompleteEnd = 0;
+  while ((match = COMPLETE_FIELD.exec(text)) !== null) {
+    out[unescapeJson(match[1]!)] = unescapeJson(match[2]!);
+    lastCompleteEnd = COMPLETE_FIELD.lastIndex;
+  }
+
+  // The tail after the last complete field: if it opens one more string that
+  // never closed, keep its content up to the cut.
+  const OPEN_FIELD = /"((?:[^"\\]|\\.)*)"\s*:\s*"((?:[^"\\]|\\.)*)$/s;
+  const open = OPEN_FIELD.exec(text.slice(lastCompleteEnd));
+  if (open?.[2]) out[unescapeJson(open[1]!)] = unescapeJson(open[2]!);
+
+  return out;
+}
+
+/**
+ * Parse a tool call's raw argument string into an object, salvaging what a
+ * truncated stream left behind and healing double-escaped text either way.
+ *
+ * Never throws: a tool call the model malformed is data the caller decides
+ * about, not an exception in the transport.
+ */
+export function parseToolArgs(raw: string): Record<string, unknown> {
+  if (!raw.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return healArgs(salvageStringFields(raw));
+  }
+  // A non-object payload is a protocol violation, not a value to pass on.
+  return healArgs(isRecord(parsed) ? parsed : {});
+}
+
+/** Whether `raw` parses at all — how a caller tells a truncated tool call from
+ *  an intact one, since `parseToolArgs` deliberately never throws. */
+export function isCompleteJson(raw: string): boolean {
+  if (!raw.trim()) return false;
+  try {
+    JSON.parse(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/tools.ts

@@ -0,0 +1,237 @@
+// The tool kernel: a validated, cancellable, time-bounded call.
+//
+// JSON Schema first, on purpose. A zod dependency would be dead weight for a
+// consumer that has none — and one of the codebases this came from is exactly
+// that. `@providerkit/core/zod` adds the ergonomic wrapper for everyone else, and
+// stays an optional peer.
+//
+// The one rule worth stating: a tool FAILING is not an exception here. A model
+// that called a tool wrong, or a tool that timed out, is data the loop feeds
+// back so the model can correct itself. `invoke` therefore returns an outcome
+// rather than throwing, and only a caller's abort escapes.
+import type { JsonObjectSchema, ToolDefinition } from "./types.ts";
+import { messageOf } from "./errors.ts";
+
+export interface ToolContext {
+  /** The model's own call id when there is one — the event, any approval row
+   *  and the tool message must all key on what the provider expects back. */
+  callId?: string;
+  signal?: AbortSignal;
+  /** Anything the host wants to hand its tools (a db handle, the actor). */
+  [key: string]: unknown;
+}
+
+export type ToolFailure = "invalid_input" | "timeout" | "aborted" | "failed";
+
+export type ToolOutcome<O> =
+  | { ok: true; callId: string; output: O; summary: string; durationMs: number }
+  | {
+      ok: false;
+      callId: string;
+      kind: ToolFailure;
+      /** Fed back to the model verbatim — so it must read as an instruction to
+       *  a reader who cannot see our stack trace. */
+      error: string;
+      durationMs: number;
+      cause?: unknown;
+    };
+
+export interface ToolSpec<I, O> {
+  name: string;
+  description: string;
+  /** Advertised to the model verbatim. */
+  inputSchema: JsonObjectSchema;
+  /**
+   * Turn raw arguments into `I`, or throw with a message the MODEL can act on.
+   * Omit to accept whatever arrived (the schema is then only a hint).
+   */
+  validate?: (raw: unknown) => I;
+  run: (input: I, ctx: ToolContext) => Promise<O>;
+  /** How the result reads back to the model. Defaults to JSON. */
+  summarize?: (output: O) => string;
+  /** Default 60s. A tool with no ceiling can hang a whole run. */
+  timeoutMs?: number;
+  isReadOnly?: boolean;
+  needsApproval?: boolean;
+  isConcurrencySafe?: boolean;
+  /** A terminal tool ends the run; its validated input is the run's output. */
+  isTerminal?: boolean;
+}
+
+export interface Tool<I = unknown, O = unknown> {
+  readonly name: string;
+  readonly description: string;
+  readonly inputSchema: JsonObjectSchema;
+  readonly timeoutMs: number;
+  readonly isReadOnly: boolean;
+  readonly needsApproval: boolean;
+  readonly isConcurrencySafe: boolean;
+  readonly isTerminal: boolean;
+  definition(): ToolDefinition;
+  /** Validate, run, and report the outcome. Never throws except on abort. */
+  invoke(rawArgs: unknown, ctx?: ToolContext): Promise<ToolOutcome<O>>;
+  /** The typed path for internal callers: throws on failure. */
+  call(input: I, ctx?: ToolContext): Promise<O>;
+}
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+export class ToolTimeoutError extends Error {
+  constructor(tool: string, ms: number) {
+    super(`Tool "${tool}" timed out after ${ms}ms`);
+    this.name = "ToolTimeoutError";
+  }
+}
+
+/** Rejects when `signal` aborts — races a `run` that ignores its own signal. */
+function abortion(signal: AbortSignal): Promise<never> {
+  return new Promise((_resolve, reject) => {
+    if (signal.aborted) reject(signal.reason);
+    else signal.addEventListener("abort", () => reject(signal.reason), { once: true });
+  });
+}
+
+function newId(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `call_${Math.random().toString(36).slice(2, 12)}`;
+}
+
+export function defineTool<I = unknown, O = unknown>(spec: ToolSpec<I, O>): Tool<I, O> {
+  const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const summarize = spec.summarize ?? ((output: O) => JSON.stringify(output) ?? "");
+  let cached: ToolDefinition | null = null;
+
+  async function execute(input: I, ctx: ToolContext): Promise<{ output: O; durationMs: number }> {
+    const started = Date.now();
+    // Two deadlines compose into the one signal `run` sees: our timeout and
+    // the caller's abort. `run` gets a signal it can honour; the race is there
+    // for the ones that do not.
+    const controller = new AbortController();
+    const onOuterAbort = () => controller.abort(ctx.signal?.reason);
+    ctx.signal?.addEventListener("abort", onOuterAbort, { once: true });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort(new ToolTimeoutError(spec.name, timeoutMs));
+    }, timeoutMs);
+    try {
+      if (ctx.signal?.aborted) throw ctx.signal.reason;
+      const output = await Promise.race([
+        spec.run(input, { ...ctx, signal: controller.signal }),
+        abortion(controller.signal),
+      ]);
+      return { output, durationMs: Date.now() - started };
+    } catch (err) {
+      throw timedOut ? new ToolTimeoutError(spec.name, timeoutMs) : err;
+    } finally {
+      clearTimeout(timer);
+      ctx.signal?.removeEventListener("abort", onOuterAbort);
+    }
+  }
+
+  function classifyFailure(err: unknown, ctx: ToolContext): ToolFailure {
+    if (err instanceof ToolTimeoutError) return "timeout";
+    // The caller's own abort — distinct from our timeout, and never something
+    // to report back to the model as a tool that "failed".
+    if (ctx.signal?.aborted) return "aborted";
+    const name = err instanceof Error ? err.name : undefined;
+    return name === "AbortError" ? "aborted" : "failed";
+  }
+
+  return {
+    name: spec.name,
+    description: spec.description,
+    inputSchema: spec.inputSchema,
+    timeoutMs,
+    isReadOnly: spec.isReadOnly ?? true,
+    needsApproval: spec.needsApproval ?? false,
+    isConcurrencySafe: spec.isConcurrencySafe ?? true,
+    isTerminal: spec.isTerminal ?? false,
+
+    definition() {
+      cached ??= {
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+      };
+      return cached;
+    },
+
+    async call(input, ctx = {}) {
+      return (await execute(input, ctx)).output;
+    },
+
+    async invoke(rawArgs, ctx = {}) {
+      const callId = ctx.callId ?? newId();
+      const started = Date.now();
+
+      let input: I;
+      try {
+        input = spec.validate ? spec.validate(rawArgs) : (rawArgs as I);
+      } catch (err) {
+        return {
+          ok: false,
+          callId,
+          kind: "invalid_input",
+          error: `Invalid arguments for ${spec.name}: ${messageOf(err)}`,
+          durationMs: 0,
+          cause: err,
+        };
+      }
+
+      try {
+        const { output, durationMs } = await execute(input, { ...ctx, callId });
+        return { ok: true, callId, output, summary: summarize(output), durationMs };
+      } catch (err) {
+        return {
+          ok: false,
+          callId,
+          kind: classifyFailure(err, ctx),
+          error: messageOf(err),
+          durationMs: Date.now() - started,
+          cause: err,
+        };
+      }
+    },
+  };
+}
+
+export class ToolRegistry {
+  private readonly tools = new Map<string, Tool>();
+
+  constructor(tools: readonly Tool[] = []) {
+    for (const tool of tools) this.register(tool);
+  }
+
+  register(tool: Tool): this {
+    this.tools.set(tool.name, tool);
+    return this;
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  get names(): string[] {
+    return [...this.tools.keys()];
+  }
+
+  /**
+   * Definitions for an allow-list, in the order given — which is the order the
+   * model reads them in, and it is part of the cached prompt prefix. Reordering
+   * or appending mid-conversation invalidates that prefix, so a caller that
+   * cares should freeze the list when the session opens.
+   */
+  definitions(allow?: readonly string[]): ToolDefinition[] {
+    const names = allow ?? this.names;
+    const out: ToolDefinition[] = [];
+    for (const name of names) {
+      const tool = this.tools.get(name);
+      if (tool) out.push(tool.definition());
+    }
+    return out;
+  }
+}