@hivemagnus/ardent 0.0.0-stage → 1.0.1

package/dist/a2a-client.js

@@ -0,0 +1,172 @@
+import { randomUUID } from 'node:crypto';
+import { Role, TaskState } from '@a2a-js/sdk';
+import { ClientFactory, ClientFactoryOptions, DefaultAgentCardResolver, JsonRpcTransportFactory, RestTransportFactory } from '@a2a-js/sdk/client';
+import { GrpcTransportFactory } from '@a2a-js/sdk/client/grpc';
+import { credentials } from '@grpc/grpc-js';
+import { loadPeers, outboundTokenEnv } from './a2a-peers.js';
+import { z } from 'zod';
+export async function fetchHermesTeamCard(card, authorization, signal) {
+    const interfaceUrl = card.supportedInterfaces.find(item => item.protocolBinding.toUpperCase() === 'JSONRPC' && item.protocolVersion === '1.0')?.url;
+    if (!interfaceUrl)
+        throw new Error('Hermes peer has no JSON-RPC 1.0 interface');
+    const url = new URL('/.well-known/hermes-team-card.json', interfaceUrl);
+    const response = await fetch(url, { redirect: 'manual', headers: { Authorization: authorization, Accept: 'application/json' }, signal: signal ?? AbortSignal.timeout(10_000) });
+    if (!response.ok)
+        throw new Error(`Hermes team card HTTP ${response.status}`);
+    const encoded = await response.text();
+    if (Buffer.byteLength(encoded) > 256_000)
+        throw new Error('Hermes team card exceeds bound');
+    const raw = JSON.parse(encoded);
+    return z.record(z.string(), z.unknown()).parse(raw);
+}
+export class ArdentA2AClient {
+    profileDir;
+    config;
+    env;
+    pushInbox;
+    preferredTransports;
+    constructor(profileDir, config, env = process.env, pushInbox, preferredTransports = ['JSONRPC', 'HTTP+JSON', 'GRPC']) {
+        this.profileDir = profileDir;
+        this.config = config;
+        this.env = env;
+        this.pushInbox = pushInbox;
+        this.preferredTransports = preferredTransports;
+    }
+    async open(peerId) {
+        const { peers } = await loadPeers(this.profileDir, this.config, this.env);
+        const peer = peers.find(item => item.id === peerId && item.enabled);
+        if (!peer)
+            throw new Error(`A2A peer is not configured: ${peerId}`);
+        const token = this.env[outboundTokenEnv(peer)];
+        if (!token)
+            throw new Error(`A2A outbound credential is missing: ${outboundTokenEnv(peer)}`);
+        const base = new URL(peer.url);
+        const basePort = Number(base.port || (base.protocol === 'https:' ? 443 : 80));
+        const allowedPorts = new Set([basePort, ...peer.transport_ports]);
+        const sameHost = (url, grpc) => {
+            const parsed = new URL(grpc ? `http://${url}` : url);
+            const port = Number(parsed.port || (parsed.protocol === 'https:' ? 443 : 80));
+            return parsed.hostname === base.hostname && !parsed.username && !parsed.password && !parsed.hash && allowedPorts.has(port) &&
+                (grpc ? Boolean(parsed.port) : (base.protocol !== 'https:' || parsed.protocol === 'https:'));
+        };
+        const safeFetch = (input, init) => {
+            const url = new URL(input instanceof Request ? input.url : String(input));
+            if (!sameHost(url.href, false))
+                throw new Error('A2A peer card redirected to an unconfigured host or port');
+            return fetch(input, { ...init, redirect: 'manual', signal: init?.signal ?? AbortSignal.timeout(30000) });
+        };
+        const resolver = new DefaultAgentCardResolver({ fetchImpl: safeFetch, legacyCompat: { enabled: true } });
+        const card = await resolver.resolve(peer.url);
+        if (!card.supportedInterfaces.length)
+            throw new Error('A2A peer card has no interfaces');
+        for (const iface of card.supportedInterfaces)
+            if (!sameHost(iface.url, iface.protocolBinding.toUpperCase() === 'GRPC'))
+                throw new Error('A2A peer card advertises an unconfigured host');
+        const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+            cardResolver: resolver,
+            transports: [new JsonRpcTransportFactory({ fetchImpl: safeFetch, legacyCompat: { enabled: true } }), new RestTransportFactory({ fetchImpl: safeFetch, legacyCompat: { enabled: true } }), new GrpcTransportFactory({ legacyCompat: { enabled: true }, grpcChannelCredentials: base.protocol === 'https:' ? credentials.createSsl() : credentials.createInsecure() })],
+            preferredTransports: this.preferredTransports
+        }));
+        return { card, client: await factory.createFromAgentCard(card), authorization: `Bearer ${token}` };
+    }
+    async teamControl(peerId, control) {
+        const { card, authorization } = await this.open(peerId);
+        const rawCard = await fetchHermesTeamCard(card, authorization);
+        const advertised = z.object({ metadata: z.object({ hermesTeam: z.object({ coordinationProtocolVersions: z.array(z.string()) }).passthrough() }).passthrough() }).passthrough().safeParse(rawCard);
+        const metadata = advertised.success ? advertised.data.metadata : undefined;
+        if (!metadata?.hermesTeam.coordinationProtocolVersions.includes('1.0'))
+            throw new Error('A2A peer does not advertise Hermes coordination 1.0');
+        const interfaceUrl = card.supportedInterfaces.find(iface => iface.protocolBinding.toUpperCase() === 'JSONRPC' && iface.protocolVersion === '1.0')?.url;
+        if (!interfaceUrl)
+            throw new Error('Hermes coordination peer has no JSON-RPC 1.0 interface');
+        const messageId = `ctl-${randomUUID()}`;
+        // Hermes's accepted control wire requires one exact text part. The SDK's
+        // canonical serializer adds mediaType, so this vendor edge is intentionally
+        // encoded separately from ordinary standards-compliant SendMessage calls.
+        const wire = { jsonrpc: '2.0', id: messageId, method: 'SendMessage', params: { message: {
+                    messageId, contextId: messageId, role: 'ROLE_USER', parts: [{ text: 'HERMES_COORDINATION_CONTROL' }],
+                    metadata: { hermesTeamControl: control }
+                }, configuration: { blocking: false } } };
+        const response = await fetch(interfaceUrl, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
+            headers: { Authorization: authorization, 'A2A-Version': '1.0', 'Content-Type': 'application/json' }, body: JSON.stringify(wire) });
+        if (!response.ok)
+            throw new Error(`Hermes coordination HTTP ${response.status}`);
+        const raw = await response.json();
+        const rpc = z.object({ jsonrpc: z.literal('2.0'), id: z.string(), result: z.unknown().optional(),
+            error: z.object({ message: z.string() }).passthrough().optional() }).passthrough().parse(raw);
+        if (rpc.id !== messageId)
+            throw new Error('Hermes coordination request ID differs');
+        if (rpc.error)
+            throw new Error(`Hermes coordination rejected the control: ${rpc.error.message}`);
+        const task = z.object({ artifacts: z.array(z.object({ parts: z.array(z.object({ text: z.string().optional() }).passthrough()) }).passthrough()) }).passthrough()
+            .safeParse(rpc.result);
+        if (!task.success)
+            throw new Error('Hermes coordination returned no task receipt');
+        const texts = task.data.artifacts.flatMap(artifact => artifact.parts.flatMap(part => part.text ? [part.text] : []));
+        if (texts.length !== 1)
+            throw new Error('Hermes coordination receipt is missing or ambiguous');
+        const receipt = JSON.parse(texts[0] ?? '');
+        const parsed = z.object({ version: z.literal('1.0'), request_digest: z.string().regex(/^[a-f0-9]{64}$/), data: z.record(z.string(), z.unknown()) }).parse(receipt);
+        return parsed;
+    }
+    async send(peerId, prompt, signal, contextId, taskId) {
+        return (await this.sendWithReceipt(peerId, prompt, signal, contextId, taskId)).result;
+    }
+    async getTask(peerId, id, historyLength) {
+        const { client, authorization } = await this.open(peerId);
+        return client.getTask({ tenant: '', id, ...(historyLength === undefined ? {} : { historyLength }) }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' } });
+    }
+    async listTasks(peerId, pageSize = 50, pageToken = '', contextId = '') {
+        if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 100)
+            throw new Error('A2A page size must be 1 to 100');
+        const { client, authorization } = await this.open(peerId);
+        return client.listTasks({ tenant: '', contextId, status: TaskState.TASK_STATE_UNSPECIFIED, pageSize, pageToken, statusTimestampAfter: undefined }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' } });
+    }
+    async cancelTask(peerId, id) {
+        const { client, authorization } = await this.open(peerId);
+        return client.cancelTask({ tenant: '', id, metadata: undefined }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' } });
+    }
+    async extendedCard(peerId) {
+        const { card, client, authorization } = await this.open(peerId);
+        if (!card.capabilities?.extendedAgentCard)
+            throw new Error('A2A peer does not advertise an extended Agent Card');
+        return client.getAgentCard({ serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' } });
+    }
+    async *subscribe(peerId, id, signal) {
+        const { client, authorization } = await this.open(peerId);
+        yield* client.resubscribeTask({ tenant: '', id }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' }, ...(signal ? { signal } : {}) });
+    }
+    async *sendStreaming(peerId, prompt, signal) {
+        if (!prompt.trim() || prompt.length > 16000)
+            throw new Error('A2A prompt must be 1 to 16000 characters');
+        const { client, authorization } = await this.open(peerId);
+        const message = { messageId: randomUUID(), contextId: '', taskId: '', role: Role.ROLE_USER, parts: [{ content: { $case: 'text', value: prompt }, metadata: undefined, filename: '', mediaType: 'text/plain' }], metadata: {}, extensions: [], referenceTaskIds: [] };
+        yield* client.sendMessageStream({ tenant: '', message, configuration: undefined, metadata: undefined }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' }, ...(signal ? { signal } : {}) });
+    }
+    async sendWithReceipt(peerId, prompt, signal, contextId, taskId) {
+        if (!prompt.trim() || prompt.length > 16000)
+            throw new Error('A2A prompt must be 1 to 16000 characters');
+        const { card, client, authorization } = await this.open(peerId);
+        const message = { messageId: randomUUID(), contextId: contextId ?? '', taskId: taskId ?? '', role: Role.ROLE_USER, parts: [{ content: { $case: 'text', value: prompt }, metadata: undefined, filename: '', mediaType: 'text/plain' }], metadata: {}, extensions: [], referenceTaskIds: [] };
+        const registered = this.pushInbox && card.capabilities?.pushNotifications ? this.pushInbox.register(peerId, message.messageId) : undefined;
+        const request = { tenant: '', message, configuration: registered ? {
+                acceptedOutputModes: ['text/plain', 'application/json'], returnImmediately: false,
+                taskPushNotificationConfig: { tenant: '', id: '', taskId: '', url: registered.url, token: registered.token, authentication: undefined }
+            } : undefined, metadata: undefined };
+        try {
+            const result = await client.sendMessage(request, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' }, ...(signal ? { signal } : {}) });
+            if (registered) {
+                if ('id' in result && typeof result.id === 'string')
+                    this.pushInbox?.bind(registered.id, result.id);
+                else
+                    this.pushInbox?.markFailed(registered.id);
+            }
+            return { result, ...(registered ? { outboundId: registered.id } : {}) };
+        }
+        catch (error) {
+            if (registered)
+                this.pushInbox?.markFailed(registered.id);
+            throw error;
+        }
+    }
+}

package/dist/a2a-hermes-alias.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from 'express';
+/** Accepted Hermes slash aliases are translated at the wire edge only. */
+export declare const hermesAlias: RequestHandler;

package/dist/a2a-hermes-alias.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+const aliases = {
+    'message/send': 'SendMessage',
+    'message/stream': 'SendStreamingMessage',
+    'tasks/get': 'GetTask',
+    'tasks/list': 'ListTasks',
+    'tasks/cancel': 'CancelTask',
+    'tasks/subscribe': 'SubscribeToTask',
+    'tasks/pushNotificationConfig/create': 'CreateTaskPushNotificationConfig',
+    'tasks/pushNotificationConfig/set': 'CreateTaskPushNotificationConfig',
+    'tasks/pushNotification/set': 'CreateTaskPushNotificationConfig',
+    'tasks/pushNotificationConfig/get': 'GetTaskPushNotificationConfig',
+    'tasks/pushNotificationConfig/list': 'ListTaskPushNotificationConfigs',
+    'tasks/pushNotificationConfig/delete': 'DeleteTaskPushNotificationConfig'
+};
+const Rpc = z.object({ jsonrpc: z.literal('2.0'), id: z.union([z.string(), z.number()]), method: z.string(), params: z.unknown().optional() }).passthrough();
+const RecordValue = z.record(z.string(), z.unknown());
+/** Accepted Hermes slash aliases are translated at the wire edge only. */
+export const hermesAlias = (req, res, next) => {
+    if (req.header('A2A-Version') !== '1.0') {
+        next();
+        return;
+    }
+    const parsed = Rpc.safeParse(req.body);
+    if (!parsed.success) {
+        next();
+        return;
+    }
+    const method = aliases[parsed.data.method];
+    if (!method) {
+        next();
+        return;
+    }
+    let params = parsed.data.params;
+    if (method === 'CreateTaskPushNotificationConfig') {
+        const outer = RecordValue.safeParse(params);
+        const inner = outer.success ? RecordValue.safeParse(outer.data.pushNotificationConfig ?? outer.data.config) : undefined;
+        if (outer?.success && inner?.success)
+            params = { ...inner.data, taskId: outer.data.taskId, tenant: outer.data.tenant ?? '' };
+    }
+    req.body = { ...parsed.data, method, params };
+    if (parsed.data.method === 'message/send' || parsed.data.method === 'tasks/pushNotificationConfig/delete') {
+        const originalJson = res.json.bind(res);
+        res.json = ((value) => {
+            const response = RecordValue.safeParse(value);
+            if (!response.success || !('result' in response.data))
+                return originalJson(value);
+            if (parsed.data.method === 'tasks/pushNotificationConfig/delete')
+                return originalJson({ ...response.data, result: { deleted: true } });
+            const result = RecordValue.safeParse(response.data.result);
+            if (!result.success)
+                return originalJson(value);
+            return originalJson({ ...response.data, result: result.data.task ?? result.data.message ?? response.data.result });
+        });
+    }
+    next();
+};

package/dist/a2a-idempotency.d.ts

@@ -0,0 +1,13 @@
+import { Message, type SendMessageRequest, type StreamResponse, type Task } from '@a2a-js/sdk';
+import { DefaultRequestHandler, type ServerCallContext } from '@a2a-js/sdk/server';
+import type Database from 'better-sqlite3';
+import type { SqliteA2ATaskStore } from './a2a-store.js';
+/** Binds transport retries to the original task before invoking the executor. */
+export declare class IdempotentA2AHandler extends DefaultRequestHandler {
+    #private;
+    readonly db: Database.Database;
+    readonly durableStore: SqliteA2ATaskStore;
+    constructor(db: Database.Database, durableStore: SqliteA2ATaskStore, ...args: ConstructorParameters<typeof DefaultRequestHandler>);
+    sendMessage(params: SendMessageRequest, context: ServerCallContext): Promise<Task | Message>;
+    sendMessageStream(params: SendMessageRequest, context: ServerCallContext): AsyncGenerator<StreamResponse, void, undefined>;
+}

package/dist/a2a-idempotency.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { Message, TaskState } from '@a2a-js/sdk';
+import { RequestMalformedError, UnsupportedOperationError } from '@a2a-js/sdk/errors';
+import { DefaultRequestHandler } from '@a2a-js/sdk/server';
+import { z } from 'zod';
+const Receipt = z.object({ request_sha256: z.string(), task_id: z.string().nullable() });
+const terminal = new Set([TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_FAILED, TaskState.TASK_STATE_CANCELED, TaskState.TASK_STATE_REJECTED]);
+/** Binds transport retries to the original task before invoking the executor. */
+export class IdempotentA2AHandler extends DefaultRequestHandler {
+    db;
+    durableStore;
+    constructor(db, durableStore, ...args) {
+        super(...args);
+        this.db = db;
+        this.durableStore = durableStore;
+    }
+    #scope(context) {
+        if (!context.user?.isAuthenticated || !context.user.userName)
+            throw new RequestMalformedError('Authenticated A2A caller required');
+        return { tenant: context.tenant ?? '', caller: context.user.userName };
+    }
+    #claim(params, context) {
+        const { tenant, caller } = this.#scope(context);
+        const message = params.message;
+        const messageId = message?.messageId;
+        if (!messageId || messageId.length > 128)
+            throw new RequestMalformedError('A bounded message.messageId is required');
+        if (!message)
+            throw new RequestMalformedError('message is required');
+        const digest = createHash('sha256').update(JSON.stringify({ message: Message.toJSON(message), configuration: params.configuration, metadata: params.metadata })).digest('hex');
+        return this.db.transaction(() => {
+            const inserted = this.db.prepare('INSERT OR IGNORE INTO a2a_request_receipts(tenant,caller,message_id,request_sha256,task_id,created_ms) VALUES (?,?,?,?,NULL,?)')
+                .run(tenant, caller, messageId, digest, Date.now());
+            const row = Receipt.parse(this.db.prepare('SELECT request_sha256,task_id FROM a2a_request_receipts WHERE tenant=? AND caller=? AND message_id=?').get(tenant, caller, messageId));
+            if (row.request_sha256 !== digest)
+                throw new RequestMalformedError('messageId reused with different A2A request content');
+            return { prior: inserted.changes === 0, tenant, caller, messageId };
+        })();
+    }
+    #bind(receipt, taskId) {
+        this.db.prepare('UPDATE a2a_request_receipts SET task_id=? WHERE tenant=? AND caller=? AND message_id=? AND (task_id IS NULL OR task_id=?)')
+            .run(taskId, receipt.tenant, receipt.caller, receipt.messageId, taskId);
+    }
+    async #original(receipt, context) {
+        const until = Date.now() + 3000;
+        while (Date.now() < until) {
+            const row = Receipt.parse(this.db.prepare('SELECT request_sha256,task_id FROM a2a_request_receipts WHERE tenant=? AND caller=? AND message_id=?')
+                .get(receipt.tenant, receipt.caller, receipt.messageId));
+            if (row.task_id) {
+                const task = await this.durableStore.load(row.task_id, context);
+                if (task)
+                    return task;
+            }
+            await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        throw new UnsupportedOperationError('Original A2A admission outcome is unresolved; inspect the receipt before retrying');
+    }
+    async sendMessage(params, context) {
+        if ('hermesTeamReport' in (params.message?.metadata ?? {}))
+            throw new RequestMalformedError('Report intake is not supported by this profile');
+        const receipt = this.#claim(params, context);
+        if (receipt.prior)
+            return this.#original(receipt, context);
+        const result = await super.sendMessage(params, context);
+        if ('id' in result)
+            this.#bind(receipt, result.id);
+        return result;
+    }
+    async *sendMessageStream(params, context) {
+        if ('hermesTeamReport' in (params.message?.metadata ?? {}))
+            throw new UnsupportedOperationError('Report intake requires a terminal SendMessage receipt');
+        const receipt = this.#claim(params, context);
+        if (receipt.prior) {
+            const task = await this.#original(receipt, context);
+            yield { payload: { $case: 'task', value: task } };
+            if (task.status && !terminal.has(task.status.state))
+                yield* this.resubscribe({ tenant: context.tenant ?? '', id: task.id }, context);
+            return;
+        }
+        for await (const event of super.sendMessageStream(params, context)) {
+            if (event.payload?.$case === 'task')
+                this.#bind(receipt, event.payload.value.id);
+            yield event;
+        }
+    }
+}

package/dist/a2a-peers.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+import type { ArdentConfig } from './config.js';
+declare const Peer: z.ZodObject<{
+    id: z.ZodString;
+    url: z.ZodString;
+    token_env: z.ZodOptional<z.ZodString>;
+    inbound_token_env: z.ZodOptional<z.ZodString>;
+    outbound_token_env: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    transport_ports: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    callback_ports: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    allow_private_callbacks: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PeerConfig = z.infer<typeof Peer>;
+export declare function inboundTokenEnv(peer: PeerConfig): string;
+export declare function outboundTokenEnv(peer: PeerConfig): string;
+export declare function parsePeersConfig(text: string): PeerConfig[];
+export declare function readPeersConfig(profileDir: string, config: ArdentConfig): Promise<{
+    text: string;
+    revision: string;
+}>;
+export declare function savePeersConfig(profileDir: string, config: ArdentConfig, text: string, expectedRevision: string): Promise<string>;
+export declare function listPeers(profileDir: string, config: ArdentConfig): Promise<PeerConfig[]>;
+export declare function loadPeers(profileDir: string, config: ArdentConfig, env?: NodeJS.ProcessEnv): Promise<{
+    peers: PeerConfig[];
+    authenticate: (authorization: string | undefined) => string | undefined;
+}>;
+export {};

package/dist/a2a-peers.js

@@ -0,0 +1,108 @@
+import { timingSafeEqual, randomUUID } from 'node:crypto';
+import { readFile, writeFile, open, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+import { revision } from './config.js';
+const envName = z.string().regex(/^[A-Z][A-Z0-9_]*$/);
+const Peer = z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/), url: z.string().url(),
+    token_env: envName.optional(), inbound_token_env: envName.optional(), outbound_token_env: envName.optional(),
+    enabled: z.boolean().default(true), transport_ports: z.array(z.number().int().min(1).max(65535)).default([]),
+    callback_ports: z.array(z.number().int().min(1).max(65535)).default([]), allow_private_callbacks: z.boolean().default(false)
+}).strict().superRefine((peer, context) => {
+    const legacy = Boolean(peer.token_env);
+    const directional = Boolean(peer.inbound_token_env && peer.outbound_token_env);
+    if (legacy === directional || Boolean(peer.inbound_token_env) !== Boolean(peer.outbound_token_env))
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'Use one legacy token_env or both directional token references' });
+    if (directional && peer.inbound_token_env === peer.outbound_token_env)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'Directional token references must differ' });
+});
+const Peers = z.object({ schema_version: z.literal(1), peers: z.array(Peer).max(100) }).strict();
+export function inboundTokenEnv(peer) { return peer.inbound_token_env ?? peer.token_env ?? ''; }
+export function outboundTokenEnv(peer) { return peer.outbound_token_env ?? peer.token_env ?? ''; }
+export function parsePeersConfig(text) {
+    const document = YAML.parseDocument(text, { uniqueKeys: true });
+    if (document.errors.length)
+        throw new Error(`Invalid peer YAML: ${document.errors[0]?.message ?? 'unknown error'}`);
+    const peers = Peers.parse(document.toJS()).peers;
+    if (new Set(peers.map(peer => peer.id)).size !== peers.length)
+        throw new Error('Duplicate A2A peer ID');
+    for (const peer of peers) {
+        const url = new URL(peer.url);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash || url.search)
+            throw new Error(`Invalid A2A peer URL: ${peer.id}`);
+    }
+    return peers;
+}
+export async function readPeersConfig(profileDir, config) {
+    const text = await readFile(join(profileDir, config.a2a.peers_file), 'utf8');
+    parsePeersConfig(text);
+    return { text, revision: revision(text) };
+}
+export async function savePeersConfig(profileDir, config, text, expectedRevision) {
+    if (Buffer.byteLength(text) > 200_000)
+        throw new Error('Peer configuration exceeds size limit');
+    parsePeersConfig(text);
+    const lockPath = join(profileDir, '.peers.write.lock');
+    const lock = await open(lockPath, 'wx', 0o600).catch((error) => {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'EEXIST')
+            throw new Error('Peer configuration edit is already in progress');
+        throw error;
+    });
+    let temporary;
+    try {
+        const current = await readPeersConfig(profileDir, config);
+        if (current.revision !== expectedRevision)
+            throw new Error('Peer configuration revision conflict');
+        temporary = join(profileDir, `.peers.${randomUUID()}.tmp`);
+        await writeFile(temporary, text, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(profileDir, config.a2a.peers_file));
+        temporary = undefined;
+        return revision(text);
+    }
+    finally {
+        if (temporary)
+            await unlink(temporary).catch(() => { });
+        await lock.close();
+        await unlink(lockPath);
+    }
+}
+export async function listPeers(profileDir, config) {
+    return parsePeersConfig(await readFile(join(profileDir, config.a2a.peers_file), 'utf8'));
+}
+export async function loadPeers(profileDir, config, env = process.env) {
+    const peers = await listPeers(profileDir, config);
+    const seen = new Set();
+    const credentials = [];
+    for (const peer of peers) {
+        if (seen.has(peer.id))
+            throw new Error(`Duplicate A2A peer id: ${peer.id}`);
+        seen.add(peer.id);
+        if (!peer.enabled)
+            continue;
+        const url = new URL(peer.url);
+        if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.hash)
+            throw new Error(`Invalid A2A peer URL: ${peer.id}`);
+        const inbound = env[inboundTokenEnv(peer)];
+        const outbound = env[outboundTokenEnv(peer)];
+        if (!inbound || inbound.length < 16)
+            throw new Error(`A2A inbound credential is missing or too short: ${inboundTokenEnv(peer)}`);
+        if (!outbound || outbound.length < 16)
+            throw new Error(`A2A outbound credential is missing or too short: ${outboundTokenEnv(peer)}`);
+        if (peer.inbound_token_env && inbound === outbound)
+            throw new Error(`A2A directional credentials must differ: ${peer.id}`);
+        if (credentials.some(entry => entry.token.length === Buffer.byteLength(inbound) && timingSafeEqual(entry.token, Buffer.from(inbound))))
+            throw new Error(`A2A inbound credential is assigned to multiple peers: ${peer.id}`);
+        credentials.push({ id: peer.id, token: Buffer.from(inbound) });
+    }
+    return { peers, authenticate: authorization => {
+            const bearer = /^Bearer (.+)$/.exec(authorization ?? '')?.[1];
+            if (!bearer)
+                return undefined;
+            const candidate = Buffer.from(bearer);
+            for (const entry of credentials)
+                if (entry.token.length === candidate.length && timingSafeEqual(entry.token, candidate))
+                    return entry.id;
+            return undefined;
+        } };
+}

