@jupyterlite/ai 0.8.1 → 0.9.0-a1

package/lib/agent.d.ts

@@ -0,0 +1,243 @@
+import { ISignal } from '@lumino/signaling';
+import { ISecretsManager } from 'jupyter-secrets-manager';
+import { AISettingsModel } from './models/settings-model';
+import type { IChatProviderRegistry } from './tokens';
+import { ITool, IToolRegistry, ITokenUsage } from './tokens';
+/**
+ * Event type mapping for type safety with inlined interface definitions
+ */
+export interface IAgentEventTypeMap {
+    message_start: {
+        messageId: string;
+    };
+    message_chunk: {
+        messageId: string;
+        chunk: string;
+        fullContent: string;
+    };
+    message_complete: {
+        messageId: string;
+        content: string;
+    };
+    tool_call_start: {
+        callId: string;
+        toolName: string;
+        input: any;
+    };
+    tool_call_complete: {
+        callId: string;
+        toolName: string;
+        output: any;
+        isError: boolean;
+    };
+    tool_approval_required: {
+        interruptionId: string;
+        toolName: string;
+        toolInput: any;
+        callId?: string;
+    };
+    grouped_approval_required: {
+        groupId: string;
+        approvals: Array<{
+            interruptionId: string;
+            toolName: string;
+            toolInput: any;
+        }>;
+    };
+    error: {
+        error: Error;
+    };
+}
+/**
+ * Events emitted by the AgentManager
+ */
+export type IAgentEvent<T extends keyof IAgentEventTypeMap = keyof IAgentEventTypeMap> = T extends keyof IAgentEventTypeMap ? {
+    type: T;
+    data: IAgentEventTypeMap[T];
+} : never;
+/**
+ * Configuration options for the AgentManager
+ */
+export interface IAgentManagerOptions {
+    /**
+     * AI settings model for configuration
+     */
+    settingsModel: AISettingsModel;
+    /**
+     * Optional tool registry for managing available tools
+     */
+    toolRegistry?: IToolRegistry;
+    /**
+     * Optional chat provider registry for model creation
+     */
+    chatProviderRegistry?: IChatProviderRegistry;
+    /**
+     * The secrets manager.
+     */
+    secretsManager?: ISecretsManager;
+    /**
+     * The token used to request the secrets manager.
+     */
+    token: symbol;
+}
+/**
+ * Manages the AI agent lifecycle and execution loop.
+ * Provides agent initialization, tool management, MCP server integration,
+ * and handles the complete agent execution cycle including tool approvals.
+ * Emits events for UI updates instead of directly manipulating the chat interface.
+ */
+export declare class AgentManager {
+    /**
+     * Creates a new AgentManager instance.
+     * @param options Configuration options for the agent manager
+     */
+    constructor(options: IAgentManagerOptions);
+    /**
+     * Signal emitted when agent events occur
+     */
+    get agentEvent(): ISignal<this, IAgentEvent>;
+    /**
+     * Signal emitted when MCP connection status changes
+     */
+    get mcpConnectionChanged(): ISignal<this, boolean>;
+    /**
+     * Gets the current token usage statistics.
+     */
+    get tokenUsage(): ITokenUsage;
+    /**
+     * Signal emitted when token usage statistics change.
+     */
+    get tokenUsageChanged(): ISignal<this, ITokenUsage>;
+    /**
+     * Sets the selected tools by name and reinitializes the agent.
+     * @param toolNames Array of tool names to select
+     */
+    setSelectedTools(toolNames: string[]): void;
+    /**
+     * Gets the currently selected tools as OpenAI agents tools.
+     * @returns Array of selected tools formatted for OpenAI agents
+     */
+    get selectedAgentTools(): ITool[];
+    /**
+     * Checks if a specific MCP server is connected by server name.
+     * @param serverName The name of the MCP server to check
+     * @returns True if the server is connected, false otherwise
+     */
+    isMCPServerConnected(serverName: string): boolean;
+    /**
+     * Checks if the current configuration is valid for agent operations.
+     * Uses the provider registry to determine if an API key is required.
+     * @returns True if the configuration is valid, false otherwise
+     */
+    hasValidConfig(): boolean;
+    /**
+     * Clears conversation history and resets agent state.
+     * Removes all conversation history, pending approvals, and interrupted state.
+     */
+    clearHistory(): void;
+    /**
+     * Stops the current streaming response by aborting the request.
+     */
+    stopStreaming(): void;
+    /**
+     * Generates AI response to user message using the agent.
+     * Handles the complete execution cycle including tool calls and approvals.
+     * @param message The user message to respond to (may include processed attachment content)
+     */
+    generateResponse(message: string): Promise<void>;
+    /**
+     * Approves a tool call by interruption ID.
+     * @param interruptionId The interruption ID to approve
+     */
+    approveToolCall(interruptionId: string): Promise<void>;
+    /**
+     * Rejects a tool call by interruption ID.
+     * @param interruptionId The interruption ID to reject
+     */
+    rejectToolCall(interruptionId: string): Promise<void>;
+    /**
+     * Approves all tools in a group by group ID.
+     * @param groupId The group ID containing the tool calls
+     * @param interruptionIds Array of interruption IDs to approve
+     */
+    approveGroupedToolCalls(groupId: string, interruptionIds: string[]): Promise<void>;
+    /**
+     * Rejects all tools in a group by group ID.
+     * @param groupId The group ID containing the tool calls
+     * @param interruptionIds Array of interruption IDs to reject
+     */
+    rejectGroupedToolCalls(groupId: string, interruptionIds: string[]): Promise<void>;
+    /**
+     * Handles settings changes and reinitializes the agent.
+     */
+    private _onSettingsChanged;
+    /**
+     * Initializes the AI agent with current settings and tools.
+     * Sets up the agent with model configuration, tools, and MCP servers.
+     */
+    private _initializeAgent;
+    /**
+     * Initializes MCP (Model Context Protocol) servers based on current settings.
+     * Closes existing servers and connects to enabled servers from configuration.
+     */
+    private _initializeMCPServers;
+    /**
+     * Processes the result stream from agent execution.
+     * Handles message streaming, tool calls, and emits appropriate events.
+     * @param result The async iterable result from agent execution
+     */
+    private _processRunResult;
+    /**
+     * Handles the start of a tool call from the model event.
+     * @param modelEvent The model event containing tool call information
+     */
+    private _handleToolCallStart;
+    /**
+     * Handles tool execution output and completion.
+     * @param event The tool output event containing result information
+     */
+    private _handleToolOutput;
+    /**
+     * Handles approval request for a single tool call.
+     * @param interruption The tool approval interruption item
+     */
+    private _handleSingleToolApproval;
+    /**
+     * Handles approval requests for multiple grouped tool calls.
+     * @param interruptions Array of tool approval interruption items
+     */
+    private _handleGroupedToolApprovals;
+    /**
+     * Checks if the current provider supports tool calling.
+     * @returns True if the provider supports tool calling, false otherwise
+     */
+    private _supportsToolCalling;
+    /**
+     * Creates a model instance based on current settings.
+     * @returns The configured model instance for the agent
+     */
+    private _createModel;
+    /**
+     * Enhances the base system prompt with tool usage guidelines.
+     * @param baseSystemPrompt The base system prompt from settings
+     * @returns The enhanced system prompt with tool usage instructions
+     */
+    private _getEnhancedSystemPrompt;
+    private _settingsModel;
+    private _toolRegistry?;
+    private _chatProviderRegistry?;
+    private _secretsManager?;
+    private _selectedToolNames;
+    private _agent;
+    private _runner;
+    private _history;
+    private _mcpServers;
+    private _isInitializing;
+    private _controller;
+    private _pendingApprovals;
+    private _interruptedState;
+    private _agentEvent;
+    private _mcpConnectionChanged;
+    private _tokenUsage;
+    private _tokenUsageChanged;
+}