nexus-ai-pro 2.4.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/operations/adapters.d.ts

@@ -58,7 +58,8 @@ export declare class RedisOperationStore<TResult = unknown> implements Operation
     private readonly client;
     private readonly prefix;
     private readonly useEval;
-    private readonly indexed;
+    /** Whether queued and leased work is kept in sorted sets, as `index: true` asks. */
+    readonly indexed: boolean;
     constructor(client: RedisOperationLikeClient, options?: RedisOperationStoreOptions);
     /**
      * Stores a new record and indexes its idempotency key. Throws `OperationDuplicateError` when another

package/dist/operations/runner.js

@@ -51,6 +51,8 @@ export class OperationRunner {
         for (const record of candidates) {
             if (claimed.length >= limit)
                 break;
+            if (!matchesFilter(record, filter))
+                continue;
             if (record.expiresAt && record.expiresAt <= nowIso) {
                 await this.settleExpired(record);
                 continue;

package/dist/operations/stats.js

@@ -5,29 +5,36 @@ export function isUnheldQueued(record, now) {
 export function matchesFilter(record, filter) {
     if (filter?.tenantId !== undefined && record.tenantId !== filter.tenantId)
         return false;
+    if (filter?.kinds && !filter.kinds.includes(record.kind ?? ''))
+        return false;
     return !filter?.kindPrefix || (record.kind ?? '').startsWith(filter.kindPrefix);
 }
 export function countRecords(records, now, filter) {
     const byStatus = {};
     let oldestQueuedAt;
     let lapsedLeases = 0;
+    const queuedByKind = {};
     for (const record of records) {
         if (isTerminalOperationStatus(record.status) || !matchesFilter(record, filter))
             continue;
         byStatus[record.status] = (byStatus[record.status] ?? 0) + 1;
-        if (record.status === 'queued' && (!oldestQueuedAt || record.createdAt < oldestQueuedAt)) {
-            oldestQueuedAt = record.createdAt;
+        if (record.status === 'queued') {
+            if (!oldestQueuedAt || record.createdAt < oldestQueuedAt)
+                oldestQueuedAt = record.createdAt;
+            const kind = record.kind ?? '';
+            queuedByKind[kind] = (queuedByKind[kind] ?? 0) + 1;
         }
         if (record.status === 'running' && (!record.lease || record.lease.expiresAt <= now))
             lapsedLeases += 1;
     }
-    return { byStatus, ...(oldestQueuedAt ? { oldestQueuedAt } : {}), lapsedLeases };
+    return { byStatus, ...(oldestQueuedAt ? { oldestQueuedAt } : {}), lapsedLeases, queuedByKind };
 }
 export async function operationStats(store, options = {}) {
     const now = (options.now ?? new Date()).toISOString();
-    const filter = options.kindPrefix || options.tenantId !== undefined
+    const filter = options.kindPrefix || options.kinds || options.tenantId !== undefined
         ? {
             ...(options.kindPrefix ? { kindPrefix: options.kindPrefix } : {}),
+            ...(options.kinds ? { kinds: options.kinds } : {}),
             ...(options.tenantId !== undefined ? { tenantId: options.tenantId } : {}),
         }
         : undefined;

package/dist/postgres/index.d.ts

@@ -9,9 +9,10 @@ export { PostgresPromptStore, type PostgresPromptStoreOptions, promptStoreMigrat
 export { PostgresRollupStore, type PostgresRollupStoreOptions, rollupStoreMigration, rollupStoreMigrations, } from './rollups.js';
 export { PostgresStore, type PostgresStoreOptions, storeMigration, storeMigrations } from './store.js';
 export { PostgresTraceStore, type PostgresTraceStoreOptions, traceStoreMigration, traceStoreMigrations, } from './traces.js';
+export { PostgresTenantUsage, type PostgresTenantUsageOptions, tenantUsageMigration, tenantUsageMigrations, } from './tenancy.js';
 export { PostgresVectorStore, type PostgresVectorStoreOptions, vectorStoreMigration, vectorStoreMigrations, } from './vectors.js';
 /** The Postgres adapters a migration can include. */
