@meetsmore-oss/use-ai-server 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/dist/agents/AISDKAgent.d.ts +220 -0
  2. package/dist/agents/AISDKAgent.d.ts.map +1 -0
  3. package/dist/agents/AISDKAgent.test.d.ts +2 -0
  4. package/dist/agents/AISDKAgent.test.d.ts.map +1 -0
  5. package/dist/agents/index.d.ts +7 -0
  6. package/dist/agents/index.d.ts.map +1 -0
  7. package/dist/agents/types.d.ts +151 -0
  8. package/dist/agents/types.d.ts.map +1 -0
  9. package/dist/agents.integration.test.d.ts +2 -0
  10. package/dist/agents.integration.test.d.ts.map +1 -0
  11. package/dist/configuration.integration.test.d.ts +2 -0
  12. package/dist/configuration.integration.test.d.ts.map +1 -0
  13. package/dist/core-architecture.integration.test.d.ts +2 -0
  14. package/dist/core-architecture.integration.test.d.ts.map +1 -0
  15. package/dist/error-handling.integration.test.d.ts +2 -0
  16. package/dist/error-handling.integration.test.d.ts.map +1 -0
  17. package/dist/index.d.ts +9 -0
  18. package/dist/index.d.ts.map +1 -0
  19. package/dist/index.js +80683 -0
  20. package/dist/instrumentation.d.ts +15 -0
  21. package/dist/instrumentation.d.ts.map +1 -0
  22. package/dist/langfuse.integration.test.d.ts +7 -0
  23. package/dist/langfuse.integration.test.d.ts.map +1 -0
  24. package/dist/logger.d.ts +30 -0
  25. package/dist/logger.d.ts.map +1 -0
  26. package/dist/mcp/RemoteMcpToolsProvider.d.ts +73 -0
  27. package/dist/mcp/RemoteMcpToolsProvider.d.ts.map +1 -0
  28. package/dist/mcp/RemoteMcpToolsProvider.test.d.ts +2 -0
  29. package/dist/mcp/RemoteMcpToolsProvider.test.d.ts.map +1 -0
  30. package/dist/mcp/index.d.ts +2 -0
  31. package/dist/mcp/index.d.ts.map +1 -0
  32. package/dist/mcp.integration.test.d.ts +2 -0
  33. package/dist/mcp.integration.test.d.ts.map +1 -0
  34. package/dist/message-sanitization.test.d.ts +2 -0
  35. package/dist/message-sanitization.test.d.ts.map +1 -0
  36. package/dist/plugins/index.d.ts +2 -0
  37. package/dist/plugins/index.d.ts.map +1 -0
  38. package/dist/plugins/types.d.ts +69 -0
  39. package/dist/plugins/types.d.ts.map +1 -0
  40. package/dist/plugins.integration.test.d.ts +2 -0
  41. package/dist/plugins.integration.test.d.ts.map +1 -0
  42. package/dist/rate-limiting.integration.test.d.ts +2 -0
  43. package/dist/rate-limiting.integration.test.d.ts.map +1 -0
  44. package/dist/rateLimiter.d.ts +17 -0
  45. package/dist/rateLimiter.d.ts.map +1 -0
  46. package/dist/rateLimiter.test.d.ts +2 -0
  47. package/dist/rateLimiter.test.d.ts.map +1 -0
  48. package/dist/server.d.ts +140 -0
  49. package/dist/server.d.ts.map +1 -0
  50. package/dist/server.test.d.ts +2 -0
  51. package/dist/server.test.d.ts.map +1 -0
  52. package/dist/src/agents/AISDKAgent.d.ts +220 -0
  53. package/dist/src/agents/AISDKAgent.d.ts.map +1 -0
  54. package/dist/src/agents/AISDKAgent.test.d.ts +2 -0
  55. package/dist/src/agents/AISDKAgent.test.d.ts.map +1 -0
  56. package/dist/src/agents/index.d.ts +7 -0
  57. package/dist/src/agents/index.d.ts.map +1 -0
  58. package/dist/src/agents/types.d.ts +151 -0
  59. package/dist/src/agents/types.d.ts.map +1 -0
  60. package/dist/src/agents.integration.test.d.ts +2 -0
  61. package/dist/src/agents.integration.test.d.ts.map +1 -0
  62. package/dist/src/configuration.integration.test.d.ts +2 -0
  63. package/dist/src/configuration.integration.test.d.ts.map +1 -0
  64. package/dist/src/core-architecture.integration.test.d.ts +2 -0
  65. package/dist/src/core-architecture.integration.test.d.ts.map +1 -0
  66. package/dist/src/error-handling.integration.test.d.ts +2 -0
  67. package/dist/src/error-handling.integration.test.d.ts.map +1 -0
  68. package/dist/src/index.d.ts +9 -0
  69. package/dist/src/index.d.ts.map +1 -0
  70. package/dist/src/instrumentation.d.ts +15 -0
  71. package/dist/src/instrumentation.d.ts.map +1 -0
  72. package/dist/src/langfuse.integration.test.d.ts +7 -0
  73. package/dist/src/langfuse.integration.test.d.ts.map +1 -0
  74. package/dist/src/logger.d.ts +30 -0
  75. package/dist/src/logger.d.ts.map +1 -0
  76. package/dist/src/mcp/RemoteMcpToolsProvider.d.ts +73 -0
  77. package/dist/src/mcp/RemoteMcpToolsProvider.d.ts.map +1 -0
  78. package/dist/src/mcp/RemoteMcpToolsProvider.test.d.ts +2 -0
  79. package/dist/src/mcp/RemoteMcpToolsProvider.test.d.ts.map +1 -0
  80. package/dist/src/mcp/index.d.ts +2 -0
  81. package/dist/src/mcp/index.d.ts.map +1 -0
  82. package/dist/src/mcp.integration.test.d.ts +2 -0
  83. package/dist/src/mcp.integration.test.d.ts.map +1 -0
  84. package/dist/src/message-sanitization.test.d.ts +2 -0
  85. package/dist/src/message-sanitization.test.d.ts.map +1 -0
  86. package/dist/src/plugins/index.d.ts +2 -0
  87. package/dist/src/plugins/index.d.ts.map +1 -0
  88. package/dist/src/plugins/types.d.ts +69 -0
  89. package/dist/src/plugins/types.d.ts.map +1 -0
  90. package/dist/src/plugins.integration.test.d.ts +2 -0
  91. package/dist/src/plugins.integration.test.d.ts.map +1 -0
  92. package/dist/src/rate-limiting.integration.test.d.ts +2 -0
  93. package/dist/src/rate-limiting.integration.test.d.ts.map +1 -0
  94. package/dist/src/rateLimiter.d.ts +17 -0
  95. package/dist/src/rateLimiter.d.ts.map +1 -0
  96. package/dist/src/rateLimiter.test.d.ts +2 -0
  97. package/dist/src/rateLimiter.test.d.ts.map +1 -0
  98. package/dist/src/server.d.ts +140 -0
  99. package/dist/src/server.d.ts.map +1 -0
  100. package/dist/src/server.test.d.ts +2 -0
  101. package/dist/src/server.test.d.ts.map +1 -0
  102. package/dist/src/test-preload.d.ts +25 -0
  103. package/dist/src/test-preload.d.ts.map +1 -0
  104. package/dist/src/tool-execution.integration.test.d.ts +2 -0
  105. package/dist/src/tool-execution.integration.test.d.ts.map +1 -0
  106. package/dist/src/types.d.ts +60 -0
  107. package/dist/src/types.d.ts.map +1 -0
  108. package/dist/src/utils/index.d.ts +6 -0
  109. package/dist/src/utils/index.d.ts.map +1 -0
  110. package/dist/src/utils/patternMatcher.d.ts +41 -0
  111. package/dist/src/utils/patternMatcher.d.ts.map +1 -0
  112. package/dist/src/utils/patternMatcher.test.d.ts +2 -0
  113. package/dist/src/utils/patternMatcher.test.d.ts.map +1 -0
  114. package/dist/src/utils/toolConverter.d.ts +22 -0
  115. package/dist/src/utils/toolConverter.d.ts.map +1 -0
  116. package/dist/src/utils/toolFilters.d.ts +101 -0
  117. package/dist/src/utils/toolFilters.d.ts.map +1 -0
  118. package/dist/test/integration-test-utils.d.ts +203 -0
  119. package/dist/test/integration-test-utils.d.ts.map +1 -0
  120. package/dist/test/test-utils.d.ts +104 -0
  121. package/dist/test/test-utils.d.ts.map +1 -0
  122. package/dist/test-preload.d.ts +25 -0
  123. package/dist/test-preload.d.ts.map +1 -0
  124. package/dist/tool-execution.integration.test.d.ts +2 -0
  125. package/dist/tool-execution.integration.test.d.ts.map +1 -0
  126. package/dist/tsconfig.tsbuildinfo +1 -0
  127. package/dist/types.d.ts +60 -0
  128. package/dist/types.d.ts.map +1 -0
  129. package/dist/utils/index.d.ts +6 -0
  130. package/dist/utils/index.d.ts.map +1 -0
  131. package/dist/utils/patternMatcher.d.ts +41 -0
  132. package/dist/utils/patternMatcher.d.ts.map +1 -0
  133. package/dist/utils/patternMatcher.test.d.ts +2 -0
  134. package/dist/utils/patternMatcher.test.d.ts.map +1 -0
  135. package/dist/utils/toolConverter.d.ts +22 -0
  136. package/dist/utils/toolConverter.d.ts.map +1 -0
  137. package/dist/utils/toolFilters.d.ts +101 -0
  138. package/dist/utils/toolFilters.d.ts.map +1 -0
  139. package/package.json +56 -0
