@jupyterlite/ai 0.17.0 → 0.19.0

package/lib/tools/commands.js

@@ -1,154 +0,0 @@
-import { Widget } from '@lumino/widgets';
-import { tool } from 'ai';
-import { z } from 'zod';
-/**
- * Search commands using case-insensitive term matching across command metadata.
- *
- * Multi-word queries are split into individual terms, and every term must be
- * contained in at least one searchable field. Results are ranked by stronger
- * field matches while keeping a stable fallback order.
- */
-function searchCommands(commands, query) {
-    const normalizedQuery = query.trim().toLowerCase();
-    if (!normalizedQuery) {
-        return commands;
-    }
-    const terms = normalizedQuery.split(/\s+/).filter(Boolean);
-    return commands
-        .map((command, index) => {
-        const fields = [
-            { value: command.label, weight: 4 },
-            { value: command.caption, weight: 3 },
-            { value: command.id, weight: 2 },
-            { value: command.description, weight: 1 }
-        ];
-        const normalizedFields = fields.map(field => ({
-            normalizedValue: field.value?.toLowerCase() ?? '',
-            weight: field.weight
-        }));
-        const matchesAllTerms = terms.every(term => normalizedFields.some(field => field.normalizedValue.includes(term)));
-        if (!matchesAllTerms) {
-            return null;
-        }
-        const score = normalizedFields.reduce((total, field) => {
-            if (!field.normalizedValue) {
-                return total;
-            }
-            let fieldScore = 0;
-            if (field.normalizedValue.includes(normalizedQuery)) {
-                fieldScore += field.weight * 4;
-            }
-            else {
-                fieldScore +=
-                    terms.filter(term => field.normalizedValue.includes(term)).length *
-                        field.weight;
-            }
-            return total + fieldScore;
-        }, 0);
-        return { command, index, score };
-    })
-        .filter((result) => result !== null)
-        .sort((a, b) => b.score - a.score || a.index - b.index)
-        .map(result => result.command);
-}
-/**
- * Create a tool to discover all available commands and their metadata
- */
-export function createDiscoverCommandsTool(commands) {
-    return tool({
-        title: 'Discover Commands',
-        description: 'Discover all available JupyterLab commands with their metadata, arguments, and descriptions',
-        inputSchema: z.object({
-            query: z
-                .string()
-                .optional()
-                .nullable()
-                .describe('Optional search query to filter commands. Supports multi-word queries (whitespace-separated) by requiring each word to be contained in the command id, label, caption, or description. Leave empty to list all commands.')
-        }),
-        execute: async (input) => {
-            const { query } = input;
-            // Build the full command list first.
-            const commandIds = commands.listCommands();
-            const allCommands = [];
-            for (const id of commandIds) {
-                const description = await commands.describedBy(id);
-                const label = commands.label(id);
-                const caption = commands.caption(id);
-                const usage = commands.usage(id);
-                allCommands.push({
-                    id,
-                    label: label || undefined,
-                    caption: caption || undefined,
-                    description: usage || undefined,
-                    args: description?.args || undefined
-                });
-            }
-            const commandList = query
-                ? searchCommands(allCommands, query)
-                : allCommands;
-            return {
-                success: true,
-                commandCount: commandList.length,
-                commands: commandList
-            };
-        }
-    });
-}
-/**
- * Create a tool to execute a specific JupyterLab command.
- * Commands in the settings' commandsRequiringApproval list will need approval.
- */
-export function createExecuteCommandTool(commands, settingsModel) {
-    return tool({
-        title: 'Execute Command',
-        description: 'Execute a specific JupyterLab command with optional arguments',
-        inputSchema: z.object({
-            commandId: z.string().describe('The ID of the command to execute'),
-            args: z
-                .record(z.string(), z.unknown())
-                .optional()
-                .describe('Optional arguments object to pass to the command (must be an object, not a string)')
-        }),
-        needsApproval: (input) => {
-            const commandsRequiringApproval = settingsModel.config.commandsRequiringApproval || [];
-            return commandsRequiringApproval.includes(input.commandId);
-        },
-        execute: async (input) => {
-            const { commandId, args } = input;
-            // Check if command exists
-            if (!commands.hasCommand(commandId)) {
-                return {
-                    success: false,
-                    error: `Command '${commandId}' does not exist. Use 'discover_commands' to see available commands.`
-                };
-            }
-            // Execute the command
-            const result = await commands.execute(commandId, args);
-            // Handle actual Lumino widgets specially by extracting id and title.
-            // Avoid collapsing plain command results that happen to contain an `id` field.
-            let serializedResult;
-            if (result instanceof Widget) {
-                serializedResult = {
-                    id: result.id,
-                    title: result.title?.label || result.title
-                };
-            }
-            else {
-                // For other objects, try JSON serialization with fallback
-                try {
-                    serializedResult = JSON.parse(JSON.stringify(result));
-                }
-                catch {
-                    serializedResult = result
-                        ? '[Complex object - cannot serialize]'
-                        : 'Command executed successfully';
-                }
-            }
-            return {
-                success: true,
-                commandId,
-                result: serializedResult
-            };
-        }
-    });
-}

