ai-functions 2.1.3 → 2.4.0

package/src/tool-orchestration.ts

@@ -156,13 +156,26 @@ export interface LoopOptions {
   onStep?: (step: StepInfo) => void
 }
 
+/**
+ * Model generation options passed to the model
+ */
+export interface ModelGenerationOptions {
+  /** Messages for the conversation */
+  messages: Message[]
+  /** Tools available for use */
+  tools: Record<
+    string,
+    { description: string; parameters: unknown; execute: (args: unknown) => Promise<unknown> }
+  >
+}
+
 /**
  * Options for running the loop
  */
 export interface RunOptions {
   /** Model to use for generation */
   model: {
-    generate: (options: any) => Promise<ModelResponse>
+    generate: (options: ModelGenerationOptions) => Promise<ModelResponse>
   }
   /** Initial prompt */
   prompt: string
@@ -263,7 +276,7 @@ export class ToolValidator {
       if (error instanceof z.ZodError) {
         return {
           valid: false,
-          errors: error.errors.map(e => `${e.path.join('.')}: ${e.message}`),
+          errors: error.errors.map((e) => `${e.path.join('.')}: ${e.message}`),
         }
       }
       return {
@@ -277,7 +290,7 @@ export class ToolValidator {
    * Validate multiple tool calls at once
    */
   validateAll(calls: ToolCall[]): ValidationResult[] {
-    return calls.map(call => this.validate(call.name, call.arguments))
+    return calls.map((call) => this.validate(call.name, call.arguments))
   }
 }
 
@@ -287,6 +300,13 @@ export class ToolValidator {
 
 /**
  * Routes tool calls to registered handlers
+ *
+ * @deprecated Phase C Week 2 — `ToolRouter` has zero production callers in
+ * primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). Only the
+ * `ai-primitives` umbrella re-export tests reference it. AI SDK 6's native
+ * tool-routing under `generateText({ tools })` and `Agent` / `ToolLoopAgent`
+ * cover the same surface. Will be removed in the Phase C semver bump
+ * alongside `AgenticLoop` and `createAgenticLoop`.
  */
 export class ToolRouter {
   private tools = new Map<string, Tool>()
@@ -353,7 +373,7 @@ export class ToolRouter {
    * Route multiple tool calls in parallel
    */
   async routeAllParallel(calls: ToolCall[]): Promise<ToolResult[]> {
-    return Promise.all(calls.map(call => this.route(call)))
+    return Promise.all(calls.map((call) => this.route(call)))
   }
 
   /**
@@ -364,13 +384,13 @@ export class ToolRouter {
       return {
         role: 'tool',
         content: JSON.stringify(result.result),
-        tool_call_id: result.toolCall?.id,
+        ...(result.toolCall?.id !== undefined && { tool_call_id: result.toolCall.id }),
       }
     }
     return {
       role: 'tool',
       content: JSON.stringify({ error: result.error }),
-      tool_call_id: result.toolCall?.id,
+      ...(result.toolCall?.id !== undefined && { tool_call_id: result.toolCall.id }),
       isError: true,
     }
   }
@@ -382,6 +402,15 @@ export class ToolRouter {
 
 /**
  * Orchestrates multi-turn model→tools→model loops
+ *
+ * @deprecated Phase C Week 2 — `AgenticLoop` has zero production callers in
+ * primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). Only the
+ * `ai-primitives` umbrella re-export tests reference it. The production
+ * cascade walker (`services-as-software/v3/invoke/cascade-walker.ts:178`)
+ * already uses AI SDK 6's `generateText({ tools, maxSteps: 10 })` directly
+ * for agentic steps — no consumer code paths through this class. AI SDK 6's
+ * `Agent` / `ToolLoopAgent` (`stopWhen: stepCountIs(N)`) are the going-
+ * forward primitives. Will be removed in the Phase C semver bump.
  */
 export class AgenticLoop {
   private options: LoopOptions
@@ -412,8 +441,14 @@ export class AgenticLoop {
   /**
    * Get tools in AI SDK format
    */
-  getToolsForSDK(): Record<string, { description: string; parameters: unknown; execute: (args: unknown) => Promise<unknown> }> {
-    const tools: Record<string, any> = {}
+  getToolsForSDK(): Record<
+    string,
+    { description: string; parameters: unknown; execute: (args: unknown) => Promise<unknown> }
+  > {
+    const tools: Record<
+      string,
+      { description: string; parameters: unknown; execute: (args: unknown) => Promise<unknown> }
+    > = {}
     for (const tool of this.options.tools) {
       tools[tool.name] = {
         description: tool.description,
@@ -484,7 +519,7 @@ export class AgenticLoop {
     return {
       name: call.name,
       arguments: call.arguments,
-      error: lastError,
+      ...(lastError !== undefined && { error: lastError }),
       retryCount: retryCount > 0 ? retryCount - 1 : 0,
     }
   }
@@ -517,7 +552,7 @@ export class AgenticLoop {
 
     for (const chunk of chunks) {
       const chunkResults = await Promise.all(
-        chunk.map(call => this.executeToolCall(call, abortSignal))
+        chunk.map((call) => this.executeToolCall(call, abortSignal))
       )
       results.push(...chunkResults)
     }
@@ -576,7 +611,9 @@ export class AgenticLoop {
     let steps = 0
     let stopReason: LoopResult['stopReason'] = 'stop'
     let finalText = ''
-    let totalUsage = trackUsage ? { promptTokens: 0, completionTokens: 0, totalTokens: 0 } : undefined
+    let totalUsage = trackUsage
+      ? { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      : undefined
 
     try {
       while (steps < maxSteps) {
@@ -622,7 +659,7 @@ export class AgenticLoop {
         const toolResults = await this.executeToolCalls(response.toolCalls, abortSignal)
 
         // Check for errors
-        const hasErrors = toolResults.some(r => r.error)
+        const hasErrors = toolResults.some((r) => r.error)
         if (hasErrors && !continueOnError) {
           // Still record the results but note the errors
         }
@@ -656,8 +693,8 @@ export class AgenticLoop {
             stepNumber: steps,
             toolCalls: response.toolCalls.map((tc, i) => ({
               ...tc,
-              result: toolResults[i]?.result,
-              error: toolResults[i]?.error,
+              ...(toolResults[i]?.result !== undefined && { result: toolResults[i]?.result }),
+              ...(toolResults[i]?.error !== undefined && { error: toolResults[i]?.error }),
             })),
             response,
             messages: [...messages],
@@ -697,7 +734,7 @@ export class AgenticLoop {
       toolCalls: allToolCalls,
       toolResults: allToolResults,
       stopReason,
-      usage: totalUsage,
+      ...(totalUsage !== undefined && { usage: totalUsage }),
       messages,
     }
   }
@@ -717,7 +754,9 @@ export class AgenticLoop {
     let steps = 0
     let stopReason: LoopResult['stopReason'] = 'stop'
     let finalText = ''
-    let totalUsage = trackUsage ? { promptTokens: 0, completionTokens: 0, totalTokens: 0 } : undefined
+    let totalUsage = trackUsage
+      ? { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
+      : undefined
 
     yield { type: 'start', prompt, timestamp: Date.now() }
 
@@ -766,8 +805,8 @@ export class AgenticLoop {
           yield {
             type: 'tool_result',
             toolName: result.name,
-            result: result.result,
-            error: result.error,
+            ...(result.result !== undefined && { result: result.result }),
+            ...(result.error !== undefined && { error: result.error }),
             stepNumber: steps,
             timestamp: Date.now(),
           }
@@ -821,7 +860,7 @@ export class AgenticLoop {
       toolCalls: allToolCalls,
       toolResults: allToolResults,
       stopReason,
-      usage: totalUsage,
+      ...(totalUsage !== undefined && { usage: totalUsage }),
       messages,
     }
   }
@@ -840,7 +879,14 @@ export type LoopStreamEvent =
   | { type: 'step_end'; stepNumber: number; hasToolCalls: boolean; timestamp: number }
   | { type: 'text'; text: string; stepNumber: number; timestamp: number }
   | { type: 'tool_calls'; toolCalls: ToolCall[]; stepNumber: number; timestamp: number }
-  | { type: 'tool_result'; toolName: string; result?: unknown; error?: string; stepNumber: number; timestamp: number }
+  | {
+      type: 'tool_result'
+      toolName: string
+      result?: unknown
+      error?: string
+      stepNumber: number
+      timestamp: number
+    }
   | { type: 'max_steps'; steps: number; timestamp: number }
   | { type: 'aborted'; steps: number; timestamp: number }
   | { type: 'error'; error: string; timestamp: number }
@@ -853,14 +899,12 @@ export type LoopStreamEvent =
 /**
  * Create a tool from a simple function
  */
-export function createTool<TParams extends z.ZodRawShape, TResult>(
-  config: {
-    name: string
-    description: string
-    parameters: TParams
-    execute: (params: z.infer<z.ZodObject<TParams>>) => Promise<TResult>
-  }
-): Tool<z.ZodObject<TParams>, TResult> {
+export function createTool<TParams extends z.ZodRawShape, TResult>(config: {
+  name: string
+  description: string
+  parameters: TParams
+  execute: (params: z.infer<z.ZodObject<TParams>>) => Promise<TResult>
+}): Tool<z.ZodObject<TParams>, TResult> {
   return {
     name: config.name,
     description: config.description,
@@ -891,9 +935,7 @@ export function wrapTool<T extends Tool>(
     ...tool,
     execute: async (params: unknown) => {
       try {
-        const modifiedParams = middleware.before
-          ? await middleware.before(params)
-          : params
+        const modifiedParams = middleware.before ? await middleware.before(params) : params
         const result = await tool.execute(modifiedParams)
         return middleware.after ? await middleware.after(result) : result
       } catch (error) {
@@ -906,34 +948,151 @@ export function wrapTool<T extends Tool>(
   }
 }
 
+/**
+ * Options for cachedTool
+ */
+export interface CachedToolOptions {
+  /** Time-to-live in milliseconds (default: 60000) */
+  ttl?: number
+  /** Function to generate cache key from params (default: JSON.stringify) */
+  keyFn?: (params: unknown) => string
+  /** Interval in ms for automatic cleanup of expired entries (default: 0 = disabled) */
+  cleanupIntervalMs?: number
+  /** Maximum cache size before LRU eviction kicks in (default: 0 = unlimited) */
+  maxSize?: number
+}
+
+/**
+ * Extended tool interface with cache management methods
+ */
+export interface CachedTool extends Tool {
+  /** Get the current number of entries in the cache */
+  cacheSize(): number
+  /** Clear all cache entries */
+  clearCache(): void
+  /** Stop cleanup timer and clear cache */
+  destroy(): void
+}
+
 /**
  * Create a tool with caching support
+ *
+ * Features:
+ * - TTL-based expiration
+ * - Optional periodic cleanup of expired entries (prevents memory leaks)
+ * - Optional max size with LRU eviction
+ * - Manual cache control (clear, destroy)
  */
-export function cachedTool<T extends Tool>(
-  tool: T,
-  options: {
-    ttl?: number
-    keyFn?: (params: unknown) => string
-  } = {}
-): Tool {
-  const cache = new Map<string, { value: unknown; expires: number }>()
-  const { ttl = 60000, keyFn = JSON.stringify } = options
+export function cachedTool<T extends Tool>(tool: T, options: CachedToolOptions = {}): CachedTool {
+  const { ttl = 60000, keyFn = JSON.stringify, cleanupIntervalMs = 0, maxSize = 0 } = options
 
-  return {
+  interface CacheEntry {
+    value: unknown
+    expires: number
+    lastAccessed: number
+  }
+
+  const cache = new Map<string, CacheEntry>()
+  let cleanupTimer: ReturnType<typeof setInterval> | null = null
+  let destroyed = false
+
+  // Cleanup function to remove expired entries
+  const cleanupExpired = () => {
+    const now = Date.now()
+    for (const [key, entry] of cache) {
+      if (entry.expires <= now) {
+        cache.delete(key)
+      }
+    }
+  }
+
+  // Start periodic cleanup if configured
+  if (cleanupIntervalMs > 0) {
+    cleanupTimer = setInterval(cleanupExpired, cleanupIntervalMs)
+    // Unref the timer so it doesn't keep the process alive (Node.js)
+    if (typeof cleanupTimer === 'object' && 'unref' in cleanupTimer) {
+      cleanupTimer.unref()
+    }
+  }
+
+  // Evict oldest entries based on lastAccessed (LRU)
+  const evictOldest = () => {
+    if (maxSize <= 0 || cache.size < maxSize) return
+
+    // Find the entry with oldest lastAccessed
+    let oldestKey: string | null = null
+    let oldestTime = Infinity
+
+    for (const [key, entry] of cache) {
+      if (entry.lastAccessed < oldestTime) {
+        oldestTime = entry.lastAccessed
+        oldestKey = key
+      }
+    }
+
+    if (oldestKey) {
+      cache.delete(oldestKey)
+    }
+  }
+
+  const cachedToolInstance: CachedTool = {
     ...tool,
     execute: async (params: unknown) => {
+      if (destroyed) {
+        // If destroyed, just execute without caching
+        return tool.execute(params)
+      }
+
       const key = keyFn(params)
       const cached = cache.get(key)
+      const now = Date.now()
 
-      if (cached && cached.expires > Date.now()) {
+      if (cached && cached.expires > now) {
+        // Cache hit - update last accessed time for LRU
+        cached.lastAccessed = now
         return cached.value
       }
 
+      // Cache miss or expired - remove expired entry if present
+      if (cached) {
+        cache.delete(key)
+      }
+
       const result = await tool.execute(params)
-      cache.set(key, { value: result, expires: Date.now() + ttl })
+
+      // Evict oldest if we're at max size
+      if (maxSize > 0 && cache.size >= maxSize) {
+        evictOldest()
+      }
+
+      cache.set(key, {
+        value: result,
+        expires: now + ttl,
+        lastAccessed: now,
+      })
+
       return result
     },
+
+    cacheSize(): number {
+      return cache.size
+    },
+
+    clearCache(): void {
+      cache.clear()
+    },
+
+    destroy(): void {
+      destroyed = true
+      if (cleanupTimer !== null) {
+        clearInterval(cleanupTimer)
+        cleanupTimer = null
+      }
+      cache.clear()
+    },
   }
+
+  return cachedToolInstance
 }
 
 /**
@@ -971,16 +1130,16 @@ export function rateLimitedTool<T extends Tool>(
 /**
  * Create a tool that times out after a specified duration
  */
-export function timeoutTool<T extends Tool>(
-  tool: T,
-  timeoutMs: number
-): Tool {
+export function timeoutTool<T extends Tool>(tool: T, timeoutMs: number): Tool {
   return {
     ...tool,
     execute: async (params: unknown) => {
       let timeoutId: ReturnType<typeof setTimeout> | undefined
       const timeoutPromise = new Promise<never>((_, reject) => {
-        timeoutId = setTimeout(() => reject(new Error(`Tool '${tool.name}' timed out after ${timeoutMs}ms`)), timeoutMs)
+        timeoutId = setTimeout(
+          () => reject(new Error(`Tool '${tool.name}' timed out after ${timeoutMs}ms`)),
+          timeoutMs
+        )
       })
       try {
         return await Promise.race([tool.execute(params), timeoutPromise])
@@ -995,6 +1154,12 @@ export function timeoutTool<T extends Tool>(
 
 /**
  * Create an agentic loop with sensible defaults
+ *
+ * @deprecated Phase C Week 2 — `createAgenticLoop` has zero production
+ * callers in primitives.org.ai (only `ai-primitives` umbrella re-export
+ * tests). Use AI SDK 6's `Agent` / `ToolLoopAgent` with
+ * `stopWhen: stepCountIs(N)` instead. Will be removed alongside
+ * `AgenticLoop` in the Phase C semver bump. See `bd show aip-ibid`.
  */
 export function createAgenticLoop(options: Partial<LoopOptions> & { tools: Tool[] }): AgenticLoop {
   return new AgenticLoop({

package/src/type-guards.ts

@@ -0,0 +1,31 @@
+/**
+ * Type Guards for AI Functions
+ *
+ * Shared type guard utilities used across AI packages.
+ *
+ * @packageDocumentation
+ */
+
+import type { ZodTypeAny } from 'zod'
+
+/**
+ * Check if value is a Zod schema
+ *
+ * Uses duck-typing to detect Zod schemas by checking for the
+ * `_def` property (internal Zod schema definition) and `parse` method.
+ *
+ * @example
+ * ```ts
+ * import { isZodSchema } from 'ai-functions'
+ * import { z } from 'zod'
+ *
+ * const schema = z.object({ name: z.string() })
+ * if (isZodSchema(schema)) {
+ *   // TypeScript knows schema is ZodTypeAny
+ *   schema.parse({ name: 'test' })
+ * }
+ * ```
+ */
+export function isZodSchema(value: unknown): value is ZodTypeAny {
+  return value !== null && typeof value === 'object' && '_def' in value && 'parse' in value
+}