package/dist/a2a-push-inbox.d.ts

@@ -0,0 +1,22 @@
+import type Database from 'better-sqlite3';
+import { type StreamResponse } from '@a2a-js/sdk';
+import type { PeerConfig } from './a2a-peers.js';
+export declare class A2APushInbox {
+    readonly db: Database.Database;
+    readonly peers: PeerConfig[];
+    readonly publicUrl: string;
+    constructor(db: Database.Database, peers: PeerConfig[], publicUrl: string);
+    register(peerId: string, messageId: string): {
+        id: string;
+        token: string;
+        url: string;
+    };
+    bind(id: string, taskId: string): void;
+    markFailed(id: string): void;
+    accept(peerId: string, token: string | undefined, raw: unknown): {
+        duplicate: boolean;
+        outboundId: string;
+        taskId: string;
+    };
+    events(outboundId: string): StreamResponse[];
+}

package/dist/a2a-push-inbox.js

@@ -0,0 +1,84 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { StreamResponse as StreamCodec } from '@a2a-js/sdk';
+import { z } from 'zod';
+const Outbound = z.object({ id: z.string(), peer_id: z.string(), task_id: z.string().nullable() });
+const Count = z.object({ count: z.number() });
+const EventRow = z.object({ event_json: z.string() });
+function digest(value) { return createHash('sha256').update(value).digest('hex'); }
+export class A2APushInbox {
+    db;
+    peers;
+    publicUrl;
+    constructor(db, peers, publicUrl) {
+        this.db = db;
+        this.peers = peers;
+        this.publicUrl = publicUrl;
+        db.exec(`CREATE TABLE IF NOT EXISTS a2a_outbound_calls (
+      id TEXT PRIMARY KEY, peer_id TEXT NOT NULL, message_id TEXT NOT NULL, task_id TEXT,
+      token_hash TEXT NOT NULL UNIQUE, state TEXT NOT NULL, created_ms INTEGER NOT NULL, updated_ms INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS a2a_inbound_push (
+      id TEXT PRIMARY KEY, outbound_id TEXT NOT NULL, task_id TEXT NOT NULL,
+      event_json TEXT NOT NULL, received_ms INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS a2a_inbound_push_outbound ON a2a_inbound_push(outbound_id,received_ms);`);
+    }
+    register(peerId, messageId) {
+        if (!this.peers.some(peer => peer.enabled && peer.id === peerId))
+            throw new Error('A2A push peer is not configured');
+        if (!messageId || messageId.length > 128)
+            throw new Error('A2A push message ID is invalid');
+        const url = new URL(`/a2a/push/${encodeURIComponent(peerId)}`, this.publicUrl);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+            throw new Error('A2A callback public URL is invalid');
+        const id = randomUUID();
+        const token = randomBytes(32).toString('base64url');
+        const now = Date.now();
+        this.db.prepare('INSERT INTO a2a_outbound_calls(id,peer_id,message_id,task_id,token_hash,state,created_ms,updated_ms) VALUES (?,?,?,NULL,?,?,?,?)')
+            .run(id, peerId, messageId, digest(token), 'pending', now, now);
+        return { id, token, url: url.href };
+    }
+    bind(id, taskId) {
+        const row = this.db.prepare('SELECT id,peer_id,task_id FROM a2a_outbound_calls WHERE id=?').get(id);
+        if (!row)
+            throw new Error('A2A outbound call is missing');
+        const call = Outbound.parse(row);
+        if (!taskId || taskId.length > 256 || (call.task_id && call.task_id !== taskId))
+            throw new Error('A2A callback task mismatch');
+        this.db.prepare("UPDATE a2a_outbound_calls SET task_id=?,state='bound',updated_ms=? WHERE id=?").run(taskId, Date.now(), id);
+    }
+    markFailed(id) { this.db.prepare("UPDATE a2a_outbound_calls SET state='failed',updated_ms=? WHERE id=?").run(Date.now(), id); }
+    accept(peerId, token, raw) {
+        if (!token || token.length > 256 || !this.peers.some(peer => peer.enabled && peer.id === peerId))
+            throw new Error('A2A push is unauthorized');
+        const row = this.db.prepare('SELECT id,peer_id,task_id FROM a2a_outbound_calls WHERE token_hash=?').get(digest(token));
+        if (!row)
+            throw new Error('A2A push is unauthorized');
+        const call = Outbound.parse(row);
+        if (call.peer_id !== peerId)
+            throw new Error('A2A push is unauthorized');
+        const event = StreamCodec.fromJSON(raw);
+        const payload = event.payload;
+        if (!payload)
+            throw new Error('A2A push event is malformed');
+        const taskId = payload.$case === 'task' ? payload.value.id : payload.value.taskId;
+        if (!taskId || taskId.length > 256 || (call.task_id && call.task_id !== taskId))
+            throw new Error('A2A push task does not match the outbound call');
+        const body = JSON.stringify(StreamCodec.toJSON(event));
+        if (Buffer.byteLength(body) > 2 * 1024 * 1024)
+            throw new Error('A2A push event exceeds 2 MiB');
+        const id = digest(`${call.id}\n${body}`);
+        return this.db.transaction(() => {
+            const count = Count.parse(this.db.prepare('SELECT COUNT(*) AS count FROM a2a_inbound_push WHERE outbound_id=?').get(call.id)).count;
+            const prior = this.db.prepare('SELECT 1 FROM a2a_inbound_push WHERE id=?').get(id);
+            if (!prior && count >= 100)
+                throw new Error('A2A push event limit reached');
+            if (!call.task_id)
+                this.db.prepare("UPDATE a2a_outbound_calls SET task_id=?,state='bound',updated_ms=? WHERE id=? AND task_id IS NULL").run(taskId, Date.now(), call.id);
+            const inserted = this.db.prepare('INSERT OR IGNORE INTO a2a_inbound_push(id,outbound_id,task_id,event_json,received_ms) VALUES (?,?,?,?,?)').run(id, call.id, taskId, body, Date.now());
+            return { duplicate: inserted.changes === 0, outboundId: call.id, taskId };
+        })();
+    }
+    events(outboundId) {
+        return this.db.prepare('SELECT event_json FROM a2a_inbound_push WHERE outbound_id=? ORDER BY received_ms,id LIMIT 100').all(outboundId)
+            .map(row => { const parsed = EventRow.parse(row); return StreamCodec.fromJSON(JSON.parse(parsed.event_json)); });
+    }
+}

