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

package/dist/src/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

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/agents/plugins/types.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -2,7 +2,7 @@ export { UseAIServer } from './server';
 export type { UseAIServerConfig, McpEndpointConfig, ToolDefinition, CorsOptions } from './types';
 export type { ClientSession } from './server';
 export type { Agent, AgentInput, EventEmitter, AgentResult } from './agents';
-export { AISDKAgent, type AISDKAgentConfig } from './agents';
+export { AISDKAgent, type AISDKAgentConfig, type MessageWithCacheContext, type CacheTtl, type CacheBreakpointResult, type CacheBreakpointFn } from './agents';
 export type { UseAIServerPlugin, MessageHandler } from './plugins';
 export { logger } from './logger';
 export { createClientToolExecutor, isRemoteTool, createGlobFilter, and, or, not, } from './utils';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjG,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAG7D,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,OAAO,EACL,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,GAAG,EACH,EAAE,EACF,GAAG,GACJ,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACjG,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAG9C,YAAY,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,KAAK,QAAQ,EAAE,KAAK,qBAAqB,EAAE,KAAK,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG9J,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAGnE,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAGlC,OAAO,EACL,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,GAAG,EACH,EAAE,EACF,GAAG,GACJ,MAAM,SAAS,CAAC"}