package/lib/tools/skills.d.ts

@@ -1,9 +0,0 @@
-import { ISkillRegistry, ITool } from '../tokens';
-/**
- * Create a tool to discover available skills and their summaries.
- */
-export declare function createDiscoverSkillsTool(skillRegistry: ISkillRegistry): ITool;
-/**
- * Create a tool to load skill instructions or a bundled resource.
- */
-export declare function createLoadSkillTool(skillRegistry: ISkillRegistry): ITool;

package/lib/tools/skills.js

@@ -1,73 +0,0 @@
-import { tool } from 'ai';
-import { z } from 'zod';
-/**
- * Create a tool to discover available skills and their summaries.
- */
-export function createDiscoverSkillsTool(skillRegistry) {
-    return tool({
-        title: 'Discover Skills',
-        description: 'Discover available agent skills with their names and descriptions',
-        inputSchema: z.object({
-            query: z
-                .string()
-                .optional()
-                .nullable()
-                .describe('Optional search query to filter skills')
-        }),
-        execute: async (input) => {
-            const filtered = skillRegistry.listSkills(input.query ?? undefined);
-            return {
-                success: true,
-                skillCount: filtered.length,
-                skills: filtered
-            };
-        }
-    });
-}
-/**
- * Create a tool to load skill instructions or a bundled resource.
- */
-export function createLoadSkillTool(skillRegistry) {
-    return tool({
-        title: 'Load Skill',
-        description: 'Load a skill definition or a specific resource file bundled with a skill',
-        inputSchema: z.object({
-            name: z.string().describe('The name of the skill to load'),
-            resource: z
-                .string()
-                .optional()
-                .nullable()
-                .describe('Optional resource path to load from the skill (e.g. references/REFERENCE.md)')
-        }),
-        execute: async (input) => {
-            const { name, resource } = input;
-            if (resource) {
-                const result = await skillRegistry.getSkillResource(name, resource);
-                if (result.error) {
-                    return {
-                        success: false,
-                        ...result
-                    };
-                }
-                return {
-                    success: true,
-                    ...result
-                };
-            }
-            const skill = skillRegistry.getSkill(name);
-            if (!skill) {
-                return {
-                    success: false,
-                    error: `Skill not found: ${name}`
-                };
-            }
-            return {
-                success: true,
-                name: skill.name,
-                description: skill.description,
-                instructions: skill.instructions,
-                ...(skill.resources.length > 0 && { resources: skill.resources })
-            };
-        }
-    });
-}

package/lib/tools/tool-registry.d.ts

@@ -1,35 +0,0 @@
-import { ISignal } from '@lumino/signaling';
-import { ITool, IToolRegistry, INamedTool } from '../tokens';
-/**
- * Implementation of the tool registry for managing AI tools
- */
-export declare class ToolRegistry implements IToolRegistry {
-    /**
-     * The registered tools as a record (name -> tool mapping).
-     */
-    get tools(): Record<string, ITool>;
-    /**
-     * The registered named tools array.
-     */
-    get namedTools(): INamedTool[];
-    /**
-     * A signal triggered when the tools have changed.
-     */
-    get toolsChanged(): ISignal<IToolRegistry, void>;
-    /**
-     * Add a new tool to the registry.
-     */
-    add(name: string, tool: ITool): void;
-    /**
-     * Get a tool for a given name.
-     * Return null if the name is not provided or if there is no registered tool with the
-     * given name.
-     */
-    get(name: string | null): ITool | null;
-    /**
-     * Remove a tool from the registry by name.
-     */
-    remove(name: string): boolean;
-    private _tools;
-    private _toolsChanged;
-}

