@tanstack/ai 0.6.3 → 0.8.0

package/dist/esm/activities/chat/middleware/types.d.ts

@@ -0,0 +1,307 @@
+import { ModelMessage, StreamChunk, Tool, ToolCall } from '../../../types.js';
+/**
+ * Phase of the chat middleware lifecycle.
+ * - 'init': Initial config transform before the chat engine starts
+ * - 'beforeModel': Before each adapter chatStream call (per agent iteration)
+ * - 'modelStream': During model streaming
+ * - 'beforeTools': Before tool execution phase
+ * - 'afterTools': After tool execution phase
+ */
+export type ChatMiddlewarePhase = 'init' | 'beforeModel' | 'modelStream' | 'beforeTools' | 'afterTools';
+/**
+ * Stable context object passed to all middleware hooks.
+ * Created once per chat() invocation and shared across all hooks.
+ */
+export interface ChatMiddlewareContext {
+    /** Unique identifier for this chat request */
+    requestId: string;
+    /** Unique identifier for this stream */
+    streamId: string;
+    /** Conversation identifier, if provided by the caller */
+    conversationId?: string;
+    /** Current lifecycle phase */
+    phase: ChatMiddlewarePhase;
+    /** Current agent loop iteration (0-indexed) */
+    iteration: number;
+    /** Running count of chunks yielded so far */
+    chunkIndex: number;
+    /** Abort signal from the chat request */
+    signal?: AbortSignal;
+    /** Abort the chat run with a reason */
+    abort: (reason?: string) => void;
+    /** Opaque user-provided value from chat() options */
+    context: unknown;
+    /**
+     * Defer a non-blocking side-effect promise.
+     * Deferred promises do not block streaming and are awaited
+     * after the terminal hook (onFinish/onAbort/onError).
+     */
+    defer: (promise: Promise<unknown>) => void;
+    /** Provider name (e.g., 'openai', 'anthropic') */
+    provider: string;
+    /** Model identifier (e.g., 'gpt-4o') */
+    model: string;
+    /** Source of the chat invocation — always 'server' for server-side chat */
+    source: 'client' | 'server';
+    /** Whether the chat is streaming */
+    streaming: boolean;
+    /** System prompts configured for this chat */
+    systemPrompts: Array<string>;
+    /** Names of configured tools, if any */
+    toolNames?: Array<string>;
+    /** Flattened generation options (temperature, topP, maxTokens, metadata) */
+    options?: Record<string, unknown>;
+    /** Provider-specific model options */
+    modelOptions?: Record<string, unknown>;
+    /** Number of messages at the start of the request */
+    messageCount: number;
+    /** Whether tools are configured */
+    hasTools: boolean;
+    /** Current assistant message ID (changes per iteration) */
+    currentMessageId: string | null;
+    /** Accumulated text content for the current iteration */
+    accumulatedContent: string;
+    /** Current messages array (read-only view) */
+    messages: ReadonlyArray<ModelMessage>;
+    /** Generate a unique ID with the given prefix */
+    createId: (prefix: string) => string;
+}
+/**
+ * Chat configuration that middleware can observe or transform.
+ * This is a subset of the chat engine's effective configuration
+ * that middleware is allowed to modify.
+ */
+export interface ChatMiddlewareConfig {
+    messages: Array<ModelMessage>;
+    systemPrompts: Array<string>;
+    tools: Array<Tool>;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    metadata?: Record<string, unknown>;
+    modelOptions?: Record<string, unknown>;
+}
+/**
+ * Context provided to tool call hooks (onBeforeToolCall / onAfterToolCall).
+ */
+export interface ToolCallHookContext {
+    /** The tool call being executed */
+    toolCall: ToolCall;
+    /** The resolved tool definition, if found */
+    tool: Tool | undefined;
+    /** Parsed arguments for the tool call */
+    args: unknown;
+    /** Name of the tool */
+    toolName: string;
+    /** ID of the tool call */
+    toolCallId: string;
+}
+/**
+ * Decision returned from onBeforeToolCall.
+ * - undefined/void: continue with normal execution
+ * - { type: 'transformArgs', args }: replace args used for execution
+ * - { type: 'skip', result }: skip execution, use provided result
+ * - { type: 'abort', reason }: abort the entire chat run
+ */
+export type BeforeToolCallDecision = void | undefined | null | {
+    type: 'transformArgs';
+    args: unknown;
+} | {
+    type: 'skip';
+    result: unknown;
+} | {
+    type: 'abort';
+    reason?: string;
+};
+/**
+ * Outcome information provided to onAfterToolCall.
+ */
+export interface AfterToolCallInfo {
+    /** The tool call that was executed */
+    toolCall: ToolCall;
+    /** The resolved tool definition */
+    tool: Tool | undefined;
+    /** Name of the tool */
+    toolName: string;
+    /** ID of the tool call */
+    toolCallId: string;
+    /** Whether the execution succeeded */
+    ok: boolean;
+    /** Duration of tool execution in milliseconds */
+    duration: number;
+    /** The result (if ok) or error (if not ok) */
+    result?: unknown;
+    error?: unknown;
+}
+/**
+ * Information passed to onIteration at the start of each agent loop iteration.
+ */
+export interface IterationInfo {
+    /** 0-based iteration index */
+    iteration: number;
+    /** The assistant message ID created for this iteration */
+    messageId: string;
+}
+/**
+ * Aggregate information passed to onToolPhaseComplete after all tool calls
+ * in an iteration have been processed.
+ */
+export interface ToolPhaseCompleteInfo {
+    /** Tool calls that were assigned to the assistant message */
+    toolCalls: Array<ToolCall>;
+    /** Completed tool results */
+    results: Array<{
+        toolCallId: string;
+        toolName: string;
+        result: unknown;
+        duration?: number;
+    }>;
+    /** Tools that need user approval */
+    needsApproval: Array<{
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+        approvalId: string;
+    }>;
+    /** Tools that need client-side execution */
+    needsClientExecution: Array<{
+        toolCallId: string;
+        toolName: string;
+        input: unknown;
+    }>;
+}
+/**
+ * Token usage statistics passed to the onUsage hook.
+ * Extracted from the RUN_FINISHED chunk when usage data is present.
+ */
+export interface UsageInfo {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Information passed to onFinish.
+ */
+export interface FinishInfo {
+    /** The finish reason from the last model response */
+    finishReason: string | null;
+    /** Total duration of the chat run in milliseconds */
+    duration: number;
+    /** Final accumulated text content */
+    content: string;
+    /** Final usage totals, if available */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Information passed to onAbort.
+ */
+export interface AbortInfo {
+    /** The reason for the abort, if provided */
+    reason?: string;
+    /** Duration until abort in milliseconds */
+    duration: number;
+}
+/**
+ * Information passed to onError.
+ */
+export interface ErrorInfo {
+    /** The error that caused the failure */
+    error: unknown;
+    /** Duration until error in milliseconds */
+    duration: number;
+}
+/**
+ * Chat middleware interface.
+ *
+ * All hooks are optional. Middleware is composed in array order:
+ * - `onConfig`: config piped through middlewares in order (first transform influences later)
+ * - `onChunk`: each output chunk is fed into the next middleware in order
+ *
+ * @example Logging middleware
+ * ```ts
+ * const loggingMiddleware: ChatMiddleware = {
+ *   name: 'logging',
+ *   onStart(ctx) { console.log('Chat started', ctx.requestId) },
+ *   onChunk(ctx, chunk) { console.log('Chunk:', chunk.type) },
+ *   onFinish(ctx, info) { console.log('Done:', info.duration, 'ms') },
+ * }
+ * ```
+ *
+ * @example Redaction middleware
+ * ```ts
+ * const redactionMiddleware: ChatMiddleware = {
+ *   name: 'redaction',
+ *   onChunk(ctx, chunk) {
+ *     if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+ *       return { ...chunk, delta: redact(chunk.delta) }
+ *     }
+ *   },
+ * }
+ * ```
+ */
+export interface ChatMiddleware {
+    /** Optional name for debugging and identification */
+    name?: string;
+    /**
+     * Called to observe or transform the chat configuration.
+     * Called at init and at the beginning of each agent iteration.
+     *
+     * Return a partial config to merge with the current config, or void to pass through.
+     * Only the fields you return are overwritten — everything else is preserved.
+     */
+    onConfig?: (ctx: ChatMiddlewareContext, config: ChatMiddlewareConfig) => void | null | Partial<ChatMiddlewareConfig> | Promise<void | Partial<ChatMiddlewareConfig>>;
+    /**
+     * Called when the chat run starts (after initial onConfig).
+     */
+    onStart?: (ctx: ChatMiddlewareContext) => void | Promise<void>;
+    /**
+     * Called at the start of each agent loop iteration, after a new assistant message ID
+     * is created. Use this to observe iteration boundaries.
+     */
+    onIteration?: (ctx: ChatMiddlewareContext, info: IterationInfo) => void | Promise<void>;
+    /**
+     * Called for every chunk yielded by chat().
+     * Can observe, transform, expand, or drop chunks.
+     *
+     * @returns void (pass through), chunk (replace), chunk[] (expand), null (drop)
+     */
+    onChunk?: (ctx: ChatMiddlewareContext, chunk: StreamChunk) => void | StreamChunk | Array<StreamChunk> | null | Promise<void | StreamChunk | Array<StreamChunk> | null>;
+    /**
+     * Called before a tool is executed.
+     * Can observe, transform args, skip execution, or abort the run.
+     */
+    onBeforeToolCall?: (ctx: ChatMiddlewareContext, hookCtx: ToolCallHookContext) => BeforeToolCallDecision | Promise<BeforeToolCallDecision>;
+    /**
+     * Called after a tool execution completes (success or failure).
+     */
+    onAfterToolCall?: (ctx: ChatMiddlewareContext, info: AfterToolCallInfo) => void | Promise<void>;
+    /**
+     * Called after all tool calls in an iteration have been processed.
+     * Provides aggregate data about tool execution results, approvals, and client tools.
+     */
+    onToolPhaseComplete?: (ctx: ChatMiddlewareContext, info: ToolPhaseCompleteInfo) => void | Promise<void>;
+    /**
+     * Called when usage data is available from a RUN_FINISHED chunk.
+     * Called once per model iteration that reports usage.
+     */
+    onUsage?: (ctx: ChatMiddlewareContext, usage: UsageInfo) => void | Promise<void>;
+    /**
+     * Called when the chat run completes normally.
+     * Exactly one of onFinish/onAbort/onError will be called per run.
+     */
+    onFinish?: (ctx: ChatMiddlewareContext, info: FinishInfo) => void | Promise<void>;
+    /**
+     * Called when the chat run is aborted.
+     * Exactly one of onFinish/onAbort/onError will be called per run.
+     */
+    onAbort?: (ctx: ChatMiddlewareContext, info: AbortInfo) => void | Promise<void>;
+    /**
+     * Called when the chat run encounters an unhandled error.
+     * Exactly one of onFinish/onAbort/onError will be called per run.
+     */
+    onError?: (ctx: ChatMiddlewareContext, info: ErrorInfo) => void | Promise<void>;
+}

package/dist/esm/activities/chat/tools/tool-calls.d.ts

@@ -1,4 +1,19 @@
 import { CustomEvent, ModelMessage, RunFinishedEvent, Tool, ToolCall, ToolCallArgsEvent, ToolCallEndEvent, ToolCallStartEvent } from '../../../types.js';
+import { AfterToolCallInfo, BeforeToolCallDecision } from '../middleware/types.js';
+/**
+ * Optional middleware hooks for tool execution.
+ * When provided, these callbacks are invoked before/after each tool execution.
+ */
+export interface ToolExecutionMiddlewareHooks {
+    onBeforeToolCall?: (toolCall: ToolCall, tool: Tool | undefined, args: unknown) => Promise<BeforeToolCallDecision>;
+    onAfterToolCall?: (info: AfterToolCallInfo) => Promise<void>;
+}
+/**
+ * Error thrown when middleware decides to abort the chat run during tool execution.
+ */
+export declare class MiddlewareAbortError extends Error {
+    constructor(reason: string);
+}
 /**
  * Manages tool call accumulation and execution for the chat() method's automatic tool execution loop.
  *
@@ -111,5 +126,5 @@ interface ExecuteToolCallsResult {
  * @param clientResults - Map of client-side execution results (toolCallId -> result)
  * @param createCustomEventChunk - Factory to create CustomEvent chunks (optional)
  */
-export declare function executeToolCalls(toolCalls: Array<ToolCall>, tools: ReadonlyArray<Tool>, approvals?: Map<string, boolean>, clientResults?: Map<string, any>, createCustomEventChunk?: (eventName: string, value: Record<string, any>) => CustomEvent): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void>;
+export declare function executeToolCalls(toolCalls: Array<ToolCall>, tools: ReadonlyArray<Tool>, approvals?: Map<string, boolean>, clientResults?: Map<string, any>, createCustomEventChunk?: (eventName: string, value: Record<string, any>) => CustomEvent, middlewareHooks?: ToolExecutionMiddlewareHooks): AsyncGenerator<CustomEvent, ExecuteToolCallsResult, void>;
 export {};

package/dist/esm/activities/chat/tools/tool-calls.js

@@ -1,4 +1,17 @@
 import { isStandardSchema, parseWithStandardSchema } from "./schema-converter.js";
+function safeJsonParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+class MiddlewareAbortError extends Error {
+  constructor(reason) {
+    super(reason);
+    this.name = "MiddlewareAbortError";
+  }
+}
 class ToolCallManager {
   constructor(tools) {
     this.toolCallsMap = /* @__PURE__ */ new Map();
@@ -152,7 +165,100 @@ async function* executeWithEventPolling(executionPromise, pendingEvents) {
   }
   return state.result;
 }
-async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ new Map(), clientResults = /* @__PURE__ */ new Map(), createCustomEventChunk) {
+async function applyBeforeToolCallDecision(toolCall, tool, input, toolName, middlewareHooks, results) {
+  if (!middlewareHooks.onBeforeToolCall) {
+    return { proceed: true, input };
+  }
+  const decision = await middlewareHooks.onBeforeToolCall(toolCall, tool, input);
+  if (!decision) {
+    return { proceed: true, input };
+  }
+  if (decision.type === "abort") {
+    throw new MiddlewareAbortError(decision.reason || "Aborted by middleware");
+  }
+  if (decision.type === "skip") {
+    const skipResult = decision.result;
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: typeof skipResult === "string" ? safeJsonParse(skipResult) : skipResult || null,
+      duration: 0
+    });
+    if (middlewareHooks.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: true,
+        duration: 0,
+        result: skipResult
+      });
+    }
+    return { proceed: false };
+  }
+  return { proceed: true, input: decision.args };
+}
+async function* executeServerTool(toolCall, tool, toolName, input, context, pendingEvents, results, middlewareHooks) {
+  const startTime = Date.now();
+  try {
+    const executionPromise = Promise.resolve(tool.execute(input, context));
+    let result = yield* executeWithEventPolling(executionPromise, pendingEvents);
+    const duration = Date.now() - startTime;
+    while (pendingEvents.length > 0) {
+      yield pendingEvents.shift();
+    }
+    if (tool.outputSchema && isStandardSchema(tool.outputSchema) && result !== void 0 && result !== null) {
+      result = parseWithStandardSchema(tool.outputSchema, result);
+    }
+    const finalResult = typeof result === "string" ? safeJsonParse(result) : result || null;
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: finalResult,
+      duration
+    });
+    if (middlewareHooks?.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: true,
+        duration,
+        result: finalResult
+      });
+    }
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    while (pendingEvents.length > 0) {
+      yield pendingEvents.shift();
+    }
+    if (error instanceof MiddlewareAbortError) {
+      throw error;
+    }
+    const message = error instanceof Error ? error.message : "Unknown error";
+    results.push({
+      toolCallId: toolCall.id,
+      toolName,
+      result: { error: message },
+      state: "output-error",
+      duration
+    });
+    if (middlewareHooks?.onAfterToolCall) {
+      await middlewareHooks.onAfterToolCall({
+        toolCall,
+        tool,
+        toolName,
+        toolCallId: toolCall.id,
+        ok: false,
+        duration,
+        error
+      });
+    }
+  }
+}
+async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ new Map(), clientResults = /* @__PURE__ */ new Map(), createCustomEventChunk, middlewareHooks) {
   const results = [];
   const needsApproval = [];
   const needsClientExecution = [];
@@ -220,11 +326,6 @@ async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ n
         }
       }
     };