-export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'prompts' | 'rollups' | 'vectors';
+export type PostgresAdapter = 'operations' | 'store' | 'traces' | 'evaluation' | 'circuits' | 'tenancy' | 'prompts' | 'rollups' | 'vectors';
 /** Options for `postgresMigrations()` and `postgresMigration()`. */
 export interface PostgresMigrationOptions {
     /**

package/dist/postgres/index.js

@@ -7,6 +7,7 @@ import { operationStoreMigrations } from './operations.js';
 import { promptStoreMigrations } from './prompts.js';
 import { rollupStoreMigrations } from './rollups.js';
 import { storeMigrations } from './store.js';
+import { tenantUsageMigrations } from './tenancy.js';
 import { traceStoreMigrations } from './traces.js';
 import { vectorStoreMigrations } from './vectors.js';
 export { migrationChecksum, SchemaMigrationError, } from '../utils/schema-migrations.js';
@@ -19,6 +20,7 @@ export { PostgresPromptStore, promptStoreMigration, promptStoreMigrations, } fro
 export { PostgresRollupStore, rollupStoreMigration, rollupStoreMigrations, } from './rollups.js';
 export { PostgresStore, storeMigration, storeMigrations } from './store.js';
 export { PostgresTraceStore, traceStoreMigration, traceStoreMigrations, } from './traces.js';
+export { PostgresTenantUsage, tenantUsageMigration, tenantUsageMigrations, } from './tenancy.js';
 export { PostgresVectorStore, vectorStoreMigration, vectorStoreMigrations, } from './vectors.js';
 export const POSTGRES_ADAPTERS = [
     'operations',
@@ -26,6 +28,7 @@ export const POSTGRES_ADAPTERS = [
     'traces',
     'evaluation',
     'circuits',
+    'tenancy',
     'prompts',
     'rollups',
     'vectors',
@@ -39,6 +42,7 @@ export function postgresMigrations(options = {}) {
         traces: () => traceStoreMigrations(),
         evaluation: () => evaluationStoreMigrations(),
         circuits: () => circuitStoreMigrations(),
+        tenancy: () => tenantUsageMigrations(),
         prompts: () => promptStoreMigrations(),
         rollups: () => rollupStoreMigrations(),
         vectors: () => {

package/dist/postgres/operations.js

@@ -131,12 +131,12 @@ export class PostgresOperationStore {
     async stats(now, filter) {
         const params = [now];
         const narrowed = filterSql(filter, params);
-        const { rows } = await this.client.query(`SELECT status, count(*)::int AS count,
+        const { rows } = await this.client.query(`SELECT status, kind, count(*)::int AS count,
          min(created_at) FILTER (WHERE status = 'queued') AS oldest,
          count(*) FILTER (WHERE status = 'running' AND (lease_expires_at IS NULL OR lease_expires_at <= $1))::int AS lapsed
        FROM ${this.table}
        WHERE status NOT IN (${TERMINAL})${narrowed}
-       GROUP BY status`, params);
+       GROUP BY status, kind`, params);
         return statsFromRows(rows);
     }
     async prune(before) {
@@ -163,6 +163,10 @@ function filterSql(filter, params) {
         params.push(filter.kindPrefix);
         sql += ` AND substr(kind, 1, char_length($${params.length})) = $${params.length}`;
     }
+    if (filter?.kinds) {
+        params.push([...filter.kinds]);
+        sql += ` AND kind = ANY($${params.length}::text[])`;
+    }
     if (filter?.tenantId !== undefined) {
         params.push(filter.tenantId);
         sql += ` AND doc ->> 'tenantId' = $${params.length}`;
@@ -173,11 +177,14 @@ function statsFromRows(rows) {
     const byStatus = {};
     let oldestQueuedAt;
     let lapsedLeases = 0;
+    const queuedByKind = {};
     for (const row of rows) {
-        byStatus[row.status] = Number(row.count);
+        byStatus[row.status] = (byStatus[row.status] ?? 0) + Number(row.count);
+        if (row.status === 'queued')
+            queuedByKind[row.kind ?? ''] = (queuedByKind[row.kind ?? ''] ?? 0) + Number(row.count);
         if (row.oldest && (!oldestQueuedAt || row.oldest < oldestQueuedAt))
             oldestQueuedAt = row.oldest;
         lapsedLeases += Number(row.lapsed);
     }
-    return { byStatus, ...(oldestQueuedAt ? { oldestQueuedAt } : {}), lapsedLeases };
+    return { byStatus, ...(oldestQueuedAt ? { oldestQueuedAt } : {}), lapsedLeases, queuedByKind };
 }

package/dist/postgres/store.d.ts

@@ -44,6 +44,13 @@ export declare class PostgresStore implements Store {
     migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
     /** Stores an item, keeping its original `createdAt` when it replaces one. */
     put<V>(namespace: StoreNamespace, key: string, value: V, options?: StorePutOptions): Promise<void>;
+    /**
+     * Stores an item only when the stored one's `version` is `expected`, or, with `expected` `null`,
+     * only when none is stored. One statement, so two writers deciding on one version cannot both win.
+     */
+    putIfVersion<V extends {
+        version: number;
+    }>(namespace: StoreNamespace, key: string, value: V, expected: number | null): Promise<boolean>;
     /** Reads an item, or `undefined` when it does not exist or has expired. */
     get<V>(namespace: StoreNamespace, key: string): Promise<StoreItem<V> | undefined>;
     /** Deletes an item. */

package/dist/postgres/store.js

@@ -71,6 +71,27 @@ export class PostgresStore {
             vector ? JSON.stringify(vector) : null,
         ]);
     }
