@tanstack/ai 0.36.0 → 0.37.0

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

@@ -0,0 +1,20 @@
+import { CapabilityHandle } from './capabilities.js';
+import { ChatMiddleware } from './types.js';
+/**
+ * A middleware whose `requires`/`provides` tuple types are captured precisely
+ * (via `const` inference) for the array coverage check and the builder.
+ */
+export interface DefinedChatMiddleware<TContext, TRequires extends ReadonlyArray<CapabilityHandle>, TProvides extends ReadonlyArray<CapabilityHandle>> extends ChatMiddleware<TContext> {
+    requires?: TRequires;
+    provides?: TProvides;
+}
+/**
+ * Identity helper for authoring middleware with precise capability inference.
+ * Returns the middleware unchanged at runtime; only sharpens its type so the
+ * `chat()` array coverage check and `createChatMiddleware` builder can read the
+ * exact `requires`/`provides`.
+ */
+export declare function defineChatMiddleware<TContext = unknown, const TRequires extends ReadonlyArray<CapabilityHandle> = readonly [], const TProvides extends ReadonlyArray<CapabilityHandle> = readonly []>(middleware: ChatMiddleware<TContext> & {
+    requires?: TRequires;
+    provides?: TProvides;
+}): DefinedChatMiddleware<TContext, TRequires, TProvides>;

package/dist/esm/activities/chat/middleware/define.js

@@ -0,0 +1,7 @@
+function defineChatMiddleware(middleware) {
+  return middleware;
+}
+export {
+  defineChatMiddleware
+};
+//# sourceMappingURL=define.js.map

package/dist/esm/activities/chat/middleware/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sources":["../../../../../src/activities/chat/middleware/define.ts"],"sourcesContent":["import type { CapabilityHandle } from './capabilities'\nimport type { ChatMiddleware } from './types'\n\n/**\n * A middleware whose `requires`/`provides` tuple types are captured precisely\n * (via `const` inference) for the array coverage check and the builder.\n */\nexport interface DefinedChatMiddleware<\n  TContext,\n  TRequires extends ReadonlyArray<CapabilityHandle>,\n  TProvides extends ReadonlyArray<CapabilityHandle>,\n> extends ChatMiddleware<TContext> {\n  requires?: TRequires\n  provides?: TProvides\n}\n\n/**\n * Identity helper for authoring middleware with precise capability inference.\n * Returns the middleware unchanged at runtime; only sharpens its type so the\n * `chat()` array coverage check and `createChatMiddleware` builder can read the\n * exact `requires`/`provides`.\n */\nexport function defineChatMiddleware<\n  TContext = unknown,\n  const TRequires extends ReadonlyArray<CapabilityHandle> = readonly [],\n  const TProvides extends ReadonlyArray<CapabilityHandle> = readonly [],\n>(\n  middleware: ChatMiddleware<TContext> & {\n    requires?: TRequires\n    provides?: TProvides\n  },\n): DefinedChatMiddleware<TContext, TRequires, TProvides> {\n  return middleware\n}\n"],"names":[],"mappings":"AAsBO,SAAS,qBAKd,YAIuD;AACvD,SAAO;AACT;"}

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

@@ -0,0 +1,10 @@
+export type { ChatMiddleware, ChatMiddlewareContext, ChatMiddlewarePhase, ChatMiddlewareConfig, StructuredOutputMiddlewareConfig, ToolCallHookContext, BeforeToolCallDecision, AfterToolCallInfo, IterationInfo, ToolPhaseCompleteInfo, UsageInfo, FinishInfo, AbortInfo, ErrorInfo, } from './types.js';
+export { MiddlewareRunner } from './compose.js';
+export { createCapability, CapabilityRegistry } from './capabilities.js';
+export type { Capability, CapabilityHandle, CapabilityContext, CapabilityGetter, CapabilityProvider, CapabilityGetOptions, } from './capabilities.js';
+export { defineChatMiddleware } from './define.js';
+export type { DefinedChatMiddleware } from './define.js';
+export { createChatMiddleware } from './builder.js';
+export type { ChatMiddlewareBuilder, MissingCapabilities, NamesOf, } from './builder.js';
+export { validateCapabilities } from './validate.js';
+export type { AnyChatMiddleware } from './types.js';

