@tanstack/ai 0.23.1 → 0.25.0

package/src/activities/chat/tools/tool-calls.ts

@@ -1,5 +1,8 @@
+import { normalizeToolResult } from '../../../utilities/tool-result'
 import { isStandardSchema, parseWithStandardSchema } from './schema-converter'
 import type {
+  AnyTool,
+  ContentPart,
   CustomEvent,
   ModelMessage,
   RunFinishedEvent,
@@ -9,11 +12,18 @@ import type {
   ToolCallEndEvent,
   ToolCallStartEvent,
   ToolExecutionContext,
+  ToolOutputState,
 } from '../../../types'
 import type {
   AfterToolCallInfo,
   BeforeToolCallDecision,
 } from '../middleware/types'
+import type {
+  ContextFromTool,
+  DefinedContext,
+  MergeContext,
+  UnionToIntersection,
+} from '../runtime-context-types'
 
 function safeJsonParse(value: string): unknown {
   try {
@@ -46,6 +56,36 @@ export class MiddlewareAbortError extends Error {
   }
 }
 
+// The leaf context-inference primitives (ContextFromTool, MergeContext,
+// UnionToIntersection, DefinedContext) are shared with the chat activity
+// options layer — see ../runtime-context-types.
+type RequiredContextFromToolUnion<T> = T extends unknown
+  ? undefined extends ContextFromTool<T>
+    ? never
+    : ContextFromTool<T>
+  : never
+
+type ContextFromToolUnion<T> = [
+  UnionToIntersection<DefinedContext<ContextFromTool<T>>>,
+] extends [never]
+  ? unknown
+  : [RequiredContextFromToolUnion<T>] extends [never]
+    ? UnionToIntersection<DefinedContext<ContextFromTool<T>>> | undefined
+    : UnionToIntersection<DefinedContext<ContextFromTool<T>>>
+
+type ContextFromTools<TTools> = TTools extends readonly [
+  infer THead,
+  ...infer TTail,
+]
+  ? MergeContext<ContextFromTool<THead>, ContextFromTools<TTail>>
+  : TTools extends ReadonlyArray<infer TTool>
+    ? ContextFromToolUnion<TTool>
+    : unknown
+
+type ExecuteToolsContextArgs<TContext> = undefined extends TContext
+  ? [userContext?: TContext]
+  : [userContext: TContext]
+
 /**
  * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
  *
@@ -80,11 +120,22 @@ export class MiddlewareAbortError extends Error {
  * }
  * ```
  */
-export class ToolCallManager {
+export class ToolCallManager<
+  TToolsOrContext = ReadonlyArray<AnyTool>,
+  TContext = TToolsOrContext extends ReadonlyArray<AnyTool>
+    ? ContextFromTools<TToolsOrContext>
+    : TToolsOrContext,
+> {
   private readonly toolCallsMap = new Map<number, ToolCall>()
-  private readonly tools: ReadonlyArray<Tool>
-
-  constructor(tools: ReadonlyArray<Tool>) {
+  private readonly tools: TToolsOrContext extends ReadonlyArray<AnyTool>
+    ? TToolsOrContext
+    : ReadonlyArray<AnyTool>
+
+  constructor(
+    tools: TToolsOrContext extends ReadonlyArray<AnyTool>
+      ? TToolsOrContext
+      : ReadonlyArray<AnyTool>,
+  ) {
     this.tools = tools
   }
 
@@ -161,14 +212,18 @@ export class ToolCallManager {
    */
   async *executeTools(
     finishEvent: RunFinishedEvent,
+    ...contextArgs: ExecuteToolsContextArgs<TContext>
   ): AsyncGenerator<ToolCallEndEvent, Array<ModelMessage>, void> {
     const toolCallsArray = this.getToolCalls()
     const toolResults: Array<ModelMessage> = []
+    const hasRuntimeContext = contextArgs.length > 0
+    const userContext = contextArgs[0]
 
     for (const toolCall of toolCallsArray) {
       const tool = this.tools.find((t) => t.name === toolCall.function.name)
 
-      let toolResultContent: string
+      let toolResultContent: string | Array<ContentPart>
+      let toolResultState: ToolOutputState | undefined
       if (tool?.execute) {
         try {
           // Parse arguments (normalize null/non-object to {} for empty tool_use blocks)
@@ -199,15 +254,21 @@ export class ToolCallManager {
           }
 
           // Execute the tool
-          let result = await tool.execute(args)
-
-          // Validate output against outputSchema if provided (for Standard Schema compliant schemas)
-          if (
-            tool.outputSchema &&
-            isStandardSchema(tool.outputSchema) &&
-            result !== undefined &&
-            result !== null
-          ) {
+          const executionContext = {
+            toolCallId: toolCall.id,
+            context: userContext,
+            emitCustomEvent: () => {},
+          } as ToolExecutionContext<TContext>
+          let result = hasRuntimeContext
+            ? await tool.execute(args, executionContext)
+            : await tool.execute(args)
+
+          // Validate output against outputSchema if provided (for Standard
+          // Schema compliant schemas). Unlike the previous implementation we
+          // intentionally validate `undefined`/`null` results too, so a tool
+          // whose schema forbids them surfaces a validation error instead of
+          // silently passing — the schema itself decides whether they're valid.
+          if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
             try {
               result = parseWithStandardSchema(tool.outputSchema, result)
             } catch (validationError: unknown) {
@@ -221,13 +282,13 @@ export class ToolCallManager {
             }
           }
 
-          toolResultContent =
-            typeof result === 'string' ? result : JSON.stringify(result)
+          toolResultContent = normalizeToolResult(result)
         } catch (error: unknown) {
           // If tool execution fails, add error message
           const message =
             error instanceof Error ? error.message : 'Unknown error'
           toolResultContent = `Error executing tool: ${message}`
+          toolResultState = 'output-error'
         }
       } else {
         // Tool doesn't have execute function, add placeholder
@@ -243,6 +304,7 @@ export class ToolCallManager {
         model: finishEvent.model,
         timestamp: Date.now(),
         result: toolResultContent,
+        ...(toolResultState !== undefined && { state: toolResultState }),
       } as ToolCallEndEvent
 
       // Add tool result message
@@ -370,7 +432,7 @@ async function applyBeforeToolCallDecision(
       result:
         typeof skipResult === 'string'
           ? safeJsonParse(skipResult)
-          : skipResult || null,
+          : (skipResult ?? null),
       duration: 0,
     })
     if (middlewareHooks.onAfterToolCall) {
@@ -394,12 +456,12 @@ async function applyBeforeToolCallDecision(
  * Execute a server-side tool with event polling, output validation, and middleware hooks.
  * Yields CustomEvent chunks during execution and pushes the result to the results array.
  */
-async function* executeServerTool(
+async function* executeServerTool<TContext = unknown>(
   toolCall: ToolCall,
-  tool: Tool,
+  tool: AnyTool,
   toolName: string,
   input: unknown,
-  context: ToolExecutionContext,
+  context: ToolExecutionContext<TContext>,
   pendingEvents: Array<CustomEvent>,
   results: Array<ToolResult>,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
@@ -419,18 +481,14 @@ async function* executeServerTool(
       yield pendingEvent
     }
 
-    // Validate output against outputSchema if provided
-    if (
-      tool.outputSchema &&
-      isStandardSchema(tool.outputSchema) &&
-      result !== undefined &&
-      result !== null
-    ) {
+    // Validate output against outputSchema if provided. Validates
+    // `undefined`/`null` too — the schema decides whether they're valid.
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
       result = parseWithStandardSchema(tool.outputSchema, result)
     }
 
     const finalResult =
-      typeof result === 'string' ? safeJsonParse(result) : result || null
+      typeof result === 'string' ? safeJsonParse(result) : (result ?? null)
 
     results.push({
       toolCallId: toolCall.id,
@@ -486,6 +544,35 @@ async function* executeServerTool(
   }
 }
 
+function buildClientToolResult(
+  toolCallId: string,
+  toolName: string,
+  tool: AnyTool,
+  rawResult: unknown,
+): ToolResult {
+  try {
+    let result = rawResult
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema)) {
+      result = parseWithStandardSchema(tool.outputSchema, result)
+    }
+
+    return {
+      toolCallId,
+      toolName,
+      result:
+        typeof result === 'string' ? safeJsonParse(result) : (result ?? null),
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : 'Validation failed'
+    return {
+      toolCallId,
+      toolName,
+      result: { error: message },
+      state: 'output-error',
+    }
+  }
+}
+
 /**
  * Execute tool calls based on their configuration.
  * Yields CustomEvent chunks during tool execution for real-time progress updates.
@@ -501,9 +588,9 @@ async function* executeServerTool(
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
  */
-export async function* executeToolCalls(
+export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
-  tools: ReadonlyArray<Tool>,
+  tools: ReadonlyArray<AnyTool>,
   approvals: Map<string, boolean> = new Map(),
   clientResults: Map<string, any> = new Map(),
   createCustomEventChunk?: (
@@ -511,13 +598,14 @@ export async function* executeToolCalls(
     value: Record<string, any>,
   ) => CustomEvent,
   middlewareHooks?: ToolExecutionMiddlewareHooks,
+  userContext?: TContext,
 ): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
   const needsClientExecution: Array<ClientToolRequest> = []
 
   // Create tool lookup map
-  const toolMap = new Map<string, Tool>()
+  const toolMap = new Map<string, AnyTool>()
   for (const tool of tools) {
     toolMap.set(tool.name, tool)
   }
@@ -588,8 +676,9 @@ export async function* executeToolCalls(
 
     // Create a ToolExecutionContext for this tool call with event emission
     const pendingEvents: Array<CustomEvent> = []
-    const context: ToolExecutionContext = {
+    const context = {
       toolCallId: toolCall.id,
+      context: userContext,
       emitCustomEvent: (eventName: string, value: Record<string, any>) => {
         if (createCustomEventChunk) {
           pendingEvents.push(
@@ -600,7 +689,7 @@ export async function* executeToolCalls(
           )
         }
       },
-    }
+    } as ToolExecutionContext<TContext>
 
     // CASE 1: Client-side tool (no execute function)
     if (!tool.execute) {
@@ -615,11 +704,14 @@ export async function* executeToolCalls(
           if (approved) {
             // Approved - check if client has executed
             if (clientResults.has(toolCall.id)) {
-              results.push({
-                toolCallId: toolCall.id,
-                toolName,
-                result: clientResults.get(toolCall.id),
-              })
+              results.push(
+                buildClientToolResult(
+                  toolCall.id,
+                  toolName,
+                  tool,
+                  clientResults.get(toolCall.id),
+                ),
+              )
             } else {
               // Approved but not executed yet - request client execution
               needsClientExecution.push({
@@ -649,11 +741,14 @@ export async function* executeToolCalls(
       } else {
         // No approval needed - check if client has executed
         if (clientResults.has(toolCall.id)) {
-          results.push({
-            toolCallId: toolCall.id,
-            toolName,
-            result: clientResults.get(toolCall.id),
-          })
+          results.push(
+            buildClientToolResult(
+              toolCall.id,
+              toolName,
+              tool,
+              clientResults.get(toolCall.id),
+            ),
+          )
         } else {
           // Request client execution
           needsClientExecution.push({

package/src/activities/chat/tools/tool-definition.ts

@@ -1,10 +1,9 @@
 import type { StandardJSONSchemaV1 } from '@standard-schema/spec'
 import type {
-  InferSchemaType,
   JSONSchema,
   SchemaInput,
   Tool,
-  ToolExecutionContext,
+  ToolExecuteFunction,
 } from '../../../types'
 
 /**
@@ -14,7 +13,8 @@ export interface ServerTool<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends Tool<TInput, TOutput, TName> {
+  TContext = unknown,
+> extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'server'
 }
 
@@ -25,6 +25,7 @@ export interface ClientTool<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
+  TContext = unknown,
 > {
   __toolSide: 'client'
   name: TName
@@ -39,9 +40,7 @@ export interface ClientTool<
   needsApproval?: boolean
   lazy?: boolean
   metadata?: Record<string, unknown>
-  execute?: (
-    args: InferSchemaType<TInput>,
-  ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>
+  execute?: ToolExecuteFunction<TInput, TOutput, TContext>
 }
 
 /**
@@ -51,7 +50,8 @@ export interface ToolDefinitionInstance<
   TInput extends SchemaInput = SchemaInput,
   TOutput extends SchemaInput = SchemaInput,
   TName extends string = string,
-> extends Tool<TInput, TOutput, TName> {
+  TContext = unknown,
+> extends Tool<TInput, TOutput, TName, TContext> {
   __toolSide: 'definition'
 }
 
@@ -59,8 +59,12 @@ export interface ToolDefinitionInstance<
  * Union type for any kind of client-side tool (client tool or definition)
  */
 export type AnyClientTool =
-  | ClientTool<SchemaInput, SchemaInput>
-  | ToolDefinitionInstance<SchemaInput, SchemaInput>
+  | (Omit<ClientTool<any, any, string, any>, 'execute'> & {
+      execute?: ((args: any, context?: any) => any) | undefined
+    })
+  | (Omit<ToolDefinitionInstance<any, any, string, any>, 'execute'> & {
+      execute?: ((args: any, context?: any) => any) | undefined
+    })
 
 /**
  * Extract the tool name as a literal type
@@ -117,21 +121,16 @@ export interface ToolDefinition<
   /**
    * Create a server-side tool with execute function
    */
-  server: (
-    execute: (
-      args: InferSchemaType<TInput>,
-      context?: ToolExecutionContext,
-    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-  ) => ServerTool<TInput, TOutput, TName>
+  server: <TContext = unknown>(
+    execute: ToolExecuteFunction<TInput, TOutput, TContext>,
+  ) => ServerTool<TInput, TOutput, TName, TContext>
 
   /**
    * Create a client-side tool with optional execute function
    */
-  client: (
-    execute?: (
-      args: InferSchemaType<TInput>,
-    ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-  ) => ClientTool<TInput, TOutput, TName>
+  client: <TContext = unknown>(
+    execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
+  ) => ClientTool<TInput, TOutput, TName, TContext>
 }
 
 /**
@@ -199,12 +198,9 @@ export function toolDefinition<
   const definition: ToolDefinition<TInput, TOutput, TName> = {
     __toolSide: 'definition',
     ...config,
-    server(
-      execute: (
-        args: InferSchemaType<TInput>,
-        context?: ToolExecutionContext,
-      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-    ): ServerTool<TInput, TOutput, TName> {
+    server<TContext = unknown>(
+      execute: ToolExecuteFunction<TInput, TOutput, TContext>,
+    ): ServerTool<TInput, TOutput, TName, TContext> {
       return {
         __toolSide: 'server',
         ...config,
@@ -212,11 +208,9 @@ export function toolDefinition<
       }
     },
 
-    client(
-      execute?: (
-        args: InferSchemaType<TInput>,
-      ) => Promise<InferSchemaType<TOutput>> | InferSchemaType<TOutput>,
-    ): ClientTool<TInput, TOutput, TName> {
+    client<TContext = unknown>(
+      execute?: ToolExecuteFunction<TInput, TOutput, TContext>,
+    ): ClientTool<TInput, TOutput, TName, TContext> {
       return {
         __toolSide: 'client',
         ...config,

package/src/activities/error-payload.ts

@@ -62,3 +62,47 @@ export function toRunErrorPayload(
   }
   return { message: fallbackMessage, code: undefined }
 }
+
+/**
+ * Extract the provider's *structured error body* from a thrown value, to attach
+ * as the AG-UI `rawEvent` on a RUN_ERROR event. This is the recoverable upstream
+ * detail (provider name, the upstream model's error JSON, rate-limit/overload
+ * codes, etc.) that `toRunErrorPayload`'s `{ message, code }` deliberately drops.
+ *
+ * Security boundary: only known provider-response-body fields are forwarded —
+ * never the raw SDK exception object, which can carry request metadata such as
+ * auth headers or request ids. The recognized sources, in priority order:
+ *
+ *  - `error.rawEvent` — a provider body an adapter attached explicitly (e.g. the
+ *    OpenRouter mid-stream `chunk.error`).
+ *  - `error.error` (object) — the parsed provider response body exposed by SDK
+ *    `APIError` instances (OpenAI/Anthropic `{ type, message, code, param }`,
+ *    OpenRouter typed errors whose `.error` carries `.metadata`). This is
+ *    provider-shaped data, distinct from `.headers` / `.request_id`.
+ *  - `error.metadata` — OpenRouter's `provider_name` + raw upstream body, when
+ *    surfaced directly on the thrown error.
+ *
+ * Returns `undefined` when no structured provider body is present, so callers
+ * omit the field entirely rather than setting it to `null`:
+ *
+ *   const rawEvent = toRunErrorRawEvent(error)
+ *   yield { type: EventType.RUN_ERROR, ..., ...(rawEvent !== undefined && { rawEvent }) }
+ */
+export function toRunErrorRawEvent(error: unknown): unknown {
+  if (!error || typeof error !== 'object') return undefined
+  const e = error as {
+    rawEvent?: unknown
+    error?: unknown
+    metadata?: unknown
+  }
+  if (e.rawEvent !== undefined && e.rawEvent !== null) return e.rawEvent
+  if (
+    e.error !== undefined &&
+    e.error !== null &&
+    typeof e.error === 'object'
+  ) {
+    return e.error
+  }
+  if (e.metadata !== undefined && e.metadata !== null) return e.metadata
+  return undefined
+}

package/src/activities/generateAudio/index.ts

@@ -174,6 +174,16 @@ async function runGenerateAudio<
       timestamp: Date.now(),
     })
 
+    if (result.usage) {
+      aiEventClient.emit('audio:usage', {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+        timestamp: Date.now(),
+      })
+    }
+
     logger.output(`activity=generateAudio provider=${providerName}`, {
       contentType: result.audio.contentType,
       audioDuration: result.audio.duration,

package/src/activities/generateSpeech/index.ts

@@ -187,6 +187,16 @@ async function runGenerateSpeech<
       timestamp: Date.now(),
     })
 
+    if (result.usage) {
+      aiEventClient.emit('speech:usage', {
+        requestId,
+        model,
+        usage: result.usage,
+        modelOptions: rest.modelOptions as Record<string, unknown> | undefined,
+        timestamp: Date.now(),
+      })
+    }
+
     logger.output(`activity=generateSpeech bytes=${result.audio.length}`, {
       bytes: result.audio.length,
       contentType: result.contentType,

package/src/adapter-internals.ts

@@ -6,4 +6,7 @@ export type { ResolvedCategories } from './logger/internal-logger'
 export { InternalLogger } from './logger/internal-logger'
 export type { Logger } from './logger/types'
 export { resolveDebugOption } from './logger/resolve'
-export { toRunErrorPayload } from './activities/error-payload'
+export {
+  toRunErrorPayload,
+  toRunErrorRawEvent,
+} from './activities/error-payload'

package/src/client.ts

@@ -46,7 +46,11 @@ export {
   type ToolDefinitionInstance,
 } from './activities/chat/tools/tool-definition'
 
-export { convertSchemaToJsonSchema } from './activities/chat/tools/schema-converter'
+export {
+  convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
+} from './activities/chat/tools/schema-converter'
 
 export {
   convertMessagesToModelMessages,

package/src/index.ts

@@ -55,6 +55,8 @@ export {
 // Schema conversion (Standard JSON Schema compliant)
 export {
   convertSchemaToJsonSchema,
+  isStandardSchema,
+  parseWithStandardSchema,
   StandardSchemaValidationError,
 } from './activities/chat/tools/schema-converter'
 
@@ -109,6 +111,9 @@ export type {
 // All types
 export * from './types'
 
+// Usage utilities
+export { buildBaseUsage, type BaseUsageInput } from './utilities/usage'
+
 // System prompts (type + normaliser used by adapters)
 export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts'
 export { normalizeSystemPrompts } from './system-prompts'
@@ -187,6 +192,11 @@ export {
 // AG-UI wire serialization (used internally by @tanstack/ai-client)
 export { uiMessagesToWire } from './utilities/ag-ui-wire'
 export type { WireMessage } from './utilities/ag-ui-wire'
+export {
+  isContentPart,
+  isContentPartArray,
+  normalizeToolResult,
+} from './utilities/tool-result'
 
 // Adapter extension utilities
 export { createModel, extendAdapter } from './extend-adapter'

package/src/tool-registry.ts

@@ -1,4 +1,4 @@
-import type { Tool } from './types'
+import type { AnyTool } from './types'
 
 /**
  * A registry that holds tools and allows dynamic tool management.
@@ -6,12 +6,12 @@ import type { Tool } from './types'
  * The registry can be either mutable (allowing additions/removals during execution)
  * or frozen (static tool list, for backward compatibility with tools arrays).
  */
-export interface ToolRegistry {
+export interface ToolRegistry<TTool extends AnyTool = AnyTool> {
   /**
    * Get all current tools in the registry.
    * Called each agent loop iteration to get the latest tool list.
    */
-  getTools: () => ReadonlyArray<Tool>
+  getTools: () => Array<TTool>
 
   /**
    * Add a tool to the registry dynamically.
@@ -19,7 +19,7 @@ export interface ToolRegistry {
    *
    * @param tool - The tool to add
    */
-  add: (tool: Tool) => void
+  add: (tool: TTool) => void
 
   /**
    * Remove a tool from the registry by name.
@@ -43,7 +43,7 @@ export interface ToolRegistry {
    * @param name - The name of the tool to get
    * @returns The tool if found, undefined otherwise
    */
-  get: (name: string) => Tool | undefined
+  get: (name: string) => TTool | undefined
 
   /**
    * Whether this registry is frozen (immutable).
@@ -75,10 +75,10 @@ export interface ToolRegistry {
  * registry.add(newTool)  // Immediately available to LLM
  * ```
  */
-export function createToolRegistry(
-  initialTools: Array<Tool> = [],
-): ToolRegistry {
-  const tools = new Map<string, Tool>()
+export function createToolRegistry<TTool extends AnyTool = AnyTool>(
+  initialTools: Array<TTool> = [],
+): ToolRegistry<TTool> {
+  const tools = new Map<string, TTool>()
 
   for (const tool of initialTools) {
     tools.set(tool.name, tool)
@@ -87,7 +87,7 @@ export function createToolRegistry(
   return {
     getTools: () => Array.from(tools.values()),
 
-    add: (tool: Tool) => {
+    add: (tool: TTool) => {
       tools.set(tool.name, tool)
     },
 
@@ -116,8 +116,10 @@ export function createToolRegistry(
  * @param tools - The static array of tools
  * @returns A frozen ToolRegistry
  */
-export function createFrozenRegistry(tools: Array<Tool> = []): ToolRegistry {
-  const toolMap = new Map<string, Tool>()
+export function createFrozenRegistry<TTool extends AnyTool = AnyTool>(
+  tools: Array<TTool> = [],
+): ToolRegistry<TTool> {
+  const toolMap = new Map<string, TTool>()
 
   for (const tool of tools) {
     toolMap.set(tool.name, tool)
@@ -126,9 +128,9 @@ export function createFrozenRegistry(tools: Array<Tool> = []): ToolRegistry {
   const frozenTools = Object.freeze([...tools])
 
   return {
-    getTools: () => frozenTools,
+    getTools: () => [...frozenTools],
 
-    add: (_tool: Tool) => {
+    add: (_tool: TTool) => {
       // No-op for frozen registry
     },