@jupyterlite/ai 0.12.0 → 0.13.0

package/src/providers/provider-tools.ts

@@ -0,0 +1,179 @@
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import type { Tool } from 'ai';
+
+import type {
+  IProviderInfo,
+  IProviderWebFetchImplementation,
+  IProviderWebSearchImplementation
+} from '../tokens';
+
+type ToolMap = Record<string, Tool>;
+
+interface IWebSearchSettings {
+  enabled?: boolean;
+  externalWebAccess?: boolean;
+  searchContextSize?: 'low' | 'medium' | 'high';
+  allowedDomains?: string[];
+  blockedDomains?: string[];
+  maxUses?: number;
+}
+
+interface IWebFetchSettings {
+  enabled?: boolean;
+  maxUses?: number;
+  maxContentTokens?: number;
+  allowedDomains?: string[];
+  blockedDomains?: string[];
+  citationsEnabled?: boolean;
+}
+
+/**
+ * Provider-level custom settings that control built-in web tools.
+ */
+export interface IProviderCustomSettings {
+  webSearch?: IWebSearchSettings;
+  webFetch?: IWebFetchSettings;
+}
+
+interface IProviderToolContext {
+  providerInfo?: IProviderInfo | null;
+  customSettings?: IProviderCustomSettings;
+  hasFunctionTools: boolean;
+}
+
+const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES = 2;
+const DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS = 12000;
+
+function normalizeDomain(value: string): string {
+  const normalized = (value || '').trim().toLowerCase();
+  const withoutProtocol = normalized.replace(/^https?:\/\//, '');
+  const hostname = withoutProtocol.split('/')[0].trim();
+  // Treat "*.example.com" as "example.com" for provider domain filters.
+  return hostname.startsWith('*.') ? hostname.slice(2) : hostname;
+}
+
+function collectDomains(value?: string[]): string[] {
+  value = value || [];
+  const values = Array.from(
+    new Set(value.map(normalizeDomain).filter(domain => domain.length > 0))
+  );
+
+  return values;
+}
+
+function createOpenAIWebSearchTool(
+  webSearchSettings: IWebSearchSettings
+): Tool {
+  const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
+  return openai.tools.webSearch({
+    externalWebAccess: webSearchSettings.externalWebAccess,
+    searchContextSize: webSearchSettings.searchContextSize,
+    filters: allowedDomains.length > 0 ? { allowedDomains } : undefined
+  });
+}
+
+function createAnthropicWebSearchTool(
+  webSearchSettings: IWebSearchSettings
+): Tool {
+  const allowedDomains = collectDomains(webSearchSettings.allowedDomains);
+  const blockedDomains = collectDomains(webSearchSettings.blockedDomains);
+  return anthropic.tools.webSearch_20250305({
+    maxUses: webSearchSettings.maxUses,
+    allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
+    blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined
+  });
+}
+
+function createAnthropicWebFetchTool(
+  webFetchSettings: IWebFetchSettings
+): Tool {
+  const maxUses =
+    webFetchSettings.maxUses ?? DEFAULT_ANTHROPIC_WEB_FETCH_MAX_USES;
+  const maxContentTokens =
+    webFetchSettings.maxContentTokens ??
+    DEFAULT_ANTHROPIC_WEB_FETCH_MAX_CONTENT_TOKENS;
+  const allowedDomains = collectDomains(webFetchSettings.allowedDomains);
+  const blockedDomains = collectDomains(webFetchSettings.blockedDomains);
+  const citationsEnabled = webFetchSettings.citationsEnabled;
+  return anthropic.tools.webFetch_20250910({
+    maxUses,
+    maxContentTokens,
+    allowedDomains: allowedDomains.length > 0 ? allowedDomains : undefined,
+    blockedDomains: blockedDomains.length > 0 ? blockedDomains : undefined,
+    citations:
+      citationsEnabled !== undefined ? { enabled: citationsEnabled } : undefined
+  });
+}
+
+function createWebSearchTool(
+  implementation: IProviderWebSearchImplementation,
+  webSearchSettings: IWebSearchSettings
+): Tool {
+  switch (implementation) {
+    case 'openai':
+      return createOpenAIWebSearchTool(webSearchSettings);
+    case 'anthropic':
+      return createAnthropicWebSearchTool(webSearchSettings);
+    default:
+      throw new Error(
+        `Unsupported web search implementation: ${implementation}`
+      );
+  }
+}
+
+function createWebFetchTool(
+  implementation: IProviderWebFetchImplementation,
+  webFetchSettings: IWebFetchSettings
+): Tool {
+  switch (implementation) {
+    case 'anthropic':
+      return createAnthropicWebFetchTool(webFetchSettings);
+    default:
+      throw new Error(
+        `Unsupported web fetch implementation: ${implementation}`
+      );
+  }
+}
+
+/**
+ * Create provider-defined tools from custom settings and provider capabilities.
+ */
+export function createProviderTools(options: IProviderToolContext): ToolMap {
+  const tools: ToolMap = {};
+  if (
+    !options.customSettings ||
+    !options.providerInfo?.providerToolCapabilities
+  ) {
+    return tools;
+  }
+
+  const capabilities = options.providerInfo.providerToolCapabilities;
+  const webSearchSettings = options.customSettings.webSearch;
+  const webFetchSettings = options.customSettings.webFetch;
+
+  const webSearchEnabled = webSearchSettings?.enabled === true;
+  const webFetchEnabled = webFetchSettings?.enabled === true;
+
+  const webSearchCapability = capabilities.webSearch;
+  if (webSearchEnabled && webSearchSettings && webSearchCapability) {
+    const requiresNoFunctionTools =
+      webSearchCapability.requiresNoFunctionTools === true;
+    if (!requiresNoFunctionTools || !options.hasFunctionTools) {
+      tools.web_search = createWebSearchTool(
+        webSearchCapability.implementation,
+        webSearchSettings
+      );
+    }
+  }
+
+  const webFetchCapability = capabilities.webFetch;
+  if (webFetchEnabled && webFetchSettings && webFetchCapability) {
+    tools.web_fetch = createWebFetchTool(
+      webFetchCapability.implementation,
+      webFetchSettings
+    );
+  }
+
+  return tools;
+}

package/src/rendered-message-outputarea.ts

@@ -0,0 +1,62 @@
+import { ChatWidget } from '@jupyter/chat';
+import { IDisposable } from '@lumino/disposable';
+
+const OUTPUT_AREA_CLASS = 'jp-OutputArea';
+const CHAT_RENDERED_MESSAGE_SELECTOR = `.jp-chat-rendered-message:not(.${OUTPUT_AREA_CLASS})`;
+
+/**
+ * Ensures chat-rendered MIME outputs also expose the OutputArea class so
+ * renderer extensions can reuse their notebook/output-area CSS rules.
+ *
+ * TODO: Remove this compatibility layer once jupyter-chat applies
+ * `jp-OutputArea` (or equivalent output-area context) to rendered MIME
+ * messages by default.
+ */
+export class RenderedMessageOutputAreaCompat implements IDisposable {
+  constructor(options: RenderedMessageOutputAreaCompat.IOptions) {
+    this._chatPanel = options.chatPanel;
+    this._chatPanel.model.messagesUpdated.connect(this._scheduleSync, this);
+    this._scheduleSync();
+  }
+
+  get isDisposed(): boolean {
+    return this._isDisposed;
+  }
+
+  dispose(): void {
+    if (this._isDisposed) {
+      return;
+    }
+    this._isDisposed = true;
+    this._chatPanel.model.messagesUpdated.disconnect(this._scheduleSync, this);
+    if (this._raf !== 0) {
+      cancelAnimationFrame(this._raf);
+      this._raf = 0;
+    }
+  }
+
+  private _scheduleSync(): void {
+    if (this._isDisposed || this._raf !== 0) {
+      return;
+    }
+    this._raf = requestAnimationFrame(() => {
+      this._raf = 0;
+      if (this._isDisposed) {
+        return;
+      }
+      this._chatPanel.node
+        .querySelectorAll<HTMLElement>(CHAT_RENDERED_MESSAGE_SELECTOR)
+        .forEach(element => element.classList.add(OUTPUT_AREA_CLASS));
+    });
+  }
+
+  private readonly _chatPanel: ChatWidget;
+  private _isDisposed = false;
+  private _raf = 0;
+}
+
+export namespace RenderedMessageOutputAreaCompat {
+  export interface IOptions {
+    chatPanel: ChatWidget;
+  }
+}

package/src/tokens.ts

@@ -168,6 +168,49 @@ export interface IProviderFactory {
   (options: IModelOptions): LanguageModel;
 }
 
+/**
+ * Built-in web search integration families supported by provider tools.
+ */
+export type IProviderWebSearchImplementation = 'openai' | 'anthropic';
+
+/**
+ * Built-in web fetch integration families supported by provider tools.
+ */
+export type IProviderWebFetchImplementation = 'anthropic';
+
+/**
+ * Capability descriptor for provider-hosted web search.
+ */
+export interface IProviderWebSearchCapability {
+  /**
+   * Which built-in integration family to use.
+   */
+  implementation: IProviderWebSearchImplementation;
+
+  /**
+   * If true, skip provider-hosted web search when function tools are enabled.
+   */
+  requiresNoFunctionTools?: boolean;
+}
+
+/**
+ * Capability descriptor for provider-hosted web fetch.
+ */
+export interface IProviderWebFetchCapability {
+  /**
+   * Which built-in integration family to use.
+   */
+  implementation: IProviderWebFetchImplementation;
+}
+
+/**
+ * Provider-hosted tool capabilities exposed by a provider.
+ */
+export interface IProviderToolCapabilities {
+  webSearch?: IProviderWebSearchCapability;
+  webFetch?: IProviderWebFetchCapability;
+}
+
 /**
  * Provider information
  */
@@ -220,6 +263,11 @@ export interface IProviderInfo {
    */
   baseUrls?: { url: string; description?: string }[];
 
+  /**
+   * Optional provider-hosted tool capabilities for web retrieval.
+   */
+  providerToolCapabilities?: IProviderToolCapabilities;
+
   /**
    * Factory function for creating language models
    */
@@ -296,21 +344,17 @@ export const IAgentManagerFactory = new Token<AgentManagerFactory>(
   '@jupyterlite/ai:agent-manager-factory'
 );
 
-export interface IChatModelRegistry {
-  add(model: AIChatModel): void;
-  get(name: string): AIChatModel | undefined;
-  getAll(): AIChatModel[];
-  remove(name: string): void;
+export interface IChatModelHandler {
   createModel(
-    name?: string,
-    activeProvider?: string,
+    name: string,
+    activeProvider: string,
     tokenUsage?: ITokenUsage
   ): AIChatModel;
   activeCellManager: ActiveCellManager | undefined;
 }
 
-export const IChatModelRegistry = new Token<IChatModelRegistry>(
-  '@jupyterlite/ai:chat-model-registry'
+export const IChatModelHandler = new Token<IChatModelHandler>(
+  '@jupyterlite/ai:chat-model-handler'
 );
 
 /**

package/src/tools/commands.ts

@@ -1,4 +1,5 @@
 import { CommandRegistry } from '@lumino/commands';
+import { Widget } from '@lumino/widgets';
 import { tool } from 'ai';
 import { z } from 'zod';
 import { ITool } from '../tokens';
@@ -115,9 +116,10 @@ export function createExecuteCommandTool(
       // Execute the command
       const result = await commands.execute(commandId, args);
 
-      // Handle Widget objects specially by extracting id and title
+      // 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 && typeof result === 'object' && result.id) {
+      if (result instanceof Widget) {
         serializedResult = {
           id: result.id,
           title: result.title?.label || result.title

package/src/tools/web.ts

@@ -0,0 +1,238 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { ITool } from '../tokens';
+
+const DEFAULT_MAX_CONTENT_CHARS = 20000;
+const MAX_ALLOWED_CONTENT_CHARS = 100000;
+const DEFAULT_TIMEOUT_MS = 20000;
+const MAX_TIMEOUT_MS = 120000;
+
+interface IReadBodyResult {
+  content: string;
+  isTruncated: boolean;
+  totalChars: number;
+  totalCharsExact: boolean;
+}
+
+/**
+ * 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: Response,
+  maxContentChars: number
+): Promise<IReadBodyResult> {
+  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(): ITool {
+  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: {
+      url: string;
+      maxContentChars?: number;
+      timeoutMs?: number;
+    }) => {
+      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: URL;
+      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 as 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);
+      }
+    }
+  });
+}