package/dist/esm/activities/chat/middleware/tool-cache-middleware.d.ts

@@ -0,0 +1,89 @@
+import { ChatMiddleware } from './types.js';
+/**
+ * A cache entry stored by the tool cache middleware.
+ */
+export interface ToolCacheEntry {
+    result: unknown;
+    timestamp: number;
+}
+/**
+ * Custom storage backend for the tool cache middleware.
+ *
+ * When provided, the middleware delegates all cache operations to this storage
+ * instead of using the built-in in-memory Map. This enables external storage
+ * backends like Redis, localStorage, databases, etc.
+ *
+ * All methods may return a Promise for async storage backends.
+ */
+export interface ToolCacheStorage {
+    getItem: (key: string) => ToolCacheEntry | undefined | Promise<ToolCacheEntry | undefined>;
+    setItem: (key: string, value: ToolCacheEntry) => void | Promise<void>;
+    deleteItem: (key: string) => void | Promise<void>;
+}
+/**
+ * Options for the tool cache middleware.
+ */
+export interface ToolCacheMiddlewareOptions {
+    /**
+     * Maximum number of entries in the cache.
+     * When exceeded, the oldest entry is evicted (LRU).
+     *
+     * Only applies to the default in-memory storage.
+     * When a custom `storage` is provided, capacity management is the storage's responsibility.
+     *
+     * @default 100
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live in milliseconds. Entries older than this are not served from cache.
+     * @default Infinity (no expiry)
+     */
+    ttl?: number;
+    /**
+     * Tool names to cache. If not provided, all tools are cached.
+     */
+    toolNames?: Array<string>;
+    /**
+     * Custom function to generate a cache key from tool name and args.
+     * Defaults to `JSON.stringify([toolName, args])`.
+     */
+    keyFn?: (toolName: string, args: unknown) => string;
+    /**
+     * Custom storage backend. When provided, the middleware uses this instead of
+     * the built-in in-memory Map. The storage is responsible for its own capacity
+     * management — the `maxSize` option is ignored.
+     *
+     * @example
+     * ```ts
+     * toolCacheMiddleware({
+     *   storage: {
+     *     getItem: (key) => redisClient.get(key).then(v => v ? JSON.parse(v) : undefined),
+     *     setItem: (key, value) => redisClient.set(key, JSON.stringify(value)),
+     *     deleteItem: (key) => redisClient.del(key),
+     *   },
+     * })
+     * ```
+     */
+    storage?: ToolCacheStorage;
+}
+/**
+ * Creates a middleware that caches tool call results based on tool name + arguments.
+ *
+ * When a tool is called with the same name and arguments as a previous call,
+ * the cached result is returned immediately without executing the tool.
+ *
+ * @example
+ * ```ts
+ * import { chat, toolCacheMiddleware } from '@tanstack/ai'
+ *
+ * const stream = chat({
+ *   adapter,
+ *   messages,
+ *   tools: [weatherTool, stockTool],
+ *   middleware: [
+ *     toolCacheMiddleware({ ttl: 60_000, toolNames: ['getWeather'] }),
+ *   ],
+ * })
+ * ```
+ */
+export declare function toolCacheMiddleware(options?: ToolCacheMiddlewareOptions): ChatMiddleware;

package/dist/esm/activities/chat/middleware/tool-cache-middleware.js

