nexus-ai-pro 2.19.0 → 2.20.2

package/dist/protocols/a2a.js

@@ -7,6 +7,7 @@ export const A2A_ERRORS = {
     unsupportedOperation: -32004,
     extendedCardNotConfigured: -32007,
     versionNotSupported: -32009,
+    permissionDenied: -32099,
 };
 export class A2aError extends Error {
     code;
@@ -45,7 +46,8 @@ export class MemoryA2aTaskStore {
     list(query) {
         const matching = [...this.tasks.values()]
             .filter((record) => (query.contextId === undefined || record.task.contextId === query.contextId) &&
-            (query.state === undefined || record.task.status.state === query.state))
+            (query.state === undefined || record.task.status.state === query.state) &&
+            (query.tenant === undefined || record.tenant === query.tenant))
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
         return {
             records: matching.slice(query.offset, query.offset + query.limit).map((record) => structuredClone(record)),
@@ -83,6 +85,7 @@ export function storeA2aTasks(store, options = {}) {
             const filter = {
                 ...(query.contextId === undefined ? {} : { 'task.contextId': query.contextId }),
                 ...(query.state === undefined ? {} : { 'task.status.state': query.state }),
+                ...(query.tenant === undefined ? {} : { tenant: query.tenant }),
             };
             const items = await store.search(tasks, {
                 limit: query.limit,
@@ -129,6 +132,7 @@ const ERROR_STATUS = {
     [-32007]: { httpStatus: 400, grpcStatus: 'FAILED_PRECONDITION', reason: 'EXTENDED_AGENT_CARD_NOT_CONFIGURED' },
     [-32008]: { httpStatus: 400, grpcStatus: 'FAILED_PRECONDITION', reason: 'EXTENSION_SUPPORT_REQUIRED' },
     [-32009]: { httpStatus: 400, grpcStatus: 'UNIMPLEMENTED', reason: 'VERSION_NOT_SUPPORTED' },
+    [-32099]: { httpStatus: 403, grpcStatus: 'PERMISSION_DENIED', reason: 'PERMISSION_DENIED' },
     [-32700]: { httpStatus: 400, grpcStatus: 'INVALID_ARGUMENT', reason: 'INVALID_PARAMS' },
     [-32600]: { httpStatus: 400, grpcStatus: 'INVALID_ARGUMENT', reason: 'INVALID_PARAMS' },
     [-32601]: { httpStatus: 404, grpcStatus: 'UNIMPLEMENTED', reason: 'METHOD_NOT_FOUND' },
@@ -184,7 +188,12 @@ export function a2aHandler(graph, options) {
         defaultInputModes: options.card.defaultInputModes ?? ['text/plain', 'application/json'],
         defaultOutputModes: options.card.defaultOutputModes ?? ['text/plain'],
         skills: options.card.skills,
+        ...(options.card.securitySchemes ? { securitySchemes: options.card.securitySchemes } : {}),
+        ...(options.card.securityRequirements ? { securityRequirements: options.card.securityRequirements } : {}),
+        ...(options.card.signatures ? { signatures: options.card.signatures } : {}),
     };
+    const tenancy = options.tenants ? (options.tenants === true ? {} : options.tenants) : undefined;
+    const conversationKey = (record) => record.tenant === undefined ? record.task.contextId : `${record.tenant}\u0000${record.task.contextId}`;
     const store = options.store ?? new MemoryA2aTaskStore({ maxTasks: options.maxTasks ?? 10_000 });
     const owner = options.lease?.owner ?? protocolId('replica');
     const leaseMs = options.lease?.ms ?? 30_000;
@@ -385,8 +394,8 @@ export function a2aHandler(graph, options) {
                 const text = answerOf(result.state);
                 const reply = agentMessage(task, text);
                 record.history.push(reply);
-                const before = (await store.conversation(task.contextId)) ?? [];
-                await store.saveConversation(task.contextId, transcriptOf(result.state, [...before, messageOf('assistant', text)]));
+                const before = (await store.conversation(conversationKey(record))) ?? [];
+                await store.saveConversation(conversationKey(record), transcriptOf(result.state, [...before, messageOf('assistant', text)]));
                 task.artifacts = [{ artifactId: `${task.id}:answer`, name: 'answer', parts: [{ text }] }];
                 if (streamed) {
                     const last = {
@@ -426,10 +435,10 @@ export function a2aHandler(graph, options) {
         }
     };
     const startRun = async (record, message, runOptions) => {
-        const history = (await store.conversation(record.task.contextId)) ?? [];
+        const history = (await store.conversation(conversationKey(record))) ?? [];
         const said = messageOf('user', textOfParts(message.parts));
         const result = await graph.invoke(options.input ? options.input(message, history) : { messages: [...history, said] }, runOptions);
-        await store.saveConversation(record.task.contextId, [...history, said]);
+        await store.saveConversation(conversationKey(record), [...history, said]);
         return result;
     };
     const carryOn = async (record, runOptions) => {
@@ -481,11 +490,12 @@ export function a2aHandler(graph, options) {
             void recover().catch((error) => options.onError?.(error));
         }, options.recoverEveryMs);
     timer?.unref?.();
-    const taskFor = async (message, principal) => {
+    const taskFor = async (message, principal, mine, tenant) => {
         if (message.taskId) {
             const existing = await store.get(message.taskId);
-            if (!existing)
+            if (!existing || !mine(existing)) {
                 return { error: A2A_ERRORS.taskNotFound, message: `Task ${message.taskId} was not found` };
+            }
             if (existing.task.status.state !== 'TASK_STATE_INPUT_REQUIRED') {
                 return { error: A2A_ERRORS.unsupportedOperation, message: `Task ${message.taskId} is not waiting for input` };
             }
@@ -504,6 +514,7 @@ export function a2aHandler(graph, options) {
             history: [said],
             run: { kind: 'invoke', message: said, ...(principal ? { principal } : {}) },
             updatedAt: new Date().toISOString(),
+            ...(tenant !== undefined ? { tenant } : {}),
         };
         await store.put(record);
         return record;
@@ -590,9 +601,29 @@ export function a2aHandler(graph, options) {
     const pushAnswer = (taskId, config, binding) => binding === 'JSONRPC' ? { taskId, ...config, pushNotificationConfig: config } : { taskId, ...config };
     const fail = (code, message) => ({ error: { code, message } });
     const call = async (method, params, context = {}) => {
-        const principal = context.principal;
+        let principal = context.principal;
         const binding = context.binding ?? 'JSONRPC';
         const pushOn = Boolean(options.pushNotifications);
+        const named = typeof params.tenant === 'string' && params.tenant !== '' ? params.tenant : undefined;
+        if (tenancy) {
+            if (named === undefined) {
+                if (tenancy.required !== false)
+                    return fail(-32602, 'This agent serves several tenants: name one as tenant');
+            }
+            else {
+                const allowed = tenancy.authorize ? await tenancy.authorize(named, principal) : principal?.tenantId === named;
+                if (!allowed)
+                    return fail(A2A_ERRORS.permissionDenied, `This caller may not act for tenant ${named}`);
+                if (principal?.tenantId !== named)
+                    principal = { ...principal, tenantId: named };
+            }
+        }
+        const tenant = tenancy ? named : undefined;
+        const mine = (record) => !tenancy || record.tenant === tenant;
+        const own = async (id) => {
+            const record = await store.get(id);
+            return record && mine(record) ? record : undefined;
+        };
         try {
             switch (method) {
                 case 'SendMessage':
@@ -605,7 +636,7 @@ export function a2aHandler(graph, options) {
                     if (pushConfig && !pushOn) {
                         return fail(A2A_ERRORS.pushNotificationNotSupported, 'This agent does not push notifications');
                     }
-                    const record = await taskFor(message, principal);
+                    const record = await taskFor(message, principal, mine, tenant);
                     if ('error' in record)
                         return fail(record.error, record.message);
                     if (pushConfig) {
@@ -623,7 +654,7 @@ export function a2aHandler(graph, options) {
                     return { events: follow(record, () => execute(record, message, principal), context.signal) };
                 }
                 case 'GetTask': {
-                    const record = await store.get(String(params.id ?? ''));
+                    const record = await own(String(params.id ?? ''));
                     if (!record)
                         return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
                     return { result: view(record, typeof params.historyLength === 'number' ? params.historyLength : undefined) };
@@ -639,6 +670,7 @@ export function a2aHandler(graph, options) {
                     const listed = await store.list({
                         ...(typeof params.contextId === 'string' && params.contextId !== '' ? { contextId: params.contextId } : {}),
                         ...(filtered ? { state: status } : {}),
+                        ...(tenant !== undefined ? { tenant } : {}),
                         limit: pageSize,
                         offset,
                     });
@@ -648,6 +680,7 @@ export function a2aHandler(graph, options) {
                     return {
                         result: {
                             tasks: listed.records
+                                .filter(mine)
                                 .filter((record) => !after || (record.task.status.timestamp ?? '') >= after)
                                 .map((record) => view(record, historyLength))
                                 .map(({ artifacts, ...task }) => params.includeArtifacts === false ? task : { ...task, ...(artifacts ? { artifacts } : {}) }),
@@ -658,7 +691,7 @@ export function a2aHandler(graph, options) {
                     };
                 }
                 case 'SubscribeToTask': {
-                    const record = await store.get(String(params.id ?? ''));
+                    const record = await own(String(params.id ?? ''));
                     if (!record)
                         return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
                     if (TERMINAL.has(record.task.status.state)) {
@@ -670,7 +703,7 @@ export function a2aHandler(graph, options) {
                     return { events: follow(record, undefined, context.signal) };
                 }
                 case 'CancelTask': {
-                    const record = await store.get(String(params.id ?? ''));
+                    const record = await own(String(params.id ?? ''));
                     if (!record)
                         return fail(A2A_ERRORS.taskNotFound, `Task ${String(params.id)} was not found`);
                     if (TERMINAL.has(record.task.status.state)) {
@@ -690,7 +723,7 @@ export function a2aHandler(graph, options) {
                     if (!pushOn)
                         return fail(A2A_ERRORS.pushNotificationNotSupported, 'This agent does not push notifications');
                     const taskId = String(params.taskId ?? params.id ?? '');
-                    const record = await store.get(taskId);
+                    const record = await own(taskId);
                     if (!record)
                         return fail(A2A_ERRORS.taskNotFound, `Task ${taskId} was not found`);
                     if (method === 'CreateTaskPushNotificationConfig') {
@@ -771,8 +804,21 @@ export function a2aHandler(graph, options) {
             return rpcError(id, outcome.error.code, outcome.error.message);
         return rpcResult(id, outcome.result);
     };
-    const httpJson = async (request, route) => {
+    const httpJson = async (request, path) => {
         const verb = request.method;
+        const known = /^\/(?:message:send$|message:stream$|tasks(?:$|\/)|extendedAgentCard$)/;
+        let route = path;
+        let routedTenant;
+        const prefixed = /^\/([^/]+)(\/.*)$/.exec(path);
+        if (!known.test(path) && prefixed && known.test(prefixed[2])) {
+            try {
+                routedTenant = decodeURIComponent(prefixed[1]);
+            }
+            catch {
+                return restError(-32602, 'The tenant in the path is not valid percent-encoding');
+            }
+            route = prefixed[2];
+        }
         const query = new URL(request.url).searchParams;
         const number = (name) => (query.has(name) ? Number(query.get(name)) : undefined);
         const id = (value) => decodeURIComponent(value ?? '');
@@ -824,6 +870,8 @@ export function a2aHandler(graph, options) {
         const refused = versionRefused(request);
         if (refused)
             return restError(A2A_ERRORS.versionNotSupported, refused);
+        if (routedTenant !== undefined)
+            params = { ...params, tenant: routedTenant };
         if (body) {
             const text = await request.text();
             try {
@@ -1034,23 +1082,34 @@ export function a2aClient(options) {
         });
         return cached;
     };
-    const endpoint = async () => isCard
-        ? ((await card()).supportedInterfaces.find((item) => item.protocolBinding === binding)?.url ?? options.url)
-        : options.url;
+    const target = async () => {
+        if (!isCard)
+            return { url: options.url, ...(options.tenant ? { tenant: options.tenant } : {}) };
+        const chosen = (await card()).supportedInterfaces.find((item) => item.protocolBinding === binding);
+        const tenant = options.tenant ?? chosen?.tenant;
+        return { url: chosen?.url ?? options.url, ...(tenant ? { tenant } : {}) };
+    };
     const headers = { 'content-type': 'application/json', 'a2a-version': A2A_PROTOCOL_VERSION, ...options.headers };
     let ids = 0;
-    const rpc = async (method, params, signal) => fetcher(await endpoint(), {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({ jsonrpc: '2.0', id: ++ids, method, params }),
-        ...(signal ? { signal } : {}),
-    });
-    const route = async (verb, path, body, signal) => fetcher(`${(await endpoint()).replace(/\/+$/, '')}${path}`, {
-        method: verb,
-        headers: body === undefined ? { ...headers, 'content-type': 'application/json' } : headers,
-        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-        ...(signal ? { signal } : {}),
-    });
+    const rpc = async (method, params, signal) => {
+        const { url, tenant } = await target();
+        return fetcher(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ jsonrpc: '2.0', id: ++ids, method, params: tenant ? { tenant, ...params } : params }),
+            ...(signal ? { signal } : {}),
+        });
+    };
+    const route = async (verb, path, body, signal) => {
+        const { url, tenant } = await target();
+        const under = tenant ? `/${encodeURIComponent(tenant)}` : '';
+        return fetcher(`${url.replace(/\/+$/, '')}${under}${path}`, {
+            method: verb,
+            headers: body === undefined ? { ...headers, 'content-type': 'application/json' } : headers,
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            ...(signal ? { signal } : {}),
+        });
+    };
     const restFailure = async (response) => {
         const body = (await response.json().catch(() => ({})));
         const reason = body.error?.details?.find((detail) => detail.reason)?.reason;

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, recorded where provenance matters, such as on every experiment. A test
  * keeps it equal to `package.json`.
  */
-export declare const NEXUS_VERSION = "2.19.0";
+export declare const NEXUS_VERSION = "2.20.2";

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.19.0';
+export const NEXUS_VERSION = '2.20.2';

package/dist-cjs/agent/capabilities.d.ts

@@ -12,6 +12,9 @@ import type { ToolDefinition } from '../types/messages.js';
  * | `mcp.read:<server>/<tool>` | An MCP tool its server says only reads |
  * | `mcp.write:<server>/<tool>` | An MCP tool its server says changes things but destroys nothing |
  * | `mcp.destructive:<server>/<tool>` | An MCP tool its server says may destroy or overwrite |
+ * | `api.read:<api>/<operation>` | An operation of an OpenAPI document whose method only reads |
+ * | `api.write:<api>/<operation>` | One whose method changes things |
+ * | `api.destructive:<api>/<operation>` | One whose method deletes |
  * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
  *
  * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all

package/dist-cjs/agent/openapi.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Tools read from a service's own API description, an OpenAPI document: one tool per operation, its
+ * name, description, and parameters the service's, the capabilities it declares read from its method,
+ * and what it returns kept as a schema. Given where the API lives, each tool calls it; without, the
+ * tools describe the API and run nowhere, as `emulatedTools()` wants them.
+ */
+import type { ToolContext, ToolDefinition } from '../types/messages.js';
+/** An OpenAPI 3 document, as parsed JSON. Only what tools are read from is typed. */
+export interface OpenApiDocument {
+    /** The OpenAPI version, `3.0.x` or `3.1.x`. */
+    openapi: string;
+    /** The API's title and version. */
+    info?: {
+        title?: string;
+        version?: string;
+        description?: string;
+    };
+    /** Where the API is served. */
+    servers?: Array<{
+        url: string;
+        variables?: Record<string, {
+            default: string;
+        }>;
+    }>;
+    /** Its operations, by path and method. */
+    paths?: Record<string, Record<string, unknown>>;
+    /** Schemas, parameters, request bodies, and responses its operations refer to. */
+    components?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** One operation of the API, as a tool reads it. */
+export interface OpenApiOperation {
+    /** The tool's name: the operation's id, or its method and path. */
+    name: string;
+    /** The HTTP method, in capitals. */
+    method: string;
+    /** The path, with its `{parameters}`. */
+    path: string;
+    /** The operation's id, when it has one. */
+    operationId?: string;
+    /** Its summary, when it has one. */
+    summary?: string;
+    /** Its tags. */
+    tags: string[];
+    /** What it does to the service, read from its method: `read` for GET, HEAD, OPTIONS, and TRACE, `destructive` for DELETE, and `write` for the rest. */
+    access: 'read' | 'write' | 'destructive';
+}
+/** What a tool's headers are chosen from: the operation, and the call's context. */
+export interface OpenApiHeadersRequest {
+    /** The operation being called. */
+    operation: OpenApiOperation;
+    /** The call's context: its tenant, principal, and thread. */
+    context?: ToolContext;
+}
+/** Options for `openApiTools()`. */
+export interface OpenApiToolsOptions {
+    /** The API's name, in each tool's capabilities. Defaults to its title, as a slug, or `api`. */
+    name?: string;
+    /**
+     * Where the API lives, its path prefix included, such as `https://shop.example.com/api`. Defaults
+     * to the document's first server, resolved against `documentUrl` when relative. Without one, the
+     * tools describe the API and run nowhere.
+     */
+    baseUrl?: string;
+    /** Where the document came from, to resolve a relative server URL against. */
+    documentUrl?: string;
+    /**
+     * Headers every call sends, such as authorization, or a function choosing them per operation and
+     * call, such as by its tenant. They win over a header parameter the model sets.
+     */
+    headers?: Readonly<Record<string, string>> | ((request: OpenApiHeadersRequest) => Record<string, string> | Promise<Record<string, string>>);
+    /** Which operations become tools. Defaults to every one. */
+    include?: (operation: OpenApiOperation) => boolean;
+    /** Put before every tool's name, with an underscore, so two APIs' operations stay apart. */
+    prefix?: string;
+    /** How long a call may take, in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** The largest answer a call reads, in bytes; a larger one fails the call. Defaults to 1 MB. */
+    maxResponseBytes?: number;
+    /** Replaces the global `fetch`. */
+    fetch?: typeof globalThis.fetch;
+}
+/** An API's operations as tools, with what each returns. */
+export interface OpenApiTools {
+    /** The API's name, as its tools' capabilities carry it. */
+    name: string;
+    /** Where the tools send their calls, when they run. */
+    baseUrl?: string;
+    /** One tool per operation. */
+    tools: ToolDefinition[];
+    /** The operations, in the tools' order. */
+    operations: OpenApiOperation[];
+    /** The JSON Schema of what each tool returns, by name: its first success response's. Pass it to `emulatedTools()` as `results`. */
+    results: Record<string, Record<string, unknown>>;
+    /** Operations that could not become tools, and why: a request body of a type the tools do not send. */
+    skipped: Array<{
+        method: string;
+        path: string;
+        reason: string;
+    }>;
+}
+/** Why an API could not be read into tools, or a call to it failed. */
+export declare class OpenApiError extends Error {
+    /**
+     * `OPENAPI_INVALID` for a malformed document or call, `OPENAPI_UNSUPPORTED` for one these tools
+     * cannot read, such as Swagger 2.0 or a reference outside the document, and `OPENAPI_REQUEST`
+     * for a call the API refused or did not answer.
+     */
+    readonly code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST';
+    /** The HTTP status the API answered with, when it did. */
+    readonly status?: number | undefined;
+    constructor(message: string, 
+    /**
+     * `OPENAPI_INVALID` for a malformed document or call, `OPENAPI_UNSUPPORTED` for one these tools
+     * cannot read, such as Swagger 2.0 or a reference outside the document, and `OPENAPI_REQUEST`
+     * for a call the API refused or did not answer.
+     */
+    code: 'OPENAPI_INVALID' | 'OPENAPI_UNSUPPORTED' | 'OPENAPI_REQUEST', 
+    /** The HTTP status the API answered with, when it did. */
+    status?: number | undefined);
+}
+/**
+ * Reads an OpenAPI 3 document into tools, one per operation: named by its `operationId`, or its
+ * method and path; described by its summary; its path, query, and header parameters, and the fields
+ * of a JSON body, as the tool's parameters. Each declares `api.read`, `api.write`, or
+ * `api.destructive` with the API's name and its own, as its method says, and `network` for the
+ * API's host when it runs. References within the document are followed; one outside it is refused.
+ *
+ * ```ts
+ * const shop = openApiTools(JSON.parse(await readFile('shop.openapi.json', 'utf8')), {
+ *   baseUrl: 'https://shop.example.com/api',
+ *   headers: { authorization: `Bearer ${process.env.SHOP_TOKEN}` },
+ * });
+ * const agent = createAgent({ client: ai, tools: shop.tools });
+ * ```
+ */
+export declare function openApiTools(document: OpenApiDocument | string, options?: OpenApiToolsOptions): OpenApiTools;
+/** Fetches an OpenAPI document, as JSON, and reads it into tools, resolving its servers against where it came from. */
+export declare function loadOpenApiTools(url: string, options?: OpenApiToolsOptions): Promise<OpenApiTools>;