+    async putIfVersion(namespace, key, value, expected) {
+        if (!key.trim())
+            throw new RangeError('A store key must not be empty');
+        const timestamp = this.now().toISOString();
+        const vector = await this.embed(value, undefined);
+        const embedding = vector ? JSON.stringify(vector) : null;
+        const cast = this.options.vectorDimensions ? '::vector' : '::jsonb';
+        const { rows } = expected === null
+            ?
+                await this.client.query(`INSERT INTO ${this.table} (ns_key, key, namespace, value, created_at, updated_at, expires_at, embedding)
+             VALUES ($1, $2, $3::jsonb, $4::jsonb, $5, $5, NULL, $6${cast})
+             ON CONFLICT (ns_key, key) DO UPDATE SET value = EXCLUDED.value, created_at = EXCLUDED.created_at,
+               updated_at = EXCLUDED.updated_at, expires_at = NULL, embedding = EXCLUDED.embedding
+             WHERE ${this.table}.expires_at IS NOT NULL AND ${this.table}.expires_at <= $5
+             RETURNING key`, [namespaceKey(namespace), key, JSON.stringify([...namespace]), JSON.stringify(value), timestamp, embedding])
+            : await this.client.query(`UPDATE ${this.table} SET value = $3::jsonb, updated_at = $4, expires_at = NULL, embedding = $5${cast}
+             WHERE ns_key = $1 AND key = $2 AND (expires_at IS NULL OR expires_at > $4)
+               AND jsonb_typeof(value -> 'version') = 'number' AND (value ->> 'version')::numeric = $6
+             RETURNING key`, [namespaceKey(namespace), key, JSON.stringify(value), timestamp, embedding, expected]);
+        return rows.length > 0;
+    }
     async get(namespace, key) {
         const { rows } = await this.client.query(`SELECT namespace::text AS namespace, key, value::text AS value, created_at, updated_at, expires_at FROM ${this.table}
        WHERE ns_key = $1 AND key = $2 AND (expires_at IS NULL OR expires_at > $3)`, [namespaceKey(namespace), key, this.now().toISOString()]);

package/dist/postgres/tenancy.d.ts

@@ -0,0 +1,43 @@
+import type { TenantUsageStore } from '../server/tenancy.js';
+import type { MigrationResult, SchemaMigration } from '../utils/schema-migrations.js';
+import { type PostgresLikeClient } from './client.js';
+import type { PostgresMigrateOptions } from './migrations.js';
+/** Options for `PostgresTenantUsage`. */
+export interface PostgresTenantUsageOptions {
+    /** Table name, optionally schema-qualified. Defaults to `nexus_tenant_usage`. */
+    table?: string;
+    /** Clock for slot leases and spending periods, in epoch milliseconds. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** The schema, as statements: every migration's, in order. */
+export declare function tenantUsageMigration(options?: Pick<PostgresTenantUsageOptions, 'table'>): string[];
+/** The versioned schema, which `migrate()` and `nexus db migrate` apply. */
+export declare function tenantUsageMigrations(options?: Pick<PostgresTenantUsageOptions, 'table'>): SchemaMigration[];
+/**
+ * Tenant usage in Postgres, shared by every replica, for a deployment that already runs Postgres
+ * and not Redis. Pass it to `tenantLimits({ usage })`.
+ *
+ * Each key is one row: a tenant's active slots as a JSON map from run to lease expiry, or its spending
+ * in the current period. Every step is a single statement on that row, and Postgres applies
+ * concurrent updates of one row one at a time, re-checking each against the newest version. Two
+ * replicas admitting runs for one tenant at the same moment therefore cannot both take its last slot.
+ */
+export declare class PostgresTenantUsage implements TenantUsageStore {
+    private readonly client;
+    private readonly options;
+    private readonly table;
+    private readonly now;
+    constructor(client: PostgresLikeClient, options?: PostgresTenantUsageOptions);
+    /** Creates the table, or brings it up to date. */
+    migrate(options?: PostgresMigrateOptions): Promise<MigrationResult>;
+    /** Takes a slot for `member` unless `max` live slots are held. Holding one already counts as taken. */
+    acquire(key: string, member: string, max: number, ttlMs: number): Promise<boolean>;
+    /** Frees a slot. Freeing one that is not held does nothing. */
+    release(key: string, member: string): Promise<void>;
+    /** Live slots held under a key. */
+    count(key: string): Promise<number>;
+    /** Adds to a total that resets at `resetAt`, and resolves to the new total. */
+    add(key: string, amount: number, resetAt: number): Promise<number>;
+    /** A total, or 0 once its period has reset. */
+    total(key: string): Promise<number>;
+}

package/dist/postgres/tenancy.js

@@ -0,0 +1,71 @@
+import { quoteTable } from './client.js';
+export function tenantUsageMigration(options = {}) {
+    return tenantUsageMigrations(options).flatMap((migration) => [...migration.statements]);
+}
+export function tenantUsageMigrations(options = {}) {
+    const name = options.table ?? 'nexus_tenant_usage';
+    return [
+        {
+            component: `tenancy:${name}`,
+            version: 1,
+            name: 'create the tenant usage table',
+            statements: [
+                `CREATE TABLE IF NOT EXISTS ${quoteTable(name)} (
+  key text PRIMARY KEY,
+  slots jsonb NOT NULL DEFAULT '{}'::jsonb,
+  total double precision NOT NULL DEFAULT 0,
+  reset_at double precision
+)`,
+            ],
+        },
+    ];
+}
+export class PostgresTenantUsage {
+    client;
+    options;
+    table;
+    now;
+    constructor(client, options = {}) {
+        this.client = client;
+        this.options = options;
+        this.table = quoteTable(options.table ?? 'nexus_tenant_usage');
+        this.now = options.now ?? Date.now;
+    }
+    async migrate(options = {}) {
+        const { applyPostgresMigrations } = await import('./migrations.js');
+        return applyPostgresMigrations(this.client, tenantUsageMigrations(this.options), options);
+    }
+    async acquire(key, member, max, ttlMs) {
+        const now = this.now();
+        await this.client.query(`INSERT INTO ${this.table} (key) VALUES ($1) ON CONFLICT (key) DO NOTHING`, [key]);
+        const live = `(SELECT COALESCE(jsonb_object_agg(slot.member, slot.expires), '{}'::jsonb)
+      FROM jsonb_each(${this.table}.slots) AS slot(member, expires)
+      WHERE (slot.expires #>> '{}')::double precision > $3)`;
+        const { rows } = await this.client.query(`UPDATE ${this.table}
+       SET slots = CASE WHEN ${live} ? $2 THEN ${live} ELSE ${live} || jsonb_build_object($2::text, $4::double precision) END
+       WHERE key = $1 AND (${live} ? $2 OR (SELECT count(*) FROM jsonb_object_keys(${live})) < $5)
+       RETURNING key`, [key, member, now, now + ttlMs, max]);
+        return rows.length > 0;
+    }
+    async release(key, member) {
+        await this.client.query(`UPDATE ${this.table} SET slots = slots - $2::text WHERE key = $1`, [key, member]);
+    }
+    async count(key) {
+        const { rows } = await this.client.query(`SELECT count(*)::int AS held FROM ${this.table}, jsonb_each(${this.table}.slots) AS slot(member, expires)
+       WHERE key = $1 AND (slot.expires #>> '{}')::double precision > $2`, [key, this.now()]);
+        return Number(rows[0]?.held ?? 0);
+    }
+    async add(key, amount, resetAt) {
+        const { rows } = await this.client.query(`INSERT INTO ${this.table} (key, total, reset_at) VALUES ($1, $2, $3)
+       ON CONFLICT (key) DO UPDATE SET
+         total = CASE WHEN ${this.table}.reset_at IS NOT NULL AND ${this.table}.reset_at <= $4
+           THEN EXCLUDED.total ELSE ${this.table}.total + EXCLUDED.total END,
+         reset_at = EXCLUDED.reset_at
+       RETURNING total`, [key, amount, resetAt, this.now()]);
+        return Number(rows[0]?.total ?? 0);
+    }
+    async total(key) {
+        const { rows } = await this.client.query(`SELECT CASE WHEN reset_at IS NULL OR reset_at > $2 THEN total ELSE 0 END AS total FROM ${this.table} WHERE key = $1`, [key, this.now()]);
+        return Number(rows[0]?.total ?? 0);
+    }
+}

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;