@@ -0,0 +1,76 @@
+function defaultKeyFn(toolName, args) {
+  return JSON.stringify([toolName, args]);
+}
+function createDefaultStorage(maxSize) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    getItem: (key) => {
+      const entry = cache.get(key);
+      if (entry !== void 0) {
+        cache.delete(key);
+        cache.set(key, entry);
+      }
+      return entry;
+    },
+    setItem: (key, value) => {
+      if (cache.has(key)) {
+        cache.delete(key);
+      } else if (cache.size >= maxSize) {
+        const firstKey = cache.keys().next().value;
+        if (firstKey !== void 0) {
+          cache.delete(firstKey);
+        }
+      }
+      cache.set(key, value);
+    },
+    deleteItem: (key) => {
+      cache.delete(key);
+    }
+  };
+}
+function toolCacheMiddleware(options = {}) {
+  const {
+    maxSize = 100,
+    ttl = Infinity,
+    toolNames,
+    keyFn = defaultKeyFn,
+    storage = createDefaultStorage(maxSize)
+  } = options;
+  return {
+    name: "tool-cache-middleware",
+    onBeforeToolCall: async (_ctx, hookCtx) => {
+      if (toolNames && !toolNames.includes(hookCtx.toolName)) {
+        return void 0;
+      }
+      const key = keyFn(hookCtx.toolName, hookCtx.args);
+      const entry = await storage.getItem(key);
+      if (entry) {
+        const age = Date.now() - entry.timestamp;
+        if (age < ttl) {
+          return { type: "skip", result: entry.result };
+        }
+        await storage.deleteItem(key);
+      }
+      return void 0;
+    },
+    onAfterToolCall: async (_ctx, info) => {
+      if (!info.ok) return;
+      if (toolNames && !toolNames.includes(info.toolName)) return;
+      let parsedArgs;
+      try {
+        parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || "{}");
+      } catch {
+        return;
+      }
+      const key = keyFn(info.toolName, parsedArgs);
+      await storage.setItem(key, {
+        result: info.result,
+        timestamp: Date.now()
+      });
+    }
+  };
+}
+export {
+  toolCacheMiddleware
+};
+//# sourceMappingURL=tool-cache-middleware.js.map

