@jupyterlite/ai 0.11.1 → 0.12.0

package/lib/agent.d.ts

@@ -3,7 +3,7 @@ import { type Tool } from 'ai';
 import { ISecretsManager } from 'jupyter-secrets-manager';
 import { AISettingsModel } from './models/settings-model';
 import type { IProviderRegistry } from './tokens';
-import { ITool, IToolRegistry, ITokenUsage } from './tokens';
+import { ISkillRegistry, ITool, IToolRegistry, ITokenUsage } from './tokens';
 type ToolMap = Record<string, Tool>;
 export declare namespace AgentManagerFactory {
     interface IOptions {
@@ -11,6 +11,10 @@ export declare namespace AgentManagerFactory {
          * The settings model.
          */
         settingsModel: AISettingsModel;
+        /**
+         * The skill registry for discovering skills.
+         */
+        skillRegistry?: ISkillRegistry;
         /**
          * The secrets manager.
          */
@@ -52,12 +56,17 @@ export declare class AgentManagerFactory {
      * Sets up the agent with model configuration, tools, and MCP servers.
      */
     private _initializeAgents;
+    /**
+     * Refresh skill snapshots across all agents.
+     */
+    refreshSkillSnapshots(): void;
     private _agentManagers;
     private _settingsModel;
+    private _skillRegistry?;
     private _secretsManager?;
     private _mcpClients;
     private _mcpConnectionChanged;
-    private _isInitializing;
+    private _initQueue;
 }
 /**
  * Event type mapping for type safety with inlined interface definitions
@@ -123,6 +132,10 @@ export interface IAgentManagerOptions {
      * Optional provider registry for model creation
      */
     providerRegistry?: IProviderRegistry;
+    /**
+     * The skill registry for discovering skills.
+     */
+    skillRegistry?: ISkillRegistry;
     /**
      * The secrets manager.
      */
@@ -164,6 +177,10 @@ export declare class AgentManager {
      * Signal emitted when token usage statistics change.
      */
     get tokenUsageChanged(): ISignal<this, ITokenUsage>;
+    /**
+     * Refresh the skills snapshot and rebuild the agent if resources are ready.
+     */
+    refreshSkills(): void;
     /**
      * The active provider for this agent.
      */
@@ -220,6 +237,18 @@ export declare class AgentManager {
      * Sets up the agent with model configuration, tools, and MCP tools.
      */
     initializeAgent: (mcpTools?: ToolMap) => Promise<void>;
+    /**
+     * Refresh the in-memory skills snapshot from the skill registry.
+     */
+    private _refreshSkills;
+    /**
+     * Prepare model, tools, and settings needed to (re)build the agent.
+     */
+    private _prepareAgentConfig;
+    /**
+     * Rebuild the agent using cached resources and the current skills snapshot.
+     */
+    private _rebuildAgent;
     /**
      * Processes the stream result from agent execution.
      * Handles message streaming, tool calls, and emits appropriate events.
@@ -262,26 +291,29 @@ export declare class AgentManager {
      */
     private _createModel;
     /**
-     * Enhances the base system prompt with tool usage guidelines.
+     * Enhances the base system prompt with dynamic context like skills.
      * @param baseSystemPrompt The base system prompt from settings
-     * @returns The enhanced system prompt with tool usage instructions
+     * @returns The enhanced system prompt with dynamic additions
      */
     private _getEnhancedSystemPrompt;
     private _settingsModel;
     private _toolRegistry?;
     private _providerRegistry?;
+    private _skillRegistry?;
     private _secretsManager?;
     private _selectedToolNames;
     private _agent;
     private _history;
     private _mcpTools;
-    private _isInitializing;
     private _controller;
     private _agentEvent;
     private _tokenUsage;
     private _tokenUsageChanged;
     private _activeProvider;
     private _activeProviderChanged;
+    private _skills;
+    private _initQueue;
+    private _agentConfig;
     private _pendingApprovals;
 }
 export {};

package/lib/agent.js

@@ -7,9 +7,15 @@ export class AgentManagerFactory {
     constructor(options) {
         Private.setToken(options.token);
         this._settingsModel = options.settingsModel;
+        this._skillRegistry = options.skillRegistry;
         this._secretsManager = options.secretsManager;
         this._mcpClients = [];
         this._mcpConnectionChanged = new Signal(this);
+        if (this._skillRegistry) {
+            this._skillRegistry.skillsChanged.connect(() => {
+                this.refreshSkillSnapshots();
+            });
+        }
         // Initialize agent on construction
         this._initializeAgents().catch(error => console.warn('Failed to initialize agent in constructor:', error));
         // Listen for settings changes
@@ -18,6 +24,7 @@ export class AgentManagerFactory {
     createAgent(options) {
         const agentManager = new AgentManager({
             ...options,
+            skillRegistry: this._skillRegistry,
             secretsManager: this._secretsManager
         });
         this._agentManagers.push(agentManager);
@@ -106,30 +113,37 @@ export class AgentManagerFactory {
      * Sets up the agent with model configuration, tools, and MCP servers.
      */
     async _initializeAgents() {
-        if (this._isInitializing) {
-            return;
-        }
-        this._isInitializing = true;
-        try {
-            await this._initializeMCPClients();
-            const mcpTools = await this.getMCPTools();
-            this._agentManagers.forEach(manager => {
-                manager.initializeAgent(mcpTools);
-            });
-        }
-        catch (error) {
-            console.warn('Failed to initialize agents:', error);
-        }
-        finally {
-            this._isInitializing = false;
-        }
+        this._initQueue = this._initQueue
+            .catch(() => undefined)
+            .then(async () => {
+            try {
+                await this._initializeMCPClients();
+                const mcpTools = await this.getMCPTools();
+                this._agentManagers.forEach(manager => {
+                    manager.initializeAgent(mcpTools);
+                });
+            }
+            catch (error) {
+                console.warn('Failed to initialize agents:', error);
+            }
+        });
+        return this._initQueue;
+    }
+    /**
+     * Refresh skill snapshots across all agents.
+     */
+    refreshSkillSnapshots() {
+        this._agentManagers.forEach(manager => {
+            manager.refreshSkills();
+        });
     }
     _agentManagers = [];
     _settingsModel;
+    _skillRegistry;
     _secretsManager;
     _mcpClients;
     _mcpConnectionChanged;
-    _isInitializing = false;
+    _initQueue = Promise.resolve();
 }
 /**
  * Default parameter values for agent configuration
@@ -151,12 +165,12 @@ export class AgentManager {
         this._settingsModel = options.settingsModel;
         this._toolRegistry = options.toolRegistry;
         this._providerRegistry = options.providerRegistry;
+        this._skillRegistry = options.skillRegistry;
         this._secretsManager = options.secretsManager;
         this._selectedToolNames = [];
         this._agent = null;
         this._history = [];
         this._mcpTools = {};
-        this._isInitializing = false;
         this._controller = null;
         this._agentEvent = new Signal(this);
         this._tokenUsage = options.tokenUsage ?? {
@@ -164,6 +178,8 @@ export class AgentManager {
             outputTokens: 0
         };
         this._tokenUsageChanged = new Signal(this);
+        this._skills = [];
+        this._agentConfig = null;
         this.activeProvider =
             options.activeProvider ?? this._settingsModel.config.defaultProvider;
         // Initialize selected tools to all available tools by default
@@ -195,6 +211,20 @@ export class AgentManager {
     get tokenUsageChanged() {
         return this._tokenUsageChanged;
     }
+    /**
+     * Refresh the skills snapshot and rebuild the agent if resources are ready.
+     */
+    refreshSkills() {
+        this._initQueue = this._initQueue
+            .catch(() => undefined)
+            .then(async () => {
+            this._refreshSkills();
+            if (!this._agentConfig) {
+                return;
+            }
+            this._rebuildAgent();
+        });
+    }
     /**
      * The active provider for this agent.
      */
@@ -390,48 +420,83 @@ export class AgentManager {
      * Sets up the agent with model configuration, tools, and MCP tools.
      */
     initializeAgent = async (mcpTools) => {
-        if (this._isInitializing) {
-            return;
-        }
-        this._isInitializing = true;
-        try {
-            const config = this._settingsModel.config;
-            if (mcpTools !== undefined) {
-                this._mcpTools = mcpTools;
+        this._initQueue = this._initQueue
+            .catch(() => undefined)
+            .then(async () => {
+            try {
+                this._refreshSkills();
+                await this._prepareAgentConfig(mcpTools);
+                this._rebuildAgent();
             }
-            const model = await this._createModel();
-            const shouldUseTools = config.toolsEnabled &&
-                this._selectedToolNames.length > 0 &&
-                this._toolRegistry &&
-                Object.keys(this._toolRegistry.tools).length > 0 &&
-                this._supportsToolCalling();
-            const tools = shouldUseTools
-                ? { ...this.selectedAgentTools, ...this._mcpTools }
-                : this._mcpTools;
-            const activeProviderConfig = this._settingsModel.getProvider(this._activeProvider);
-            const temperature = activeProviderConfig?.parameters?.temperature ?? DEFAULT_TEMPERATURE;
-            const maxTokens = activeProviderConfig?.parameters?.maxOutputTokens;
-            const maxTurns = activeProviderConfig?.parameters?.maxTurns ?? DEFAULT_MAX_TURNS;
-            const instructions = shouldUseTools
-                ? this._getEnhancedSystemPrompt(config.systemPrompt || '')
-                : config.systemPrompt || 'You are a helpful assistant.';
-            this._agent = new ToolLoopAgent({
-                model,
-                instructions,
-                tools,
-                temperature,
-                maxOutputTokens: maxTokens,
-                stopWhen: stepCountIs(maxTurns)
-            });
+            catch (error) {
+                console.warn('Failed to initialize agent:', error);
+                this._agent = null;
+            }
+        });
+        return this._initQueue;
+    };
+    /**
+     * Refresh the in-memory skills snapshot from the skill registry.
+     */
+    _refreshSkills() {
+        if (!this._skillRegistry) {
+            this._skills = [];
+            return;
         }
-        catch (error) {
-            console.warn('Failed to initialize agent:', error);
+        this._skills = this._skillRegistry.listSkills();
+    }
+    /**
+     * Prepare model, tools, and settings needed to (re)build the agent.
+     */
+    async _prepareAgentConfig(mcpTools) {
+        const config = this._settingsModel.config;
+        if (mcpTools !== undefined) {
+            this._mcpTools = mcpTools;
+        }
+        const model = await this._createModel();
+        const shouldUseTools = !!(config.toolsEnabled &&
+            this._selectedToolNames.length > 0 &&
+            this._toolRegistry &&
+            Object.keys(this._toolRegistry.tools).length > 0 &&
+            this._supportsToolCalling());
+        const tools = shouldUseTools
+            ? { ...this.selectedAgentTools, ...this._mcpTools }
+            : this._mcpTools;
+        const activeProviderConfig = this._settingsModel.getProvider(this._activeProvider);
+        const temperature = activeProviderConfig?.parameters?.temperature ?? DEFAULT_TEMPERATURE;
+        const maxTokens = activeProviderConfig?.parameters?.maxOutputTokens;
+        const maxTurns = activeProviderConfig?.parameters?.maxTurns ?? DEFAULT_MAX_TURNS;
+        this._agentConfig = {
+            model,
+            tools,
+            temperature,
+            maxOutputTokens: maxTokens,
+            maxTurns,
+            baseSystemPrompt: config.systemPrompt || '',
+            shouldUseTools
+        };
+    }
+    /**
+     * Rebuild the agent using cached resources and the current skills snapshot.
+     */
+    _rebuildAgent() {
+        if (!this._agentConfig) {
             this._agent = null;
+            return;
         }
-        finally {
-            this._isInitializing = false;
-        }
-    };
+        const { model, tools, temperature, maxOutputTokens, maxTurns, baseSystemPrompt, shouldUseTools } = this._agentConfig;
+        const instructions = shouldUseTools
+            ? this._getEnhancedSystemPrompt(baseSystemPrompt)
+            : baseSystemPrompt || 'You are a helpful assistant.';
+        this._agent = new ToolLoopAgent({
+            model,
+            instructions,
+            tools,
+            temperature,
+            maxOutputTokens,
+            stopWhen: stepCountIs(maxTurns)
+        });
+    }
     /**
      * Processes the stream result from agent execution.
      * Handles message streaming, tool calls, and emits appropriate events.
@@ -630,67 +695,48 @@ export class AgentManager {
         }, this._providerRegistry);
     }
     /**
-     * Enhances the base system prompt with tool usage guidelines.
+     * Enhances the base system prompt with dynamic context like skills.
      * @param baseSystemPrompt The base system prompt from settings
-     * @returns The enhanced system prompt with tool usage instructions
+     * @returns The enhanced system prompt with dynamic additions
      */
     _getEnhancedSystemPrompt(baseSystemPrompt) {
-        const progressReportingPrompt = `
-
-IMPORTANT: Follow this message flow pattern for better user experience:
-
-1. FIRST: Explain what you're going to do and your approach
-2. THEN: Execute tools (these will show automatically with step numbers)
-3. FINALLY: Provide a concise summary of what was accomplished
-
-Example flow:
-- "I'll help you create a notebook with example cells. Let me first create the file structure, then add Python and Markdown cells."
-- [Tool executions happen with automatic step display]
-- "Successfully created your notebook with 3 cells: a title, code example, and visualization cell."
-
-Guidelines:
-- Start responses with your plan/approach before tool execution
-- Let the system handle tool execution display (don't duplicate details)
-- End with a brief summary of accomplishments
-- Use natural, conversational tone throughout
-
-PRIMARY TOOL USAGE - COMMAND-BASED OPERATIONS:
-Most operations in JupyterLab should be performed using the command system:
-1. Use 'discover_commands' to find available commands and their metadata
-2. Use 'execute_command' to perform the actual operation
+        if (this._skills.length === 0) {
+            return baseSystemPrompt;
+        }
+        const lines = this._skills.map(skill => `- ${skill.name}: ${skill.description}`);
+        const skillsPrompt = `
 
-COMMAND DISCOVERY WORKFLOW:
-- For file and notebook operations, use query 'jupyterlab-ai-commands' to discover the curated set of AI commands (~17 commands for file/notebook/directory operations)
-- For other JupyterLab operations (terminal, launcher, UI), use specific keywords like 'terminal', 'launcher', etc.
-- IMPORTANT: Always use 'jupyterlab-ai-commands' as the query for file/notebook tasks - this returns a focused set of commands instead of 100+ generic JupyterLab commands
+AGENT SKILLS:
+Skills are provided via the skills registry and accessed through tools (not commands).
+When a skill is relevant to the user's task, activate it by calling load_skill with the skill name to load its full instructions, then follow those instructions.
+If the user explicitly asks for the latest list of skills, call discover_skills (optionally with a query).
+Do NOT call discover_skills just to list skills; use the preloaded snapshot below instead unless you need to verify a skill not present in the snapshot.
+If the load_skill result includes a non-empty "resources" array, those are bundled files (scripts, references, templates) you MUST load before proceeding. Only load the listed resource paths; never invent resource names. For each resource path, execute load_skill again with the resource argument, e.g.: load_skill({ name: "<skill>", resource: "<path>" }). Load all listed resources before starting the task.
 
-KERNEL PREFERENCE FOR NOTEBOOKS AND CONSOLES:
-When creating notebooks or consoles for a specific programming language, use the 'kernelPreference' argument to specify the kernel:
-- To specify by language: { "kernelPreference": { "language": "python" } } or { "kernelPreference": { "language": "julia" } }
-- To specify by kernel name: { "kernelPreference": { "name": "python3" } } or { "kernelPreference": { "name": "julia-1.10" } }
-- Example: execute_command with commandId="notebook:create-new" and args={ "kernelPreference": { "language": "python" } }
-- Example: execute_command with commandId="console:create" and args={ "kernelPreference": { "name": "python3" } }
-- Common kernel names: "python3" (Python), "julia-1.10" (Julia), "ir" (R), "xpython" (xeus-python)
-- If unsure of exact kernel name, prefer using "language" which will match any kernel supporting that language
+AVAILABLE SKILLS (preloaded snapshot):
+${lines.join('\n')}
 `;
-        return baseSystemPrompt + progressReportingPrompt;
+        return baseSystemPrompt + skillsPrompt;
     }
     // Private attributes
     _settingsModel;
     _toolRegistry;
     _providerRegistry;
+    _skillRegistry;
     _secretsManager;
     _selectedToolNames;
     _agent;
     _history;
     _mcpTools;
-    _isInitializing;
     _controller;
     _agentEvent;
     _tokenUsage;
     _tokenUsageChanged;
     _activeProvider = '';
     _activeProviderChanged = new Signal(this);
+    _skills;
+    _initQueue = Promise.resolve();
+    _agentConfig;
     _pendingApprovals = new Map();
 }
 var Private;

package/lib/chat-commands/clear.d.ts

@@ -0,0 +1,8 @@
+import { ChatCommand, IChatCommandProvider, IInputModel } from '@jupyter/chat';
+export declare class ClearCommandProvider implements IChatCommandProvider {
+    id: string;
+    listCommandCompletions(inputModel: IInputModel): Promise<ChatCommand[]>;
+    onSubmit(inputModel: IInputModel): Promise<void>;
+    private _command;
+    private _regex;
+}

package/lib/chat-commands/clear.js

@@ -0,0 +1,30 @@
+export class ClearCommandProvider {
+    id = '@jupyterlite/ai:clear-command';
+    async listCommandCompletions(inputModel) {
+        const match = inputModel.currentWord?.match(this._regex)?.[0];
+        if (!match) {
+            return [];
+        }
+        if (this._command.name.startsWith(match)) {
+            return [this._command];
+        }
+        return [];
+    }
+    async onSubmit(inputModel) {
+        const trimmed = inputModel.value.trim();
+        if (trimmed !== this._command.name) {
+            return;
+        }
+        const context = inputModel.chatContext;
+        context?.clearMessages?.();
+        inputModel.value = '';
+        inputModel.clearAttachments();
+        inputModel.clearMentions();
+    }
+    _command = {
+        name: '/clear',
+        providerId: this.id,
+        description: 'Clear the current chat history'
+    };
+    _regex = /^\/\w*$/;
+}

package/lib/chat-commands/index.d.ts

@@ -0,0 +1,2 @@
+export * from './clear';
+export * from './skills';

package/lib/chat-commands/index.js

@@ -0,0 +1,2 @@
+export * from './clear';
+export * from './skills';

package/lib/chat-commands/skills.d.ts

@@ -0,0 +1,19 @@
+import { ChatCommand, IChatCommandProvider, IInputModel } from '@jupyter/chat';
+import { CommandRegistry } from '@lumino/commands';
+import { ISkillRegistry } from '../tokens';
+export declare class SkillsCommandProvider implements IChatCommandProvider {
+    constructor(options: SkillsCommandProvider.IOptions);
+    id: string;
+    listCommandCompletions(inputModel: IInputModel): Promise<ChatCommand[]>;
+    onSubmit(inputModel: IInputModel): Promise<void>;
+    private _command;
+    private _regex;
+    private _commands;
+    private _skillRegistry;
+}
+export declare namespace SkillsCommandProvider {
+    interface IOptions {
+        skillRegistry: ISkillRegistry;
+        commands: CommandRegistry;
+    }
+}

package/lib/chat-commands/skills.js

@@ -0,0 +1,57 @@
+import { CommandIds } from '../tokens';
+export class SkillsCommandProvider {
+    constructor(options) {
+        this._skillRegistry = options.skillRegistry;
+        this._commands = options.commands;
+    }
+    id = '@jupyterlite/ai:skills-command';
+    async listCommandCompletions(inputModel) {
+        const match = inputModel.currentWord?.match(this._regex)?.[0];
+        if (!match) {
+            return [];
+        }
+        if (this._command.name.startsWith(match)) {
+            return [this._command];
+        }
+        return [];
+    }
+    async onSubmit(inputModel) {
+        const trimmed = inputModel.value.trim();
+        const match = trimmed.match(/^\/skills(?:\s+(.+))?$/);
+        if (!match) {
+            return;
+        }
+        // Refresh skills from disk before listing
+        if (this._commands.hasCommand(CommandIds.refreshSkills)) {
+            await this._commands.execute(CommandIds.refreshSkills);
+        }
+        const query = match[1]?.trim();
+        const filtered = this._skillRegistry.listSkills(query);
+        let body = '';
+        if (filtered.length === 0) {
+            body = query
+                ? `No skills found matching "${query}".`
+                : 'No skills are currently registered.';
+        }
+        else {
+            const heading = query
+                ? `Skills matching "${query}" (${filtered.length}):`
+                : `Available skills (${filtered.length}):`;
+            const lines = filtered.map(skill => `- \`${skill.name}\` — ${skill.description}`);
+            body = [heading, '', ...lines].join('\n');
+        }
+        const context = inputModel.chatContext;
+        context?.addSystemMessage?.(body);
+        inputModel.value = '';
+        inputModel.clearAttachments();
+        inputModel.clearMentions();
+    }
+    _command = {
+        name: '/skills',
+        providerId: this.id,
+        description: 'List available skills'
+    };
+    _regex = /^\/\w*$/;
+    _commands;
+    _skillRegistry;
+}

package/lib/chat-model.d.ts

@@ -48,6 +48,10 @@ export declare class AIChatModel extends AbstractChatModel {
      * Clears all messages from the chat and resets conversation state.
      */
     clearMessages: () => void;
+    /**
+     * Adds a non-user message to the chat (used by chat commands).
+     */
+    addSystemMessage(body: string): void;
     /**
      * Sends a message to the AI and generates a response.
      * @param message The user message to send
@@ -184,6 +188,10 @@ export declare namespace AIChatModel {
          * The clear messages callback.
          */
         clearMessages: () => void;
+        /**
+         * Adds an assistant/system message to the chat.
+         */
+        addSystemMessage: (body: string) => void;
         /**
          * The agent manager of the chat.
          */

package/lib/chat-model.js

@@ -76,7 +76,8 @@ export class AIChatModel extends AbstractChatModel {
             messages: this.messages,
             stopStreaming: () => this.stopStreaming(),
             clearMessages: () => this.clearMessages(),
-            agentManager: this._agentManager
+            agentManager: this._agentManager,
+            addSystemMessage: (body) => this.addSystemMessage(body)
         };
     }
     /**
@@ -93,11 +94,30 @@ export class AIChatModel extends AbstractChatModel {
         this._toolContexts.clear();
         this._agentManager.clearHistory();
     };
+    /**
+     * Adds a non-user message to the chat (used by chat commands).
+     */
+    addSystemMessage(body) {
+        const message = {
+            body,
+            sender: this._getAIUser(),
+            id: UUID.uuid4(),
+            time: Date.now() / 1000,
+            type: 'msg',
+            raw_time: false
+        };
+        this.messageAdded(message);
+    }
     /**
      * Sends a message to the AI and generates a response.
      * @param message The user message to send
      */
     async sendMessage(message) {
+        const hasBody = message.body.trim().length > 0;
+        const hasAttachments = this.input.attachments.length > 0;
+        if (!hasBody && !hasAttachments) {
+            return;
+        }
         // Add user message to chat
         const userMessage = {
             body: message.body,
@@ -262,6 +282,19 @@ export class AIChatModel extends AbstractChatModel {
                         return `query: "${parsedInput.query}"`;
                     }
                     break;
+                case 'discover_skills':
+                    if (parsedInput.query) {
+                        return `query: "${parsedInput.query}"`;
+                    }
+                    break;
+                case 'load_skill':
+                    if (parsedInput.name) {
+                        if (parsedInput.resource) {
+                            return `${parsedInput.name} (${parsedInput.resource})`;
+                        }
+                        return parsedInput.name;
+                    }
+                    break;
             }
         }
         catch {
@@ -361,8 +394,7 @@ export class AIChatModel extends AbstractChatModel {
             return;
         }
         context.status = status;
-        this.messageAdded({
-            ...existingMessage,
+        existingMessage.update({
             body: Private.buildToolCallHtml({
                 toolName: context.toolName,
                 input: context.input,