@tanstack/ai 0.35.0 → 0.36.0

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

@@ -1,20 +0,0 @@
-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

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

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

@@ -1 +0,0 @@
-{"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

@@ -1,10 +0,0 @@
-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

@@ -1,89 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,405 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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 {};