@jupyterlite/ai 0.8.1 → 0.9.0-a1

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 (162) hide show
  1. package/lib/agent.d.ts +243 -0
  2. package/lib/agent.js +627 -0
  3. package/lib/chat-model.d.ts +195 -0
  4. package/lib/chat-model.js +591 -0
  5. package/lib/completion/completion-provider.d.ts +93 -0
  6. package/lib/completion/completion-provider.js +235 -0
  7. package/lib/completion/index.d.ts +1 -0
  8. package/lib/completion/index.js +1 -0
  9. package/lib/components/clear-button.d.ts +18 -0
  10. package/lib/components/clear-button.js +31 -0
  11. package/lib/components/index.d.ts +3 -0
  12. package/lib/components/index.js +3 -0
  13. package/lib/components/model-select.d.ts +19 -0
  14. package/lib/components/model-select.js +154 -0
  15. package/lib/components/stop-button.d.ts +3 -3
  16. package/lib/components/stop-button.js +8 -9
  17. package/lib/components/token-usage-display.d.ts +45 -0
  18. package/lib/components/token-usage-display.js +74 -0
  19. package/lib/components/tool-select.d.ts +27 -0
  20. package/lib/components/tool-select.js +130 -0
  21. package/lib/icons.d.ts +3 -1
  22. package/lib/icons.js +10 -13
  23. package/lib/index.d.ts +5 -5
  24. package/lib/index.js +341 -169
  25. package/lib/mcp/browser.d.ts +68 -0
  26. package/lib/mcp/browser.js +132 -0
  27. package/lib/models/settings-model.d.ts +70 -0
  28. package/lib/models/settings-model.js +296 -0
  29. package/lib/providers/built-in-providers.d.ts +9 -0
  30. package/lib/providers/built-in-providers.js +266 -0
  31. package/lib/providers/models.d.ts +37 -0
  32. package/lib/providers/models.js +28 -0
  33. package/lib/providers/provider-registry.d.ts +94 -0
  34. package/lib/providers/provider-registry.js +155 -0
  35. package/lib/tokens.d.ts +167 -86
  36. package/lib/tokens.js +25 -12
  37. package/lib/tools/commands.d.ts +11 -0
  38. package/lib/tools/commands.js +126 -0
  39. package/lib/tools/file.d.ts +27 -0
  40. package/lib/tools/file.js +262 -0
  41. package/lib/tools/notebook.d.ts +41 -0
  42. package/lib/tools/notebook.js +779 -0
  43. package/lib/tools/tool-registry.d.ts +35 -0
  44. package/lib/tools/tool-registry.js +55 -0
  45. package/lib/widgets/ai-settings.d.ts +49 -0
  46. package/lib/widgets/ai-settings.js +580 -0
  47. package/lib/widgets/chat-wrapper.d.ts +144 -0
  48. package/lib/widgets/chat-wrapper.js +390 -0
  49. package/lib/widgets/provider-config-dialog.d.ts +14 -0
  50. package/lib/widgets/provider-config-dialog.js +112 -0
  51. package/package.json +151 -40
  52. package/schema/settings-model.json +159 -0
  53. package/src/agent.ts +836 -0
  54. package/src/chat-model.ts +771 -0
  55. package/src/completion/completion-provider.ts +346 -0
  56. package/src/completion/index.ts +1 -0
  57. package/src/components/clear-button.tsx +56 -0
  58. package/src/components/index.ts +3 -0
  59. package/src/components/model-select.tsx +245 -0
  60. package/src/components/stop-button.tsx +11 -11
  61. package/src/components/token-usage-display.tsx +130 -0
  62. package/src/components/tool-select.tsx +218 -0
  63. package/src/icons.ts +12 -14
  64. package/src/index.ts +485 -232
  65. package/src/mcp/browser.ts +213 -0
  66. package/src/models/settings-model.ts +413 -0
  67. package/src/providers/built-in-providers.ts +294 -0
  68. package/src/providers/models.ts +79 -0
  69. package/src/providers/provider-registry.ts +189 -0
  70. package/src/tokens.ts +217 -90
  71. package/src/tools/commands.ts +151 -0
  72. package/src/tools/file.ts +307 -0
  73. package/src/tools/notebook.ts +987 -0
  74. package/src/tools/tool-registry.ts +63 -0
  75. package/src/types.d.ts +4 -0
  76. package/src/widgets/ai-settings.tsx +1233 -0
  77. package/src/widgets/chat-wrapper.tsx +543 -0
  78. package/src/widgets/provider-config-dialog.tsx +272 -0
  79. package/style/base.css +335 -14
  80. package/style/icons/jupyternaut-lite.svg +1 -1
  81. package/lib/base-completer.d.ts +0 -49
  82. package/lib/base-completer.js +0 -14
  83. package/lib/chat-handler.d.ts +0 -56
  84. package/lib/chat-handler.js +0 -201
  85. package/lib/completion-provider.d.ts +0 -34
  86. package/lib/completion-provider.js +0 -32
  87. package/lib/default-prompts.d.ts +0 -2
  88. package/lib/default-prompts.js +0 -31
  89. package/lib/default-providers/Anthropic/completer.d.ts +0 -12
  90. package/lib/default-providers/Anthropic/completer.js +0 -46
  91. package/lib/default-providers/Anthropic/settings-schema.json +0 -70
  92. package/lib/default-providers/ChromeAI/completer.d.ts +0 -12
  93. package/lib/default-providers/ChromeAI/completer.js +0 -56
  94. package/lib/default-providers/ChromeAI/instructions.d.ts +0 -6
  95. package/lib/default-providers/ChromeAI/instructions.js +0 -42
  96. package/lib/default-providers/ChromeAI/settings-schema.json +0 -18
  97. package/lib/default-providers/Gemini/completer.d.ts +0 -12
  98. package/lib/default-providers/Gemini/completer.js +0 -48
  99. package/lib/default-providers/Gemini/instructions.d.ts +0 -2
  100. package/lib/default-providers/Gemini/instructions.js +0 -9
  101. package/lib/default-providers/Gemini/settings-schema.json +0 -64
  102. package/lib/default-providers/MistralAI/completer.d.ts +0 -13
  103. package/lib/default-providers/MistralAI/completer.js +0 -52
  104. package/lib/default-providers/MistralAI/instructions.d.ts +0 -2
  105. package/lib/default-providers/MistralAI/instructions.js +0 -18
  106. package/lib/default-providers/MistralAI/settings-schema.json +0 -75
  107. package/lib/default-providers/Ollama/completer.d.ts +0 -12
  108. package/lib/default-providers/Ollama/completer.js +0 -43
  109. package/lib/default-providers/Ollama/instructions.d.ts +0 -2
  110. package/lib/default-providers/Ollama/instructions.js +0 -70
  111. package/lib/default-providers/Ollama/settings-schema.json +0 -143
  112. package/lib/default-providers/OpenAI/completer.d.ts +0 -12
  113. package/lib/default-providers/OpenAI/completer.js +0 -43
  114. package/lib/default-providers/OpenAI/settings-schema.json +0 -628
  115. package/lib/default-providers/WebLLM/completer.d.ts +0 -21
  116. package/lib/default-providers/WebLLM/completer.js +0 -127
  117. package/lib/default-providers/WebLLM/instructions.d.ts +0 -6
  118. package/lib/default-providers/WebLLM/instructions.js +0 -32
  119. package/lib/default-providers/WebLLM/settings-schema.json +0 -19
  120. package/lib/default-providers/index.d.ts +0 -2
  121. package/lib/default-providers/index.js +0 -179
  122. package/lib/provider.d.ts +0 -144
  123. package/lib/provider.js +0 -412
  124. package/lib/settings/base.json +0 -7
  125. package/lib/settings/index.d.ts +0 -3
  126. package/lib/settings/index.js +0 -3
  127. package/lib/settings/panel.d.ts +0 -226
  128. package/lib/settings/panel.js +0 -510
  129. package/lib/settings/textarea.d.ts +0 -2
  130. package/lib/settings/textarea.js +0 -18
  131. package/lib/settings/utils.d.ts +0 -2
  132. package/lib/settings/utils.js +0 -4
  133. package/lib/types/ai-model.d.ts +0 -24
  134. package/lib/types/ai-model.js +0 -5
  135. package/schema/chat.json +0 -28
  136. package/schema/provider-registry.json +0 -29
  137. package/schema/system-prompts.json +0 -22
  138. package/src/base-completer.ts +0 -75
  139. package/src/chat-handler.ts +0 -262
  140. package/src/completion-provider.ts +0 -64
  141. package/src/default-prompts.ts +0 -33
  142. package/src/default-providers/Anthropic/completer.ts +0 -59
  143. package/src/default-providers/ChromeAI/completer.ts +0 -73
  144. package/src/default-providers/ChromeAI/instructions.ts +0 -45
  145. package/src/default-providers/Gemini/completer.ts +0 -61
  146. package/src/default-providers/Gemini/instructions.ts +0 -9
  147. package/src/default-providers/MistralAI/completer.ts +0 -69
  148. package/src/default-providers/MistralAI/instructions.ts +0 -18
  149. package/src/default-providers/Ollama/completer.ts +0 -54
  150. package/src/default-providers/Ollama/instructions.ts +0 -70
  151. package/src/default-providers/OpenAI/completer.ts +0 -54
  152. package/src/default-providers/WebLLM/completer.ts +0 -151
  153. package/src/default-providers/WebLLM/instructions.ts +0 -33
  154. package/src/default-providers/index.ts +0 -211
  155. package/src/global.d.ts +0 -9
  156. package/src/provider.ts +0 -514
  157. package/src/settings/index.ts +0 -3
  158. package/src/settings/panel.tsx +0 -773
  159. package/src/settings/textarea.tsx +0 -33
  160. package/src/settings/utils.ts +0 -5
  161. package/src/types/ai-model.ts +0 -37
  162. package/src/types/service-worker.d.ts +0 -6