-    function* flushEvents() {
-      while (pendingEvents.length > 0) {
-        yield pendingEvents.shift();
-      }
-    }
     if (!tool.execute) {
       if (tool.needsApproval) {
         const approvalId = `approval_${toolCall.id}`;
@@ -282,38 +383,28 @@ async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ n
       if (approvals.has(approvalId)) {
         const approved = approvals.get(approvalId);
         if (approved) {
-          const startTime2 = Date.now();
-          try {
-            const executionPromise = Promise.resolve(
-              tool.execute(input, context)
-            );
-            let result = yield* executeWithEventPolling(
-              executionPromise,
-              pendingEvents
-            );
-            const duration = Date.now() - startTime2;
-            yield* flushEvents();
-            if (tool.outputSchema && isStandardSchema(tool.outputSchema) && result !== void 0 && result !== null) {
-              result = parseWithStandardSchema(tool.outputSchema, result);
-            }
-            results.push({
-              toolCallId: toolCall.id,
-              toolName,
-              result: typeof result === "string" ? JSON.parse(result) : result || null,
-              duration
-            });
-          } catch (error) {
-            const duration = Date.now() - startTime2;
-            yield* flushEvents();
-            const message = error instanceof Error ? error.message : "Unknown error";
-            results.push({
-              toolCallId: toolCall.id,
+          if (middlewareHooks) {
+            const decision = await applyBeforeToolCallDecision(
+              toolCall,
+              tool,
+              input,
               toolName,
-              result: { error: message },
-              state: "output-error",
-              duration
-            });
+              middlewareHooks,
+              results
+            );
+            if (!decision.proceed) continue;
+            input = decision.input;
           }
+          yield* executeServerTool(
+            toolCall,
+            tool,
+            toolName,
+            input,
+            context,
+            pendingEvents,
+            results,
+            middlewareHooks
+          );
         } else {
           results.push({
             toolCallId: toolCall.id,
@@ -332,40 +423,33 @@ async function* executeToolCalls(toolCalls, tools, approvals = /* @__PURE__ */ n
       }
       continue;
     }
-    const startTime = Date.now();
-    try {
-      const executionPromise = Promise.resolve(tool.execute(input, context));
-      let result = yield* executeWithEventPolling(
-        executionPromise,
-        pendingEvents
-      );
-      const duration = Date.now() - startTime;
-      yield* flushEvents();
-      if (tool.outputSchema && isStandardSchema(tool.outputSchema) && result !== void 0 && result !== null) {
-        result = parseWithStandardSchema(tool.outputSchema, result);
-      }
-      results.push({
-        toolCallId: toolCall.id,
-        toolName,
-        result: typeof result === "string" ? JSON.parse(result) : result || null,
-        duration
-      });
-    } catch (error) {
-      const duration = Date.now() - startTime;
-      yield* flushEvents();
-      const message = error instanceof Error ? error.message : "Unknown error";
-      results.push({
-        toolCallId: toolCall.id,
+    if (middlewareHooks) {
+      const decision = await applyBeforeToolCallDecision(
+        toolCall,
+        tool,
+        input,
         toolName,
-        result: { error: message },
-        state: "output-error",
-        duration
-      });
+        middlewareHooks,
+        results
+      );
+      if (!decision.proceed) continue;
+      input = decision.input;
     }
+    yield* executeServerTool(
+      toolCall,
+      tool,
+      toolName,
+      input,
+      context,
+      pendingEvents,
+      results,
+      middlewareHooks
+    );
   }
   return { results, needsApproval, needsClientExecution };
 }
 export {
+  MiddlewareAbortError,
   ToolCallManager,
   executeToolCalls
 };