package/lib/tools/tool-registry.js

@@ -1,55 +0,0 @@
-import { Signal } from '@lumino/signaling';
-/**
- * Implementation of the tool registry for managing AI tools
- */
-export class ToolRegistry {
-    /**
-     * The registered tools as a record (name -> tool mapping).
-     */
-    get tools() {
-        return { ...this._tools }; // Return a copy to prevent external modification
-    }
-    /**
-     * The registered named tools array.
-     */
-    get namedTools() {
-        return Object.entries(this._tools).map(([name, tool]) => ({ name, tool }));
-    }
-    /**
-     * A signal triggered when the tools have changed.
-     */
-    get toolsChanged() {
-        return this._toolsChanged;
-    }
-    /**
-     * Add a new tool to the registry.
-     */
-    add(name, tool) {
-        this._tools[name] = tool;
-        this._toolsChanged.emit();
-    }
-    /**
-     * Get a tool for a given name.
-     * Return null if the name is not provided or if there is no registered tool with the
-     * given name.
-     */
-    get(name) {
-        if (name === null) {
-            return null;
-        }
-        return this._tools[name] || null;
-    }
-    /**
-     * Remove a tool from the registry by name.
-     */
-    remove(name) {
-        if (name in this._tools) {
-            delete this._tools[name];
-            this._toolsChanged.emit();
-            return true;
-        }
-        return false;
-    }
-    _tools = {};
-    _toolsChanged = new Signal(this);
-}

package/lib/tools/web.d.ts

@@ -1,8 +0,0 @@
-import { ITool } from '../tokens';
-/**
- * Create a browser-native URL fetch tool.
- *
- * This is best-effort and subject to normal browser constraints (CORS, CSP,
- * mixed content, bot protections).
- */
-export declare function createBrowserFetchTool(): ITool;

package/lib/tools/web.js

