@meetsmore-oss/use-ai-client 1.7.0 → 1.9.0
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.
- package/dist/bundled.js +18421 -18312
- package/dist/bundled.js.map +1 -1
- package/dist/index.d.ts +259 -145
- package/dist/index.js +533 -436
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,48 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
export { z } from 'zod';
|
|
3
|
-
import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, UseAIClientMessage } from '@meetsmore-oss/use-ai-core';
|
|
3
|
+
import { ToolAnnotations, ToolDefinition, WorkflowStatus, FeedbackValue, AgentInfo, MultimodalContent, UseAIForwardedProps, AGUIEvent, Message as Message$1, UseAIClientMessage, ToolApprovalRequestEvent } from '@meetsmore-oss/use-ai-core';
|
|
4
4
|
export { AgentInfo, ToolAnnotations, ToolDefinition } from '@meetsmore-oss/use-ai-core';
|
|
5
5
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
6
|
-
import React$1, { ReactNode } from 'react';
|
|
6
|
+
import React$1, { MutableRefObject, RefObject, ReactNode } from 'react';
|
|
7
7
|
|
|
8
|
+
/**
|
|
9
|
+
* Context provided to tool execution functions.
|
|
10
|
+
* Allows tools to dynamically request user approval at runtime.
|
|
11
|
+
*/
|
|
12
|
+
interface ToolExecutionContext {
|
|
13
|
+
/**
|
|
14
|
+
* Request user approval during tool execution.
|
|
15
|
+
* Use this for conditional approval based on runtime values
|
|
16
|
+
* (e.g., API endpoint, input values, computed risk).
|
|
17
|
+
*
|
|
18
|
+
* @param input - Approval request details
|
|
19
|
+
* @returns Promise resolving with approval decision
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```typescript
|
|
23
|
+
* const callApi = defineTool(
|
|
24
|
+
* 'Call an external API',
|
|
25
|
+
* z.object({ url: z.string() }),
|
|
26
|
+
* async (input, ctx) => {
|
|
27
|
+
* if (input.url.includes('production')) {
|
|
28
|
+
* const { approved } = await ctx.requestApproval({
|
|
29
|
+
* message: `This will call production API: ${input.url}`,
|
|
30
|
+
* });
|
|
31
|
+
* if (!approved) return { error: 'User rejected the action' };
|
|
32
|
+
* }
|
|
33
|
+
* return fetch(input.url);
|
|
34
|
+
* }
|
|
35
|
+
* );
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
requestApproval(input: {
|
|
39
|
+
message: string;
|
|
40
|
+
metadata?: Record<string, unknown>;
|
|
41
|
+
}): Promise<{
|
|
42
|
+
approved: boolean;
|
|
43
|
+
reason?: string;
|
|
44
|
+
}>;
|
|
45
|
+
}
|
|
8
46
|
/**
|
|
9
47
|
* Options for configuring tool behavior.
|
|
10
48
|
*/
|
|
@@ -36,13 +74,13 @@ interface DefinedTool<T extends z.ZodType> {
|
|
|
36
74
|
/** Zod schema for validating input */
|
|
37
75
|
_zodSchema: T;
|
|
38
76
|
/** The function to execute when the tool is called */
|
|
39
|
-
fn: (input: z.infer<T
|
|
77
|
+
fn: (input: z.infer<T>, ctx: ToolExecutionContext) => unknown | Promise<unknown>;
|
|
40
78
|
/** Configuration options for the tool */
|
|
41
79
|
_options: ToolOptions;
|
|
42
80
|
/** Converts this tool to a ToolDefinition for registration with the server */
|
|
43
81
|
_toToolDefinition: (name: string) => ToolDefinition;
|
|
44
82
|
/** Validates input and executes the tool function */
|
|
45
|
-
_execute: (input: unknown) => Promise<unknown>;
|
|
83
|
+
_execute: (input: unknown, ctx: ToolExecutionContext) => Promise<unknown>;
|
|
46
84
|
}
|
|
47
85
|
/**
|
|
48
86
|
* Defines a tool with no input parameters that can be called by the AI.
|
|
@@ -61,7 +99,7 @@ interface DefinedTool<T extends z.ZodType> {
|
|
|
61
99
|
* );
|
|
62
100
|
* ```
|
|
63
101
|
*/
|
|
64
|
-
declare function defineTool<TReturn>(description: string, fn: () => TReturn | Promise<TReturn>, options?: ToolOptions): DefinedTool<z.ZodObject<{}>>;
|
|
102
|
+
declare function defineTool<TReturn>(description: string, fn: (ctx: ToolExecutionContext) => TReturn | Promise<TReturn>, options?: ToolOptions): DefinedTool<z.ZodObject<{}>>;
|
|
65
103
|
/**
|
|
66
104
|
* Defines a tool with typed input parameters that can be called by the AI.
|
|
67
105
|
*
|
|
@@ -87,7 +125,7 @@ declare function defineTool<TReturn>(description: string, fn: () => TReturn | Pr
|
|
|
87
125
|
* );
|
|
88
126
|
* ```
|
|
89
127
|
*/
|
|
90
|
-
declare function defineTool<TSchema extends z.ZodType>(description: string, schema: TSchema, fn: (input: z.infer<TSchema
|
|
128
|
+
declare function defineTool<TSchema extends z.ZodType>(description: string, schema: TSchema, fn: (input: z.infer<TSchema>, ctx: ToolExecutionContext) => unknown | Promise<unknown>, options?: ToolOptions): DefinedTool<TSchema>;
|
|
91
129
|
/**
|
|
92
130
|
* A collection of named tools.
|
|
93
131
|
* Used to register multiple tools with the useAI hook.
|
|
@@ -111,7 +149,7 @@ declare function convertToolsToDefinitions(tools: ToolsDefinition): ToolDefiniti
|
|
|
111
149
|
* @throws Error if the tool is not found
|
|
112
150
|
* @internal
|
|
113
151
|
*/
|
|
114
|
-
declare function executeDefinedTool(tools: ToolsDefinition, toolName: string, input: unknown): Promise<unknown>;
|
|
152
|
+
declare function executeDefinedTool(tools: ToolsDefinition, toolName: string, input: unknown, ctx: ToolExecutionContext): Promise<unknown>;
|
|
115
153
|
|
|
116
154
|
/**
|
|
117
155
|
* Options for configuring the useAI hook.
|
|
@@ -1143,6 +1181,80 @@ declare class UseAIClient {
|
|
|
1143
1181
|
submitFeedback(messageId: string, traceId: string, feedback: FeedbackValue): void;
|
|
1144
1182
|
}
|
|
1145
1183
|
|
|
1184
|
+
interface RegisterToolsOptions {
|
|
1185
|
+
/** Mark component as invisible (no visual state, skip prompt wait) */
|
|
1186
|
+
invisible?: boolean;
|
|
1187
|
+
}
|
|
1188
|
+
/**
|
|
1189
|
+
* Pending tool approval request state.
|
|
1190
|
+
*/
|
|
1191
|
+
interface PendingToolApproval {
|
|
1192
|
+
toolCallId: string;
|
|
1193
|
+
toolCallName: string;
|
|
1194
|
+
toolCallArgs: Record<string, unknown>;
|
|
1195
|
+
annotations?: ToolAnnotations;
|
|
1196
|
+
/** Optional message explaining why approval is needed (runtime approval) */
|
|
1197
|
+
message?: string;
|
|
1198
|
+
/** Optional metadata for the approval request (runtime approval) */
|
|
1199
|
+
metadata?: Record<string, unknown>;
|
|
1200
|
+
}
|
|
1201
|
+
interface UseToolSystemOptions {
|
|
1202
|
+
/** Reference to the UseAI client for sending responses */
|
|
1203
|
+
clientRef: RefObject<UseAIClient | null>;
|
|
1204
|
+
/** Builds the aggregated state from all registered prompts */
|
|
1205
|
+
buildState: () => unknown;
|
|
1206
|
+
}
|
|
1207
|
+
interface UseToolSystemReturn {
|
|
1208
|
+
/** Registers tools for a specific component */
|
|
1209
|
+
registerTools: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
|
|
1210
|
+
/** Unregisters tools for a specific component */
|
|
1211
|
+
unregisterTools: (id: string) => void;
|
|
1212
|
+
/** Checks if a component is marked as invisible */
|
|
1213
|
+
isInvisible: (id: string) => boolean;
|
|
1214
|
+
/** All tools aggregated from registered components */
|
|
1215
|
+
aggregatedTools: ToolsDefinition;
|
|
1216
|
+
/** Whether any tools are registered */
|
|
1217
|
+
hasTools: boolean;
|
|
1218
|
+
/** Ref to current aggregated tools (for use in closures) */
|
|
1219
|
+
aggregatedToolsRef: MutableRefObject<ToolsDefinition>;
|
|
1220
|
+
/** Signals that a component has completed its registration in useLayoutEffect */
|
|
1221
|
+
signalReady: (id: string) => void;
|
|
1222
|
+
/** Current tool registry version (increments when tools change) */
|
|
1223
|
+
toolRegistryVersion: number;
|
|
1224
|
+
/** Registers a waiter function for a component (called when tool exec needs to wait for re-render) */
|
|
1225
|
+
registerWaiter: (id: string, waiter: () => Promise<void>) => void;
|
|
1226
|
+
/** Unregisters a waiter function */
|
|
1227
|
+
unregisterWaiter: (id: string) => void;
|
|
1228
|
+
/** All pending tool approval requests */
|
|
1229
|
+
pendingApprovals: PendingToolApproval[];
|
|
1230
|
+
/** Handle a tool approval request event from the server */
|
|
1231
|
+
handleApprovalRequest: (event: ToolApprovalRequestEvent) => void;
|
|
1232
|
+
/** Execute a tool call and send the response to the server */
|
|
1233
|
+
executeToolCall: (toolCallId: string, name: string, input: unknown) => Promise<void>;
|
|
1234
|
+
/** Store a tool call as pending approval (deferred execution) */
|
|
1235
|
+
storePendingToolCall: (toolCallId: string, name: string, input: unknown, toolCallData: {
|
|
1236
|
+
name: string;
|
|
1237
|
+
args: string;
|
|
1238
|
+
}) => void;
|
|
1239
|
+
/** Approve all pending tool calls and execute them */
|
|
1240
|
+
approveAll: () => Promise<void>;
|
|
1241
|
+
/** Reject all pending tool calls with optional reason */
|
|
1242
|
+
rejectAll: (reason?: string) => void;
|
|
1243
|
+
}
|
|
1244
|
+
/**
|
|
1245
|
+
* Unified hook for the tool lifecycle: registration, waiter coordination,
|
|
1246
|
+
* and execution (including approval flow).
|
|
1247
|
+
*
|
|
1248
|
+
* Merges what were previously three separate concerns:
|
|
1249
|
+
* - Tool registry (registration, aggregation, ownership tracking)
|
|
1250
|
+
* - Waiters (waiting for component re-renders after tool execution)
|
|
1251
|
+
* - Tool execution (running tools, sending responses, approval flow)
|
|
1252
|
+
*
|
|
1253
|
+
* The only external dependency is `buildState` from prompt management,
|
|
1254
|
+
* which provides the aggregated app state sent alongside tool responses.
|
|
1255
|
+
*/
|
|
1256
|
+
declare function useToolSystem({ clientRef, buildState, }: UseToolSystemOptions): UseToolSystemReturn;
|
|
1257
|
+
|
|
1146
1258
|
/**
|
|
1147
1259
|
* Options for programmatically sending a message via sendMessage().
|
|
1148
1260
|
*/
|
|
@@ -1161,96 +1273,39 @@ interface SendMessageOptions {
|
|
|
1161
1273
|
*/
|
|
1162
1274
|
forwardedProps?: UseAIForwardedProps;
|
|
1163
1275
|
}
|
|
1164
|
-
interface
|
|
1165
|
-
/**
|
|
1166
|
-
|
|
1167
|
-
/**
|
|
1168
|
-
|
|
1169
|
-
/** Current messages state (owned by provider) */
|
|
1170
|
-
messages: Message[];
|
|
1171
|
-
/** Setter for messages state (owned by provider) */
|
|
1172
|
-
setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
|
|
1173
|
-
/** Callback to send a message (from UseAIProvider) */
|
|
1174
|
-
onSendMessage?: (message: string, attachments?: FileAttachment[], forwardedProps?: UseAIForwardedProps) => Promise<void>;
|
|
1276
|
+
interface UseMessageQueueOptions {
|
|
1277
|
+
/** The function that actually sends a message (the provider's handleSendMessage) */
|
|
1278
|
+
sendFn: (message: string, attachments?: FileAttachment[], forwardedProps?: UseAIForwardedProps) => Promise<void>;
|
|
1279
|
+
/** Creates a new chat */
|
|
1280
|
+
createNewChat: (options?: CreateChatOptions) => Promise<string>;
|
|
1175
1281
|
/** Callback to open/close the chat panel */
|
|
1176
1282
|
setOpen?: (open: boolean) => void;
|
|
1177
1283
|
/** Whether the client is connected */
|
|
1178
|
-
connected
|
|
1179
|
-
/** Whether the AI is currently loading/processing
|
|
1180
|
-
loading
|
|
1284
|
+
connected: boolean;
|
|
1285
|
+
/** Whether the AI is currently loading/processing */
|
|
1286
|
+
loading: boolean;
|
|
1181
1287
|
/** Whether there's a pending tool approval blocking the queue */
|
|
1182
|
-
hasPendingApproval
|
|
1288
|
+
hasPendingApproval: boolean;
|
|
1183
1289
|
}
|
|
1184
|
-
interface
|
|
1185
|
-
/** Current active chat ID where AI responses are saved */
|
|
1186
|
-
currentChatId: string | null;
|
|
1187
|
-
/** Chat loaded for viewing but not yet active for AI responses */
|
|
1188
|
-
pendingChatId: string | null;
|
|
1189
|
-
/** The displayed chat ID (pending or current) */
|
|
1190
|
-
displayedChatId: string | null;
|
|
1191
|
-
/** Creates a new chat and switches to it */
|
|
1192
|
-
createNewChat: (options?: CreateChatOptions) => Promise<string>;
|
|
1193
|
-
/** Loads an existing chat by ID */
|
|
1194
|
-
loadChat: (chatId: string) => Promise<void>;
|
|
1195
|
-
/** Deletes a chat by ID */
|
|
1196
|
-
deleteChat: (chatId: string) => Promise<void>;
|
|
1197
|
-
/** Lists all available chats */
|
|
1198
|
-
listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
|
|
1199
|
-
/** Clears the current chat messages */
|
|
1200
|
-
clearCurrentChat: () => Promise<void>;
|
|
1201
|
-
/** Activates the pending chat (called when user sends first message) */
|
|
1202
|
-
activatePendingChat: () => string | null;
|
|
1203
|
-
/** Saves a user message to storage and reloads messages */
|
|
1204
|
-
saveUserMessage: (chatId: string, content: PersistedMessageContent) => Promise<boolean>;
|
|
1205
|
-
/** Saves an AI response to storage and optionally reloads messages */
|
|
1206
|
-
saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string) => Promise<void>;
|
|
1207
|
-
/** Reloads messages from storage for the given chat ID */
|
|
1208
|
-
reloadMessages: (chatId: string) => Promise<void>;
|
|
1290
|
+
interface UseMessageQueueReturn {
|
|
1209
1291
|
/**
|
|
1210
1292
|
* Programmatically send a message to the chat.
|
|
1211
|
-
*
|
|
1293
|
+
* Messages are queued and processed one at a time.
|
|
1294
|
+
* Throws on failure (e.g., not connected, no sendFn).
|
|
1212
1295
|
*/
|
|
1213
1296
|
sendMessage: (message: string, options?: SendMessageOptions) => Promise<void>;
|
|
1214
|
-
/** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
|
|
1215
|
-
getCurrentChat: () => Promise<Chat | null>;
|
|
1216
|
-
/** Update metadata for the current chat */
|
|
1217
|
-
updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
|
|
1218
|
-
/** Snapshot refs for use in event handlers */
|
|
1219
|
-
currentChatIdSnapshot: React.MutableRefObject<string | null>;
|
|
1220
|
-
pendingChatIdSnapshot: React.MutableRefObject<string | null>;
|
|
1221
1297
|
}
|
|
1222
1298
|
/**
|
|
1223
|
-
* Hook for
|
|
1224
|
-
*
|
|
1225
|
-
* Features:
|
|
1226
|
-
* - Creates, loads, deletes chats
|
|
1227
|
-
* - Manages pending/active chat state machine
|
|
1228
|
-
* - Saves user messages and AI responses
|
|
1229
|
-
* - Auto-generates chat titles
|
|
1230
|
-
* - Initializes with most recent chat or creates new one
|
|
1299
|
+
* Hook for queuing and sending programmatic messages.
|
|
1231
1300
|
*
|
|
1232
|
-
*
|
|
1233
|
-
*
|
|
1234
|
-
*
|
|
1235
|
-
*
|
|
1236
|
-
*
|
|
1237
|
-
*
|
|
1238
|
-
* loadChat,
|
|
1239
|
-
* deleteChat,
|
|
1240
|
-
* listChats,
|
|
1241
|
-
* clearCurrentChat,
|
|
1242
|
-
* activatePendingChat,
|
|
1243
|
-
* saveUserMessage,
|
|
1244
|
-
* saveAIResponse,
|
|
1245
|
-
* } = useChatManagement({
|
|
1246
|
-
* repository: chatRepository,
|
|
1247
|
-
* clientRef,
|
|
1248
|
-
* messages,
|
|
1249
|
-
* setMessages,
|
|
1250
|
-
* });
|
|
1251
|
-
* ```
|
|
1301
|
+
* Handles:
|
|
1302
|
+
* - Message queuing (one at a time)
|
|
1303
|
+
* - Waiting for loading + approval to complete between messages
|
|
1304
|
+
* - Creating new chats before sending
|
|
1305
|
+
* - Opening the chat panel after sending
|
|
1306
|
+
* - Converting File[] to FileAttachment[]
|
|
1252
1307
|
*/
|
|
1253
|
-
declare function
|
|
1308
|
+
declare function useMessageQueue({ sendFn, createNewChat, setOpen, connected, loading, hasPendingApproval, }: UseMessageQueueOptions): UseMessageQueueReturn;
|
|
1254
1309
|
|
|
1255
1310
|
/**
|
|
1256
1311
|
* Chat management context (from useChatManagement hook).
|
|
@@ -1311,15 +1366,19 @@ interface CommandContextValue {
|
|
|
1311
1366
|
delete: (id: string) => Promise<void>;
|
|
1312
1367
|
}
|
|
1313
1368
|
/**
|
|
1314
|
-
* Tool
|
|
1369
|
+
* Tool system context (from useToolSystem hook).
|
|
1315
1370
|
*/
|
|
1316
1371
|
interface ToolRegistryContextValue {
|
|
1317
1372
|
/** Registers tools for a specific component */
|
|
1318
|
-
register: (id: string, tools: ToolsDefinition, options?:
|
|
1319
|
-
invisible?: boolean;
|
|
1320
|
-
}) => void;
|
|
1373
|
+
register: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
|
|
1321
1374
|
/** Unregisters tools for a specific component */
|
|
1322
1375
|
unregister: (id: string) => void;
|
|
1376
|
+
/** Signals that a component has completed registration in useLayoutEffect */
|
|
1377
|
+
signalReady: (id: string) => void;
|
|
1378
|
+
/** Registers a waiter function for a component */
|
|
1379
|
+
registerWaiter: (id: string, waiter: () => Promise<void>) => void;
|
|
1380
|
+
/** Unregisters a waiter function */
|
|
1381
|
+
unregisterWaiter: (id: string) => void;
|
|
1323
1382
|
}
|
|
1324
1383
|
/**
|
|
1325
1384
|
* Prompt management context.
|
|
@@ -1327,10 +1386,6 @@ interface ToolRegistryContextValue {
|
|
|
1327
1386
|
interface PromptsContextValue {
|
|
1328
1387
|
/** Updates the prompt and suggestions for a specific component */
|
|
1329
1388
|
update: (id: string, prompt?: string, suggestions?: string[]) => void;
|
|
1330
|
-
/** Registers a waiter function for a component */
|
|
1331
|
-
registerWaiter: (id: string, waiter: () => Promise<void>) => void;
|
|
1332
|
-
/** Unregisters a waiter function */
|
|
1333
|
-
unregisterWaiter: (id: string) => void;
|
|
1334
1389
|
}
|
|
1335
1390
|
/**
|
|
1336
1391
|
* Context value provided by UseAIProvider.
|
|
@@ -1343,15 +1398,15 @@ interface UseAIContextValue {
|
|
|
1343
1398
|
connected: boolean;
|
|
1344
1399
|
/** The underlying WebSocket client instance */
|
|
1345
1400
|
client: UseAIClient | null;
|
|
1346
|
-
/** Tool
|
|
1401
|
+
/** Tool system (registry, waiters, execution) */
|
|
1347
1402
|
tools: ToolRegistryContextValue;
|
|
1348
1403
|
/** Prompt management */
|
|
1349
1404
|
prompts: PromptsContextValue;
|
|
1350
|
-
/** Chat management
|
|
1405
|
+
/** Chat management */
|
|
1351
1406
|
chat: ChatContextValue;
|
|
1352
|
-
/** Agent selection
|
|
1407
|
+
/** Agent selection */
|
|
1353
1408
|
agents: AgentContextValue;
|
|
1354
|
-
/** Command management
|
|
1409
|
+
/** Command management */
|
|
1355
1410
|
commands: CommandContextValue;
|
|
1356
1411
|
}
|
|
1357
1412
|
/**
|
|
@@ -1557,18 +1612,6 @@ declare function UseAIProvider({ serverUrl, children, systemPrompt, CustomButton
|
|
|
1557
1612
|
/**
|
|
1558
1613
|
* Hook to access the UseAI context.
|
|
1559
1614
|
* When used outside a UseAIProvider, returns a no-op context and logs a warning.
|
|
1560
|
-
* This allows components with useAI hooks to render even when UseAIProvider
|
|
1561
|
-
* is conditionally not rendered (e.g., feature flagged).
|
|
1562
|
-
*
|
|
1563
|
-
* @returns The UseAI context value (or no-op if provider is missing)
|
|
1564
|
-
*
|
|
1565
|
-
* @example
|
|
1566
|
-
* ```typescript
|
|
1567
|
-
* function MyComponent() {
|
|
1568
|
-
* const { connected, client } = useAIContext();
|
|
1569
|
-
* return <div>Connected: {connected}</div>;
|
|
1570
|
-
* }
|
|
1571
|
-
* ```
|
|
1572
1615
|
*/
|
|
1573
1616
|
declare function useAIContext(): UseAIContextValue;
|
|
1574
1617
|
|
|
@@ -2018,6 +2061,63 @@ interface UseSlashCommandsReturn {
|
|
|
2018
2061
|
*/
|
|
2019
2062
|
declare function useSlashCommands({ commands, onCommandSelect, onSaveCommand, onRenameCommand, onDeleteCommand, }: UseSlashCommandsOptions): UseSlashCommandsReturn;
|
|
2020
2063
|
|
|
2064
|
+
interface UseChatManagementOptions {
|
|
2065
|
+
/** Chat repository for persistence */
|
|
2066
|
+
repository: ChatRepository;
|
|
2067
|
+
/** Reference to the UseAIClient (can be null during initialization) */
|
|
2068
|
+
clientRef: React.MutableRefObject<UseAIClient | null>;
|
|
2069
|
+
/** Current messages state (owned by provider) */
|
|
2070
|
+
messages: Message[];
|
|
2071
|
+
/** Setter for messages state (owned by provider) */
|
|
2072
|
+
setMessages: React.Dispatch<React.SetStateAction<Message[]>>;
|
|
2073
|
+
/** Whether the client is connected */
|
|
2074
|
+
connected?: boolean;
|
|
2075
|
+
}
|
|
2076
|
+
interface UseChatManagementReturn {
|
|
2077
|
+
/** Current active chat ID where AI responses are saved */
|
|
2078
|
+
currentChatId: string | null;
|
|
2079
|
+
/** Chat loaded for viewing but not yet active for AI responses */
|
|
2080
|
+
pendingChatId: string | null;
|
|
2081
|
+
/** The displayed chat ID (pending or current) */
|
|
2082
|
+
displayedChatId: string | null;
|
|
2083
|
+
/** Creates a new chat and switches to it */
|
|
2084
|
+
createNewChat: (options?: CreateChatOptions) => Promise<string>;
|
|
2085
|
+
/** Loads an existing chat by ID */
|
|
2086
|
+
loadChat: (chatId: string) => Promise<void>;
|
|
2087
|
+
/** Deletes a chat by ID */
|
|
2088
|
+
deleteChat: (chatId: string) => Promise<void>;
|
|
2089
|
+
/** Lists all available chats */
|
|
2090
|
+
listChats: () => Promise<Array<Omit<Chat, 'messages'>>>;
|
|
2091
|
+
/** Clears the current chat messages */
|
|
2092
|
+
clearCurrentChat: () => Promise<void>;
|
|
2093
|
+
/** Activates the pending chat (called when user sends first message) */
|
|
2094
|
+
activatePendingChat: () => string | null;
|
|
2095
|
+
/** Saves a user message to storage and reloads messages */
|
|
2096
|
+
saveUserMessage: (chatId: string, content: PersistedMessageContent) => Promise<boolean>;
|
|
2097
|
+
/** Saves an AI response to storage and optionally reloads messages */
|
|
2098
|
+
saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string) => Promise<void>;
|
|
2099
|
+
/** Reloads messages from storage for the given chat ID */
|
|
2100
|
+
reloadMessages: (chatId: string) => Promise<void>;
|
|
2101
|
+
/** Get the current chat object. Metadata is frozen to prevent accidental mutation. */
|
|
2102
|
+
getCurrentChat: () => Promise<Chat | null>;
|
|
2103
|
+
/** Update metadata for the current chat */
|
|
2104
|
+
updateMetadata: (metadata: ChatMetadata, overwrite?: boolean) => Promise<void>;
|
|
2105
|
+
/** Snapshot refs for use in event handlers */
|
|
2106
|
+
currentChatIdSnapshot: React.MutableRefObject<string | null>;
|
|
2107
|
+
pendingChatIdSnapshot: React.MutableRefObject<string | null>;
|
|
2108
|
+
}
|
|
2109
|
+
/**
|
|
2110
|
+
* Hook for managing chat lifecycle operations.
|
|
2111
|
+
*
|
|
2112
|
+
* Features:
|
|
2113
|
+
* - Creates, loads, deletes chats
|
|
2114
|
+
* - Manages pending/active chat state machine
|
|
2115
|
+
* - Saves user messages and AI responses
|
|
2116
|
+
* - Auto-generates chat titles
|
|
2117
|
+
* - Initializes with most recent chat or creates new one
|
|
2118
|
+
*/
|
|
2119
|
+
declare function useChatManagement({ repository, clientRef, messages, setMessages, connected, }: UseChatManagementOptions): UseChatManagementReturn;
|
|
2120
|
+
|
|
2021
2121
|
interface UseAgentSelectionOptions {
|
|
2022
2122
|
/** Reference to the UseAIClient (can be null during initialization) */
|
|
2023
2123
|
clientRef: React.MutableRefObject<UseAIClient | null>;
|
|
@@ -2125,33 +2225,6 @@ interface UseCommandManagementReturn {
|
|
|
2125
2225
|
*/
|
|
2126
2226
|
declare function useCommandManagement({ repository, }?: UseCommandManagementOptions): UseCommandManagementReturn;
|
|
2127
2227
|
|
|
2128
|
-
interface RegisterToolsOptions {
|
|
2129
|
-
/** Mark component as invisible (no visual state, skip prompt wait) */
|
|
2130
|
-
invisible?: boolean;
|
|
2131
|
-
}
|
|
2132
|
-
interface UseToolRegistryReturn {
|
|
2133
|
-
/** Registers tools for a specific component */
|
|
2134
|
-
registerTools: (id: string, tools: ToolsDefinition, options?: RegisterToolsOptions) => void;
|
|
2135
|
-
/** Unregisters tools for a specific component */
|
|
2136
|
-
unregisterTools: (id: string) => void;
|
|
2137
|
-
/** Checks if a component is marked as invisible */
|
|
2138
|
-
isInvisible: (id: string) => boolean;
|
|
2139
|
-
/** All tools aggregated from registered components */
|
|
2140
|
-
aggregatedTools: ToolsDefinition;
|
|
2141
|
-
/** Whether any tools are registered */
|
|
2142
|
-
hasTools: boolean;
|
|
2143
|
-
/** Ref to current aggregated tools (for use in closures) */
|
|
2144
|
-
aggregatedToolsRef: React.MutableRefObject<ToolsDefinition>;
|
|
2145
|
-
/** Ref mapping tool names to component IDs */
|
|
2146
|
-
toolOwnershipRef: React.MutableRefObject<Map<string, string>>;
|
|
2147
|
-
}
|
|
2148
|
-
/**
|
|
2149
|
-
* Hook for managing tool registration and aggregation.
|
|
2150
|
-
*
|
|
2151
|
-
* Only handles tools - prompt management is handled separately.
|
|
2152
|
-
*/
|
|
2153
|
-
declare function useToolRegistry(): UseToolRegistryReturn;
|
|
2154
|
-
|
|
2155
2228
|
interface UsePromptStateOptions {
|
|
2156
2229
|
/** System prompt to include in state */
|
|
2157
2230
|
systemPrompt?: string;
|
|
@@ -2163,16 +2236,12 @@ interface UsePromptStateOptions {
|
|
|
2163
2236
|
interface UsePromptStateReturn {
|
|
2164
2237
|
/** Updates the prompt and suggestions for a specific component */
|
|
2165
2238
|
updatePrompt: (id: string, prompt?: string, suggestions?: string[]) => void;
|
|
2166
|
-
/** Registers a waiter function for a component */
|
|
2167
|
-
registerWaiter: (id: string, waiter: () => Promise<void>) => void;
|
|
2168
|
-
/** Unregisters a waiter function */
|
|
2169
|
-
unregisterWaiter: (id: string) => void;
|
|
2170
|
-
/** Gets the waiter function for a component */
|
|
2171
|
-
getWaiter: (id: string) => (() => Promise<void>) | undefined;
|
|
2172
2239
|
/** All suggestions aggregated from registered components */
|
|
2173
2240
|
aggregatedSuggestions: string[];
|
|
2174
|
-
/**
|
|
2175
|
-
|
|
2241
|
+
/** Builds the aggregated state from all registered prompts */
|
|
2242
|
+
buildStateFromPrompts: () => {
|
|
2243
|
+
context: string;
|
|
2244
|
+
} | null;
|
|
2176
2245
|
}
|
|
2177
2246
|
/**
|
|
2178
2247
|
* Hook for managing prompt state across multiple useAI hooks.
|
|
@@ -2180,11 +2249,56 @@ interface UsePromptStateReturn {
|
|
|
2180
2249
|
* Handles:
|
|
2181
2250
|
* - Storing prompts and suggestions per component
|
|
2182
2251
|
* - Updating client state when prompts change
|
|
2183
|
-
* - Managing waiter functions for prompt change notifications
|
|
2184
2252
|
* - Aggregating suggestions from all components
|
|
2185
2253
|
*/
|
|
2186
2254
|
declare function usePromptState({ systemPrompt, clientRef, connected, }: UsePromptStateOptions): UsePromptStateReturn;
|
|
2187
2255
|
|
|
2256
|
+
interface UseServerEventsOptions {
|
|
2257
|
+
/** Tool system for executing tools and looking up tool metadata */
|
|
2258
|
+
toolSystem: UseToolSystemReturn;
|
|
2259
|
+
/** Saves an AI response to chat storage */
|
|
2260
|
+
saveAIResponse: (content: string, displayMode?: 'default' | 'error', traceId?: string) => Promise<void>;
|
|
2261
|
+
/** UI strings for error messages and tool execution fallbacks */
|
|
2262
|
+
strings: UseAIStrings;
|
|
2263
|
+
}
|
|
2264
|
+
interface ExecutingToolDisplay {
|
|
2265
|
+
displayText: string;
|
|
2266
|
+
}
|
|
2267
|
+
interface UseServerEventsReturn {
|
|
2268
|
+
/** Whether the AI is currently loading/processing a response */
|
|
2269
|
+
loading: boolean;
|
|
2270
|
+
/** Set the loading state (e.g., when sending a message) */
|
|
2271
|
+
setLoading: React.Dispatch<React.SetStateAction<boolean>>;
|
|
2272
|
+
/** Current streaming text from the AI response */
|
|
2273
|
+
streamingText: string;
|
|
2274
|
+
/** Clear streaming text (e.g., when starting a new message) */
|
|
2275
|
+
clearStreamingText: () => void;
|
|
2276
|
+
/** Currently executing tool info for UI display, or null */
|
|
2277
|
+
executingTool: ExecutingToolDisplay | null;
|
|
2278
|
+
/** Ref tracking which chat the current streaming text belongs to */
|
|
2279
|
+
streamingChatIdRef: React.MutableRefObject<string | null>;
|
|
2280
|
+
/**
|
|
2281
|
+
* Handles a server event. Called from the provider's client subscription.
|
|
2282
|
+
* Takes the client instance so it can access client-internal state
|
|
2283
|
+
* (currentToolCalls, currentMessageContent).
|
|
2284
|
+
*/
|
|
2285
|
+
handleServerEvent: (client: UseAIClient, event: AGUIEvent) => Promise<void>;
|
|
2286
|
+
}
|
|
2287
|
+
/**
|
|
2288
|
+
* Hook that owns all server event handling state and logic.
|
|
2289
|
+
*
|
|
2290
|
+
* Manages:
|
|
2291
|
+
* - Loading state (set on message send, cleared on RUN_FINISHED/RUN_ERROR)
|
|
2292
|
+
* - Streaming text accumulation (TEXT_MESSAGE_CONTENT/END events)
|
|
2293
|
+
* - Executing tool display (TOOL_CALL_START/END events)
|
|
2294
|
+
* - Tool execution dispatch (delegates to toolSystem)
|
|
2295
|
+
* - Error handling (RUN_ERROR events)
|
|
2296
|
+
*
|
|
2297
|
+
* The provider creates the client and subscribes `handleServerEvent` to it.
|
|
2298
|
+
* This hook doesn't manage the client lifecycle — only the event handling.
|
|
2299
|
+
*/
|
|
2300
|
+
declare function useServerEvents({ toolSystem, saveAIResponse, strings, }: UseServerEventsOptions): UseServerEventsReturn;
|
|
2301
|
+
|
|
2188
2302
|
interface UseFeedbackOptions {
|
|
2189
2303
|
/** Reference to the UseAIClient */
|
|
2190
2304
|
clientRef: React.MutableRefObject<UseAIClient | null>;
|
|
@@ -2304,4 +2418,4 @@ interface UseDropdownStateOptions {
|
|
|
2304
2418
|
*/
|
|
2305
2419
|
declare function useDropdownState(options?: UseDropdownStateOptions): UseDropdownStateReturn;
|
|
2306
2420
|
|
|
2307
|
-
export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type
|
|
2421
|
+
export { type AgentContextValue, type Chat, type ChatContextValue, type ChatMetadata, type ChatPanelProps, type ChatRepository, CloseButton, type CommandContextValue, type CommandRepository, type CreateChatOptions, type CreateCommandOptions, DEFAULT_MAX_FILE_SIZE, type DefinedTool, type DropZoneProps, EmbedFileUploadBackend, type ExecutingToolDisplay, type FileAttachment, type FileProcessingState, type FileProcessingStatus, type FileTransformer, type FileTransformerContext, type FileTransformerMap, type FileUploadBackend, type FileUploadConfig, type FloatingButtonProps, type InlineSaveProps, type ListChatsOptions, type ListCommandsOptions, LocalStorageChatRepository, LocalStorageCommandRepository, type Message, type PendingToolApproval, type PersistedContentPart, type PersistedFileContent, type PersistedFileMetadata, type PersistedMessage, type PersistedMessageContent, type PersistedTextContent, type ProcessAttachmentsConfig, type PromptsContextValue, type RegisterToolsOptions, type SavedCommand, type SendMessageOptions, type ToolExecutionContext, type ToolOptions, type ToolRegistryContextValue, type ToolsDefinition, type TriggerWorkflowOptions, UseAIChat, UseAIChatPanel, type UseAIChatPanelProps, type UseAIChatPanelStrings, type UseAIChatPanelTheme, type UseAIChatProps, UseAIClient, type UseAIConfig, type UseAIContextValue, UseAIFloatingButton, UseAIFloatingChatWrapper, type UseAIOptions, UseAIProvider, type UseAIProviderProps, type UseAIResult, type UseAIStrings, type UseAITheme, type UseAIWorkflowResult, type UseAgentSelectionOptions, type UseAgentSelectionReturn, type UseChatManagementOptions, type UseChatManagementReturn, type UseCommandManagementOptions, type UseCommandManagementReturn, type UseDropdownStateOptions, type UseDropdownStateReturn, type UseFeedbackOptions, type UseFeedbackReturn, type UseFileUploadOptions, type UseFileUploadReturn, type UseMessageQueueOptions, type UseMessageQueueReturn, type UsePromptStateOptions, type UsePromptStateReturn, type UseServerEventsOptions, type UseServerEventsReturn, type UseSlashCommandsOptions, type UseSlashCommandsReturn, type UseToolSystemOptions, type UseToolSystemReturn, type WorkflowProgress, clearTransformationCache, convertToolsToDefinitions, defaultStrings, defaultTheme, defineTool, executeDefinedTool, findTransformerPattern, generateChatId, generateCommandId, generateMessageId, matchesMimeType, processAttachments, useAI, useAIContext, useAIWorkflow, useAgentSelection, useChatManagement, useCommandManagement, useDropdownState, useFeedback, useFileUpload, useMessageQueue, usePromptState, useServerEvents, useSlashCommands, useStableTools, useStrings, useTheme, useToolSystem, validateCommandName };
|