package/src/agent.ts ADDED
@@ -0,0 +1,836 @@
1
+ import { ISignal, Signal } from '@lumino/signaling';
2
+ import {
3
+ Agent,
4
+ AgentInputItem,
5
+ Runner,
6
+ RunToolApprovalItem,
7
+ RunToolCallOutputItem,
8
+ StreamedRunResult,
9
+ user
10
+ } from '@openai/agents';
11
+ import { ISecretsManager } from 'jupyter-secrets-manager';
12
+
13
+ import { BrowserMCPServerStreamableHttp } from './mcp/browser';
14
+ import { AISettingsModel } from './models/settings-model';
15
+ import { createModel } from './providers/models';
16
+ import type { IChatProviderRegistry } from './tokens';
17
+ import { ITool, IToolRegistry, ITokenUsage, SECRETS_NAMESPACE } from './tokens';
18
+
19
+ /**
20
+ * Event type mapping for type safety with inlined interface definitions
21
+ */
22
+ export interface IAgentEventTypeMap {
23
+ message_start: {
24
+ messageId: string;
25
+ };
26
+ message_chunk: {
27
+ messageId: string;
28
+ chunk: string;
29
+ fullContent: string;
30
+ };
31
+ message_complete: {
32
+ messageId: string;
33
+ content: string;
34
+ };
35
+ tool_call_start: {
36
+ callId: string;
37
+ toolName: string;
38
+ input: any;
39
+ };
40
+ tool_call_complete: {
41
+ callId: string;
42
+ toolName: string;
43
+ output: any;
44
+ isError: boolean;
45
+ };
46
+ tool_approval_required: {
47
+ interruptionId: string;
48
+ toolName: string;
49
+ toolInput: any;
50
+ callId?: string;
51
+ };
52
+ grouped_approval_required: {
53
+ groupId: string;
54
+ approvals: Array<{
55
+ interruptionId: string;
56
+ toolName: string;
57
+ toolInput: any;
58
+ }>;
59
+ };
60
+ error: {
61
+ error: Error;
62
+ };
63
+ }
64
+
65
+ /**
66
+ * Events emitted by the AgentManager
67
+ */
68
+ export type IAgentEvent<
69
+ T extends keyof IAgentEventTypeMap = keyof IAgentEventTypeMap
70
+ > = T extends keyof IAgentEventTypeMap
71
+ ? {
72
+ type: T;
73
+ data: IAgentEventTypeMap[T];
74
+ }
75
+ : never;
76
+
77
+ /**
78
+ * Configuration options for the AgentManager
79
+ */
80
+ export interface IAgentManagerOptions {
81
+ /**
82
+ * AI settings model for configuration
83
+ */
84
+ settingsModel: AISettingsModel;
85
+
86
+ /**
87
+ * Optional tool registry for managing available tools
88
+ */
89
+ toolRegistry?: IToolRegistry;
90
+
91
+ /**
92
+ * Optional chat provider registry for model creation
93
+ */
94
+ chatProviderRegistry?: IChatProviderRegistry;
95
+
96
+ /**
97
+ * The secrets manager.
98
+ */
99
+ secretsManager?: ISecretsManager;
100
+ /**
101
+ * The token used to request the secrets manager.
102
+ */
103
+ token: symbol;
104
+ }
105
+
106
+ /**
107
+ * Manages the AI agent lifecycle and execution loop.
108
+ * Provides agent initialization, tool management, MCP server integration,
109
+ * and handles the complete agent execution cycle including tool approvals.
110
+ * Emits events for UI updates instead of directly manipulating the chat interface.
111
+ */
112
+ export class AgentManager {
113
+ /**
114
+ * Creates a new AgentManager instance.
115
+ * @param options Configuration options for the agent manager
116
+ */
117
+ constructor(options: IAgentManagerOptions) {
118
+ Private.setToken(options.token);
119
+ this._settingsModel = options.settingsModel;
120
+ this._toolRegistry = options.toolRegistry;
121
+ this._chatProviderRegistry = options.chatProviderRegistry;
122
+ this._secretsManager = options.secretsManager;
123
+ this._selectedToolNames = [];
124
+ this._agent = null;
125
+ this._runner = new Runner({ tracingDisabled: true });
126
+ this._history = [];
127
+ this._mcpServers = [];
128
+ this._isInitializing = false;
129
+ this._controller = null;
130
+ this._pendingApprovals = new Map();
131
+ this._interruptedState = null;
132
+ this._agentEvent = new Signal<this, IAgentEvent>(this);
133
+ this._mcpConnectionChanged = new Signal<this, boolean>(this);
134
+ this._tokenUsage = { inputTokens: 0, outputTokens: 0 };
135
+ this._tokenUsageChanged = new Signal<this, ITokenUsage>(this);
136
+
137
+ // Initialize selected tools to all available tools by default
138
+ if (this._toolRegistry) {
139
+ this._selectedToolNames = Object.keys(this._toolRegistry.tools);
140
+ }
141
+
142
+ // Initialize agent on construction
143
+ this._initializeAgent().catch(error =>
144
+ console.warn('Failed to initialize agent in constructor:', error)
145
+ );
146
+
147
+ // Listen for settings changes
148
+ this._settingsModel.stateChanged.connect(this._onSettingsChanged, this);
149
+ }
150
+
151
+ /**
152
+ * Signal emitted when agent events occur
153
+ */
154
+ get agentEvent(): ISignal<this, IAgentEvent> {
155
+ return this._agentEvent;
156
+ }
157
+
158
+ /**
159
+ * Signal emitted when MCP connection status changes
160
+ */
161
+ get mcpConnectionChanged(): ISignal<this, boolean> {
162
+ return this._mcpConnectionChanged;
163
+ }
164
+
165
+ /**
166
+ * Gets the current token usage statistics.
167
+ */
168
+ get tokenUsage(): ITokenUsage {
169
+ return this._tokenUsage;
170
+ }
171
+
172
+ /**
173
+ * Signal emitted when token usage statistics change.
174
+ */
175
+ get tokenUsageChanged(): ISignal<this, ITokenUsage> {
176
+ return this._tokenUsageChanged;
177
+ }
178
+
179
+ /**
180
+ * Sets the selected tools by name and reinitializes the agent.
181
+ * @param toolNames Array of tool names to select
182
+ */
183
+ setSelectedTools(toolNames: string[]): void {
184
+ this._selectedToolNames = [...toolNames];
185
+ this._initializeAgent().catch(error =>
186
+ console.warn('Failed to initialize agent on tools change:', error)
187
+ );
188
+ }
189
+
190
+ /**
191
+ * Gets the currently selected tools as OpenAI agents tools.
192
+ * @returns Array of selected tools formatted for OpenAI agents
193
+ */
194
+ get selectedAgentTools(): ITool[] {
195
+ if (!this._toolRegistry) {
196
+ return [];
197
+ }
198
+
199
+ const result: ITool[] = [];
200
+ for (const name of this._selectedToolNames) {
201
+ const tool: ITool | null = this._toolRegistry.get(name);
202
+ if (tool) {
203
+ result.push(tool);
204
+ }
205
+ }
206
+
207
+ return result;
208
+ }
209
+
210
+ /**
211
+ * Checks if a specific MCP server is connected by server name.
212
+ * @param serverName The name of the MCP server to check
213
+ * @returns True if the server is connected, false otherwise
214
+ */
215
+ isMCPServerConnected(serverName: string): boolean {
216
+ return this._mcpServers.some(server => server.name === serverName);
217
+ }
218
+
219
+ /**
220
+ * Checks if the current configuration is valid for agent operations.
221
+ * Uses the provider registry to determine if an API key is required.
222
+ * @returns True if the configuration is valid, false otherwise
223
+ */
224
+ hasValidConfig(): boolean {
225
+ const activeProvider = this._settingsModel.getActiveProvider();
226
+ if (!activeProvider) {
227
+ return false;
228
+ }
229
+
230
+ if (!activeProvider.model) {
231
+ return false;
232
+ }
233
+
234
+ if (this._chatProviderRegistry) {
235
+ const providerInfo = this._chatProviderRegistry.getProviderInfo(
236
+ activeProvider.provider
237
+ );
238
+ if (providerInfo?.requiresApiKey) {
239
+ return !!activeProvider.apiKey;
240
+ }
241
+ }
242
+
243
+ return true;
244
+ }
245
+
246
+ /**
247
+ * Clears conversation history and resets agent state.
248
+ * Removes all conversation history, pending approvals, and interrupted state.
249
+ */
250
+ clearHistory(): void {
251
+ this._history = [];
252
+ this._runner = new Runner();
253
+ this._pendingApprovals.clear();
254
+ this._interruptedState = null;
255
+ // Reset token usage
256
+ this._tokenUsage = { inputTokens: 0, outputTokens: 0 };
257
+ this._tokenUsageChanged.emit(this._tokenUsage);
258
+ }
259
+
260
+ /**
261
+ * Stops the current streaming response by aborting the request.
262
+ */
263
+ stopStreaming(): void {
264
+ this._controller?.abort();
265
+ }
266
+
267
+ /**
268
+ * Generates AI response to user message using the agent.
269
+ * Handles the complete execution cycle including tool calls and approvals.
270
+ * @param message The user message to respond to (may include processed attachment content)
271
+ */
272
+ async generateResponse(message: string): Promise<void> {
273
+ const config = this._settingsModel.config;
274
+ this._controller = new AbortController();
275
+
276
+ try {
277
+ // Ensure we have an agent
278
+ if (!this._agent) {
279
+ await this._initializeAgent();
280
+ }
281
+
282
+ if (!this._agent) {
283
+ throw new Error('Failed to initialize agent');
284
+ }
285
+
286
+ const shouldUseTools =
287
+ config.toolsEnabled &&
288
+ this._selectedToolNames.length > 0 &&
289
+ this._toolRegistry &&
290
+ Object.keys(this._toolRegistry.tools).length > 0 &&
291
+ this._supportsToolCalling();
292
+
293
+ // Add user message to history
294
+ this._history.push(user(message));
295
+
296
+ // Main agentic loop
297
+ let result = await this._runner.run(this._agent, this._history, {
298
+ stream: true,
299
+ signal: this._controller.signal,
300
+ ...(shouldUseTools && { maxTurns: config.maxTurns })
301
+ });
302
+
303
+ await this._processRunResult(result);
304
+
305
+ let hasInterruptions =
306
+ result.interruptions && result.interruptions.length > 0;
307
+
308
+ while (hasInterruptions) {
309
+ this._interruptedState = result;
310
+ const interruptions = result.interruptions!;
311
+
312
+ if (interruptions.length > 1) {
313
+ await this._handleGroupedToolApprovals(interruptions);
314
+ } else {
315
+ await this._handleSingleToolApproval(interruptions[0]);
316
+ }
317
+
318
+ // Wait for all approvals to be resolved
319
+ while (this._pendingApprovals.size > 0) {
320
+ await new Promise(resolve => setTimeout(resolve, 100));
321
+ }
322
+
323
+ // Continue execution
324
+ result = await this._runner.run(this._agent!, result.state, {
325
+ stream: true,
326
+ signal: this._controller.signal,
327
+ maxTurns: config.maxTurns
328
+ });
329
+
330
+ await this._processRunResult(result);
331
+ hasInterruptions =
332
+ result.interruptions && result.interruptions.length > 0;
333
+ }
334
+
335
+ // Clear interrupted state
336
+ this._interruptedState = null;
337
+ this._history = result.history;
338
+ } catch (error) {
339
+ this._agentEvent.emit({
340
+ type: 'error',
341
+ data: { error: error as Error }
342
+ });
343
+ } finally {
344
+ this._controller = null;
345
+ }
346
+ }
347
+
348
+ /**
349
+ * Approves a tool call by interruption ID.
350
+ * @param interruptionId The interruption ID to approve
351
+ */
352
+ async approveToolCall(interruptionId: string): Promise<void> {
353
+ const pending = this._pendingApprovals.get(interruptionId);
354
+ if (!pending) {
355
+ console.warn(
356
+ `No pending approval found for interruption ${interruptionId}`
357
+ );
358
+ return;
359
+ }
360
+
361
+ if (this._interruptedState) {
362
+ this._interruptedState.state.approve(pending.interruption);
363
+ }
364
+
365
+ pending.approved = true;
366
+ this._pendingApprovals.delete(interruptionId);
367
+ }
368
+
369
+ /**
370
+ * Rejects a tool call by interruption ID.
371
+ * @param interruptionId The interruption ID to reject
372
+ */
373
+ async rejectToolCall(interruptionId: string): Promise<void> {
374
+ const pending = this._pendingApprovals.get(interruptionId);
375
+ if (!pending) {
376
+ console.warn(
377
+ `No pending approval found for interruption ${interruptionId}`
378
+ );
379
+ return;
380
+ }
381
+
382
+ if (this._interruptedState) {
383
+ this._interruptedState.state.reject(pending.interruption);
384
+ }
385
+
386
+ pending.approved = false;
387
+ this._pendingApprovals.delete(interruptionId);
388
+ }
389
+
390
+ /**
391
+ * Approves all tools in a group by group ID.
392
+ * @param groupId The group ID containing the tool calls
393
+ * @param interruptionIds Array of interruption IDs to approve
394
+ */
395
+ async approveGroupedToolCalls(
396
+ groupId: string,
397
+ interruptionIds: string[]
398
+ ): Promise<void> {
399
+ for (const interruptionId of interruptionIds) {
400
+ const pending = this._pendingApprovals.get(interruptionId);
401
+ if (pending && pending.groupId === groupId) {
402
+ if (this._interruptedState) {
403
+ this._interruptedState.state.approve(pending.interruption);
404
+ }
405
+ pending.approved = true;
406
+ this._pendingApprovals.delete(interruptionId);
407
+ }
408
+ }
409
+ }
410
+
411
+ /**
412
+ * Rejects all tools in a group by group ID.
413
+ * @param groupId The group ID containing the tool calls
414
+ * @param interruptionIds Array of interruption IDs to reject
415
+ */
416
+ async rejectGroupedToolCalls(
417
+ groupId: string,
418
+ interruptionIds: string[]
419
+ ): Promise<void> {
420
+ for (const interruptionId of interruptionIds) {
421
+ const pending = this._pendingApprovals.get(interruptionId);
422
+ if (pending && pending.groupId === groupId) {
423
+ if (this._interruptedState) {
424
+ this._interruptedState.state.reject(pending.interruption);
425
+ }
426
+ pending.approved = false;
427
+ this._pendingApprovals.delete(interruptionId);
428
+ }
429
+ }
430
+ }
431
+
432
+ /**
433
+ * Handles settings changes and reinitializes the agent.
434
+ */
435
+ private _onSettingsChanged(): void {
436
+ this._initializeAgent().catch(error =>
437
+ console.warn('Failed to initialize agent on settings change:', error)
438
+ );
439
+ }
440
+
441
+ /**
442
+ * Initializes the AI agent with current settings and tools.
443
+ * Sets up the agent with model configuration, tools, and MCP servers.
444
+ */
445
+ private async _initializeAgent(): Promise<void> {
446
+ if (this._isInitializing) {
447
+ return;
448
+ }
449
+ this._isInitializing = true;
450
+
451
+ try {
452
+ const config = this._settingsModel.config;
453
+ const model = await this._createModel();
454
+
455
+ const shouldUseTools =
456
+ config.toolsEnabled &&
457
+ this._selectedToolNames.length > 0 &&
458
+ this._toolRegistry &&
459
+ Object.keys(this._toolRegistry.tools).length > 0 &&
460
+ this._supportsToolCalling();
461
+
462
+ await this._initializeMCPServers();
463
+
464
+ const tools = shouldUseTools ? this.selectedAgentTools : [];
465
+
466
+ const mcpServers = this._mcpServers.filter(server => server !== null);
467
+
468
+ this._agent = new Agent({
469
+ name: 'Assistant',
470
+ instructions: shouldUseTools
471
+ ? this._getEnhancedSystemPrompt(config.systemPrompt || '')
472
+ : config.systemPrompt || 'You are a helpful assistant.',
473
+ model: model,
474
+ mcpServers,
475
+ tools,
476
+ ...(config.temperature && {
477
+ modelSettings: {
478
+ temperature: config.temperature,
479
+ ...(config.maxTokens && { maxTokens: config.maxTokens })
480
+ }
481
+ })
482
+ });
483
+ } catch (error) {
484
+ console.warn('Failed to initialize agent:', error);
485
+ this._agent = null;
486
+ } finally {
487
+ this._isInitializing = false;
488
+ }
489
+ }
490
+
491
+ /**
492
+ * Initializes MCP (Model Context Protocol) servers based on current settings.
493
+ * Closes existing servers and connects to enabled servers from configuration.
494
+ */
495
+ private async _initializeMCPServers(): Promise<void> {
496
+ const config = this._settingsModel.config;
497
+ const enabledServers = config.mcpServers.filter(server => server.enabled);
498
+ let connectionChanged = false;
499
+
500
+ // Close existing servers
501
+ for (const server of this._mcpServers) {
502
+ try {
503
+ await server.close();
504
+ connectionChanged = true;
505
+ } catch (error) {
506
+ console.warn('Error closing MCP server:', error);
507
+ }
508
+ }
509
+ this._mcpServers = [];
510
+
511
+ // Initialize new servers
512
+ for (const serverConfig of enabledServers) {
513
+ try {
514
+ const mcpServer = new BrowserMCPServerStreamableHttp({
515
+ url: serverConfig.url,
516
+ name: serverConfig.name
517
+ });
518
+ await mcpServer.connect();
519
+ this._mcpServers.push(mcpServer);
520
+ connectionChanged = true;
521
+ } catch (error) {
522
+ console.warn(
523
+ `Failed to connect to MCP server "${serverConfig.name}" at ${serverConfig.url}:`,
524
+ error
525
+ );
526
+ }
527
+ }
528
+
529
+ // Emit connection change signal if there were any changes
530
+ if (connectionChanged) {
531
+ this._mcpConnectionChanged.emit(this._mcpServers.length > 0);
532
+ }
533
+ }
534
+
535
+ /**
536
+ * Processes the result stream from agent execution.
537
+ * Handles message streaming, tool calls, and emits appropriate events.
538
+ * @param result The async iterable result from agent execution
539
+ */
540
+ private async _processRunResult(
541
+ result: StreamedRunResult<any, any>
542
+ ): Promise<void> {
543
+ let fullResponse = '';
544
+ let currentMessageId: string | null = null;
545
+
546
+ for await (const event of result) {
547
+ if (event.type === 'raw_model_stream_event') {
548
+ const data = event.data;
549
+
550
+ if (data.type === 'response_started') {
551
+ currentMessageId = `msg-${Date.now()}-${Math.random()}`;
552
+ fullResponse = '';
553
+ this._agentEvent.emit({
554
+ type: 'message_start',
555
+ data: { messageId: currentMessageId }
556
+ });
557
+ } else if (data.type === 'output_text_delta') {
558
+ if (currentMessageId) {
559
+ const chunk = data.delta || '';
560
+ fullResponse += chunk;
561
+ this._agentEvent.emit({
562
+ type: 'message_chunk',
563
+ data: {
564
+ messageId: currentMessageId,
565
+ chunk,
566
+ fullContent: fullResponse
567
+ }
568
+ });
569
+ }
570
+ } else if (data.type === 'response_done') {
571
+ if (currentMessageId) {
572
+ this._agentEvent.emit({
573
+ type: 'message_complete',
574
+ data: {
575
+ messageId: currentMessageId,
576
+ content: fullResponse
577
+ }
578
+ });
579
+ currentMessageId = null;
580
+ }
581
+ } else if (data.type === 'model') {
582
+ const modelEvent = data.event as any;
583
+ if (modelEvent.type === 'tool-call') {
584
+ this._handleToolCallStart(modelEvent);
585
+ }
586
+ }
587
+ } else if (event.type === 'run_item_stream_event') {
588
+ if (event.name === 'tool_output') {
589
+ this._handleToolOutput(event);
590
+ }
591
+ }
592
+ }
593
+ }
594
+
595
+ /**
596
+ * Handles the start of a tool call from the model event.
597
+ * @param modelEvent The model event containing tool call information
598
+ */
599
+ private _handleToolCallStart(modelEvent: any): void {
600
+ const toolCallId = modelEvent.toolCallId;
601
+ const toolName = modelEvent.toolName;
602
+ const toolInput = modelEvent.input;
603
+ let parsedToolInput;
604
+ try {
605
+ parsedToolInput = JSON.parse(toolInput);
606
+ } catch (error) {
607
+ parsedToolInput = {};
608
+ }
609
+
610
+ this._agentEvent.emit({
611
+ type: 'tool_call_start',
612
+ data: {
613
+ callId: toolCallId,
614
+ toolName,
615
+ input: parsedToolInput
616
+ }
617
+ });
618
+ }
619
+
620
+ /**
621
+ * Handles tool execution output and completion.
622
+ * @param event The tool output event containing result information
623
+ */
624
+ private _handleToolOutput(event: any): void {
625
+ const toolEvent = event;
626
+ const toolCallOutput = toolEvent.item as RunToolCallOutputItem;
627
+ const callId = toolCallOutput.rawItem.callId;
628
+ const resultText =
629
+ typeof toolCallOutput.output === 'string'
630
+ ? toolCallOutput.output
631
+ : JSON.stringify(toolCallOutput.output, null, 2);
632
+
633
+ const isError =
634
+ toolCallOutput.rawItem.type === 'function_call_result' &&
635
+ (toolCallOutput.rawItem as any).error;
636
+
637
+ const toolName =
638
+ toolCallOutput.rawItem.type === 'function_call_result'
639
+ ? toolCallOutput.rawItem.name
640
+ : 'Unknown Tool';
641
+
642
+ this._agentEvent.emit({
643
+ type: 'tool_call_complete',
644
+ data: {
645
+ callId,
646
+ toolName,
647
+ output: resultText,
648
+ isError
649
+ }
650
+ });
651
+ }
652
+
653
+ /**
654
+ * Handles approval request for a single tool call.
655
+ * @param interruption The tool approval interruption item
656
+ */
657
+ private async _handleSingleToolApproval(
658
+ interruption: RunToolApprovalItem
659
+ ): Promise<void> {
660
+ const toolName = (interruption.rawItem as any)?.name || 'Unknown Tool';
661
+ const toolInput = (interruption.rawItem as any)?.arguments || {};
662
+ const interruptionId = `int-${Date.now()}-${Math.random()}`;
663
+ const callId = (interruption.rawItem as any)?.callId;
664
+
665
+ this._pendingApprovals.set(interruptionId, { interruption });
666
+
667
+ this._agentEvent.emit({
668
+ type: 'tool_approval_required',
669
+ data: {
670
+ interruptionId,
671
+ toolName,
672
+ toolInput,
673
+ callId
674
+ }
675
+ });
676
+ }
677
+
678
+ /**
679
+ * Handles approval requests for multiple grouped tool calls.
680
+ * @param interruptions Array of tool approval interruption items
681
+ */
682
+ private async _handleGroupedToolApprovals(
683
+ interruptions: RunToolApprovalItem[]
684
+ ): Promise<void> {
685
+ const groupId = `group-${Date.now()}-${Math.random()}`;
686
+ const approvals = interruptions.map(interruption => {
687
+ const toolName = (interruption.rawItem as any)?.name || 'Unknown Tool';
688
+ const toolInput = (interruption.rawItem as any)?.arguments || {};
689
+ const interruptionId = `int-${Date.now()}-${Math.random()}`;
690
+
691
+ this._pendingApprovals.set(interruptionId, { interruption, groupId });
692
+
693
+ return {
694
+ interruptionId,
695
+ toolName,
696
+ toolInput
697
+ };
698
+ });
699
+
700
+ this._agentEvent.emit({
701
+ type: 'grouped_approval_required',
702
+ data: {
703
+ groupId,
704
+ approvals
705
+ }
706
+ });
707
+ }
708
+
709
+ /**
710
+ * Checks if the current provider supports tool calling.
711
+ * @returns True if the provider supports tool calling, false otherwise
712
+ */
713
+ private _supportsToolCalling(): boolean {
714
+ const activeProvider = this._settingsModel.getActiveProvider();
715
+ if (!activeProvider || !this._chatProviderRegistry) {
716
+ return false;
717
+ }
718
+
719
+ const providerInfo = this._chatProviderRegistry.getProviderInfo(
720
+ activeProvider.provider
721
+ );
722
+
723
+ // Default to true if supportsToolCalling is not specified
724
+ return providerInfo?.supportsToolCalling !== false;
725
+ }
726
+
727
+ /**
728
+ * Creates a model instance based on current settings.
729
+ * @returns The configured model instance for the agent
730
+ */
731
+ private async _createModel() {
732
+ const activeProvider = this._settingsModel.getActiveProvider();
733
+ if (!activeProvider) {
734
+ throw new Error('No active provider configured');
735
+ }
736
+ const provider = activeProvider.provider;
737
+ const model = activeProvider.model;
738
+
739
+ let apiKey: string;
740
+ if (this._secretsManager && this._settingsModel.config.useSecretsManager) {
741
+ apiKey =
742
+ (
743
+ await this._secretsManager.get(
744
+ Private.getToken(),
745
+ SECRETS_NAMESPACE,
746
+ `${provider}:apiKey`
747
+ )
748
+ )?.value ?? '';
749
+ } else {
750
+ apiKey = this._settingsModel.getApiKey(activeProvider.id);
751
+ }
752
+
753
+ return createModel(
754
+ {
755
+ provider,
756
+ model,
757
+ apiKey
758
+ },
759
+ this._chatProviderRegistry
760
+ );
761
+ }
762
+
763
+ /**
764
+ * Enhances the base system prompt with tool usage guidelines.
765
+ * @param baseSystemPrompt The base system prompt from settings
766
+ * @returns The enhanced system prompt with tool usage instructions
767
+ */
768
+ private _getEnhancedSystemPrompt(baseSystemPrompt: string): string {
769
+ const progressReportingPrompt = `
770
+
771
+ IMPORTANT: Follow this message flow pattern for better user experience:
772
+
773
+ 1. FIRST: Explain what you're going to do and your approach
774
+ 2. THEN: Execute tools (these will show automatically with step numbers)
775
+ 3. FINALLY: Provide a concise summary of what was accomplished
776
+
777
+ Example flow:
778
+ - "I'll help you create a notebook with example cells. Let me first create the file structure, then add Python and Markdown cells."
779
+ - [Tool executions happen with automatic step display]
780
+ - "Successfully created your notebook with 3 cells: a title, code example, and visualization cell."
781
+
782
+ Guidelines:
783
+ - Start responses with your plan/approach before tool execution
784
+ - Let the system handle tool execution display (don't duplicate details)
785
+ - End with a brief summary of accomplishments
786
+ - Use natural, conversational tone throughout
787
+
788
+ COMMAND DISCOVERY:
789
+ - When you want to execute JupyterLab commands, ALWAYS use the 'discover_commands' tool first to find available commands and their metadata.
790
+ - This ensures you have complete information about command IDs, descriptions, and required arguments before attempting to execute them. Only after discovering the available commands should you use the 'execute_command' tool with the correct command ID and arguments.
791
+
792
+ TOOL SELECTION GUIDELINES:
793
+ - For file operations (create, read, write, modify files and directories): Use dedicated file manipulation tools
794
+ - For general JupyterLab UI interactions (opening panels, running commands, navigating interface): Use the general command tool (execute_command)
795
+ - Examples of file operations: Creating notebooks, editing code files, managing project structure
796
+ - Examples of UI interactions: Opening terminal, switching tabs, running notebook cells, accessing menus
797
+ `;
798
+
799
+ return baseSystemPrompt + progressReportingPrompt;
800
+ }
801
+
802
+ // Private attributes
803
+ private _settingsModel: AISettingsModel;
804
+ private _toolRegistry?: IToolRegistry;
805
+ private _chatProviderRegistry?: IChatProviderRegistry;
806
+ private _secretsManager?: ISecretsManager;
807
+ private _selectedToolNames: string[];
808
+ private _agent: Agent | null;
809
+ private _runner: Runner;
810
+ private _history: AgentInputItem[];
811
+ private _mcpServers: BrowserMCPServerStreamableHttp[];
812
+ private _isInitializing: boolean;
813
+ private _controller: AbortController | null;
814
+ private _pendingApprovals: Map<
815
+ string,
816
+ { interruption: RunToolApprovalItem; approved?: boolean; groupId?: string }
817
+ >;
818
+ private _interruptedState: any;
819
+ private _agentEvent: Signal<this, IAgentEvent>;
820
+ private _mcpConnectionChanged: Signal<this, boolean>;
821
+ private _tokenUsage: ITokenUsage;
822
+ private _tokenUsageChanged: Signal<this, ITokenUsage>;
823
+ }
824
+
825
+ namespace Private {
826
+ /**
827
+ * The token to use with the secrets manager, setter and getter.
828
+ */
829
+ let secretsToken: symbol;
830
+ export function setToken(value: symbol): void {
831
+ secretsToken = value;
832
+ }
833
+ export function getToken(): symbol {
834
+ return secretsToken;
835
+ }
836
+ }