nexus-ai-pro 2.5.0 → 2.6.0

package/dist/mcp/server.js

@@ -66,10 +66,37 @@ export class McpServer {
             case 'tools/call': {
                 const name = String(params.name ?? '');
                 const tool = this.tools.get(name);
-                if (!tool?.execute)
+                if (!tool?.execute && !tool?.stream)
                     return { content: textContent(`Unknown tool "${name}"`), isError: true };
+                const args = (params.arguments ?? {});
+                const token = params._meta?.progressToken;
+                let reports = 0;
+                const progress = typeof token === 'string' || typeof token === 'number'
+                    ? (value) => {
+                        reports += 1;
+                        void this.transport?.send({
+                            jsonrpc: '2.0',
+                            method: 'notifications/progress',
+                            params: { progressToken: token, ...progressParams(value, reports) },
+                        });
+                    }
+                    : undefined;
                 try {
-                    const output = await tool.execute((params.arguments ?? {}));
+                    let output;
+                    if (tool.stream) {
+                        const generator = tool.stream(args, progress ? { progress } : {});
+                        for (;;) {
+                            const step = await generator.next();
+                            if (step.done) {
+                                output = step.value;
+                                break;
+                            }
+                            progress?.(step.value);
+                        }
+                    }
+                    else {
+                        output = await tool.execute(args, progress ? { progress } : {});
+                    }
                     return { content: textContent(output) };
                 }
                 catch (error) {
@@ -136,3 +163,16 @@ export function createStdioServerTransport(streams) {
         },
     };
 }
+function progressParams(value, position) {
+    if (typeof value === 'number')
+        return { progress: value };
+    if (value && typeof value === 'object') {
+        const report = value;
+        return {
+            progress: typeof report.progress === 'number' ? report.progress : position,
+            ...(typeof report.total === 'number' ? { total: report.total } : {}),
+            message: typeof report.message === 'string' ? report.message : JSON.stringify(value),
+        };
+    }
+    return { progress: position, message: String(value) };
+}

package/dist/protocols/a2a.d.ts

@@ -1,5 +1,6 @@
 import type { Message, ToolDefinition } from '../types/messages.js';
 import type { Principal } from '../types/principal.js';
+import type { Store } from '../types/store.js';
 import { type ProtocolGraph, type ProtocolInterrupt } from './shared.js';
 export type { ProtocolGraph, ProtocolInterrupt, ProtocolResult, ProtocolRunOptions } from './shared.js';
 /** The protocol version this module speaks. */
@@ -137,7 +138,9 @@ export type A2aStreamEvent = {
 export declare const A2A_ERRORS: {
     readonly taskNotFound: -32001;
     readonly taskNotCancelable: -32002;
+    readonly pushNotificationNotSupported: -32003;
     readonly unsupportedOperation: -32004;
+    readonly extendedCardNotConfigured: -32007;
     readonly versionNotSupported: -32009;
 };
 /** Raised by the client when an agent answers with a JSON-RPC error. */
@@ -152,6 +155,109 @@ export declare class A2aError extends Error {
     /** The error's data, when the agent sent any. */
     data?: unknown | undefined);
 }
+/** Where a task's updates are pushed: a webhook the calling agent gave. */
+export interface A2aPushNotificationConfig {
+    /** Its id, unique within the task. Given one when it has none. */
+    id?: string;
+    /** Where each update is POSTed. */
+    url: string;
+    /** Sent back as the `X-A2A-Notification-Token` header, so the receiver knows the update is its own. */
+    token?: string;
+}
+/** A task as a store keeps it: the task, its messages, the questions it waits on, and its webhooks. */
+export interface A2aTaskRecord {
+    /** The task. */
+    task: A2aTask;
+    /** Every message of the task, the caller's and the agent's. */
+    history: A2aMessage[];
+    /** The questions the paused run asked, which the next message answers. */
+    interrupts?: ProtocolInterrupt[];
+    /** Where its updates are pushed. */
+    push?: A2aPushNotificationConfig[];
+    /** ISO-8601 time it was last written. */
+    updatedAt: string;
+}
+/** Which tasks `A2aTaskStore.list()` returns. */
+export interface A2aTaskQuery {
+    /** Only this conversation's. */
+    contextId?: string;
+    /** Only those in this state. */
+    state?: A2aTaskState;
+    /** Most returned. */
+    limit: number;
+    /** Skipped first, for paging. */
+    offset: number;
+}
+/**
+ * Where an A2A agent keeps its tasks and conversations. A store outside the process lets a restart, or
+ * another replica, pick a task up: answer a task's question, read it, list it, or cancel it.
+ */
+export interface A2aTaskStore {
+    /** A task's record. */
+    get(taskId: string): Promise<A2aTaskRecord | undefined> | A2aTaskRecord | undefined;
+    /** Writes a task's record. */
+    put(record: A2aTaskRecord): Promise<void> | void;
+    /** Tasks, most recently written first, and how many match when the store knows. */
+    list(query: A2aTaskQuery): Promise<{
+        records: A2aTaskRecord[];
+        total?: number;
+    }> | {
+        records: A2aTaskRecord[];
+        total?: number;
+    };
+    /** A conversation's transcript, as the agent last left it. */
+    conversation(contextId: string): Promise<Message[] | undefined> | Message[] | undefined;
+    /** Writes a conversation's transcript. */
+    saveConversation(contextId: string, messages: Message[]): Promise<void> | void;
+}
+/** Tasks and conversations in this process: the default, for one replica. */
+export declare class MemoryA2aTaskStore implements A2aTaskStore {
+    private readonly tasks;
+    private readonly conversations;
+    private readonly max;
+    constructor(options?: {
+        maxTasks?: number;
+    });
+    /** A task's record, as a copy. */
+    get(taskId: string): A2aTaskRecord | undefined;
+    /** Writes a task's record, dropping the least recently written beyond `maxTasks`. */
+    put(record: A2aTaskRecord): void;
+    /** Tasks, most recently written first, with how many match. */
+    list(query: A2aTaskQuery): {
+        records: A2aTaskRecord[];
+        total: number;
+    };
+    /** A conversation's transcript. */
+    conversation(contextId: string): Message[] | undefined;
+    /** Writes a conversation's transcript. */
+    saveConversation(contextId: string, messages: Message[]): void;
+}
+/**
+ * Tasks and conversations in any long-term `Store`: the memory, Redis, Postgres, or SQLite store, so
+ * every replica sees one set. Listing filters on the task's fields in the store; it does not count
+ * all matches, so `total` is unknown.
+ */
+export declare function storeA2aTasks(store: Store, options?: {
+    namespace?: readonly string[];
+}): A2aTaskStore;
+/** Options for pushing task updates to the webhooks callers give. */
+export interface A2aPushOptions {
+    /**
+     * Signs every delivery with an \`x-nexus-signature\` header, as the server's operation webhooks are,
+     * so a receiver checks it with \`verifyOperationWebhook()\` from \`nexus-ai-pro/operations\`.
+     */
+    secret?: string;
+    /**
+     * Allows webhooks on loopback, private, and link-local addresses, and plain \`http\`. Off by default,
+     * so a caller cannot make the agent reach into its own network. Turn it on for tests, or when every
+     * caller is trusted.
+     */
+    allowPrivateNetworks?: boolean;
+    /** Replaces \`fetch\` for deliveries: a client with its own address checks, a proxy, or a test. */
+    fetch?: typeof globalThis.fetch;
+    /** How long one delivery may take, in milliseconds. Defaults to 5 seconds. */
+    timeoutMs?: number;
+}
 /** Options for `a2aHandler()`. */
 export interface A2aServerOptions {
     /** The card's content: the endpoint `url` is where this handler is mounted. */
@@ -170,8 +276,25 @@ export interface A2aServerOptions {
     answer?: (message: A2aMessage, interrupt: ProtocolInterrupt) => unknown;
     /** Who the task is for, from the request: the place to authenticate the calling agent. */
     principal?: (request: Request) => Principal | undefined | Promise<Principal | undefined>;
-    /** Most tasks and contexts kept in memory. Defaults to 10,000 each. */
+    /**
+     * Where tasks and conversations are kept. Defaults to memory, for one replica; \`storeA2aTasks()\`
+     * keeps them in a shared store. A task resumed elsewhere needs the graph's own checkpointer to be
+     * shared too.
+     */
+    store?: A2aTaskStore;
+    /** Most tasks and contexts the default memory store keeps. Defaults to 10,000 each. */
     maxTasks?: number;
+    /** Pushes each task's updates to the webhooks callers give. Without it, push notifications are not offered. */
+    pushNotifications?: A2aPushOptions;
+    /**
+     * The extended card an authenticated caller may read with `GetExtendedAgentCard`: more skills, or
+     * anything else this caller may see. Without it, there is no extended card.
+     */
+    extendedCard?: (principal: Principal) => Partial<A2aAgentCard> | Promise<Partial<A2aAgentCard>>;
+    /** How often `SubscribeToTask` reads a task another replica runs, in milliseconds. Defaults to 1 second. */
+    pollMs?: number;
+    /** Receives push delivery failures, which never fail a task. */
+    onError?: (error: unknown) => void;
 }
 /**
  * An HTTP handler that serves a graph as an A2A agent: `GET` the card, `POST` JSON-RPC. Mount it
@@ -201,21 +324,63 @@ export interface A2aSendOptions {
     taskId?: string;
     /** Structured data sent beside the text, such as `{ approved: true }`. */
     data?: unknown;
+    /** A webhook for this task's updates, when the agent pushes them. */
+    push?: A2aPushNotificationConfig;
+    /** Returns the task while it runs, instead of when it is done. */
+    returnImmediately?: boolean;
     /** Cancels the request. */
     signal?: AbortSignal;
 }
+/** Which tasks `A2aClient.listTasks()` asks for. */
+export interface A2aListTasksOptions {
+    /** Only this conversation's. */
+    contextId?: string;
+    /** Only those in this state. */
+    status?: A2aTaskState;
+    /** Tasks per page, up to 100. Defaults to 50. */
+    pageSize?: number;
+    /** The `nextPageToken` of the page before. */
+    pageToken?: string;
+    /** Messages of each task's history to include. */
+    historyLength?: number;
+}
+/** A page of tasks. */
+export interface A2aTaskPage {
+    /** The tasks. */
+    tasks: A2aTask[];
+    /** The token for the next page, or empty when this is the last. */
+    nextPageToken: string;
+    /** The page size used. */
+    pageSize: number;
+    /** How many tasks match, when the agent's store counts them. */
+    totalSize?: number;
+}
 /** A client for one A2A agent. */
 export interface A2aClient {
     /** The agent's card, fetched once. */
     card(): Promise<A2aAgentCard>;
+    /** The card for an authenticated caller, as `GetExtendedAgentCard` returns it. */
+    extendedCard(): Promise<A2aAgentCard>;
     /** Sends a message and waits for the task it starts or continues. */
     send(text: string, options?: A2aSendOptions): Promise<A2aTask>;
     /** Sends a message and reads the task's events as they arrive. */
     stream(text: string, options?: A2aSendOptions): AsyncGenerator<A2aStreamEvent>;
     /** Reads a task. */
     getTask(taskId: string, historyLength?: number): Promise<A2aTask>;
+    /** Lists tasks, a page at a time. */
+    listTasks(options?: A2aListTasksOptions): Promise<A2aTaskPage>;
+    /** Follows a task that is still running, from now until it finishes or waits. */
+    subscribe(taskId: string, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<A2aStreamEvent>;
     /** Cancels a task. */
     cancel(taskId: string): Promise<A2aTask>;
+    /** Adds a webhook for a task's updates. */
+    setPushNotification(taskId: string, config: A2aPushNotificationConfig): Promise<A2aPushNotificationConfig>;
+    /** A task's webhooks. */
+    listPushNotifications(taskId: string): Promise<A2aPushNotificationConfig[]>;
+    /** Removes one of a task's webhooks. */
+    deletePushNotification(taskId: string, configId: string): Promise<void>;
 }
 /** A client for an A2A agent, by its card or endpoint URL. */
 export declare function a2aClient(options: A2aClientOptions): A2aClient;