@@ -0,0 +1,220 @@
1
+ import { LanguageModel } from 'ai';
2
+ import type { Agent, AgentInput, EventEmitter, AgentResult } from './types';
3
+ import type { ToolDefinition } from '../types';
4
+ /**
5
+ * Configuration for AISDKAgent.
6
+ */
7
+ export interface AISDKAgentConfig {
8
+ /**
9
+ * AI SDK Language Model (works with any provider).
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * import { anthropic } from '@ai-sdk/anthropic';
14
+ * import { openai } from '@ai-sdk/openai';
15
+ * import { google } from '@ai-sdk/google';
16
+ *
17
+ * // With Anthropic Claude
18
+ * { model: anthropic('claude-3-5-sonnet-20241022') }
19
+ *
20
+ * // With OpenAI GPT
21
+ * { model: openai('gpt-4-turbo') }
22
+ *
23
+ * // With Google Gemini
24
+ * { model: google('gemini-pro') }
25
+ * ```
26
+ */
27
+ model: LanguageModel;
28
+ /**
29
+ * Agent name for identification (defaults to 'ai-sdk').
30
+ * Use this to differentiate multiple AI SDK agents.
31
+ */
32
+ name?: string;
33
+ /**
34
+ * Optional annotation/description for the agent.
35
+ * Displayed in the use-ai agent selector UI to help users understand
36
+ * the agent's capabilities or purpose.
37
+ *
38
+ * @example
39
+ * ```typescript
40
+ * { annotation: 'Fast responses for simple tasks' }
41
+ * { annotation: 'Deep thinking mode for complex reasoning' }
42
+ * ```
43
+ */
44
+ annotation?: string;
45
+ /**
46
+ * Optional system prompt to configure the agent's behavior.
47
+ * This prompt is set on the backend and not exposed to the frontend,
48
+ * making it suitable for sensitive instructions.
49
+ *
50
+ * Can be a string, a function returning a string, or an async function
51
+ * returning a Promise<string>. Use a function when the prompt needs to
52
+ * be dynamically resolved (e.g., fetched from Langfuse or other external
53
+ * sources) so updates take effect immediately without server restart.
54
+ *
55
+ * When both this and the runtime systemPrompt (from AgentInput) are provided,
56
+ * they are combined with this config prompt coming first.
57
+ *
58
+ * @example
59
+ * ```typescript
60
+ * // Static prompt
61
+ * {
62
+ * systemPrompt: 'You are a helpful assistant.'
63
+ * }
64
+ *
65
+ * // Sync function (e.g., reading from cache)
66
+ * {
67
+ * systemPrompt: () => promptCache.get('my-prompt')
68
+ * }
69
+ *
70
+ * // Async function (e.g., fetching from Langfuse)
71
+ * {
72
+ * systemPrompt: async () => {
73
+ * const prompt = await langfuse.getPrompt('my-prompt');
74
+ * return prompt.compile();
75
+ * }
76
+ * }
77
+ * ```
78
+ */
79
+ systemPrompt?: string | (() => string | Promise<string>);
80
+ /**
81
+ * Optional filter function for tools.
82
+ * Use this to control which tools are available to this agent.
83
+ * Return true to include the tool, false to exclude it.
84
+ *
85
+ * @example
86
+ * ```typescript
87
+ * // Only allow MCP tools starting with 'db_'
88
+ * {
89
+ * toolFilter: (tool) =>
90
+ * !tool._remote || tool.name.startsWith('db_')
91
+ * }
92
+ *
93
+ * // Block dangerous MCP tools
94
+ * {
95
+ * toolFilter: (tool) =>
96
+ * !tool._remote ||
97
+ * (!tool.name.includes('delete') && !tool.name.includes('drop'))
98
+ * }
99
+ * ```
100
+ */
101
+ toolFilter?: (tool: ToolDefinition) => boolean;
102
+ }
103
+ /**
104
+ * Agent implementation for AI SDK models (Anthropic, OpenAI, Google, etc.).
105
+ *
106
+ * This agent is provider-agnostic and works with any AI SDK LanguageModel:
107
+ * - Anthropic Claude (via @ai-sdk/anthropic)
108
+ * - OpenAI GPT (via @ai-sdk/openai)
109
+ * - Google Gemini (via @ai-sdk/google)
110
+ * - And more...
111
+ *
112
+ * Features:
113
+ * - API calls via Vercel AI SDK
114
+ * - Tool coordination with promise-based waiting
115
+ * - Multi-turn conversation history
116
+ * - AG-UI event emission
117
+ * - Optional Langfuse telemetry
118
+ *
119
+ * Used for conversational chat (via useAI hook).
120
+ *
121
+ * @example
122
+ * ```typescript
123
+ * import { createAnthropic } from '@ai-sdk/anthropic';
124
+ * import { openai } from '@ai-sdk/openai';
125
+ *
126
+ * // With Claude
127
+ * const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
128
+ * const claudeAgent = new AISDKAgent({
129
+ * model: anthropic('claude-3-5-sonnet-20241022'),
130
+ * });
131
+ *
132
+ * // With GPT-4
133
+ * const gptAgent = new AISDKAgent({
134
+ * model: openai('gpt-4-turbo'),
135
+ * });
136
+ *
137
+ * // Agent names come from agents object keys, not from agent config
138
+ * const server = new UseAIServer({
139
+ * agents: {
140
+ * claude: claudeAgent,
141
+ * 'gpt-4': gptAgent,
142
+ * },
143
+ * defaultAgent: 'claude', // Default agent name
144
+ * });
145
+ * ```
146
+ */
147
+ export declare class AISDKAgent implements Agent {
148
+ private model;
149
+ private name;
150
+ private annotation?;
151
+ private langfuse;
152
+ private toolFilter?;
153
+ private systemPrompt?;
154
+ constructor(config: AISDKAgentConfig);
155
+ getName(): string;
156
+ getAnnotation(): string | undefined;
157
+ /**
158
+ * Flushes pending Langfuse telemetry data.
159
+ * Useful for tests to ensure data is sent before querying.
160
+ */
161
+ flushTelemetry(): Promise<void>;
162
+ run(input: AgentInput, events: EventEmitter): Promise<AgentResult>;
163
+ /**
164
+ * Resolves the systemPrompt configuration value.
165
+ * Handles string, sync function, and async function cases.
166
+ *
167
+ * @returns The resolved system prompt string, or undefined if not configured or empty
168
+ */
169
+ private resolveSystemPrompt;
170
+ /**
171
+ * Builds an array of system messages from config and runtime prompts.
172
+ * Each prompt becomes a separate SystemModelMessage, preserving their distinct purposes.
173
+ *
174
+ * @param configPrompt - Resolved system prompt from agent config (already resolved via resolveSystemPrompt)
175
+ * @param runtimePrompt - System prompt from AgentInput (generated by server based on state)
176
+ * @returns Array of SystemModelMessage objects, or undefined if both are empty
177
+ */
178
+ private buildSystemMessages;
179
+ /**
180
+ * Type guard to check if a tool is a remote MCP tool.
181
+ */
182
+ private isRemoteTool;
183
+ /**
184
+ * Filters tools using the configured filter function.
185
+ * If no filter is configured, returns all tools.
186
+ */
187
+ private filterTools;
188
+ /**
189
+ * Creates execute function for MCP tools.
190
+ * Note: TOOL_CALL events are emitted from the stream loop, not here.
191
+ * The toolCallId is provided by AI SDK in the execute options.
192
+ */
193
+ private createMcpToolExecutor;
194
+ private sanitizeToolsForAPI;
195
+ /**
196
+ * Zod schemas for AI SDK ModelMessage format.
197
+ * These schemas define the exact structure expected by the AI SDK,
198
+ * automatically stripping any provider-specific fields (like 'id', 'tool_use_id').
199
+ * Using .strip() to silently remove unknown fields rather than throwing errors.
200
+ */
201
+ private static readonly toolResultContentSchema;
202
+ private static readonly toolCallContentSchema;
203
+ private static readonly textContentSchema;
204
+ private static readonly imageContentSchema;
205
+ private static readonly fileContentSchema;
206
+ private static readonly contentPartSchema;
207
+ private static readonly messageSchema;
208
+ private static readonly messagesArraySchema;
209
+ /**
210
+ * Sanitizes messages from AI SDK responses by removing provider-specific fields.
211
+ * This prevents validation errors when messages are re-sent to the API in subsequent requests.
212
+ *
213
+ * Issue: AI SDK responses may include provider-specific fields (e.g., Anthropic's `id`, `tool_use_id`)
214
+ * that are not valid when sent back to the API. These fields must be stripped.
215
+ *
216
+ * Uses Zod schema parsing with .strict() to automatically strip any extra fields.
217
+ */
218
+ private sanitizeMessages;
219
+ }
220
+ //# sourceMappingURL=AISDKAgent.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=AISDKAgent.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"AISDKAgent.test.d.ts","sourceRoot":"","sources":["../../../src/agents/AISDKAgent.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * Agents module for use-ai server.
3
+ * Provides pluggable AI agent backends that emit AG-UI protocol events.
4
+ */
5
+ export type { Agent, AgentInput, EventEmitter, AgentResult, ClientSession } from './types';
6
+ export { AISDKAgent, type AISDKAgentConfig } from './AISDKAgent';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,151 @@
1
+ import type { Socket } from 'socket.io';
2
+ import type { ModelMessage } from 'ai';
3
+ import type { ToolDefinition, AGUIEvent } from '../types';
4
+ /**
5
+ * Context for a single client session.
6
+ * Contains all state needed for multi-turn conversations and tool coordination.
7
+ */
8
+ export interface ClientSession {
9
+ /** Unique identifier for this client connection */
10
+ clientId: string;
11
+ /** IP address of the client (used for rate limiting) */
12
+ ipAddress: string;
13
+ /** Socket.IO socket for bidirectional communication with client */
14
+ socket: Socket;
15
+ /** Unique identifier for the conversation thread */
16
+ threadId: string;
17
+ /** ID of the currently executing run (if any) */
18
+ currentRunId?: string;
19
+ /** Tools available to the AI agent for this session */
20
+ tools: ToolDefinition[];
21
+ /** Current application state (AG-UI format) */
22
+ state: unknown;
23
+ /** Full conversation history in AI SDK ModelMessage format (for AI API calls) */
24
+ conversationHistory: ModelMessage[];
25
+ /** Map of pending tool calls awaiting results from the client. Key: toolCallId, Value: resolver function */
26
+ pendingToolCalls: Map<string, (content: string) => void>;
27
+ /** MCP headers configuration for the current request (temporary, cleared after request) */
28
+ currentMcpHeaders?: import('@meetsmore-oss/use-ai-core').McpHeadersMap;
29
+ /** AbortController for cancelling the current run */
30
+ abortController?: AbortController;
31
+ /** Cached MCP tools for this session, keyed by endpoint URL */
32
+ mcpToolsCache?: Map<string, ToolDefinition[]>;
33
+ /** Hash of auth headers used for cache key */
34
+ mcpHeadersHash?: string;
35
+ /** Timestamp when MCP tools cache was populated (for TTL-based invalidation) */
36
+ mcpToolsCacheTimestamp?: number;
37
+ }
38
+ /**
39
+ * Input for running an agent.
40
+ * Provides all context needed to execute a run.
41
+ */
42
+ export interface AgentInput {
43
+ /** The client session context */
44
+ session: ClientSession;
45
+ /** The unique identifier for this run */
46
+ runId: string;
47
+ /** Conversation history in AI SDK ModelMessage format */
48
+ messages: ModelMessage[];
49
+ /** Available tools that the agent can call */
50
+ tools: ToolDefinition[];
51
+ /** Current application state (if any) */
52
+ state: unknown;
53
+ /** Optional system prompt to guide the agent */
54
+ systemPrompt?: string;
55
+ /** The original RunAgentInput from AG-UI protocol (for emitting RUN_STARTED event) */
56
+ originalInput: import('../types').RunAgentInput;
57
+ }
58
+ /**
59
+ * Interface for emitting AG-UI protocol events.
60
+ * All agents must use this to communicate results to clients.
61
+ */
62
+ export interface EventEmitter {
63
+ /** Emit an AG-UI event to the client */
64
+ emit<T extends AGUIEvent = AGUIEvent>(event: T): void;
65
+ }
66
+ /**
67
+ * Result from an agent execution.
68
+ * Indicates whether the run completed successfully and any final state.
69
+ */
70
+ export interface AgentResult {
71
+ /** Whether the run completed successfully */
72
+ success: boolean;
73
+ /** Error message if the run failed */
74
+ error?: string;
75
+ /** Final conversation history after the run */
76
+ conversationHistory: ModelMessage[];
77
+ }
78
+ /**
79
+ * Abstract interface for AI agents.
80
+ *
81
+ * Agents are pluggable backends that execute AI logic and emit AG-UI events.
82
+ * Examples: AISDKAgent (via AI SDK with various providers like Anthropic, OpenAI, etc.)
83
+ *
84
+ * All agents must:
85
+ * - Accept AgentInput with messages, tools, and state
86
+ * - Emit AG-UI protocol events (TEXT_MESSAGE_*, TOOL_CALL_*, RUN_*, etc.)
87
+ * - Handle tool call coordination (emit TOOL_CALL_START, wait for result, continue)
88
+ * - Return AgentResult indicating success/failure
89
+ *
90
+ * @example
91
+ * ```typescript
92
+ * class MyCustomAgent implements Agent {
93
+ * async run(input: AgentInput, events: EventEmitter): Promise<AgentResult> {
94
+ * // 1. Emit RUN_STARTED
95
+ * events.emit({ type: EventType.RUN_STARTED, ... });
96
+ *
97
+ * // 2. Process with your backend (API call, etc.)
98
+ * const result = await myBackend.process(input);
99
+ *
100
+ * // 3. Emit TEXT_MESSAGE_* events for responses
101
+ * events.emit({ type: EventType.TEXT_MESSAGE_START, ... });
102
+ *
103
+ * // 4. For tool calls, emit TOOL_CALL_START and wait for results
104
+ * events.emit({ type: EventType.TOOL_CALL_START, ... });
105
+ * const toolResult = await input.session.waitForToolResult(toolCallId);
106
+ *
107
+ * // 5. Emit RUN_FINISHED
108
+ * events.emit({ type: EventType.RUN_FINISHED, ... });
109
+ *
110
+ * return { success: true, conversationHistory: [...] };
111
+ * }
112
+ * }
113
+ * ```
114
+ */
115
+ export interface Agent {
116
+ /**
117
+ * Executes an agent run with the given input.
118
+ * Must emit AG-UI events and coordinate tool execution.
119
+ *
120
+ * @param input - The run context (session, messages, tools, state)
121
+ * @param events - Event emitter for sending AG-UI events to client
122
+ * @returns Promise resolving to the run result
123
+ */
124
+ run(input: AgentInput, events: EventEmitter): Promise<AgentResult>;
125
+ /**
126
+ * Returns the unique identifier for this agent type.
127
+ * Used for logging and debugging.
128
+ *
129
+ * @example
130
+ * ```typescript
131
+ * getName(): string {
132
+ * return 'claude';
133
+ * }
134
+ * ```
135
+ */
136
+ getName(): string;
137
+ /**
138
+ * Returns an optional annotation/description for this agent.
139
+ * Displayed in the use-ai agent selector UI to help users understand
140
+ * the agent's capabilities or purpose.
141
+ *
142
+ * @example
143
+ * ```typescript
144
+ * getAnnotation(): string | undefined {
145
+ * return 'Fast responses for simple tasks';
146
+ * }
147
+ * ```
148
+ */
149
+ getAnnotation?(): string | undefined;
150
+ }
151
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agents/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1D;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,+CAA+C;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,iFAAiF;IACjF,mBAAmB,EAAE,YAAY,EAAE,CAAC;IACpC,4GAA4G;IAC5G,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,CAAC;IACzD,2FAA2F;IAC3F,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,aAAa,CAAC;IACvE,qDAAqD;IACrD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,+DAA+D;IAC/D,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;IAC9C,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,OAAO,EAAE,aAAa,CAAC;IACvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,8CAA8C;IAC9C,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,yCAAyC;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,aAAa,EAAE,OAAO,UAAU,EAAE,aAAa,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,IAAI,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;CACvD;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,mBAAmB,EAAE,YAAY,EAAE,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,KAAK;IACpB;;;;;;;OAOG;IACH,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEnE;;;;;;;;;;OAUG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,IAAI,MAAM,GAAG,SAAS,CAAC;CACtC"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=agents.integration.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agents.integration.test.d.ts","sourceRoot":"","sources":["../../src/agents.integration.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=configuration.integration.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"configuration.integration.test.d.ts","sourceRoot":"","sources":["../../src/configuration.integration.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=core-architecture.integration.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"core-architecture.integration.test.d.ts","sourceRoot":"","sources":["../../src/core-architecture.integration.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=error-handling.integration.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"error-handling.integration.test.d.ts","sourceRoot":"","sources":["../../src/error-handling.integration.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,9 @@
1
+ export { UseAIServer } from './server';
2
+ export type { UseAIServerConfig, McpEndpointConfig, ToolDefinition } from './types';
3
+ export type { ClientSession } from './server';
4
+ export type { Agent, AgentInput, EventEmitter, AgentResult } from './agents';
5
+ export { AISDKAgent, type AISDKAgentConfig } from './agents';
6
+ export type { UseAIServerPlugin, MessageHandler } from './plugins';
7
+ export { logger } from './logger';
8
+ export { createClientToolExecutor, isRemoteTool, createGlobFilter, and, or, not, } from './utils';
9
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +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,MAAM,SAAS,CAAC;AACpF,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"}