@jupyterlite/ai 0.14.0 → 0.16.0

package/src/tokens.ts

@@ -1,12 +1,13 @@
-import { ActiveCellManager } from '@jupyter/chat';
+import { ActiveCellManager, IMessage, IMessageContent } from '@jupyter/chat';
+import { VDomRenderer } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
 import { Token } from '@lumino/coreutils';
 import type { IDisposable } from '@lumino/disposable';
 import { ISignal } from '@lumino/signaling';
 import type { Tool, LanguageModel } from 'ai';
-import { AgentManager } from './agent';
-import type { AISettingsModel } from './models/settings-model';
+import { ISecretsManager } from 'jupyter-secrets-manager';
+
 import type { IModelOptions } from './providers/models';
-import { AgentManagerFactory } from './agent';
 import { AIChatModel } from './chat-model';
 import type {
   ISkillDefinition,
@@ -31,27 +32,20 @@ export namespace CommandIds {
   export const openChat = '@jupyterlite/ai:open-chat';
   export const moveChat = '@jupyterlite/ai:move-chat';
   export const refreshSkills = '@jupyterlite/ai:refresh-skills';
+  export const saveChat = '@jupyterlite/ai:save-chat';
+  export const restoreChat = '@jupyterlite/ai:restore-chat';
 }
 
+/* THE TOOL REGISTRY */
 /**
  * Type definition for a tool
  */
 export type ITool = Tool;
 
 /**
- * Interface for token usage statistics from AI model interactions
+ * A map containing tools.
  */
-export interface ITokenUsage {
-  /**
-   * Number of input tokens consumed (prompt tokens)
-   */
-  inputTokens: number;
-
-  /**
-   * Number of output tokens generated (completion tokens)
-   */
-  outputTokens: number;
-}
+export type ToolMap = Record<string, ITool>;
 
 /**
  * Interface for a named tool (tool with a name identifier)
@@ -108,10 +102,12 @@ export interface IToolRegistry {
  * The tool registry token.
  */
 export const IToolRegistry = new Token<IToolRegistry>(
-  '@jupyterlite/ai:tool-registry',
+  '@jupyterlite/ai:IToolRegistry',
   'Tool registry for AI agent functionality'
 );
 
+/* THE SKILL REGISTRY */
+
 /**
  * Registry for skills available to the AI agent.
  */
@@ -149,17 +145,11 @@ export interface ISkillRegistry {
  * The skill registry token.
  */
 export const ISkillRegistry = new Token<ISkillRegistry>(
-  '@jupyterlite/ai:skill-registry',
+  '@jupyterlite/ai:ISkillRegistry',
   'Skill registry for AI agent functionality'
 );
 
-/**
- * Token for the provider registry.
- */
-export const IProviderRegistry = new Token<IProviderRegistry>(
-  '@jupyterlite/ai:provider-registry',
-  'Registry for AI providers'
-);
+/* THE LLM PROVIDER REGISTRY */
 
 /**
  * Interface for a provider factory function that creates language models
@@ -214,6 +204,13 @@ export interface IProviderToolCapabilities {
 /**
  * Provider information
  */
+export interface IProviderModelInfo {
+  /**
+   * Default context window for the model in tokens.
+   */
+  contextWindow?: number;
+}
+
 export interface IProviderInfo {
   /**
    * Unique identifier for the provider
@@ -238,6 +235,11 @@ export interface IProviderInfo {
    */
   defaultModels: string[];
 
+  /**
+   * Optional per-model metadata keyed by model ID.
+   */
+  modelInfo?: Record<string, IProviderModelInfo>;
+
   /**
    * Whether this provider supports custom base URLs
    */
@@ -317,75 +319,392 @@ export interface IProviderRegistry {
   getAvailableProviders(): string[];
 }
 
+/**
+ * Token for the provider registry.
+ */
+export const IProviderRegistry = new Token<IProviderRegistry>(
+  '@jupyterlite/ai:IProviderRegistry',
+  'Registry for AI providers'
+);
+
+/* THE SETTINGS MODEL */
+
+export interface IProviderParameters {
+  temperature?: number;
+  maxOutputTokens?: number;
+  maxTurns?: number;
+  contextWindow?: number;
+  supportsFillInMiddle?: boolean;
+  useFilterText?: boolean;
+}
+
+export interface IProviderConfig {
+  id: string;
+  name: string;
+  provider: string;
+  model: string;
+  apiKey?: string;
+  baseURL?: string;
+  headers?: Record<string, string>;
+  parameters?: IProviderParameters;
+  customSettings?: Record<string, any>;
+  [key: string]: any; // Index signature for JupyterLab settings compatibility
+}
+
+export interface IMCPServerConfig {
+  id: string;
+  name: string;
+  url: string;
+  enabled: boolean;
+  [key: string]: any; // Index signature for JupyterLab settings compatibility
+}
+
+export interface IAIConfig {
+  // Whether to use the secrets manager
+  useSecretsManager: boolean;
+  // List of configured providers
+  providers: IProviderConfig[];
+  // Active provider IDs for different use cases
+  defaultProvider: string; // Default provider for chat
+  activeCompleterProvider?: string; // Provider for completions (if different)
+  // When true, use the same provider for chat and completions
+  useSameProviderForChatAndCompleter: boolean;
+  // MCP servers configuration
+  mcpServers: IMCPServerConfig[];
+  // Global settings
+  contextAwareness: boolean;
+  codeExecution: boolean;
+  systemPrompt: string;
+  completionSystemPrompt: string;
+  toolsEnabled: boolean;
+  // Chat behavior settings
+  sendWithShiftEnter: boolean;
+  // Token usage display setting
+  showTokenUsage: boolean;
+  // Context usage display setting
+  showContextUsage: boolean;
+  // Commands that require approval before execution
+  commandsRequiringApproval: string[];
+  // Commands whose execute_command outputs may auto-render MIME bundles in chat
+  commandsAutoRenderMimeBundles: string[];
+  // MIME types that are trusted when auto-rendering execute_command outputs
+  trustedMimeTypesForAutoRender: string[];
+  // Diff display settings
+  showCellDiff: boolean;
+  showFileDiff: boolean;
+  diffDisplayMode: 'split' | 'unified';
+  // Paths to directories containing agent skills
+  skillsPaths: string[];
+  // Directory where chat backups are saved
+  chatBackupDirectory: string;
+}
+
+export interface IAISettingsModel extends VDomRenderer.IModel {
+  readonly config: IAIConfig;
+  updateConfig(updates: Partial<IAIConfig>): Promise<void>;
+  readonly providers: IProviderConfig[];
+  getProvider(id: string): IProviderConfig | undefined;
+  getDefaultProvider(): IProviderConfig | undefined;
+  getCompleterProvider(): IProviderConfig | undefined;
+  addProvider(providerConfig: Omit<IProviderConfig, 'id'>): Promise<string>;
+  removeProvider(id: string): Promise<void>;
+  updateProvider(id: string, updates: Partial<IProviderConfig>): Promise<void>;
+  setActiveProvider(id: string): Promise<void>;
+  setActiveCompleterProvider(id: string | undefined): Promise<void>;
+  readonly mcpServers: IMCPServerConfig[];
+  getMCPServer(id: string): IMCPServerConfig | undefined;
+  addMCPServer(serverConfig: Omit<IMCPServerConfig, 'id'>): Promise<string>;
+  removeMCPServer(id: string): Promise<void>;
+  updateMCPServer(
+    id: string,
+    updates: Partial<IMCPServerConfig>
+  ): Promise<void>;
+  /**
+   * Get the API key saved in the settings file for a given provider.
+   *
+   * @param id - the id of the provider.
+   */
+  getApiKey(id: string): string;
+}
+
 /**
  * Token for the AI settings model.
  */
-export const IAISettingsModel = new Token<AISettingsModel>(
+export const IAISettingsModel = new Token<IAISettingsModel>(
   '@jupyterlite/ai:IAISettingsModel'
 );
 
+/* THE AGENT MANAGER */
+
 /**
- * Internal interface for AI provider secret access within the shared namespace.
+ * A namespace for agent manager.
  */
-export interface IAISecretsAccess {
+export namespace IAgentManager {
+  /**
+   * Configuration options for the AgentManager
+   */
+  export interface IOptions {
+    /**
+     * AI settings model for configuration
+     */
+    settingsModel: IAISettingsModel;
+
+    /**
+     * Optional tool registry for managing available tools
+     */
+    toolRegistry?: IToolRegistry;
+
+    /**
+     * Optional provider registry for model creation
+     */
+    providerRegistry?: IProviderRegistry;
+
+    /**
+     * The skill registry for discovering skills.
+     */
+    skillRegistry?: ISkillRegistry;
+
+    /**
+     * The secrets manager.
+     */
+    secretsManager?: ISecretsManager;
+
+    /**
+     * The active provider to use with this agent.
+     */
+    activeProvider?: string;
+
+    /**
+     * Initial token usage.
+     */
+    tokenUsage?: ITokenUsage;
+
+    /**
+     * JupyterLab render mime registry for discovering supported MIME types.
+     */
+    renderMimeRegistry?: IRenderMimeRegistry;
+  }
+
+  /**
+   * 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: string;
+    };
+    tool_call_complete: {
+      callId: string;
+      toolName: string;
+      outputData: unknown;
+      isError: boolean;
+    };
+    tool_approval_request: {
+      approvalId: string;
+      toolCallId: string;
+      toolName: string;
+      args: unknown;
+    };
+    tool_approval_resolved: {
+      approvalId: string;
+      approved: boolean;
+    };
+    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;
+}
+
+export interface IAgentManager {
   /**
-   * Whether secrets access is currently available.
+   * The active provider for this agent.
    */
-  readonly isAvailable: boolean;
-
+  activeProvider: string;
   /**
-   * Get a secret value by ID.
+   * Signal emitted when agent events occur
    */
-  get(id: string): Promise<string | undefined>;
-
+  readonly agentEvent: ISignal<IAgentManager, IAgentManager.IAgentEvent>;
   /**
-   * Set a secret value by ID.
+   * Signal emitted when the active provider has changed.
    */
-  set(id: string, value: string): Promise<void>;
-
+  readonly activeProviderChanged: ISignal<IAgentManager, string | undefined>;
   /**
-   * Attach an input field to a secret ID.
+   * Gets the current token usage statistics.
    */
-  attach(
-    id: string,
-    input: HTMLInputElement,
-    callback?: (value: string) => void
-  ): Promise<void>;
+  readonly tokenUsage: ITokenUsage;
+  /**
+   * Signal emitted when token usage statistics change.
+   */
+  readonly tokenUsageChanged: ISignal<IAgentManager, ITokenUsage>;
+  /**
+   * Refresh the skills snapshot and rebuild the agent if resources are ready.
+   */
+  refreshSkills(): void;
+  /**
+   * 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 a record.
+   * @returns Record of selected tools
+   */
+  readonly selectedAgentTools: ToolMap;
+  /**
+   * 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.
+   */
+  clearHistory(): void;
+  /**
+   * Sets the conversation history with a list of messages from the chat.
+   * @param messages The chat messages to set as history
+   */
+  setHistory(messages: IMessageContent[]): void;
+  /**
+   * Stops the current streaming response by aborting the request.
+   */
+  stopStreaming(): void;
+  /**
+   * Approves a pending tool call.
+   * @param approvalId The approval ID to approve
+   * @param reason Optional reason for approval
+   */
+  approveToolCall(approvalId: string, reason?: string): void;
+  /**
+   * Rejects a pending tool call.
+   * @param approvalId The approval ID to reject
+   * @param reason Optional reason for rejection
+   */
+  rejectToolCall(approvalId: string, reason?: string): void;
+  /**
+   * Generates AI response to user message using the agent.
+   * Handles the complete execution cycle including tool calls.
+   * @param message The user message to respond to (may include processed attachment content)
+   */
+  generateResponse(message: string): Promise<void>;
+  /**
+   * Initializes the AI agent with current settings and tools.
+   * Sets up the agent with model configuration, tools, and MCP tools.
+   */
+  initializeAgent(mcpTools?: ToolMap): Promise<void>;
 }
 
 /**
  * Token for the agent manager.
  */
-export const IAgentManager = new Token<AgentManager>(
-  '@jupyterlite/ai:agent-manager'
+export const IAgentManager = new Token<IAgentManager>(
+  '@jupyterlite/ai:IAgentManager'
 );
 
+/* The AGENT MANAGER FACTORY */
 /**
- * The string that replaces a secret key in settings.
+ * The interface for a agent manager factory.
  */
-export const SECRETS_NAMESPACE = '@jupyterlite/ai:providers';
-export const SECRETS_REPLACEMENT = '***';
+export interface IAgentManagerFactory {
+  /**
+   * Create a new agent.
+   */
+  createAgent(options: IAgentManager.IOptions): IAgentManager;
+  /**
+   * Signal emitted when MCP connection status changes
+   */
+  readonly mcpConnectionChanged: ISignal<IAgentManagerFactory, boolean>;
+  /**
+   * Checks whether a specific MCP server is connected.
+   * @param serverName The name of the MCP server to check
+   * @returns True if the server is connected, false otherwise
+   */
+  isMCPServerConnected(serverName: string): boolean;
+  /**
+   * Gets the MCP tools from connected servers
+   */
+  getMCPTools(): Promise<ToolMap>;
+}
 
 /*
- * Token for the agent manager registry.
+ * Token for the agent manager factory.
  */
-export const IAgentManagerFactory = new Token<AgentManagerFactory>(
-  '@jupyterlite/ai:agent-manager-factory'
+export const IAgentManagerFactory = new Token<IAgentManagerFactory>(
+  '@jupyterlite/ai:IAgentManagerFactory'
 );
 
+/* THE CHAT MODELS HANDLER */
+
+/**
+ * The interface for the chat model handler.
+ */
 export interface IChatModelHandler {
-  createModel(
-    name: string,
-    activeProvider: string,
-    tokenUsage?: ITokenUsage
-  ): AIChatModel;
+  /**
+   * The function to create a new model.
+   */
+  createModel(options: ICreateChatOptions): AIChatModel;
+  /**
+   * The active cell manager (to copy code from chat to cell).
+   */
   activeCellManager: ActiveCellManager | undefined;
 }
 
+export interface ICreateChatOptions {
+  /**
+   * The name of the chat.
+   */
+  name: string;
+  /**
+   * The id of the active provider of the chat.
+   */
+  activeProvider: string;
+  /**
+   * The current token usage in this chat.
+   */
+  tokenUsage?: ITokenUsage;
+  /**
+   * The messages to ad by default.
+   */
+  messages?: IMessage[];
+  /**
+   * Whether the chat is autosaved or not.
+   */
+  autosave?: boolean;
+}
+/**
+ * Token for the chat model handler.
+ */
 export const IChatModelHandler = new Token<IChatModelHandler>(
-  '@jupyterlite/ai:chat-model-handler'
+  '@jupyterlite/ai:IChatModelHandler'
 );
 
+/* THE DIFF MANAGER */
+
 /**
  * Parameters for showing cell diff
  */
@@ -456,5 +775,66 @@ export interface IDiffManager {
  * Token for the diff manager.
  */
 export const IDiffManager = new Token<IDiffManager>(
-  '@jupyterlite/ai:diff-manager'
+  '@jupyterlite/ai:IDiffManager'
 );
+
+/**
+ * Interface for token usage statistics from AI model interactions
+ */
+export interface ITokenUsage {
+  /**
+   * Number of input tokens consumed (prompt tokens)
+   */
+  inputTokens: number;
+
+  /**
+   * Number of output tokens generated (completion tokens)
+   */
+  outputTokens: number;
+
+  /**
+   * Estimated prompt tokens used by the most recent model request.
+   * This is based on the final step of the latest request.
+   */
+  lastRequestInputTokens?: number;
+
+  /**
+   * Configured context window size for the active provider/model.
+   */
+  contextWindow?: number;
+}
+
+/**
+ * The string that replaces a secret key in settings.
+ */
+export const SECRETS_NAMESPACE = '@jupyterlite/ai:providers';
+export const SECRETS_REPLACEMENT = '***';
+
+/**
+ * Internal interface for AI provider secret access within the shared namespace.
+ */
+export interface IAISecretsAccess {
+  /**
+   * Whether secrets access is currently available.
+   */
+  readonly isAvailable: boolean;
+
+  /**
+   * Get a secret value by ID.
+   */
+  get(id: string): Promise<string | undefined>;
+
+  /**
+   * Set a secret value by ID.
+   */
+  set(id: string, value: string): Promise<void>;
+
+  /**
+   * Attach an input field to a secret ID.
+   */
+  attach(
+    id: string,
+    input: HTMLInputElement,
+    callback?: (value: string) => void
+  ): Promise<void>;
+}

package/src/tools/commands.ts

@@ -2,8 +2,7 @@ import { CommandRegistry } from '@lumino/commands';
 import { Widget } from '@lumino/widgets';
 import { tool } from 'ai';
 import { z } from 'zod';
-import { ITool } from '../tokens';
-import { AISettingsModel } from '../models/settings-model';
+import type { IAISettingsModel, ITool } from '../tokens';
 
 interface ICommandEntry {
   id: string;
@@ -148,7 +147,7 @@ export function createDiscoverCommandsTool(commands: CommandRegistry): ITool {
  */
 export function createExecuteCommandTool(
   commands: CommandRegistry,
-  settingsModel: AISettingsModel
+  settingsModel: IAISettingsModel
 ): ITool {
   return tool({
     title: 'Execute Command',