package/dist/a2a-push.d.ts

@@ -0,0 +1,27 @@
+import type Database from 'better-sqlite3';
+import { type StreamResponse, type Task, type TaskPushNotificationConfig } from '@a2a-js/sdk';
+import type { PushNotificationSender, PushNotificationStore, ServerCallContext, StoredPushNotificationConfig } from '@a2a-js/sdk/server';
+import type { PeerConfig } from './a2a-peers.js';
+export declare class SqliteA2APushStore implements PushNotificationStore {
+    readonly db: Database.Database;
+    readonly peers: PeerConfig[];
+    constructor(db: Database.Database, peers: PeerConfig[]);
+    save(taskId: string, context: ServerCallContext, config: TaskPushNotificationConfig): Promise<void>;
+    load(taskId: string, context: ServerCallContext): Promise<TaskPushNotificationConfig[]>;
+    loadWithMetadata(taskId: string, context: ServerCallContext): Promise<StoredPushNotificationConfig[]>;
+    delete(taskId: string, context: ServerCallContext, configId?: string): Promise<void>;
+    claimDelivery(id: string, taskId: string, context: ServerCallContext, configId: string): boolean;
+    deliveryState(id: string): 'queued' | 'sent' | 'failed' | 'unknown' | undefined;
+    setDelivery(id: string, state: 'sent' | 'failed' | 'unknown', httpStatus?: number, error?: string): void;
+}
+/** Thrown by a `beforeDelivery` hook to refuse a push deterministically (recorded as failed, not unknown). */
+export declare class DeliveryVetoError extends Error {
+}
+export declare class SafeA2APushSender implements PushNotificationSender {
+    #private;
+    readonly store: SqliteA2APushStore;
+    readonly beforeDelivery?: ((taskId: string) => void) | undefined;
+    constructor(store: SqliteA2APushStore, beforeDelivery?: ((taskId: string) => void) | undefined);
+    drain(): Promise<void>;
+    send(event: StreamResponse, context: ServerCallContext, _task?: Task): Promise<void>;
+}