@@ -1,196 +0,0 @@
-import { tool } from 'ai';
-import { z } from 'zod';
-const DEFAULT_MAX_CONTENT_CHARS = 20000;
-const MAX_ALLOWED_CONTENT_CHARS = 100000;
-const DEFAULT_TIMEOUT_MS = 20000;
-const MAX_TIMEOUT_MS = 120000;
-/**
- * Read response body text with a character cap.
- *
- * Stops early once the cap is reached to avoid buffering arbitrarily large
- * payloads in memory.
- */
-async function readResponseText(response, maxContentChars) {
-    if (!response.body) {
-        const body = await response.text();
-        return {
-            content: body.slice(0, maxContentChars),
-            isTruncated: body.length > maxContentChars,
-            totalChars: body.length,
-            totalCharsExact: true
-        };
-    }
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let content = '';
-    let totalChars = 0;
-    let isTruncated = false;
-    let done = false;
-    while (!done) {
-        const readResult = await reader.read();
-        done = readResult.done;
-        if (done) {
-            continue;
-        }
-        const chunk = decoder.decode(readResult.value, { stream: true });
-        if (!chunk) {
-            continue;
-        }
-        totalChars += chunk.length;
-        if (!isTruncated) {
-            const remaining = maxContentChars - content.length;
-            if (chunk.length <= remaining) {
-                content += chunk;
-            }
-            else {
-                content += chunk.slice(0, remaining);
-                isTruncated = true;
-            }
-        }
-        if (isTruncated) {
-            await reader.cancel();
-            return {
-                content,
-                isTruncated: true,
-                totalChars,
-                totalCharsExact: false
-            };
-        }
-    }
-    const tail = decoder.decode();
-    if (tail) {
-        totalChars += tail.length;
-        const remaining = maxContentChars - content.length;
-        if (tail.length <= remaining) {
-            content += tail;
-        }
-        else {
-            content += tail.slice(0, remaining);
-            isTruncated = true;
-        }
-    }
-    return {
-        content,
-        isTruncated,
-        totalChars,
-        totalCharsExact: true
-    };
-}
-/**
- * Create a browser-native URL fetch tool.
- *
- * This is best-effort and subject to normal browser constraints (CORS, CSP,
- * mixed content, bot protections).
- */
-export function createBrowserFetchTool() {
-    return tool({
-        title: 'Browser Fetch',
-        description: 'Fetch a URL directly from the browser using HTTP GET for exact URL inspection when CORS/access permits.',
-        inputSchema: z.object({
-            url: z.string().describe('HTTP(S) URL to fetch'),
-            maxContentChars: z
-                .number()
-                .int()
-                .min(1)
-                .max(MAX_ALLOWED_CONTENT_CHARS)
-                .optional()
-                .describe(`Maximum number of response characters to return (default: ${DEFAULT_MAX_CONTENT_CHARS})`),
-            timeoutMs: z
-                .number()
-                .int()
-                .min(1000)
-                .max(MAX_TIMEOUT_MS)
-                .optional()
-                .describe(`Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS})`)
-        }),
-        execute: async (input) => {
-            const maxContentChars = Math.min(input.maxContentChars ?? DEFAULT_MAX_CONTENT_CHARS, MAX_ALLOWED_CONTENT_CHARS);
-            const timeoutMs = Math.min(input.timeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
-            let parsedUrl;
-            try {
-                parsedUrl = new URL(input.url);
-            }
-            catch {
-                return {
-                    success: false,
-                    errorType: 'invalid_url',
-                    error: 'Invalid URL format',
-                    url: input.url
-                };
-            }
-            if (!['http:', 'https:'].includes(parsedUrl.protocol)) {
-                return {
-                    success: false,
-                    errorType: 'unsupported_protocol',
-                    error: 'Only http:// and https:// URLs are supported',
-                    url: input.url
-                };
-            }
-            const controller = new AbortController();
-            const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
-            try {
-                const response = await fetch(parsedUrl.toString(), {
-                    method: 'GET',
-                    credentials: 'omit',
-                    redirect: 'follow',
-                    signal: controller.signal,
-                    headers: {
-                        Accept: 'text/html,text/plain,application/json,text/markdown,*/*;q=0.8'
-                    }
-                });
-                const contentType = response.headers.get('content-type') || '';
-                const contentLength = response.headers.get('content-length');
-                const body = await readResponseText(response, maxContentChars);
-                const success = response.ok;
-                return {
-                    success,
-                    url: response.url,
-                    requestedUrl: parsedUrl.toString(),
-                    status: response.status,
-                    statusText: response.statusText,
-                    contentType,
-                    contentLength,
-                    ...(success
-                        ? {}
-                        : {
-                            errorType: 'http_error',
-                            error: `HTTP ${response.status} ${response.statusText}`
-                        }),
-                    isTruncated: body.isTruncated,
-                    returnedChars: body.content.length,
-                    totalChars: body.totalChars,
-                    totalCharsExact: body.totalCharsExact,
-                    content: body.content,
-                    limitations: 'Browser fetch is subject to CORS, site bot protections, and browser network policy.'
-                };
-            }
-            catch (error) {
-                if (error.name === 'AbortError') {
-                    return {
-                        success: false,
-                        errorType: 'timeout',
-                        error: `Request timed out after ${timeoutMs} ms`,
-                        url: parsedUrl.toString()
-                    };
-                }
-                return {
-                    success: false,
-                    errorType: 'network_or_cors',
-                    error: error instanceof Error && error.message
-                        ? error.message
-                        : 'Fetch failed',
-                    url: parsedUrl.toString(),
-                    likelyCauses: [
-                        'CORS blocked by the target website',
-                        'DNS/network resolution failure',
-                        'TLS/certificate issue',
-                        'Target server rejected browser access'
-                    ]
-                };
-            }
-            finally {
-                clearTimeout(timeoutHandle);
-            }
-        }
-    });
-}