nexus-ai-pro 2.16.0 → 2.18.0

package/dist/mcp/client.js

@@ -1,4 +1,11 @@
 import { isNotification, isRequest, isResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
+export function mcpToolCapabilities(tool, server) {
+    const hints = tool.annotations;
+    if (!hints || typeof hints !== 'object')
+        return undefined;
+    const effect = hints.readOnlyHint === true ? 'mcp.read' : hints.destructiveHint === false ? 'mcp.write' : 'mcp.destructive';
+    return [`${effect}:${server}/${tool.name}`, ...(hints.openWorldHint === false ? [] : ['network'])];
+}
 export class McpClient {
     transport;
     options;
@@ -8,11 +15,23 @@ export class McpClient {
     initialized = false;
     connecting;
     serverInfo = {};
+    toolsChanged = new Set();
+    stopped = false;
     constructor(transport, options = {}) {
         this.transport = transport;
         this.options = options;
         transport.onMessage((message) => this.receive(message));
-        transport.onClose?.(() => this.failAll(new McpError('The MCP connection closed')));
+        transport.onClose?.(() => {
+            this.failAll(new McpError('The MCP connection closed'));
+            if (this.options.reconnect && !this.stopped)
+                this.initialized = false;
+        });
+    }
+    onToolsChanged(handler) {
+        this.toolsChanged.add(handler);
+        return () => {
+            this.toolsChanged.delete(handler);
+        };
     }
     async connect() {
         if (this.initialized)
@@ -79,24 +98,37 @@ export class McpClient {
     }
     async toNexusTools(options = {}) {
         const tools = await this.listTools();
-        return tools.map((descriptor) => ({
-            name: options.prefix ? `${options.prefix}_${descriptor.name}` : descriptor.name,
-            description: descriptor.description ?? `MCP tool ${descriptor.name}`,
-            parameters: descriptor.inputSchema ?? { type: 'object', properties: {} },
-            execute: async (args, context) => {
-                const progress = context?.progress;
-                const result = await this.callTool(descriptor.name, args, progress ? { progress } : {});
-                const text = result.content
-                    .map((part) => part.text ?? (part.type === 'text' ? '' : JSON.stringify(part)))
-                    .filter(Boolean)
-                    .join('\n');
-                if (result.isError)
-                    throw new McpError(text || `MCP tool ${descriptor.name} failed`);
-                return text;
-            },
-        }));
+        const server = options.server ?? options.prefix ?? this.serverInfo.name ?? 'mcp';
+        const declared = (descriptor) => {
+            const { capabilities } = options;
+            if (!capabilities)
+                return undefined;
+            const list = capabilities === true ? mcpToolCapabilities(descriptor, server) : capabilities(descriptor);
+            return list === undefined ? undefined : [...list];
+        };
+        return tools.map((descriptor) => {
+            const capabilities = declared(descriptor);
+            return {
+                name: options.prefix ? `${options.prefix}_${descriptor.name}` : descriptor.name,
+                description: descriptor.description ?? `MCP tool ${descriptor.name}`,
+                parameters: descriptor.inputSchema ?? { type: 'object', properties: {} },
+                ...(capabilities ? { capabilities } : {}),
+                execute: async (args, context) => {
+                    const progress = context?.progress;
+                    const result = await this.callTool(descriptor.name, args, progress ? { progress } : {});
+                    const text = result.content
+                        .map((part) => part.text ?? (part.type === 'text' ? '' : JSON.stringify(part)))
+                        .filter(Boolean)
+                        .join('\n');
+                    if (result.isError)
+                        throw new McpError(text || `MCP tool ${descriptor.name} failed`);
+                    return text;
+                },
+            };
+        });
     }
     async close() {
+        this.stopped = true;
         this.failAll(new McpError('The MCP client was closed'));
         await this.transport.close();
     }
@@ -122,6 +154,16 @@ export class McpClient {
             this.settle(message.id, message.result, message.error ? new McpError(message.error.message, message.error.code, message.error.data) : undefined);
             return;
         }
+        if (isNotification(message) && message.method === 'notifications/tools/list_changed') {
+            for (const handler of this.toolsChanged) {
+                try {
+                    handler();
+                }
+                catch {
+                }
+            }
+            return;
+        }
         if (isNotification(message) && message.method === 'notifications/progress') {
             const params = (message.params ?? {});
             const report = this.progress.get(String(params.progressToken));
@@ -216,11 +258,11 @@ export function serverEnvironment(source, options = {}) {
 }
 export function createStdioTransport(options) {
     let child;
-    const decoder = new LineDecoder();
     let onMessage = () => undefined;
     let onClose = () => undefined;
     return {
         async start() {
+            const decoder = new LineDecoder();
             const { spawn } = await import('node:child_process');
             const spawned = spawn(options.command, options.args ?? [], {
                 cwd: options.cwd,
@@ -297,6 +339,137 @@ export function createHttpTransport(options) {
         },
     };
 }
+export function createSseTransport(options) {
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    let onMessage = () => undefined;
+    const onClose = [];
+    let endpoint;
+    let opening;
+    let closed = false;
+    let stopped = false;
+    let stream = new AbortController();
+    const ended = (from) => {
+        if (closed || from !== stream)
+            return;
+        closed = true;
+        for (const handler of onClose)
+            handler();
+    };
+    const open = async () => {
+        const own = new AbortController();
+        stream = own;
+        try {
+            const response = await fetchImplementation(options.url, {
+                headers: { accept: 'text/event-stream', ...options.headers },
+                signal: own.signal,
+            });
+            if (!response.ok || !response.body)
+                throw new McpError(`MCP SSE transport failed with ${response.status}`);
+            const reader = response.body.getReader();
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new McpError(`The MCP server named no endpoint within ${options.timeoutMs ?? 10_000}ms`)), options.timeoutMs ?? 10_000);
+                const event = (name, data) => {
+                    if (name === 'endpoint') {
+                        if (endpoint)
+                            return;
+                        const target = new URL(data.trim(), options.url);
+                        if (target.origin !== new URL(options.url).origin) {
+                            clearTimeout(timer);
+                            reject(new McpError(`The MCP server named an endpoint on another origin, ${target.origin}`));
+                            return;
+                        }
+                        endpoint = target.href;
+                        clearTimeout(timer);
+                        resolve();
+                    }
+                    else if (name === 'message') {
+                        try {
+                            onMessage(JSON.parse(data));
+                        }
+                        catch {
+                        }
+                    }
+                };
+                void readEvents(reader, event).then(() => {
+                    clearTimeout(timer);
+                    reject(new McpError('The MCP event stream ended'));
+                    ended(own);
+                }, (error) => {
+                    clearTimeout(timer);
+                    reject(error instanceof McpError ? error : new McpError(`The MCP event stream failed: ${String(error)}`));
+                    ended(own);
+                });
+            });
+        }
+        catch (error) {
+            own.abort();
+            ended(own);
+            throw error;
+        }
+    };
+    const started = () => {
+        if (closed && options.reopen && !stopped) {
+            closed = false;
+            endpoint = undefined;
+            opening = undefined;
+        }
+        opening ??= open();
+        return opening;
+    };
+    return {
+        start: started,
+        async send(message) {
+            await started();
+            if (closed || !endpoint)
+                throw new McpError('The MCP event stream is closed');
+            const response = await fetchImplementation(endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...options.headers },
+                body: JSON.stringify(message),
+            });
+            await response.body?.cancel().catch(() => undefined);
+            if (!response.ok)
+                throw new McpError(`MCP SSE transport failed with ${response.status}`);
+        },
+        onMessage(handler) {
+            onMessage = handler;
+        },
+        onClose(handler) {
+            onClose.push(handler);
+        },
+        close() {
+            stopped = true;
+            stream.abort();
+            ended(stream);
+        },
+    };
+}
+async function readEvents(reader, event) {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            return;
+        buffer += decoder.decode(value, { stream: true }).replace(/\r\n?/g, '\n');
+        let boundary = buffer.indexOf('\n\n');
+        while (boundary !== -1) {
+            const frame = buffer.slice(0, boundary);
+            buffer = buffer.slice(boundary + 2);
+            let name = 'message';
+            const data = [];
+            for (const line of frame.split('\n')) {
+                if (line.startsWith('event:'))
+                    name = line.slice(6).trim();
+                else if (line.startsWith('data:'))
+                    data.push(line.slice(5).replace(/^ /, ''));
+            }
+            if (data.length)
+                event(name, data.join('\n'));
+            boundary = buffer.indexOf('\n\n');
+        }
+    }
+}
 function sseData(body) {
     return body
         .split('\n')

package/dist/mcp/index.d.ts

@@ -1,3 +1,3 @@
-export { createHttpTransport, createStdioTransport, type HttpClientOptions, McpClient, type McpClientOptions, type McpContent, type McpResourceDescriptor, type McpToolDescriptor, type McpToolResult, type StdioClientOptions, } from './client.js';
+export { createHttpTransport, createSseTransport, createStdioTransport, type HttpClientOptions, McpClient, type McpClientOptions, type McpContent, type McpResourceDescriptor, type McpToolAnnotations, type McpToolDescriptor, type McpToolResult, type McpToolsOptions, mcpToolCapabilities, type SseClientOptions, type StdioClientOptions, } from './client.js';
 export { JSON_RPC_ERRORS, type JsonRpcMessage, type JsonRpcNotification, type JsonRpcRequest, type JsonRpcResponse, LineDecoder, MCP_PROTOCOL_VERSION, McpError, type McpTransport, } from './protocol.js';
-export { createStdioServerTransport, McpServer, type McpServerOptions } from './server.js';
+export { createStdioServerTransport, McpServer, type McpServerOptions, mcpToolAnnotations } from './server.js';

package/dist/mcp/index.js

@@ -1,3 +1,3 @@
-export { createHttpTransport, createStdioTransport, McpClient, } from './client.js';
+export { createHttpTransport, createSseTransport, createStdioTransport, McpClient, mcpToolCapabilities, } from './client.js';
 export { JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, } from './protocol.js';
-export { createStdioServerTransport, McpServer } from './server.js';
+export { createStdioServerTransport, McpServer, mcpToolAnnotations } from './server.js';

package/dist/mcp/server.d.ts

@@ -1,4 +1,5 @@
 import type { ToolDefinition } from '../types/messages.js';
+import type { McpToolAnnotations } from './client.js';
 import { type JsonRpcMessage, type McpTransport } from './protocol.js';
 /** Options for an MCP server. */
 export interface McpServerOptions {
@@ -17,6 +18,17 @@ export interface McpServerOptions {
         read(): Promise<unknown> | unknown;
     }>;
 }
+/**
+ * The annotations a tool is served with, from the capabilities it declares, read so a client is never
+ * told less than the tool may do:
+ * - read-only only when every capability reads, `filesystem:read` or `mcp.read`, or there are none;
+ * - not destructive only when everything else it does is `mcp.write`;
+ * - closed to the world only when every capability is the filesystem's or an MCP tool's effect.
+ *
+ * A tool whose capabilities depend on its arguments, or that declares none, is served without
+ * annotations, which a client reads as the specification's defaults: it may do anything.
+ */
+export declare function mcpToolAnnotations(tool: Pick<ToolDefinition, 'capabilities'>): McpToolAnnotations | undefined;
 /**
  * Exposes tools over MCP, so other assistants can call them.
  *
@@ -29,7 +41,7 @@ export declare class McpServer {
     private readonly tools;
     private transport;
     constructor(options?: McpServerOptions);
-    /** Adds a tool. Returns the server, for chaining. */
+    /** Adds a tool, and tells a connected client its tools changed. Returns the server, for chaining. */
     register(tool: ToolDefinition): this;
     /** Starts serving requests over a transport. */
     connect(transport: McpTransport): Promise<void>;

package/dist/mcp/server.js

@@ -1,4 +1,19 @@
+import { parseCapability } from '../agent/capabilities.js';
 import { isNotification, isRequest, JSON_RPC_ERRORS, LineDecoder, MCP_PROTOCOL_VERSION, McpError, textContent, } from './protocol.js';
+const CLOSED = new Set(['filesystem', 'mcp.read', 'mcp.write', 'mcp.destructive']);
+export function mcpToolAnnotations(tool) {
+    const declared = tool.capabilities;
+    if (!declared || typeof declared === 'function')
+        return undefined;
+    const parsed = declared.map((capability) => parseCapability(capability));
+    const reads = (item) => (item.kind === 'filesystem' && item.access === 'read') || item.kind === 'mcp.read';
+    const readOnly = parsed.every(reads);
+    return {
+        readOnlyHint: readOnly,
+        ...(readOnly ? {} : { destructiveHint: !parsed.every((item) => reads(item) || item.kind === 'mcp.write') }),
+        openWorldHint: !parsed.every((item) => CLOSED.has(item.kind)),
+    };
+}
 export class McpServer {
     options;
     tools = new Map();
@@ -10,6 +25,9 @@ export class McpServer {
     }
     register(tool) {
         this.tools.set(tool.name, tool);
+        if (this.transport) {
+            void Promise.resolve(this.transport.send({ jsonrpc: '2.0', method: 'notifications/tools/list_changed' })).catch(() => undefined);
+        }
         return this;
     }
     async connect(transport) {
@@ -48,7 +66,7 @@ export class McpServer {
                 return {
                     protocolVersion: MCP_PROTOCOL_VERSION,
                     capabilities: {
-                        tools: { listChanged: false },
+                        tools: { listChanged: true },
                         ...(this.options.resources?.length ? { resources: { listChanged: false } } : {}),
                     },
                     serverInfo: { name: this.options.name ?? 'nexus-ai-pro', version: this.options.version ?? '1.x' },
@@ -57,11 +75,15 @@ export class McpServer {
                 return {};
             case 'tools/list':
                 return {
-                    tools: [...this.tools.values()].map((item) => ({
-                        name: item.name,
-                        description: item.description,
-                        inputSchema: item.parameters ?? { type: 'object', properties: {} },
-                    })),
+                    tools: [...this.tools.values()].map((item) => {
+                        const annotations = mcpToolAnnotations(item);
+                        return {
+                            name: item.name,
+                            description: item.description,
+                            inputSchema: item.parameters ?? { type: 'object', properties: {} },
+                            ...(annotations ? { annotations } : {}),
+                        };
+                    }),
                 };
             case 'tools/call': {
                 const name = String(params.name ?? '');

package/dist/protocols/acp-editor.d.ts

@@ -10,9 +10,11 @@
  *
  * A tool is offered only when the editor said it can do that thing, in `initialize`. Each declares
  * what it touches, as `filesystem:read:<path>`, `filesystem:write:<path>`, or `shell:<command>`, so a
- * permission policy decides it like any other tool, and an approval asks the person in the editor.
+ * permission policy decides it like any other tool, and an approval asks the person in the editor. An
+ * MCP server's tools, over stdio, HTTP, or SSE, declare what their server says they do.
  */
 import type { ToolSourceContext } from '../agent/create-agent.js';
+import { type McpToolDescriptor } from '../mcp/client.js';
 import type { ToolDefinition } from '../types/messages.js';
 import type { AcpEditorBridge } from './acp.js';
 /** Options for `acpEditor()`. */
@@ -25,8 +27,15 @@ export interface AcpEditorOptions {
     mcp?: boolean;
     /** How long a request to an MCP server may take, in milliseconds. Defaults to 30 seconds. */
     mcpTimeoutMs?: number;
-    /** Replaces `fetch` for MCP servers reached over HTTP: a proxy, or a test. */
+    /** Replaces `fetch` for MCP servers reached over HTTP or SSE: a proxy, or a test. */
     mcpFetch?: typeof globalThis.fetch;
+    /**
+     * What an MCP server's tools declare they do, for a permission policy. `true`, the default, reads
+     * it from the server's annotations, with `mcpToolCapabilities()`: `mcp.read`, `mcp.write`, or
+     * `mcp.destructive` under the server's name, and `network` for a tool that reaches beyond it. A
+     * function decides per tool, and `false` declares nothing, as before 2.17.
+     */
+    mcpToolCapabilities?: boolean | ((tool: McpToolDescriptor, server: string) => readonly string[] | undefined);
     /** The most terminal output a command returns, in bytes. Defaults to 64 KB. */
     maxOutputBytes?: number;
     /** Receives an MCP server that failed to start, whose tools are then not offered. */
@@ -34,6 +43,11 @@ export interface AcpEditorOptions {
 }
 /** The editor, as tools for an agent. */
 export interface AcpEditor extends AcpEditorBridge {
+    /** The MCP transports it connects, which the agent tells the editor in `initialize`. */
+    readonly mcpCapabilities: {
+        http: boolean;
+        sse: boolean;
+    };
     /** The tools of one session, for `CreateAgentOptions.toolSource`: the session is the run's thread. */
     toolSource(context: ToolSourceContext): Promise<ToolDefinition[]>;
     /** Closes every MCP server it connected. */

package/dist/protocols/acp-editor.js

@@ -1,4 +1,4 @@
-import { createHttpTransport, createStdioTransport, McpClient } from '../mcp/client.js';
+import { createHttpTransport, createSseTransport, createStdioTransport, McpClient, } from '../mcp/client.js';
 export function acpEditor(options = {}) {
     let connection;
     const servers = new Map();
@@ -7,11 +7,20 @@ export function acpEditor(options = {}) {
         let connected = servers.get(session.id);
         if (!connected) {
             connected = (async () => {
-                const clients = [];
-                const tools = [];
+                const entries = [];
+                const declare = options.mcpToolCapabilities ?? true;
                 for (const offered of session.mcpServers) {
                     const name = String(offered.name ?? 'mcp');
+                    const prefix = name.replace(/[^A-Za-z0-9_-]/g, '_');
                     try {
+                        const remote = offered.url
+                            ? {
+                                url: offered.url,
+                                headers: Object.fromEntries((offered.headers ?? []).map((item) => [item.name, item.value])),
+                                ...(options.mcpFetch ? { fetch: options.mcpFetch } : {}),
+                            }
+                            : undefined;
+                        const sse = remote && offered.type === 'sse';
                         const transport = offered.command
                             ? createStdioTransport({
                                 command: offered.command,
@@ -19,24 +28,40 @@ export function acpEditor(options = {}) {
                                 env: Object.fromEntries((offered.env ?? []).map((item) => [item.name, item.value])),
                                 ...(session.cwd ? { cwd: session.cwd } : {}),
                             })
-                            : offered.url && (offered.type === 'http' || offered.type === undefined)
-                                ? createHttpTransport({
-                                    url: offered.url,
-                                    headers: Object.fromEntries((offered.headers ?? []).map((item) => [item.name, item.value])),
-                                    ...(options.mcpFetch ? { fetch: options.mcpFetch } : {}),
-                                })
-                                : undefined;
+                            : sse
+                                ?
+                                    createSseTransport({ ...remote, timeoutMs: options.mcpTimeoutMs ?? 30_000, reopen: true })
+                                : remote && (offered.type === 'http' || offered.type === undefined)
+                                    ? createHttpTransport(remote)
+                                    : undefined;
                         if (!transport)
                             throw new Error(`MCP server "${name}" uses a transport this agent does not speak`);
-                        const client = new McpClient(transport, { timeoutMs: options.mcpTimeoutMs ?? 30_000 });
-                        tools.push(...(await client.toNexusTools({ prefix: name.replace(/[^A-Za-z0-9_-]/g, '_') })));
-                        clients.push(client);
+                        const client = new McpClient(transport, {
+                            timeoutMs: options.mcpTimeoutMs ?? 30_000,
+                            ...(sse ? { reconnect: true } : {}),
+                        });
+                        const entry = {
+                            name,
+                            client,
+                            tools: [],
+                            stale: false,
+                            list: () => client.toNexusTools({
+                                prefix,
+                                server: prefix,
+                                capabilities: typeof declare === 'function' ? (tool) => declare(tool, prefix) : declare,
+                            }),
+                        };
+                        entries.push(entry);
+                        client.onToolsChanged(() => {
+                            entry.stale = true;
+                        });
+                        entry.tools = await entry.list();
                     }
                     catch (error) {
                         options.onError?.(error, name);
                     }
                 }
-                return { clients, tools };
+                return entries;
             })();
             servers.set(session.id, connected);
         }
@@ -130,6 +155,7 @@ export function acpEditor(options = {}) {
         return list;
     };
     return {
+        mcpCapabilities: { http: options.mcp !== false, sse: options.mcp !== false },
         attach(next) {
             connection = next;
         },
@@ -143,13 +169,26 @@ export function acpEditor(options = {}) {
             const own = tools(session);
             if (options.mcp === false || session.mcpServers.length === 0)
                 return own;
-            return [...own, ...(await mcpTools(session)).tools];
+            const entries = await mcpTools(session);
+            await Promise.all(entries
+                .filter((entry) => entry.stale)
+                .map(async (entry) => {
+                entry.stale = false;
+                try {
+                    entry.tools = await entry.list();
+                }
+                catch (error) {
+                    entry.stale = true;
+                    options.onError?.(error, entry.name);
+                }
+            }));
+            return [...own, ...entries.flatMap((entry) => entry.tools)];
         },
         async close() {
             const connected = [...servers.values()];
             servers.clear();
-            for (const { clients } of await Promise.all(connected)) {
-                await Promise.all(clients.map((client) => client.close().catch(() => undefined)));
+            for (const entries of await Promise.all(connected)) {
+                await Promise.all(entries.map((entry) => entry.client.close().catch(() => undefined)));
             }
         },
     };

package/dist/protocols/acp.d.ts

@@ -104,6 +104,14 @@ export interface AcpConnection {
 }
 /** Something that uses the editor's connection, such as `acpEditor()`. `serveAcp()` attaches it when it starts. */
 export interface AcpEditorBridge {
+    /**
+     * The MCP transports it connects beyond stdio, which the agent tells the editor in `initialize` so
+     * the editor offers servers over them too.
+     */
+    readonly mcpCapabilities?: {
+        http?: boolean;
+        sse?: boolean;
+    };
     /** Receives the connection to the editor. */
     attach(connection: AcpConnection): void;
     /** Called when the editor closes its end, or the server is closed: the place to stop what it started. */

package/dist/protocols/acp.js

@@ -249,6 +249,7 @@ export function serveAcp(graph, streams, options = {}) {
                     agentCapabilities: {
                         loadSession: true,
                         promptCapabilities: { image: true, audio: true, embeddedContext: true },
+                        ...(options.editor?.mcpCapabilities ? { mcpCapabilities: options.editor.mcpCapabilities } : {}),
                     },
                     authMethods: [],
                     ...(options.agentInfo ? { agentInfo: options.agentInfo } : {}),

package/dist/router/failover.js

@@ -7,6 +7,7 @@ export class FailoverExecutor {
     async complete(request, decision, providers, options = {}) {
         const attempts = attemptsOf(decision);
         const errors = [];
+        const failures = [];
         const retry = this.mergeRetry(options.retry, request.retry);
         const timeoutMs = this.resolveTimeout(request.timeoutMs, options.timeoutMs);
         const refreshed = new Set();
@@ -37,6 +38,8 @@ export class FailoverExecutor {
                     if (retryIndex > 0) {
                         response.meta.guardrailsApplied.push(`provider-retry-${retryIndex}`);
                     }
+                    if (failures.length)
+                        response.meta.failedAttempts = failures;
                     return response;
                 }
                 catch (caught) {
@@ -53,6 +56,7 @@ export class FailoverExecutor {
                     }
                     const message = `${attempt.providerName}/${attempt.model}: ${error instanceof Error ? error.message : String(error)}`;
                     errors.push(message);
+                    failures.push(failureOf(attempt, error));
                     if (error instanceof UnsettledProviderAttemptError) {
                         break attemptsLoop;
                     }
@@ -108,6 +112,7 @@ export class FailoverExecutor {
         const retry = this.mergeRetry(options.retry, request.retry);
         const timeoutMs = this.resolveTimeout(request.timeoutMs, options.timeoutMs);
         const errors = [];
+        const failures = [];
         const refreshed = new Set();
         attemptsLoop: for (const attempt of attempts) {
             const provider = providers.get(attempt.providerName);
@@ -151,7 +156,9 @@ export class FailoverExecutor {
                         if (chunk.type === 'error')
                             throw new Error(chunk.error || 'stream error');
                         emitted = emitted || chunk.type === 'text' || chunk.type === 'tool_call';
-                        yield chunk;
+                        yield chunk.type === 'done' && failures.length
+                            ? { ...chunk, meta: { ...chunk.meta, failedAttempts: [...failures] } }
+                            : chunk;
                     }
                 }
                 catch (caught) {
@@ -184,6 +191,7 @@ export class FailoverExecutor {
                     return;
                 }
                 errors.push(`${attempt.providerName}/${attempt.model}: ${attemptError instanceof Error ? attemptError.message : String(attemptError)}`);
+                failures.push(failureOf(attempt, attemptError));
                 if (attemptError instanceof UnsettledProviderAttemptError)
                     break attemptsLoop;
                 if (emitted)
@@ -423,3 +431,13 @@ function attemptsOf(decision) {
 function maxRetriesFor(attempt, retry) {
     return Math.max(retry.maxRetries, attempt.rateLimit?.maxRetries ?? 0);
 }
+function failureOf(attempt, error) {
+    const category = error instanceof NexusProviderError ? error.category : undefined;
+    return {
+        provider: attempt.providerName,
+        model: attempt.model,
+        error: error instanceof Error ? error.message : String(error),
+        ...(category ? { category } : {}),
+        at: new Date().toISOString(),
+    };
+}

package/dist/server/index.d.ts

@@ -12,6 +12,7 @@ export { CronScheduler, type CronSchedulerOptions, type DueCronJob, parseCron }
 export { AssistantCapabilityError, BadRequestError, ForbiddenError, NotFoundError, RunHandOffError, ServerError, type TenantLimit, TenantLimitError, ThreadBusyError, UnauthorizedError, } from './errors.js';
 export { MemoryRunEventLog, type MemoryRunEventLogOptions, type RedisEventLogLikeClient, RedisRunEventLog, type RedisRunEventLogOptions, } from './events.js';
 export { type NodeListenerOptions, type NodeRequestLike, type NodeResponseLike, toNodeListener, } from './node.js';
+export type { ListPage } from './list-page.js';
 export { type DrainResult, RunManager, type RunManagerOptions, type RunQueueOptions, type StartRunOptions, } from './runs.js';
 export { type AgentServer, type AgentServerOptions, createAgentServer } from './server.js';
 export { fromStore, MemoryServerStore, type StoreLike } from './state.js';

package/dist/server/list-page.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The order an agent server lists threads and runs in, and the cursor that pages through it. The
+ * regional gateway reads both, so a cursor one region gave pages every region the same way.
+ */
+/** A page of a list, newest first, and the cursor of the page after it. */
+export interface ListPage<T> {
+    /** The page's records, newest first. */
+    items: T[];
+    /** Asks for the page after this one, as `cursor`. Absent on the last page. */
+    nextCursor?: string;
+}
+/** A record as a list places it: by its last write, then its id. */
+interface Listed {
+    id?: unknown;
+    updatedAt?: unknown;
+    createdAt?: unknown;
+}
+/** Where a record falls in a list. */
+interface Place {
+    at: string;
+    id: string;
+}
+/** Every list's order: the newest written first, and by id among records written at the same time. */
+export declare function newestFirst(a: Listed, b: Listed): number;
+/** The cursor of the page after one that ends with `record`. */
+export declare function cursorAfter(record: Listed): string;
+/** The place a cursor names, or `undefined` for one no list gave. */
+export declare function readCursor(cursor: string): Place | undefined;
+/** Whether `record` comes after `place`, so belongs to the pages after the cursor that names it. */
+export declare function isAfter(record: Listed, place: Place): boolean;
+/**
+ * The page of the records `keep` takes, after `after`, from a store that lists newest written first.
+ * It reads more of the store until the page is full or the store ends. Until the store ends, only
+ * records newer than the oldest one read are placed for sure: another written in that same instant
+ * may be unread yet, and come before them by id.
+ */
+export declare function pageOf<R extends Listed>(list: (limit: number) => Promise<R[]> | R[], keep: (record: R) => boolean, limit: number, after: Place | undefined): Promise<ListPage<R>>;
+export {};