package/dist/esm/activities/chat/middleware/tool-cache-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-cache-middleware.js","sources":["../../../../../src/activities/chat/middleware/tool-cache-middleware.ts"],"sourcesContent":["import type { ChatMiddleware } from './types'\n\n/**\n * A cache entry stored by the tool cache middleware.\n */\nexport interface ToolCacheEntry {\n  result: unknown\n  timestamp: number\n}\n\n/**\n * Custom storage backend for the tool cache middleware.\n *\n * When provided, the middleware delegates all cache operations to this storage\n * instead of using the built-in in-memory Map. This enables external storage\n * backends like Redis, localStorage, databases, etc.\n *\n * All methods may return a Promise for async storage backends.\n */\nexport interface ToolCacheStorage {\n  getItem: (\n    key: string,\n  ) => ToolCacheEntry | undefined | Promise<ToolCacheEntry | undefined>\n  setItem: (key: string, value: ToolCacheEntry) => void | Promise<void>\n  deleteItem: (key: string) => void | Promise<void>\n}\n\n/**\n * Options for the tool cache middleware.\n */\nexport interface ToolCacheMiddlewareOptions {\n  /**\n   * Maximum number of entries in the cache.\n   * When exceeded, the oldest entry is evicted (LRU).\n   *\n   * Only applies to the default in-memory storage.\n   * When a custom `storage` is provided, capacity management is the storage's responsibility.\n   *\n   * @default 100\n   */\n  maxSize?: number\n\n  /**\n   * Time-to-live in milliseconds. Entries older than this are not served from cache.\n   * @default Infinity (no expiry)\n   */\n  ttl?: number\n\n  /**\n   * Tool names to cache. If not provided, all tools are cached.\n   */\n  toolNames?: Array<string>\n\n  /**\n   * Custom function to generate a cache key from tool name and args.\n   * Defaults to `JSON.stringify([toolName, args])`.\n   */\n  keyFn?: (toolName: string, args: unknown) => string\n\n  /**\n   * Custom storage backend. When provided, the middleware uses this instead of\n   * the built-in in-memory Map. The storage is responsible for its own capacity\n   * management — the `maxSize` option is ignored.\n   *\n   * @example\n   * ```ts\n   * toolCacheMiddleware({\n   *   storage: {\n   *     getItem: (key) => redisClient.get(key).then(v => v ? JSON.parse(v) : undefined),\n   *     setItem: (key, value) => redisClient.set(key, JSON.stringify(value)),\n   *     deleteItem: (key) => redisClient.del(key),\n   *   },\n   * })\n   * ```\n   */\n  storage?: ToolCacheStorage\n}\n\nfunction defaultKeyFn(toolName: string, args: unknown): string {\n  return JSON.stringify([toolName, args])\n}\n\nfunction createDefaultStorage(maxSize: number): ToolCacheStorage {\n  const cache = new Map<string, ToolCacheEntry>()\n\n  return {\n    getItem: (key) => {\n      const entry = cache.get(key)\n      if (entry !== undefined) {\n        // Refresh recency: delete and re-insert so this key becomes newest\n        cache.delete(key)\n        cache.set(key, entry)\n      }\n      return entry\n    },\n    setItem: (key, value) => {\n      // Delete first so re-inserts also refresh recency\n      if (cache.has(key)) {\n        cache.delete(key)\n      } else if (cache.size >= maxSize) {\n        // LRU eviction: Map iteration order is insertion order — first key is least recently used\n        const firstKey = cache.keys().next().value\n        if (firstKey !== undefined) {\n          cache.delete(firstKey)\n        }\n      }\n      cache.set(key, value)\n    },\n    deleteItem: (key) => {\n      cache.delete(key)\n    },\n  }\n}\n\n/**\n * Creates a middleware that caches tool call results based on tool name + arguments.\n *\n * When a tool is called with the same name and arguments as a previous call,\n * the cached result is returned immediately without executing the tool.\n *\n * @example\n * ```ts\n * import { chat, toolCacheMiddleware } from '@tanstack/ai'\n *\n * const stream = chat({\n *   adapter,\n *   messages,\n *   tools: [weatherTool, stockTool],\n *   middleware: [\n *     toolCacheMiddleware({ ttl: 60_000, toolNames: ['getWeather'] }),\n *   ],\n * })\n * ```\n */\nexport function toolCacheMiddleware(\n  options: ToolCacheMiddlewareOptions = {},\n): ChatMiddleware {\n  const {\n    maxSize = 100,\n    ttl = Infinity,\n    toolNames,\n    keyFn = defaultKeyFn,\n    storage = createDefaultStorage(maxSize),\n  } = options\n\n  return {\n    name: 'tool-cache-middleware',\n\n    onBeforeToolCall: async (_ctx, hookCtx) => {\n      if (toolNames && !toolNames.includes(hookCtx.toolName)) {\n        return undefined\n      }\n\n      const key = keyFn(hookCtx.toolName, hookCtx.args)\n      const entry = await storage.getItem(key)\n\n      if (entry) {\n        const age = Date.now() - entry.timestamp\n        if (age < ttl) {\n          return { type: 'skip', result: entry.result }\n        }\n        // Expired — remove\n        await storage.deleteItem(key)\n      }\n\n      return undefined\n    },\n\n    onAfterToolCall: async (_ctx, info) => {\n      if (!info.ok) return\n      if (toolNames && !toolNames.includes(info.toolName)) return\n\n      // Re-derive the key from the raw arguments to match what onBeforeToolCall produces\n      let parsedArgs: unknown\n      try {\n        parsedArgs = JSON.parse(info.toolCall.function.arguments.trim() || '{}')\n      } catch {\n        return\n      }\n\n      const key = keyFn(info.toolName, parsedArgs)\n\n      await storage.setItem(key, {\n        result: info.result,\n        timestamp: Date.now(),\n      })\n    },\n  }\n}\n"],"names":[],"mappings":"AA8EA,SAAS,aAAa,UAAkB,MAAuB;AAC7D,SAAO,KAAK,UAAU,CAAC,UAAU,IAAI,CAAC;AACxC;AAEA,SAAS,qBAAqB,SAAmC;AAC/D,QAAM,4BAAY,IAAA;AAElB,SAAO;AAAA,IACL,SAAS,CAAC,QAAQ;AAChB,YAAM,QAAQ,MAAM,IAAI,GAAG;AAC3B,UAAI,UAAU,QAAW;AAEvB,cAAM,OAAO,GAAG;AAChB,cAAM,IAAI,KAAK,KAAK;AAAA,MACtB;AACA,aAAO;AAAA,IACT;AAAA,IACA,SAAS,CAAC,KAAK,UAAU;AAEvB,UAAI,MAAM,IAAI,GAAG,GAAG;AAClB,cAAM,OAAO,GAAG;AAAA,MAClB,WAAW,MAAM,QAAQ,SAAS;AAEhC,cAAM,WAAW,MAAM,KAAA,EAAO,OAAO;AACrC,YAAI,aAAa,QAAW;AAC1B,gBAAM,OAAO,QAAQ;AAAA,QACvB;AAAA,MACF;AACA,YAAM,IAAI,KAAK,KAAK;AAAA,IACtB;AAAA,IACA,YAAY,CAAC,QAAQ;AACnB,YAAM,OAAO,GAAG;AAAA,IAClB;AAAA,EAAA;AAEJ;AAsBO,SAAS,oBACd,UAAsC,IACtB;AAChB,QAAM;AAAA,IACJ,UAAU;AAAA,IACV,MAAM;AAAA,IACN;AAAA,IACA,QAAQ;AAAA,IACR,UAAU,qBAAqB,OAAO;AAAA,EAAA,IACpC;AAEJ,SAAO;AAAA,IACL,MAAM;AAAA,IAEN,kBAAkB,OAAO,MAAM,YAAY;AACzC,UAAI,aAAa,CAAC,UAAU,SAAS,QAAQ,QAAQ,GAAG;AACtD,eAAO;AAAA,MACT;AAEA,YAAM,MAAM,MAAM,QAAQ,UAAU,QAAQ,IAAI;AAChD,YAAM,QAAQ,MAAM,QAAQ,QAAQ,GAAG;AAEvC,UAAI,OAAO;AACT,cAAM,MAAM,KAAK,IAAA,IAAQ,MAAM;AAC/B,YAAI,MAAM,KAAK;AACb,iBAAO,EAAE,MAAM,QAAQ,QAAQ,MAAM,OAAA;AAAA,QACvC;AAEA,cAAM,QAAQ,WAAW,GAAG;AAAA,MAC9B;AAEA,aAAO;AAAA,IACT;AAAA,IAEA,iBAAiB,OAAO,MAAM,SAAS;AACrC,UAAI,CAAC,KAAK,GAAI;AACd,UAAI,aAAa,CAAC,UAAU,SAAS,KAAK,QAAQ,EAAG;AAGrD,UAAI;AACJ,UAAI;AACF,qBAAa,KAAK,MAAM,KAAK,SAAS,SAAS,UAAU,KAAA,KAAU,IAAI;AAAA,MACzE,QAAQ;AACN;AAAA,MACF;AAEA,YAAM,MAAM,MAAM,KAAK,UAAU,UAAU;AAE3C,YAAM,QAAQ,QAAQ,KAAK;AAAA,QACzB,QAAQ,KAAK;AAAA,QACb,WAAW,KAAK,IAAA;AAAA,MAAI,CACrB;AAAA,IACH;AAAA,EAAA;AAEJ;"}

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

@@ -0,0 +1,405 @@
+import { JSONSchema, ModelMessage, StreamChunk, TokenUsage, Tool, ToolCall } from '../../../types.js';
+import { SystemPrompt } from '../../../system-prompts.js';
+import { Capability, CapabilityHandle, CapabilityRegistry } from './capabilities.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
+ * - 'structuredOutput': During the final structured-output adapter call (set
+ *   for chunks from adapter.structuredOutputStream or the synthesized fallback)
+ */
+export type ChatMiddlewarePhase = 'init' | 'beforeModel' | 'modelStream' | 'beforeTools' | 'afterTools' | 'structuredOutput';
+/**
+ * Stable context object passed to all middleware hooks.
+ * Created once per chat() invocation and shared across all hooks.
+ */
+export interface ChatMiddlewareContext<TContext = unknown> {
+    /** Unique identifier for this chat request */
+    requestId: string;
+    /** Unique identifier for this stream */
+    streamId: string;
+    /** AG-UI run identifier for correlating client and server events */
+    runId: string;
+    /**
+     * AG-UI thread identifier — a stable per-conversation ID used to
+     * correlate client and server devtools events. Resolves to the
+     * caller-provided `threadId` (or legacy `conversationId`), or an
+     * auto-generated value when neither is supplied.
+     */
+    threadId: string;
+    /**
+     * @deprecated Use `threadId` instead. Retained as an alias of
+     * `threadId` so middleware written before the AG-UI rename keeps
+     * working unchanged. Will be removed in a future major release.
+     */
+    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;
+    /** Runtime context provided by chat() options */
+    context: TContext;
+    /**
+     * 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;
+    /**
+     * Which activity this context describes — always `'chat'`. Present so the
+     * chat context structurally satisfies the base `GenerationMiddlewareContext`,
+     * letting an observe-only middleware authored against the base (e.g.
+     * `otelMiddleware`) run on both chat and media activities.
+     */
+    activity: 'chat';
+    /** 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<SystemPrompt>;
+    /** Names of configured tools, if any */
+    toolNames?: Array<string>;
+    /** Flattened generation options (metadata) */
+    options?: Record<string, unknown> | undefined;
+    /** Provider-specific model options */
+    modelOptions?: Record<string, unknown> | undefined;
+    /** 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;
+    /**
+     * Capability bookkeeping for this request. Populated by middleware `setup`
+     * hooks (via `provide` accessors) and read by later middleware (via `get`
+     * accessors). Prefer the accessors returned by `createCapability` over using
+     * this directly. Orthogonal to `context` (the user runtime context).
+     */
+    capabilities: CapabilityRegistry;
+    /**
+     * Read a provided capability by its handle. Equivalent to the handle's own
+     * `get` accessor (`getX(ctx)`); throws if the capability was never provided.
+     */
+    get: <TValue>(capability: Capability<TValue>) => TValue;
+    /**
+     * Read a capability by its handle, returning `undefined` if it was never
+     * provided (never throws).
+     */
+    getOptional: <TValue>(capability: Capability<TValue>) => TValue | undefined;
+    /**
+     * Provide a capability value. Equivalent to the handle's own `provide`
+     * accessor (`provideX(ctx, value)`). Typically called from `setup`.
+     */
+    provide: <TValue>(capability: Capability<TValue>, value: TValue) => void;
+}
+/**
+ * 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<SystemPrompt>;
+    tools: Array<Tool>;
+    metadata?: Record<string, unknown> | undefined;
+    modelOptions?: Record<string, unknown> | undefined;
+}
+/**
+ * Config passed to onStructuredOutputConfig.
+ *
+ * Mirrors ChatMiddlewareConfig minus `tools` (the final structured-output call
+ * is a single typed-response request, not an agentic loop — tools cannot be
+ * forwarded to it), plus the `outputSchema` being sent to the provider.
+ * Middleware may transform the schema (e.g., inject $defs, strip
+ * vendor-incompatible keywords) by returning a partial that includes
+ * `outputSchema`.
+ */
+export interface StructuredOutputMiddlewareConfig extends Omit<ChatMiddlewareConfig, 'tools'> {
+    /** JSON Schema being sent to the provider for structured output. */
+    outputSchema: JSONSchema;
+}
+/**
+ * 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.
+ *
+ * Includes optional provider-reported `cost`/`costDetails` (see {@link TokenUsage}).
+ * Kept as an interface extending `TokenUsage` to preserve declaration merging for
+ * this publicly exported type.
+ */
+export interface UsageInfo extends TokenUsage {
+}
+/**
+ * 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 (optionally including provider-reported cost) */
+    usage?: TokenUsage | undefined;
+}
+/**
+ * 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<TContext = unknown> {
+    /** Optional name for debugging and identification */
+    name?: string;
+    /**
+     * Capabilities this middleware requires. `chat()` validates that some
+     * middleware (or the adapter) provides each one; unsatisfied requirements are
+     * a compile-time error (array coverage / builder) and a runtime error before
+     * the adapter runs.
+     */
+    requires?: ReadonlyArray<CapabilityHandle>;
+    /**
+     * Capabilities this middleware provides. Each declared capability MUST be
+     * provided (via its `provide` accessor) inside `setup`, or `chat()` throws
+     * after the setup phase.
+     */
+    provides?: ReadonlyArray<CapabilityHandle>;
+    /**
+     * Capabilities this middleware uses if present but does not require.
+     * Non-gating: never causes a validation error. Read with
+     * `getX(ctx, { optional: true })`.
+     */
+    optionalRequires?: ReadonlyArray<CapabilityHandle>;
+    /**
+     * Provisioning hook. Runs FIRST — before `onConfig` (init) — across all
+     * middleware in array order. Use it to call `provide` accessors so later
+     * middleware (`onConfig` onward) can consume the capabilities. Receives the
+     * stable context; does NOT receive the mutable config.
+     */
+    setup?: (ctx: ChatMiddlewareContext<TContext>) => void | Promise<void>;
+    /**
+     * 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<TContext>, config: ChatMiddlewareConfig) => void | null | Partial<ChatMiddlewareConfig> | Promise<void | null | Partial<ChatMiddlewareConfig>>;
+    /**
+     * Called at the start of the final structured-output call (when the chat
+     * was invoked with outputSchema). Pipes through middleware in order, like
+     * onConfig, but with access to the JSON Schema being sent to the provider.
+     *
+     * Return a partial to shallow-merge into the current config, or void to
+     * pass through.
+     *
+     * Fires BEFORE onConfig at the structured-output boundary. onConfig also
+     * re-fires at the same boundary with ctx.phase === 'structuredOutput',
+     * receiving the post-onStructuredOutputConfig view of the config (minus
+     * outputSchema). Use onConfig for general-purpose transforms that apply
+     * to every adapter call; use this hook when you need to transform the
+     * outputSchema or apply structured-output-specific behavior.
+     */
+    onStructuredOutputConfig?: (ctx: ChatMiddlewareContext<TContext>, config: StructuredOutputMiddlewareConfig) => void | null | Partial<StructuredOutputMiddlewareConfig> | Promise<void | null | Partial<StructuredOutputMiddlewareConfig>>;
+    /**
+     * Called when the chat run starts (after initial onConfig).
+     */
+    onStart?: (ctx: ChatMiddlewareContext<TContext>) => 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<TContext>, 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<TContext>, 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<TContext>, hookCtx: ToolCallHookContext) => BeforeToolCallDecision | Promise<BeforeToolCallDecision>;
+    /**
+     * Called after a tool execution completes (success or failure).
+     */
+    onAfterToolCall?: (ctx: ChatMiddlewareContext<TContext>, 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<TContext>, 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<TContext>, 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<TContext>, 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<TContext>, 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<TContext>, info: ErrorInfo) => void | Promise<void>;
+}
+/** A `ChatMiddleware` with a permissive context — for use as a constraint. */
+export type AnyChatMiddleware = ChatMiddleware<any>;

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

@@ -0,0 +1,19 @@
+import { CapabilityHandle } from './capabilities.js';
+import { AnyChatMiddleware } from './types.js';
+/** Minimal adapter shape needed for capability validation. */
+interface CapabilityRequiringAdapter {
+    name: string;
+    requires?: ReadonlyArray<CapabilityHandle>;
+}
+/**
+ * Runtime validation: every required capability (from middleware `requires` and
+ * the adapter's `requires`) must be provided by some middleware's `provides`.
+ * `optionalRequires` is never gating. Throws a clear error otherwise.
+ *
+ * Presence only — ORDER is not validated here (a provider may appear after its
+ * consumer in the array and still pass). Use the `createChatMiddleware()`
+ * builder for compile-time order enforcement; at runtime, a consumer that reads
+ * a not-yet-provided capability during `setup` fails loud via its getter.
+ */
+export declare function validateCapabilities(middlewares: ReadonlyArray<AnyChatMiddleware>, adapter: CapabilityRequiringAdapter): void;
+export {};