nexus-ai-pro 2.20.2 → 2.22.0

package/dist/loaders/web.d.ts

@@ -28,7 +28,62 @@ export interface WebLoaderOptions extends SafeFetchPolicy {
     onError?: 'throw' | 'skip';
     /** Called for each page skipped, with the reason. */
     onSkip?: (url: string, reason: Error) => void;
+    /**
+     * Renders a page whose content a script builds, with a browser of the application's own, such as
+     * `browserRenderer()` over Playwright's: given the page fetched, it returns the HTML the browser ends
+     * with. Called for an HTML page that runs a script and whose text, as fetched, is shorter than
+     * `renderBelow`. The fetch has checked the page's URL first; the browser fetches what the page
+     * loads under its own policy.
+     */
+    render?: WebPageRenderer;
+    /** Renders a page whose fetched text is shorter than this many characters. Defaults to 200; `Infinity` renders every page that runs a script. */
+    renderBelow?: number;
+}
+/** A page as fetched, which a renderer is given. */
+export interface WebPageToRender {
+    /** Its URL, after redirects. */
+    url: string;
+    /** The HTML the server sent. */
+    html: string;
+}
+/**
+ * Renders a page with a browser: the HTML it ends with once the page's scripts have run, which is
+ * what a page built by script holds.
+ */
+export type WebPageRenderer = (page: WebPageToRender, signal: AbortSignal) => Promise<string> | string;
+/** What `browserRenderer()` drives: a Playwright or Puppeteer browser, or anything shaped like one. */
+export interface RenderingBrowser {
+    /** Opens a page. */
+    newPage(): Promise<{
+        /** Goes to a URL and waits as told. */
+        goto(url: string, options?: {
+            waitUntil?: string;
+            timeout?: number;
+        }): Promise<unknown>;
+        /** The HTML the page holds now. */
+        content(): Promise<string>;
+        /** Closes it. */
+        close(): Promise<unknown>;
+    }>;
+}
+/** Options for `browserRenderer()`. */
+export interface BrowserRendererOptions {
+    /** When the page counts as rendered. Defaults to `networkidle`, as Playwright names it. */
+    waitUntil?: string;
+    /** Time allowed per page, in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
 }
+/**
+ * A renderer over a browser of the application's own, such as Playwright's `chromium.launch()`: each
+ * page is opened, waited on, read, and closed. The package depends on no browser; the browser fetches
+ * the page and what it loads under its own network policy, not the loader's.
+ *
+ * ```ts
+ * const browser = await chromium.launch();
+ * for await (const page of loadWebPages(urls, { render: browserRenderer(browser) })) store(page);
+ * ```
+ */
+export declare function browserRenderer(browser: RenderingBrowser, options?: BrowserRendererOptions): WebPageRenderer;
 /** Raised when a page cannot be loaded: a status that is not 2xx, or a type that is not text. */
 export declare class WebLoaderError extends Error {
     /** The page. */

package/dist/loaders/web.js

@@ -1,5 +1,19 @@
 import { parseUrl, safeFetch } from '../utils/safe-fetch.js';
 import { htmlToText } from './html.js';
+export function browserRenderer(browser, options = {}) {
+    return async (page, signal) => {
+        signal.throwIfAborted();
+        const tab = await browser.newPage();
+        try {
+            await tab.goto(page.url, { waitUntil: options.waitUntil ?? 'networkidle', timeout: options.timeoutMs ?? 30_000 });
+            signal.throwIfAborted();
+            return await tab.content();
+        }
+        finally {
+            await tab.close().catch(() => undefined);
+        }
+    };
+}
 const MAX_SITEMAP_BYTES = 50 * 1024 * 1024;
 export class WebLoaderError extends Error {
     url;
@@ -84,7 +98,12 @@ async function loadPage(url, options) {
     const body = new TextDecoder().decode(response.bytes);
     const metadata = { ...options.metadata, url: response.url };
     if (type === 'text/html' || type === 'application/xhtml+xml' || (!type && /^\s*</.test(body))) {
-        const page = htmlToText(body, { baseUrl: response.url, mainContent: options.mainContent });
+        let page = htmlToText(body, { baseUrl: response.url, mainContent: options.mainContent });
+        if (options.render && page.text.length < (options.renderBelow ?? 200) && /<script\b/i.test(body)) {
+            const html = await options.render({ url: response.url, html: body }, options.signal ?? new AbortController().signal);
+            page = htmlToText(html, { baseUrl: response.url, mainContent: options.mainContent });
+            metadata.rendered = true;
+        }
         if (page.title)
             metadata.title = page.title;
         if (page.description)

package/dist/mcp/client.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition } from '../types/messages.js';
-import { type McpTransport } from './protocol.js';
+import { type McpElicitationRequest, type McpElicitationResult, type McpRoot, type McpSamplingRequest, type McpSamplingResult, type McpTransport } from './protocol.js';
 /**
  * What a server says a tool does, as MCP's tool annotations: hints, which a client trusts only as far
  * as it trusts the server. A hint left out takes the specification's default.
@@ -99,6 +99,26 @@ export interface McpClientOptions {
      * `reopen` a new stream.
      */
     reconnect?: boolean;
+    /**
+     * Answers a server's `sampling/createMessage` with this client's model, so a server's tool can ask
+     * for a completion: `samplingFrom(ai, { model })` is one. Declared to the server when given;
+     * without it, a server's request for one is refused.
+     */
+    sampling?: (request: McpSamplingRequest, context: {
+        signal: AbortSignal;
+    }) => McpSamplingResult | Promise<McpSamplingResult>;
+    /**
+     * Answers a server's `elicitation/create`, a question for the person using this client, with the
+     * form of its answer. Declared to the server when given; without it, a request is refused.
+     */
+    elicitation?: (request: McpElicitationRequest, context: {
+        signal: AbortSignal;
+    }) => McpElicitationResult | Promise<McpElicitationResult>;
+    /**
+     * The roots a server may work within, answered to its `roots/list`. Declared to the server when
+     * given; `rootsChanged()` tells it they changed.
+     */
+    roots?: () => McpRoot[] | Promise<McpRoot[]>;
 }
 /**
  * Talks to an MCP server.
@@ -119,6 +139,10 @@ export declare class McpClient {
     private serverInfo;
     /** Who hears that the server's tools changed. */
     private readonly toolsChanged;
+    /** Who hears each of the server's notifications, by method. */
+    private readonly listeners;
+    /** Requests the server is waiting on this client for, by id, so a cancellation stops them. */
+    private readonly answering;
     private stopped;
     constructor(transport: McpTransport, options?: McpClientOptions);
     /**
@@ -126,6 +150,22 @@ export declare class McpClient {
      * `listTools()` returned. Returns a function that stops hearing.
      */
     onToolsChanged(handler: () => void): () => void;
+    /** Hears each `notifications/prompts/list_changed`: the server's prompts changed. Returns a function that stops hearing. */
+    onPromptsChanged(handler: () => void): () => void;
+    /** Hears each `notifications/resources/list_changed`: the server's resources changed. Returns a function that stops hearing. */
+    onResourcesChanged(handler: () => void): () => void;
+    /**
+     * Hears each `notifications/resources/updated`, for a resource this client subscribed to with
+     * `subscribeResource()`: its URI. Returns a function that stops hearing.
+     */
+    onResourceUpdated(handler: (uri: string) => void): () => void;
+    /** Asks the server to say when a resource changes, by `onResourceUpdated()`. */
+    subscribeResource(uri: string): Promise<void>;
+    /** Stops hearing that a resource changed. */
+    unsubscribeResource(uri: string): Promise<void>;
+    /** Tells the server this client's roots changed, so it lists them again. */
+    rootsChanged(): Promise<void>;
+    private listen;
     /**
      * Performs the handshake and returns the server's name and version. Called automatically by the
      * first request that needs it; requests made together share one handshake.
@@ -174,6 +214,8 @@ export declare class McpClient {
     private request;
     private notify;
     private receive;
+    /** Answers one request the server sent, with its result or why not. */
+    private answer;
     private settle;
     private failAll;
 }
@@ -218,12 +260,19 @@ export interface HttpClientOptions {
     headers?: Record<string, string>;
     /** Replaces the global `fetch`. */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Holds a `GET` stream open once the server names a session, for what the server sends of its own
+     * accord: notifications that its tools or resources changed, and requests outside any call. A server
+     * that answers it with 405 does not offer one, and none is opened. Off by default.
+     */
+    listen?: boolean;
 }
 /**
- * Speaks to an MCP server over HTTP, one POST per message.
- *
- * Server-initiated streaming is not implemented: this covers request and response, which is what
- * calling a tool needs.
+ * Speaks to an MCP server over streamable HTTP, MCP's transport since 2025-03-26: a `POST` per
+ * message, answered as JSON or as a stream of events the transport reads as they come, so a server
+ * may report progress and ask this client for something in the middle of a call. With `listen`, a
+ * `GET` stream carries what the server sends of its own accord. It keeps the session the server
+ * names, sends the protocol version on every request, and ends the session when it closes.
  */
 export declare function createHttpTransport(options: HttpClientOptions): McpTransport;
 /** Connects to a remote MCP server over HTTP with Server-Sent Events, the transport before streamable HTTP. */

package/dist/mcp/client.js

@@ -16,6 +16,8 @@ export class McpClient {
     connecting;
     serverInfo = {};
     toolsChanged = new Set();
+    listeners = new Map();
+    answering = new Map();
     stopped = false;
     constructor(transport, options = {}) {
         this.transport = transport;
@@ -33,6 +35,38 @@ export class McpClient {
             this.toolsChanged.delete(handler);
         };
     }
+    onPromptsChanged(handler) {
+        return this.listen('notifications/prompts/list_changed', () => handler());
+    }
+    onResourcesChanged(handler) {
+        return this.listen('notifications/resources/list_changed', () => handler());
+    }
+    onResourceUpdated(handler) {
+        return this.listen('notifications/resources/updated', (params) => handler(String(params.uri ?? '')));
+    }
+    async subscribeResource(uri) {
+        await this.connect();
+        await this.request('resources/subscribe', { uri });
+    }
+    async unsubscribeResource(uri) {
+        await this.connect();
+        await this.request('resources/unsubscribe', { uri });
+    }
+    async rootsChanged() {
+        await this.connect();
+        await this.notify('notifications/roots/list_changed');
+    }
+    listen(method, handler) {
+        let handlers = this.listeners.get(method);
+        if (!handlers) {
+            handlers = new Set();
+            this.listeners.set(method, handlers);
+        }
+        handlers.add(handler);
+        return () => {
+            handlers.delete(handler);
+        };
+    }
     async connect() {
         if (this.initialized)
             return this.serverInfo;
@@ -45,7 +79,14 @@ export class McpClient {
         await this.transport.start?.();
         const result = (await this.request('initialize', {
             protocolVersion: MCP_PROTOCOL_VERSION,
-            capabilities: { tools: {}, resources: {}, prompts: {} },
+            capabilities: {
+                tools: {},
+                resources: {},
+                prompts: {},
+                ...(this.options.sampling ? { sampling: {} } : {}),
+                ...(this.options.elicitation ? { elicitation: {} } : {}),
+                ...(this.options.roots ? { roots: { listChanged: true } } : {}),
+            },
             clientInfo: this.options.clientInfo ?? { name: 'nexus-ai-pro', version: '1.x' },
         }));
         this.initialized = true;
@@ -164,6 +205,22 @@ export class McpClient {
             }
             return;
         }
+        if (isNotification(message) && message.method === 'notifications/cancelled') {
+            const requestId = message.params?.requestId;
+            if (requestId !== undefined)
+                this.answering.get(requestId)?.abort(new McpError('The server cancelled its request'));
+            return;
+        }
+        if (isNotification(message) && this.listeners.has(message.method)) {
+            for (const handler of this.listeners.get(message.method) ?? []) {
+                try {
+                    handler((message.params ?? {}));
+                }
+                catch {
+                }
+            }
+            return;
+        }
         if (isNotification(message) && message.method === 'notifications/progress') {
             const params = (message.params ?? {});
             const report = this.progress.get(String(params.progressToken));
@@ -174,12 +231,49 @@ export class McpClient {
             });
             return;
         }
-        if (isRequest(message)) {
-            void this.transport.send({
+        if (isRequest(message))
+            void this.answer(message.id, message.method, message.params);
+    }
+    async answer(id, method, params) {
+        const controller = new AbortController();
+        this.answering.set(id, controller);
+        const handlers = {
+            ping: () => ({}),
+            'sampling/createMessage': this.options.sampling
+                ? () => this.options.sampling(params, {
+                    signal: controller.signal,
+                })
+                : undefined,
+            'elicitation/create': this.options.elicitation
+                ? () => this.options.elicitation(params, { signal: controller.signal })
+                : undefined,
+            'roots/list': this.options.roots
+                ? async () => ({ roots: await this.options.roots() })
+                : undefined,
+        };
+        const handler = Object.hasOwn(handlers, method) ? handlers[method] : undefined;
+        try {
+            if (!handler)
+                throw new McpError(`This client does not implement "${method}"`, -32_601);
+            const result = await handler();
+            if (controller.signal.aborted)
+                return;
+            await this.transport.send({ jsonrpc: '2.0', id, result });
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                return;
+            await Promise.resolve(this.transport.send({
                 jsonrpc: '2.0',
-                id: message.id,
-                error: { code: -32_601, message: `This client does not implement "${message.method}"` },
-            });
+                id,
+                error: {
+                    code: error instanceof McpError ? error.code : -32_603,
+                    message: error instanceof Error ? error.message : String(error),
+                },
+            })).catch(() => undefined);
+        }
+        finally {
+            this.answering.delete(id);
         }
     }
     settle(id, result, error) {
@@ -303,39 +397,96 @@ export function createHttpTransport(options) {
     const fetchImplementation = options.fetch ?? globalThis.fetch;
     let onMessage = () => undefined;
     let sessionId;
+    let listening;
+    let refused = false;
+    const deliver = (data) => {
+        try {
+            onMessage(JSON.parse(data));
+        }
+        catch {
+        }
+    };
+    const headers = () => ({
+        'mcp-protocol-version': MCP_PROTOCOL_VERSION,
+        ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
+        ...options.headers,
+    });
+    const listen = () => {
+        if (!options.listen || !sessionId || listening || refused)
+            return;
+        const own = new AbortController();
+        listening = own;
+        void (async () => {
+            try {
+                const response = await fetchImplementation(options.url, {
+                    method: 'GET',
+                    headers: { accept: 'text/event-stream', ...headers() },
+                    signal: own.signal,
+                });
+                if (response.status === 405)
+                    refused = true;
+                if (!response.ok || !response.body) {
+                    await response.body?.cancel().catch(() => undefined);
+                    return;
+                }
+                await readEvents(response.body.getReader(), (_name, data) => deliver(data));
+            }
+            catch {
+            }
+            finally {
+                if (listening === own)
+                    listening = undefined;
+            }
+        })();
+    };
     return {
         async send(message) {
             const response = await fetchImplementation(options.url, {
                 method: 'POST',
-                headers: {
-                    'content-type': 'application/json',
-                    accept: 'application/json, text/event-stream',
-                    ...(sessionId ? { 'mcp-session-id': sessionId } : {}),
-                    ...options.headers,
-                },
+                headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...headers() },
                 body: JSON.stringify(message),
             });
             sessionId = response.headers.get('mcp-session-id') ?? sessionId;
-            if (!response.ok)
+            if (response.status === 404 && sessionId) {
+                sessionId = undefined;
+                await response.body?.cancel().catch(() => undefined);
+                throw new McpError('The MCP server ended the session');
+            }
+            if (!response.ok) {
+                await response.body?.cancel().catch(() => undefined);
                 throw new McpError(`MCP HTTP transport failed with ${response.status}`);
-            if (response.status === 202)
+            }
+            listen();
+            if (response.status === 202 || !response.body)
+                return;
+            if ((response.headers.get('content-type') ?? '').includes('text/event-stream')) {
+                void readEvents(response.body.getReader(), (_name, data) => deliver(data)).catch(() => undefined);
                 return;
+            }
             const body = await response.text();
             if (!body.trim())
                 return;
             for (const payload of body.startsWith('event:') || body.startsWith('data:') ? sseData(body) : [body]) {
-                try {
-                    onMessage(JSON.parse(payload));
-                }
-                catch {
-                }
+                deliver(payload);
             }
         },
         onMessage(handler) {
             onMessage = handler;
         },
-        close() {
+        async close() {
+            listening?.abort();
+            listening = undefined;
+            const ending = sessionId;
             sessionId = undefined;
+            refused = false;
+            if (ending) {
+                await fetchImplementation(options.url, {
+                    method: 'DELETE',
+                    headers: { ...options.headers, 'mcp-protocol-version': MCP_PROTOCOL_VERSION, 'mcp-session-id': ending },
+                })
+                    .then((response) => response.body?.cancel())
+                    .catch(() => undefined);
+            }
         },
     };
 }

package/dist/mcp/http.d.ts

@@ -0,0 +1,45 @@
+import type { McpServer } from './server.js';
+/** Options for `mcpHttpHandler()`. */
+export interface McpHttpOptions {
+    /**
+     * Origins allowed to call it from a browser, beside the endpoint's own: a request whose `Origin`
+     * header names any other is refused with 403, so a web page cannot reach a server on this machine
+     * through the person's browser.
+     */
+    allowedOrigins?: readonly string[];
+    /**
+     * Answers each request as JSON, after the server finishes, rather than as a stream of events. What
+     * the server sends meanwhile then waits for the session's `GET` stream.
+     */
+    json?: boolean;
+    /** How long a session lasts without a request, in milliseconds. Defaults to 30 minutes. */
+    sessionTtlMs?: number;
+    /** The most sessions held at once: a new one past it is refused with 503. Defaults to 1,000. */
+    maxSessions?: number;
+    /** Makes a new session's id. Defaults to a random UUID. */
+    sessionId?: () => string;
+}
+/** A Web handler serving an MCP server over streamable HTTP, and what it holds. */
+export interface McpHttpHandler {
+    /** Answers one HTTP request: a `POST` of a message, a `GET` stream, or a `DELETE` of a session. */
+    (request: Request): Promise<Response>;
+    /** How many sessions are open. */
+    sessions(): number;
+    /** Ends every session. */
+    close(): Promise<void>;
+}
+/**
+ * Serves an MCP server over streamable HTTP, MCP's transport since 2025-03-26: each client that sends
+ * `initialize` gets a session, named in the `Mcp-Session-Id` header it sends from then on. A request is
+ * answered as a stream of events, which carries the server's progress and its questions for the
+ * client, such as a tool's `context.mcp.createMessage()`, before the answer; with `json`, as JSON. A
+ * notification or an answer the client sends is taken with 202. A `GET` holds the session's own stream,
+ * for what the server sends of its own accord, and a `DELETE` ends the session. A request from a web
+ * page on another origin is refused, unless `allowedOrigins` names it.
+ *
+ * ```ts
+ * const handle = mcpHttpHandler(new McpServer({ tools: [search] }));
+ * Bun.serve({ fetch: handle }); // or any server that speaks Request and Response
+ * ```
+ */
+export declare function mcpHttpHandler(server: McpServer, options?: McpHttpOptions): McpHttpHandler;