@meetsmore-oss/use-ai-server 1.2.2 → 1.2.4

package/dist/agents/AISDKAgent.d.ts

@@ -1,6 +1,7 @@
 import { LanguageModel } from 'ai';
 import type { Agent, AgentInput, EventEmitter, AgentResult } from './types';
 import type { ToolDefinition } from '../types';
+import { type CacheBreakpointFn } from './anthropicCache';
 /**
  * Configuration for AISDKAgent.
  */
@@ -99,6 +100,53 @@ export interface AISDKAgentConfig {
      * ```
      */
     toolFilter?: (tool: ToolDefinition) => boolean;
+    /**
+     * Anthropic-specific: Configure cache breakpoints for prompt caching.
+     * Only applies when using Anthropic models (Claude).
+     *
+     * Prompt caching reduces costs and latency by caching message prefixes.
+     * Cache breakpoints mark where the cacheable prefix ends.
+     *
+     * The function receives each message with positional context and returns
+     * true to add a cache breakpoint after that message.
+     *
+     * System prompt is included as role: 'system' at index 0 when present.
+     *
+     * @see https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+     *
+     * @example
+     * ```typescript
+     * // Cache system prompt + last message (most common pattern)
+     * {
+     *   cacheBreakpoint: (msg) => msg.role === 'system' || msg.isLast
+     * }
+     *
+     * // Cache only the last message
+     * {
+     *   cacheBreakpoint: (msg) => msg.isLast
+     * }
+     *
+     * // Cache system prompt only
+     * {
+     *   cacheBreakpoint: (msg) => msg.role === 'system'
+     * }
+     *
+     * // Cache first 3 messages + last
+     * {
+     *   cacheBreakpoint: (msg) => msg.index < 3 || msg.isLast
+     * }
+     *
+     * // System prompt with 1h TTL, last message with 5m TTL
+     * {
+     *   cacheBreakpoint: (msg) => {
+     *     if (msg.role === 'system') return '1h';
+     *     if (msg.isLast) return '5m';
+     *     return false;
+     *   }
+     * }
+     * ```
+     */
+    cacheBreakpoint?: CacheBreakpointFn;
 }
 /**
  * Agent implementation for AI SDK models (Anthropic, OpenAI, Google, etc.).
@@ -151,6 +199,7 @@ export declare class AISDKAgent implements Agent {
     private langfuse;
     private toolFilter?;
     private systemPrompt?;
+    private cacheBreakpoint?;
     constructor(config: AISDKAgentConfig);
     getName(): string;
     getAnnotation(): string | undefined;

package/dist/agents/AISDKAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AISDKAgent.d.ts","sourceRoot":"","sources":["../../../src/agents/AISDKAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,aAAa,EAA2D,MAAM,IAAI,CAAC;AAIpH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAiB,MAAM,SAAS,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AA8C/C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,UAAW,YAAW,KAAK;IACtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,UAAU,CAAC,CAAoC;IACvD,OAAO,CAAC,YAAY,CAAC,CAA4C;gBAErD,MAAM,EAAE,gBAAgB;IAUpC,OAAO,IAAI,MAAM;IAIjB,aAAa,IAAI,MAAM,GAAG,SAAS;IAInC;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAqXxE;;;;;OAKG;YACW,mBAAmB;IAcjC;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAsBnB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,mBAAmB;IA2B3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAMpC;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAKlC;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAG9B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAG/B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAI9B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAMtC;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAM1B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAqC;IAEhF;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;CAgBzB"}
+{"version":3,"file":"AISDKAgent.d.ts","sourceRoot":"","sources":["../../../src/agents/AISDKAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,aAAa,EAA2D,MAAM,IAAI,CAAC;AAIpH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAiB,MAAM,SAAS,CAAC;AAC3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAqB/C,OAAO,EAAyB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AA0BjF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,UAAW,YAAW,KAAK;IACtC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,UAAU,CAAC,CAAS;IAC5B,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,UAAU,CAAC,CAAoC;IACvD,OAAO,CAAC,YAAY,CAAC,CAA4C;IACjE,OAAO,CAAC,eAAe,CAAC,CAAoB;gBAEhC,MAAM,EAAE,gBAAgB;IAWpC,OAAO,IAAI,MAAM;IAIjB,aAAa,IAAI,MAAM,GAAG,SAAS;IAInC;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IA6XxE;;;;;OAKG;YACW,mBAAmB;IAcjC;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;IACH,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,WAAW;IAsBnB;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,mBAAmB;IA2B3B;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAMpC;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAKlC;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAG9B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAG/B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAI9B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAMtC;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAM1B;IAEX,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAqC;IAEhF;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;CAgBzB"}

package/dist/agents/anthropicCache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Anthropic prompt caching utilities for AI SDK Agent.
+ *
+ * This module handles cache breakpoint configuration for Anthropic models (Claude).
+ * Prompt caching reduces costs and latency by caching message prefixes.
+ *
+ * @see https://platform.claude.com/docs/en/build-with-claude/prompt-caching
+ */
+import type { LanguageModel, ModelMessage } from 'ai';
+/**
+ * ModelMessage extended with positional context for cache breakpoint decisions.
+ * Used by the cacheBreakpoint config to determine which messages should have
+ * Anthropic's cache_control breakpoints applied.
+ *
+ * System prompt is included as role: 'system' at index 0 when present.
+ */
+export type MessageWithCacheContext = ModelMessage & {
+    /** Position in the messages array (0-indexed, system prompt is 0 if present) */
+    index: number;
+    /** Total number of messages including system prompt */
+    totalCount: number;
+    /** True if this is the first message */
+    isFirst: boolean;
+    /** True if this is the last message */
+    isLast: boolean;
+};
+/**
+ * Cache TTL options for Anthropic prompt caching.
+ * - '5m': 5-minute cache (default, refreshed on each use at no cost)
+ * - '1h': 1-hour cache (additional cost, useful for infrequent access patterns)
+ *
+ * @see https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration
+ */
+export type CacheTtl = '5m' | '1h';
+/**
+ * Return type for cacheBreakpoint function.
+ * - `false` / `null` / `undefined`: No cache breakpoint
+ * - `true`: Cache breakpoint with default TTL (5m)
+ * - `'5m'` / `'1h'`: Cache breakpoint with specified TTL
+ */
+export type CacheBreakpointResult = boolean | CacheTtl | null | undefined;
+/**
+ * Function type for determining cache breakpoints.
+ */
+export type CacheBreakpointFn = (message: MessageWithCacheContext) => CacheBreakpointResult;
+/**
+ * Checks if the given model is an Anthropic model (Claude).
+ */
+export declare function isAnthropicModel(model: LanguageModel): boolean;
+/**
+ * Applies cache breakpoints to messages for Anthropic prompt caching.
+ * Only applies when:
+ * 1. cacheBreakpoint config is provided
+ * 2. Model is an Anthropic model
+ *
+ * Adds providerOptions.anthropic.cacheControl to messages where
+ * the cacheBreakpoint function returns true.
+ *
+ * @param messages - The messages array (system prompt should be prepended as role: 'system')
+ * @param cacheBreakpoint - Function to determine which messages should have cache breakpoints
+ * @param model - The AI SDK LanguageModel to check if it's Anthropic
+ * @returns Messages with cache control providerOptions added where applicable
+ */
+export declare function applyCacheBreakpoints(messages: ModelMessage[], cacheBreakpoint: CacheBreakpointFn | undefined, model: LanguageModel): ModelMessage[];
+//# sourceMappingURL=anthropicCache.d.ts.map

package/dist/agents/anthropicCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropicCache.d.ts","sourceRoot":"","sources":["../../../src/agents/anthropicCache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAGtD;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAAG,YAAY,GAAG;IACnD,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,uBAAuB,KAAK,qBAAqB,CAAC;AAE5F;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAQ9D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,eAAe,EAAE,iBAAiB,GAAG,SAAS,EAC9C,KAAK,EAAE,aAAa,GACnB,YAAY,EAAE,CAyDhB"}

package/dist/agents/index.d.ts

@@ -4,4 +4,5 @@
  */
 export type { Agent, AgentInput, EventEmitter, AgentResult, ClientSession } from './types';
 export { AISDKAgent, type AISDKAgentConfig } from './AISDKAgent';
+export { applyCacheBreakpoints, isAnthropicModel, type MessageWithCacheContext, type CacheTtl, type CacheBreakpointResult, type CacheBreakpointFn, } from './anthropicCache';
 //# sourceMappingURL=index.d.ts.map

package/dist/agents/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,QAAQ,EACb,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/agents/plugins/__tests__/runner.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runner.test.d.ts.map

package/dist/agents/plugins/__tests__/runner.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.test.d.ts","sourceRoot":"","sources":["../../../../../src/agents/plugins/__tests__/runner.test.ts"],"names":[],"mappings":""}

package/dist/agents/plugins/citations/citationPlugin.d.ts

@@ -0,0 +1,72 @@
+import type { AgentPlugin } from '../types';
+/**
+ * Citation source that can be included in tool results.
+ * Tools (like RAG) can return citations in their results using this format.
+ *
+ * @example
+ * ```typescript
+ * // In your RAG tool implementation:
+ * return {
+ *   answer: "Based on the documentation...",
+ *   _citations: [
+ *     { url: "https://docs.example.com/api", title: "API Reference" },
+ *     { url: "https://docs.example.com/guide", title: "Getting Started Guide" },
+ *   ]
+ * };
+ * ```
+ */
+export interface ToolCitationSource {
+    /** URL of the source document */
+    url: string;
+    /** Title of the source (optional) */
+    title?: string;
+    /** Additional metadata (optional) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Available citation types.
+ *
+ * - `anthropic`: Extracts from Anthropic web search source chunks (streaming) and result.sources
+ * - `openai`: Extracts from OpenAI url_citation annotations in response messages
+ * - `rag`: Extracts from tool results with `_citations`, `citations`, or `sources` fields
+ */
+export type CitationType = 'rag';
+/**
+ * Plugin that handles citation collection and emission.
+ *
+ * Supports multiple citation sources:
+ * - **rag**: Citations in tool results via `_citations`, `citations`, or `sources` fields
+ * - **anthropic**: Source chunks during streaming + result.sources (for future use)
+ * - **openai**: url_citation annotations in response (for future use)
+ *
+ * @param enabledTypes - Which extractors to enable. If not provided, all extractors are enabled.
+ *                       Extractors run in the order specified.
+ *
+ * @example
+ * ```typescript
+ * // With custom RAG tool - return citations in the tool result
+ * import { AISDKAgent, citationPlugin } from '@meetsmore-oss/use-ai-server';
+ *
+ * const ragTool = defineTool(
+ *   'Search internal documentation',
+ *   z.object({ query: z.string() }),
+ *   async ({ query }) => {
+ *     const results = await vectorDb.search(query);
+ *     return {
+ *       answer: results.map(r => r.content).join('\n'),
+ *       _citations: results.map(r => ({
+ *         url: r.sourceUrl,
+ *         title: r.title,
+ *       })),
+ *     };
+ *   }
+ * );
+ *
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-sonnet-4-20250514'),
+ *   plugins: [citationPlugin(['rag'])],
+ * });
+ * ```
+ */
+export declare function citationPlugin(enabledTypes?: CitationType[]): AgentPlugin;
+//# sourceMappingURL=citationPlugin.d.ts.map

package/dist/agents/plugins/citations/citationPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citationPlugin.d.ts","sourceRoot":"","sources":["../../../../../src/agents/plugins/citations/citationPlugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAgF,MAAM,UAAU,CAAC;AAI1H;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC;AAoPjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,cAAc,CAAC,YAAY,CAAC,EAAE,YAAY,EAAE,GAAG,WAAW,CA4CzE"}

package/dist/agents/plugins/citations/citationPlugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=citationPlugin.test.d.ts.map

package/dist/agents/plugins/citations/citationPlugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citationPlugin.test.d.ts","sourceRoot":"","sources":["../../../../../src/agents/plugins/citations/citationPlugin.test.ts"],"names":[],"mappings":""}

package/dist/agents/plugins/citations/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Citation plugin for AISDKAgent.
+ * Collects sources from AI responses and emits citation events.
+ */
+export { citationPlugin } from './citationPlugin';
+export type { ToolCitationSource, CitationType } from './citationPlugin';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/plugins/citations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/agents/plugins/citations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/agents/plugins/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Agent plugin system for extending AISDKAgent functionality.
+ *
+ * Plugins can hook into the agent lifecycle to:
+ * - Modify inputs before sending to AI
+ * - Transform streaming chunks
+ * - Intercept or modify tool calls
+ * - Process and transform responses
+ * - Handle errors
+ *
+ * @example
+ * ```typescript
+ * import { AISDKAgent } from '@meetsmore-oss/use-ai-server';
+ * import type { AgentPlugin } from '@meetsmore-oss/use-ai-server';
+ *
+ * const loggingPlugin: AgentPlugin = {
+ *   id: 'logging',
+ *   onUserMessage(input, ctx) {
+ *     ctx.logger.info('Message received');
+ *     return input;
+ *   },
+ * };
+ *
+ * const agent = new AISDKAgent({
+ *   model: anthropic('claude-3-5-sonnet-20241022'),
+ *   plugins: [loggingPlugin],
+ * });
+ * ```
+ */
+export type { AgentPlugin, AgentPluginContext, AgentRunInput, AgentRunResult, ToolCallInfo, ToolResultInfo, StreamChunk, TextDeltaChunk, ReasoningDeltaChunk, SourceChunk, ToolInputStartChunk, ToolInputDeltaChunk, ToolCallChunk, ToolResultChunk, StartStepChunk, FinishStepChunk, ErrorChunk, UnknownChunk, } from './types';
+export { AgentPluginRunner } from './runner';
+export { citationPlugin } from './citations';
+export type { ToolCitationSource, CitationType } from './citations';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/plugins/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/agents/plugins/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EAEd,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,cAAc,EACd,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/agents/plugins/runner.d.ts

@@ -0,0 +1,76 @@
+import type { AgentPlugin, AgentPluginContext, AgentRunInput, AgentRunResult, ToolCallInfo, ToolResultInfo, StreamChunk } from './types';
+/**
+ * Orchestrates plugin execution for AISDKAgent.
+ *
+ * Plugins are executed in the order they were registered.
+ * Each hook is called sequentially, with the output of one plugin
+ * becoming the input of the next.
+ *
+ * @example
+ * ```typescript
+ * const runner = new AgentPluginRunner([
+ *   loggingPlugin,
+ *   metricsPlugin,
+ * ]);
+ *
+ * // Initialize plugins
+ * await runner.initialize({ provider: 'anthropic' });
+ *
+ * // Use in agent run
+ * const processedInput = await runner.onUserMessage(input, context);
+ * ```
+ */
+export declare class AgentPluginRunner {
+    private plugins;
+    constructor(plugins?: AgentPlugin[]);
+    /**
+     * Initialize all plugins.
+     * Called once when the agent is created.
+     */
+    initialize(context: {
+        provider: string;
+    }): Promise<void>;
+    /**
+     * Run onUserMessage hook for all plugins.
+     * Each plugin receives the output of the previous plugin.
+     */
+    onUserMessage(input: AgentRunInput, context: AgentPluginContext): Promise<AgentRunInput>;
+    /**
+     * Run onAgentResponse hook for all plugins.
+     * Each plugin receives the output of the previous plugin.
+     */
+    onAgentResponse(result: AgentRunResult, context: AgentPluginContext): Promise<AgentRunResult>;
+    /**
+     * Run onTextChunk hook for all plugins.
+     * Returns the transformed chunk (or original if no transform).
+     */
+    onTextChunk(chunk: string, context: AgentPluginContext): Promise<string>;
+    /**
+     * Run onBeforeToolCall hook for all plugins.
+     * Returns null if any plugin returns null (tool call should be skipped).
+     */
+    onBeforeToolCall(toolCall: ToolCallInfo, context: AgentPluginContext): Promise<ToolCallInfo | null>;
+    /**
+     * Run onAfterToolCall hook for all plugins.
+     * Returns the final transformed result.
+     */
+    onAfterToolCall(toolResult: ToolResultInfo, context: AgentPluginContext): Promise<unknown>;
+    /**
+     * Run onChunk hook for all plugins.
+     * Called for each chunk from the AI SDK stream.
+     */
+    onChunk(chunk: StreamChunk, context: AgentPluginContext): Promise<void>;
+    /**
+     * Destroy all plugins and release resources.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Check if any plugins are registered.
+     */
+    hasPlugins(): boolean;
+    /**
+     * Get the number of registered plugins.
+     */
+    get pluginCount(): number;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/agents/plugins/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../../src/agents/plugins/runner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,YAAY,EACZ,cAAc,EACd,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAAqB;gBAExB,OAAO,GAAE,WAAW,EAAO;IAIvC;;;OAGG;IACG,UAAU,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9D;;;OAGG;IACG,aAAa,CACjB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,aAAa,CAAC;IAUzB;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC;IAU1B;;;OAGG;IACG,WAAW,CACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC;IAalB;;;OAGG;IACG,gBAAgB,CACpB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAW/B;;;OAGG;IACG,eAAe,CACnB,UAAU,EAAE,cAAc,EAC1B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,OAAO,CAAC;IAUnB;;;OAGG;IACG,OAAO,CACX,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAQhB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B;;OAEG;IACH,UAAU,IAAI,OAAO;IAIrB;;OAEG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;CACF"}

package/dist/agents/plugins/types.d.ts

@@ -0,0 +1,280 @@
+import type { ModelMessage, SystemModelMessage } from 'ai';
+import type { EventEmitter, ClientSession } from '../types';
+import type { ToolDefinition } from '../../types';
+import type { Logger } from '../../logger';
+/**
+ * Context available to plugins during a run.
+ * Contains session info, event emitter, and shared state.
+ */
+export interface AgentPluginContext {
+    /** Unique identifier for this run */
+    runId: string;
+    /** Client identifier from the session */
+    clientId: string;
+    /** Thread identifier for the conversation */
+    threadId?: string;
+    /** AI provider name (e.g., 'openai', 'anthropic') */
+    provider: string;
+    /** Event emitter for sending AG-UI events */
+    events: EventEmitter;
+    /** Shared state between plugins within a single run */
+    state: Map<string, unknown>;
+    /** Logger instance */
+    logger: Logger;
+    /** The client session */
+    session: ClientSession;
+}
+/**
+ * Input data passed to onUserMessage hook.
+ * Plugins can modify these values before they're sent to the AI SDK.
+ */
+export interface AgentRunInput {
+    /** Conversation messages in AI SDK format */
+    messages: ModelMessage[];
+    /** System messages (if any). Passed directly to AI SDK. */
+    systemMessages?: SystemModelMessage[];
+    /** Available tools for this run */
+    tools: ToolDefinition[];
+}
+/**
+ * Result data passed to onAgentResponse hook.
+ * Plugins can process or transform the response.
+ */
+export interface AgentRunResult {
+    /** The generated text response */
+    text: string;
+    /** Sources/citations from the AI response */
+    sources?: unknown[];
+    /** Raw response object from AI SDK */
+    response?: {
+        messages: unknown[];
+    };
+    /** Provider-specific metadata */
+    providerMetadata?: Record<string, unknown>;
+    /** Tool calls made during the run */
+    toolCalls?: unknown[];
+    /** Results from tool executions */
+    toolResults?: unknown[];
+    /** Token usage information */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+/**
+ * Information about a tool call (before execution).
+ */
+export interface ToolCallInfo {
+    /** Unique identifier for this tool call */
+    id: string;
+    /** Name of the tool being called */
+    name: string;
+    /** Arguments passed to the tool */
+    args: unknown;
+}
+/**
+ * Information about a tool result (after execution).
+ */
+export interface ToolResultInfo extends ToolCallInfo {
+    /** Result returned from the tool */
+    result: unknown;
+    /** Error if the tool execution failed */
+    error?: Error;
+}
+/**
+ * Known AI SDK stream chunk types.
+ * These are the chunk types commonly emitted by the AI SDK fullStream.
+ */
+/** Text content being streamed */
+export interface TextDeltaChunk {
+    type: 'text-delta';
+    text: string;
+}
+/** Extended thinking/reasoning content (Claude) */
+export interface ReasoningDeltaChunk {
+    type: 'reasoning-delta';
+    text: string;
+}
+/** Source/citation from web search or RAG */
+export interface SourceChunk {
+    type: 'source';
+    id: string;
+    sourceType: string;
+    url?: string;
+    title?: string;
+    providerMetadata?: Record<string, unknown>;
+}
+/** Tool call starting to stream */
+export interface ToolInputStartChunk {
+    type: 'tool-input-start';
+    id: string;
+    toolName: string;
+}
+/** Tool arguments being streamed */
+export interface ToolInputDeltaChunk {
+    type: 'tool-input-delta';
+    id: string;
+    delta: string;
+}
+/** Tool call complete with parsed input */
+export interface ToolCallChunk {
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Tool execution result */
+export interface ToolResultChunk {
+    type: 'tool-result';
+    toolCallId: string;
+    toolName: string;
+    output: unknown;
+}
+/** Step started in multi-step execution */
+export interface StartStepChunk {
+    type: 'start-step';
+}
+/** Step finished in multi-step execution */
+export interface FinishStepChunk {
+    type: 'finish-step';
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+    finishReason?: string;
+}
+/** Stream error */
+export interface ErrorChunk {
+    type: 'error';
+    error: Error;
+}
+/** Unknown chunk type (fallback for future AI SDK chunk types) */
+export interface UnknownChunk {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Union of all known AI SDK stream chunk types.
+ * Plugins can use type narrowing with `chunk.type` to handle specific chunk types.
+ *
+ * @example
+ * ```typescript
+ * onChunk(chunk, context) {
+ *   if (chunk.type === 'source') {
+ *     // TypeScript knows chunk is SourceChunk here
+ *     console.log(chunk.url);
+ *   }
+ * }
+ * ```
+ */
+export type StreamChunk = TextDeltaChunk | ReasoningDeltaChunk | SourceChunk | ToolInputStartChunk | ToolInputDeltaChunk | ToolCallChunk | ToolResultChunk | StartStepChunk | FinishStepChunk | ErrorChunk | UnknownChunk;
+/**
+ * Plugin interface for extending AISDKAgent functionality.
+ *
+ * Plugins can hook into various points of the agent lifecycle to:
+ * - Modify inputs before sending to AI
+ * - Transform streaming chunks
+ * - Intercept or modify tool calls
+ * - Process and transform responses
+ * - Handle errors
+ *
+ * @example
+ * ```typescript
+ * const loggingPlugin: AgentPlugin = {
+ *   id: 'logging',
+ *
+ *   onUserMessage(input, context) {
+ *     context.logger.info('User message received', {
+ *       messageCount: input.messages.length,
+ *     });
+ *     return input;
+ *   },
+ *
+ *   onAgentResponse(result, context) {
+ *     context.logger.info('Agent response', {
+ *       textLength: result.text.length,
+ *     });
+ *     return result;
+ *   },
+ * };
+ * ```
+ */
+export interface AgentPlugin {
+    /** Unique plugin identifier */
+    id: string;
+    /**
+     * Initialize plugin (called once when agent is created).
+     * Use this to set up any resources the plugin needs.
+     *
+     * @param context - Initialization context with provider info
+     */
+    initialize?(context: {
+        provider: string;
+    }): void | Promise<void>;
+    /**
+     * Called before the user message is sent to AI SDK.
+     * Can modify messages, system prompt, or tools.
+     *
+     * @param input - The input data (messages, system prompt, tools)
+     * @param context - Plugin context with run info and shared state
+     * @returns Modified input or unchanged input
+     */
+    onUserMessage?(input: AgentRunInput, context: AgentPluginContext): AgentRunInput | Promise<AgentRunInput>;
+    /**
+     * Called after AI SDK completes processing (including all tool calls).
+     * Can process results, emit events, or transform the final text.
+     *
+     * @param result - The agent's response data
+     * @param context - Plugin context with run info and shared state
+     * @returns Modified result or unchanged result
+     */
+    onAgentResponse?(result: AgentRunResult, context: AgentPluginContext): AgentRunResult | Promise<AgentRunResult>;
+    /**
+     * Called for each streaming text chunk.
+     * Can transform chunks. Return undefined/void to keep chunk unchanged.
+     *
+     * @param chunk - The text chunk being streamed
+     * @param context - Plugin context with run info and shared state
+     * @returns Transformed chunk, or undefined to keep original
+     */
+    onTextChunk?(chunk: string, context: AgentPluginContext): string | void | Promise<string | void>;
+    /**
+     * Called before a tool is executed.
+     * Can modify the tool call or return null to skip execution.
+     *
+     * @param toolCall - Information about the tool being called
+     * @param context - Plugin context with run info and shared state
+     * @returns Modified tool call, null to skip, or unchanged
+     */
+    onBeforeToolCall?(toolCall: ToolCallInfo, context: AgentPluginContext): ToolCallInfo | null | Promise<ToolCallInfo | null>;
+    /**
+     * Called after a tool is executed.
+     * Can modify the tool result before it's sent back to the AI.
+     *
+     * @param toolResult - Information about the completed tool call
+     * @param context - Plugin context with run info and shared state
+     * @returns Modified result or unchanged result
+     */
+    onAfterToolCall?(toolResult: ToolResultInfo, context: AgentPluginContext): unknown | Promise<unknown>;
+    /**
+     * Called for each chunk from the AI SDK stream.
+     * Plugins can filter by chunk.type to handle specific chunk types.
+     *
+     * Common chunk types:
+     * - 'text-delta': Text content being streamed
+     * - 'source': Citation/source from web search or RAG
+     * - 'tool-call': Tool invocation
+     * - 'tool-result': Tool execution result
+     * - 'start-step', 'finish-step': Multi-step execution markers
+     *
+     * @param chunk - The stream chunk with type and type-specific properties
+     * @param context - Plugin context with run info and shared state
+     */
+    onChunk?(chunk: StreamChunk, context: AgentPluginContext): void | Promise<void>;
+    /**
+     * Cleanup (called when agent is destroyed).
+     * Use to release any resources the plugin acquired.
+     */
+    destroy?(): void | Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map