nexus-ai-pro 2.2.0 → 2.4.0

package/dist-cjs/mcp/client.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.McpClient = void 0;
+exports.serverEnvironment = serverEnvironment;
 exports.createStdioTransport = createStdioTransport;
 exports.createHttpTransport = createHttpTransport;
 const protocol_js_1 = require("./protocol.js");
@@ -170,6 +171,64 @@ class McpClient {
     }
 }
 exports.McpClient = McpClient;
+const INHERITED_ENV = new Set([
+    'PATH',
+    'PATHEXT',
+    'HOME',
+    'USER',
+    'USERNAME',
+    'LOGNAME',
+    'SHELL',
+    'TERM',
+    'LANG',
+    'LANGUAGE',
+    'TZ',
+    'TMPDIR',
+    'TEMP',
+    'TMP',
+    'XDG_CONFIG_HOME',
+    'XDG_CACHE_HOME',
+    'XDG_DATA_HOME',
+    'XDG_RUNTIME_DIR',
+    'SYSTEMROOT',
+    'SYSTEMDRIVE',
+    'WINDIR',
+    'COMSPEC',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'USERPROFILE',
+    'HOMEDRIVE',
+    'HOMEPATH',
+    'PROGRAMDATA',
+    'PROGRAMFILES',
+    'PROGRAMFILES(X86)',
+    'COMMONPROGRAMFILES',
+    'PROCESSOR_ARCHITECTURE',
+    'NUMBER_OF_PROCESSORS',
+    'OS',
+    'HTTP_PROXY',
+    'HTTPS_PROXY',
+    'NO_PROXY',
+    'ALL_PROXY',
+    'NODE_EXTRA_CA_CERTS',
+    'SSL_CERT_FILE',
+    'SSL_CERT_DIR',
+]);
+function serverEnvironment(source, options = {}) {
+    if (options.inheritEnv === false)
+        return { ...options.env };
+    const named = new Set((Array.isArray(options.inheritEnv) ? options.inheritEnv : []).map((name) => name.toUpperCase()));
+    const inherited = {};
+    for (const [name, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        const upper = name.toUpperCase();
+        if (options.inheritEnv === true || INHERITED_ENV.has(upper) || upper.startsWith('LC_') || named.has(upper)) {
+            inherited[name] = value;
+        }
+    }
+    return { ...inherited, ...options.env };
+}
 function createStdioTransport(options) {
     let child;
     const decoder = new protocol_js_1.LineDecoder();
@@ -180,7 +239,7 @@ function createStdioTransport(options) {
             const { spawn } = await Promise.resolve().then(() => __importStar(require('node:child_process')));
             const spawned = spawn(options.command, options.args ?? [], {
                 cwd: options.cwd,
-                env: { ...process.env, ...options.env },
+                env: serverEnvironment(process.env, options),
                 stdio: ['pipe', 'pipe', 'inherit'],
             });
             spawned.stdout.setEncoding('utf8');

package/dist-cjs/mcp/registry.d.ts

@@ -15,6 +15,12 @@ export interface McpServerConfig {
     env?: Record<string, string>;
     /** Working directory for the process. */
     cwd?: string;
+    /**
+     * Which of this process's own environment variables a local server inherits, besides `env`. By
+     * default, only what a process needs to start, never an API key; a list adds variables by name,
+     * `true` passes the whole environment, and `false` nothing but `env`.
+     */
+    inheritEnv?: boolean | string[];
     /** The endpoint of a remote server, reached over HTTP. */
     url?: string;
     /** Headers sent to a remote server, such as authorization. */

package/dist-cjs/mcp/registry.js

@@ -97,6 +97,7 @@ class McpRegistry {
                         ...(resolved.args ? { args: resolved.args } : {}),
                         ...(resolved.env ? { env: resolved.env } : {}),
                         ...(resolved.cwd ? { cwd: resolved.cwd } : {}),
+                        ...(resolved.inheritEnv !== undefined ? { inheritEnv: resolved.inheritEnv } : {}),
                     })
                     : (0, client_js_1.createHttpTransport)({
                         url: resolved.url,
@@ -202,6 +203,12 @@ function validateMcpConfig(value) {
                 throw new McpRegistryError(`Server "${name}": "${field}" is a list of strings`, name);
             }
         }
+        const inherit = server.inheritEnv;
+        if (inherit !== undefined &&
+            typeof inherit !== 'boolean' &&
+            !(Array.isArray(inherit) && inherit.every((item) => typeof item === 'string'))) {
+            throw new McpRegistryError(`Server "${name}": "inheritEnv" is true, false, or a list of names`, name);
+        }
         for (const field of ['env', 'headers']) {
             const map = server[field];
             if (map !== undefined &&

package/dist-cjs/postgres/fulltext.d.ts

@@ -0,0 +1,67 @@
+import type { RagChunk } from '../hallucination/rag.js';
+import type { VectorSearchResult } from '../hallucination/retrieval.js';
+import type { RetrieveOptions, SparseRetriever } from '../rag/retrievers.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
+import { type PostgresLikeClient } from './client.js';
+import type { PostgresMigrateOptions } from './migrations.js';
+/** Options for `PostgresKeywordIndex`. */
+export interface PostgresKeywordIndexOptions {
+    /** Table name, optionally schema-qualified. Defaults to `nexus_keywords`. */
+    table?: string;
+    /**
+     * Searches the table of a `PostgresVectorStore` instead of keeping chunks of its own. `migrate()`
+     * adds a generated search column and its index to that table, the store's writes keep it current,
+     * and `add()` and `delete()` leave writing to the store. One copy of every chunk, and keyword and
+     * vector search can never disagree about what exists.
+     */
+    shared?: boolean;
+    /** The text search configuration: `english`, `simple`, `german`, and so on. Defaults to `english`. */
+    language?: string;
+    /**
+     * `any` (the default) finds chunks with any of the query's terms, ranked by how many and how close,
+     * as keyword search for retrieval should. `all` needs every term, read as a web search query, with
+     * quoted phrases and `-` for exclusion.
+     */
+    match?: 'any' | 'all';
+}
+/**
+ * The versioned schema, which `migrate()` applies. Version 1 creates the table with a generated
+ * `tsvector` column and a GIN index, or, `shared`, adds the column and the index to a vector table.
+ */
+export declare function keywordIndexMigrations(options?: PostgresKeywordIndexOptions): SchemaMigration[];
+/**
+ * Keyword search in Postgres, with its full-text search: stemmed terms, a GIN index, and
+ * `ts_rank_cd` ranking, so only the best matches leave the database however large the table.
+ *
+ * A `SparseRetriever`, so `hybridRetriever()` fuses it with `PostgresVectorStore`. With `shared`, it
+ * searches the vector store's own table, and the hybrid search runs over one copy of the data. A
+ * metadata filter runs in SQL, with the same meaning as the vector store's.
+ *
+ * ```ts
+ * const vectors = new PostgresVectorStore(client, { dimensions: 1536, embed });
+ * const keywords = new PostgresKeywordIndex(client, { table: 'nexus_vectors', shared: true });
+ * await vectors.migrate();
+ * await keywords.migrate();
+ * const retriever = hybridRetriever([vectorRetriever(vectors), keywords]);
+ * ```
+ */
+export declare class PostgresKeywordIndex implements SparseRetriever {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    private readonly language;
+    constructor(client: PostgresLikeClient, options?: PostgresKeywordIndexOptions);
+    /**
+     * Applies this index's pending migrations, recorded in `nexus_schema_migrations`, under a lock.
+     * Never runs implicitly. With `shared`, run the vector store's `migrate()` first.
+     */
+    migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
+    /** Adds chunks, or replaces those whose id exists. With `shared`, does nothing: the vector store writes. */
+    add(chunks: readonly RagChunk[]): Promise<void>;
+    /** Removes chunks by id. With `shared`, does nothing: the vector store deletes. */
+    delete(ids: readonly string[]): Promise<void>;
+    /** The chunks that best match a query's terms, best first, scored from 0 to 1. */
+    retrieve(query: string, options?: RetrieveOptions): Promise<VectorSearchResult[]>;
+    /** Chunks held. */
+    size(): Promise<number>;
+}

package/dist-cjs/postgres/fulltext.js

@@ -0,0 +1,129 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresKeywordIndex = void 0;
+exports.keywordIndexMigrations = keywordIndexMigrations;
+const client_js_1 = require("./client.js");
+const sql_js_1 = require("./sql.js");
+const DEFAULT_TABLE = 'nexus_keywords';
+function languageOf(options) {
+    const language = options.language ?? 'english';
+    if (!/^[a-z_]{1,63}$/.test(language))
+        throw new RangeError(`"${language}" is not a text search configuration name`);
+    return language;
+}
+function keywordIndexMigrations(options = {}) {
+    const name = options.table ?? DEFAULT_TABLE;
+    const table = (0, client_js_1.quoteTable)(name);
+    const generated = `fts tsvector GENERATED ALWAYS AS (to_tsvector('${languageOf(options)}'::regconfig, content)) STORED`;
+    return [
+        {
+            component: `keywords:${name}`,
+            version: 1,
+            name: options.shared ? 'add full-text search to a vector table' : 'create the keyword table',
+            statements: [
+                options.shared
+                    ? `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS ${generated}`
+                    : `CREATE TABLE IF NOT EXISTS ${table} (
+  id text PRIMARY KEY,
+  content text NOT NULL,
+  source text,
+  metadata jsonb,
+  ${generated}
+)`,
+                `CREATE INDEX IF NOT EXISTS ${(0, client_js_1.quoteDerived)(name, 'fts')} ON ${table} USING gin (fts)`,
+            ],
+        },
+    ];
+}
+class PostgresKeywordIndex {
+    client;
+    options;
+    table;
+    language;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.table = (0, client_js_1.quoteTable)(options.table ?? DEFAULT_TABLE);
+        this.language = languageOf(options);
+    }
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await Promise.resolve().then(() => __importStar(require('./migrations.js')));
+        return applyPostgresMigrations(this.client, keywordIndexMigrations(this.options), options);
+    }
+    async add(chunks) {
+        if (this.options.shared || chunks.length === 0)
+            return;
+        const params = new sql_js_1.SqlParams();
+        const rows = chunks.map((chunk) => `(${params.add(chunk.id)}, ${params.add(chunk.content)}, ${params.add(chunk.source ?? null)}, ${params.add(chunk.metadata === undefined ? null : JSON.stringify(chunk.metadata))}::jsonb)`);
+        await this.client.query(`INSERT INTO ${this.table} (id, content, source, metadata) VALUES ${rows.join(', ')}
+       ON CONFLICT (id) DO UPDATE SET content = EXCLUDED.content, source = EXCLUDED.source, metadata = EXCLUDED.metadata`, params.values);
+    }
+    async delete(ids) {
+        if (this.options.shared || ids.length === 0)
+            return;
+        await this.client.query(`DELETE FROM ${this.table} WHERE id = ANY($1::text[])`, [(0, sql_js_1.textArray)(ids)]);
+    }
+    async retrieve(query, options = {}) {
+        options.signal?.throwIfAborted();
+        const params = new sql_js_1.SqlParams();
+        const text = params.add(query);
+        const language = `'${this.language}'::regconfig`;
+        const tsquery = this.options.match === 'all'
+            ? `websearch_to_tsquery(${language}, ${text})`
+            : `NULLIF(replace(plainto_tsquery(${language}, ${text})::text, ' & ', ' | '), '')::tsquery`;
+        const conditions = ['fts @@ q.query'];
+        if (options.filter && Object.keys(options.filter).length > 0) {
+            conditions.push(`metadata @> ${params.add(JSON.stringify(options.filter))}::jsonb`);
+        }
+        const limit = params.add(options.topK ?? 5);
+        const { rows } = await this.client.query(`SELECT id, content, source, metadata::text AS metadata, ts_rank_cd(fts, q.query, 32) AS score
+       FROM ${this.table}, (SELECT ${tsquery} AS query) AS q
+       WHERE ${conditions.join(' AND ')}
+       ORDER BY score DESC, id LIMIT ${limit}`, params.values);
+        return rows.map((row) => ({
+            id: row.id,
+            content: row.content,
+            ...(row.source === null ? {} : { source: row.source }),
+            ...(row.metadata === null ? {} : { metadata: (0, client_js_1.fromJson)(row.metadata) }),
+            score: Number(row.score),
+        }));
+    }
+    async size() {
+        const { rows } = await this.client.query(`SELECT count(*)::int AS count FROM ${this.table}`);
+        return Number(rows[0]?.count ?? 0);
+    }
+}
+exports.PostgresKeywordIndex = PostgresKeywordIndex;

package/dist-cjs/prompts/file.js

@@ -44,20 +44,24 @@ class FilePromptStore {
     }
     async setLabel(label, expected) {
         const file = this.labelFile(label.name, label.label);
-        if (expected !== undefined) {
-            const current = await readJson(file);
-            if (expected === null ? current !== undefined : current?.version !== expected)
-                return false;
-        }
-        await writeJson(file, label);
-        return true;
+        return serialized(file, async () => {
+            if (expected !== undefined) {
+                const current = await readJson(file);
+                if (expected === null ? current !== undefined : current?.version !== expected)
+                    return false;
+            }
+            await writeJson(file, label);
+            return true;
+        });
     }
     async deleteLabel(name, label) {
         const file = this.labelFile(name, label);
-        if ((await readJson(file)) === undefined)
-            return false;
-        await (0, promises_1.rm)(file, { force: true });
-        return true;
+        return serialized(file, async () => {
+            if ((await readJson(file)) === undefined)
+                return false;
+            await (0, promises_1.rm)(file, { force: true });
+            return true;
+        });
     }
     async appendHistory(entry) {
         await (0, promises_1.mkdir)(this.promptDir(entry.name), { recursive: true });
@@ -116,6 +120,19 @@ async function readJson(file) {
         return undefined;
     }
 }
+const labelWrites = new Map();
+async function serialized(file, work) {
+    const key = node_path_1.default.resolve(file);
+    const next = (labelWrites.get(key) ?? Promise.resolve()).catch(() => undefined).then(work);
+    labelWrites.set(key, next);
+    try {
+        return await next;
+    }
+    finally {
+        if (labelWrites.get(key) === next)
+            labelWrites.delete(key);
+    }
+}
 async function writeJson(file, value) {
     await (0, promises_1.mkdir)(node_path_1.default.dirname(file), { recursive: true });
     const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;

package/dist-cjs/protocols/a2a.d.ts

@@ -0,0 +1,235 @@
+import type { Message, ToolDefinition } from '../types/messages.js';
+import type { Principal } from '../types/principal.js';
+import { type ProtocolGraph, type ProtocolInterrupt } from './shared.js';
+export type { ProtocolGraph, ProtocolInterrupt, ProtocolResult, ProtocolRunOptions } from './shared.js';
+/** The protocol version this module speaks. */
+export declare const A2A_PROTOCOL_VERSION = "1.0";
+/** Who a message is from. */
+export type A2aRole = 'ROLE_USER' | 'ROLE_AGENT';
+/** Where a task stands. */
+export type A2aTaskState = 'TASK_STATE_SUBMITTED' | 'TASK_STATE_WORKING' | 'TASK_STATE_INPUT_REQUIRED' | 'TASK_STATE_AUTH_REQUIRED' | 'TASK_STATE_COMPLETED' | 'TASK_STATE_FAILED' | 'TASK_STATE_CANCELED' | 'TASK_STATE_REJECTED';
+/** One part of a message or an artifact: text, structured data, or a file by URL or bytes. */
+export interface A2aPart {
+    /** Text. */
+    text?: string;
+    /** Structured data. */
+    data?: unknown;
+    /** A file, by URL. */
+    url?: string;
+    /** A file, as base64 bytes. */
+    raw?: string;
+    /** The part's media type. */
+    mediaType?: string;
+    /** A file's name. */
+    filename?: string;
+    /** Anything else. */
+    metadata?: Record<string, unknown>;
+}
+/** A message between agents. */
+export interface A2aMessage {
+    /** Its id. */
+    messageId: string;
+    /** Who it is from. */
+    role: A2aRole;
+    /** What it says. */
+    parts: A2aPart[];
+    /** The conversation it belongs to. */
+    contextId?: string;
+    /** The task it continues, when it answers one. */
+    taskId?: string;
+    /** Anything else. */
+    metadata?: Record<string, unknown>;
+}
+/** What a task produced. */
+export interface A2aArtifact {
+    /** Its id. */
+    artifactId: string;
+    /** Its name. */
+    name?: string;
+    /** Its content. */
+    parts: A2aPart[];
+}
+/** A unit of work an agent was asked to do. */
+export interface A2aTask {
+    /** Its id. */
+    id: string;
+    /** The conversation it belongs to. */
+    contextId: string;
+    /** Where it stands, with the agent's latest message. */
+    status: {
+        state: A2aTaskState;
+        message?: A2aMessage;
+        timestamp?: string;
+    };
+    /** What it produced. */
+    artifacts?: A2aArtifact[];
+    /** The messages exchanged, when asked for. */
+    history?: A2aMessage[];
+    /** Anything else. */
+    metadata?: Record<string, unknown>;
+}
+/** A skill an agent card advertises. */
+export interface A2aSkill {
+    /** Its id. */
+    id: string;
+    /** Its name. */
+    name: string;
+    /** What it does. */
+    description: string;
+    /** Labels for discovery. */
+    tags: string[];
+    /** Example requests. */
+    examples?: string[];
+}
+/** What an agent publishes about itself at `/.well-known/agent-card.json`. */
+export interface A2aAgentCard {
+    /** Its name. */
+    name: string;
+    /** What it does. */
+    description: string;
+    /** Its version. */
+    version: string;
+    /** Who provides it. */
+    provider?: {
+        organization: string;
+        url?: string;
+    };
+    /** Where it is reached, and how. */
+    supportedInterfaces: Array<{
+        url: string;
+        protocolBinding: string;
+        protocolVersion: string;
+    }>;
+    /** What it supports. */
+    capabilities: {
+        streaming: boolean;
+        pushNotifications: boolean;
+        extendedAgentCard: boolean;
+    };
+    /** Media types it accepts. */
+    defaultInputModes: string[];
+    /** Media types it produces. */
+    defaultOutputModes: string[];
+    /** What it can do. */
+    skills: A2aSkill[];
+}
+/** A streamed event: a task, a status change, or a piece of an artifact. */
+export type A2aStreamEvent = {
+    task: A2aTask;
+} | {
+    message: A2aMessage;
+} | {
+    statusUpdate: {
+        taskId: string;
+        contextId: string;
+        status: A2aTask['status'];
+    };
+} | {
+    artifactUpdate: {
+        taskId: string;
+        contextId: string;
+        artifact: A2aArtifact;
+        append?: boolean;
+        lastChunk?: boolean;
+    };
+};
+/** A2A's error codes, beside JSON-RPC's own. */
+export declare const A2A_ERRORS: {
+    readonly taskNotFound: -32001;
+    readonly taskNotCancelable: -32002;
+    readonly unsupportedOperation: -32004;
+    readonly versionNotSupported: -32009;
+};
+/** Raised by the client when an agent answers with a JSON-RPC error. */
+export declare class A2aError extends Error {
+    /** The JSON-RPC error code. */
+    readonly code: number;
+    /** The error's data, when the agent sent any. */
+    readonly data?: unknown | undefined;
+    constructor(
+    /** The JSON-RPC error code. */
+    code: number, message: string, 
+    /** The error's data, when the agent sent any. */
+    data?: unknown | undefined);
+}
+/** Options for `a2aHandler()`. */
+export interface A2aServerOptions {
+    /** The card's content: the endpoint `url` is where this handler is mounted. */
+    card: Omit<A2aAgentCard, 'supportedInterfaces' | 'capabilities' | 'defaultInputModes' | 'defaultOutputModes'> & {
+        url: string;
+        defaultInputModes?: string[];
+        defaultOutputModes?: string[];
+    };
+    /** The graph input for a task. Defaults to `{ messages }`: the context's conversation and the new message. */
+    input?: (message: A2aMessage, history: Message[]) => unknown;
+    /**
+     * The answer a message gives a paused task's question. Defaults to its first data part's value,
+     * such as `{ approved: true }` for a tool approval, or else its text. Text answering an approval is
+     * read as words: yes, ok, allow, approve, or confirm allows, and anything else refuses.
+     */
+    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. */
+    maxTasks?: number;
+}
+/**
+ * An HTTP handler that serves a graph as an A2A agent: `GET` the card, `POST` JSON-RPC. Mount it
+ * at the card's `url`; it answers the well-known card path under the same origin too.
+ *
+ * ```ts
+ * const handler = a2aHandler(agent, {
+ *   card: { name: 'Researcher', description: 'Answers research questions', version: '1.0.0', url: 'https://agents.example.com/a2a', skills: [] },
+ * });
+ * ```
+ */
+export declare function a2aHandler(graph: ProtocolGraph, options: A2aServerOptions): (request: Request) => Promise<Response>;
+/** Options for `a2aClient()`. */
+export interface A2aClientOptions {
+    /** The agent: its card's URL, or its JSON-RPC endpoint, whose origin serves the card. */
+    url: string;
+    /** Replaces the global `fetch`, for authentication, a proxy, or tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Headers added to every request, such as an authorization header. */
+    headers?: Record<string, string>;
+}
+/** What to send: text, and optionally data, a conversation, or the paused task it answers. */
+export interface A2aSendOptions {
+    /** The conversation to continue. */
+    contextId?: string;
+    /** The paused task this message answers. */
+    taskId?: string;
+    /** Structured data sent beside the text, such as `{ approved: true }`. */
+    data?: unknown;
+    /** Cancels the request. */
+    signal?: AbortSignal;
+}
+/** A client for one A2A agent. */
+export interface A2aClient {
+    /** The agent's card, fetched once. */
+    card(): 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>;
+    /** Cancels a task. */
+    cancel(taskId: string): Promise<A2aTask>;
+}
+/** A client for an A2A agent, by its card or endpoint URL. */
+export declare function a2aClient(options: A2aClientOptions): A2aClient;
+/** Options for `a2aTool()`. */
+export interface A2aToolOptions extends A2aClientOptions {
+    /** The tool's name, as the model calls it. */
+    name: string;
+    /** What the remote agent does, written for the model that decides when to call it. */
+    description: string;
+}
+/**
+ * A remote A2A agent as a tool another agent can call. Each call is a task, and the remote agent's
+ * answer is the result; a remote task that needs input reports its question, which the model can
+ * answer by calling again with `taskId`. The tool declares the host it reaches, as
+ * `network:<host>`, so a permission policy grants or denies it like any other.
+ */
+export declare function a2aTool(options: A2aToolOptions): ToolDefinition;