@hivemagnus/ardent 0.0.0-stage → 1.0.1

package/dist/a2a-push.js

@@ -0,0 +1,188 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
+import { StreamResponse as StreamCodec, TaskPushNotificationConfig as PushCodec } from '@a2a-js/sdk';
+import { RequestMalformedError } from '@a2a-js/sdk/errors';
+import { z } from 'zod';
+const Row = z.object({ config_json: z.string(), wire_version: z.string() });
+const Delivery = z.object({ state: z.enum(['queued', 'sent', 'failed', 'unknown']) });
+function scope(context) {
+    const user = context.user;
+    if (!user?.isAuthenticated || !user.userName)
+        throw new Error('Authenticated A2A caller required');
+    return { tenant: context.tenant ?? '', caller: user.userName };
+}
+function validatedUrl(raw, peer) {
+    if (raw.length > 2048)
+        throw new RequestMalformedError('A2A callback URL is too long');
+    let callback;
+    try {
+        callback = new URL(raw);
+    }
+    catch {
+        throw new RequestMalformedError('A2A callback URL is invalid');
+    }
+    const home = new URL(peer.url);
+    const port = Number(callback.port || (callback.protocol === 'https:' ? 443 : 80));
+    const homePort = Number(home.port || (home.protocol === 'https:' ? 443 : 80));
+    if (!['http:', 'https:'].includes(callback.protocol) || callback.username || callback.password || callback.hash || callback.search ||
+        callback.hostname !== home.hostname || !new Set([homePort, ...peer.callback_ports]).has(port))
+        throw new RequestMalformedError('A2A callback URL is outside the configured peer destination');
+    if (callback.protocol === 'http:' && (!peer.allow_private_callbacks || !isIP(callback.hostname)))
+        throw new RequestMalformedError('HTTP callback requires an explicit trusted IP peer');
+    if (home.protocol === 'https:' && callback.protocol !== 'https:')
+        throw new RequestMalformedError('A2A callback cannot downgrade a secure peer');
+    return callback.href;
+}
+export class SqliteA2APushStore {
+    db;
+    peers;
+    constructor(db, peers) {
+        this.db = db;
+        this.peers = peers;
+        db.exec(`CREATE TABLE IF NOT EXISTS a2a_push_configs (
+      task_id TEXT NOT NULL, tenant TEXT NOT NULL, caller TEXT NOT NULL, id TEXT NOT NULL,
+      config_json TEXT NOT NULL, wire_version TEXT NOT NULL, created_ms INTEGER NOT NULL,
+      PRIMARY KEY(task_id,tenant,caller,id));
+      CREATE TABLE IF NOT EXISTS a2a_push_deliveries (
+      id TEXT PRIMARY KEY, task_id TEXT NOT NULL, tenant TEXT NOT NULL, caller TEXT NOT NULL,
+      config_id TEXT NOT NULL, state TEXT NOT NULL, http_status INTEGER, error TEXT,
+      created_ms INTEGER NOT NULL, updated_ms INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS a2a_push_delivery_task ON a2a_push_deliveries(task_id,tenant,caller);`);
+        const columns = z.array(z.object({ name: z.string() })).parse(db.pragma('table_info(a2a_push_deliveries)'));
+        if (!columns.some(column => column.name === 'error'))
+            db.exec('ALTER TABLE a2a_push_deliveries ADD COLUMN error TEXT');
+        db.prepare("UPDATE a2a_push_deliveries SET state='unknown',updated_ms=? WHERE state='queued'").run(Date.now());
+    }
+    async save(taskId, context, config) {
+        const owner = scope(context);
+        const peer = this.peers.find(item => item.id === owner.caller && item.enabled);
+        if (!peer)
+            throw new RequestMalformedError('A2A callback caller is not a configured peer');
+        if (config.taskId !== taskId || (config.tenant && config.tenant !== owner.tenant))
+            throw new RequestMalformedError('A2A callback task or tenant mismatch');
+        const url = validatedUrl(config.url, peer);
+        if (config.token.length > 512 || (config.authentication && (config.authentication.scheme.toLowerCase() !== 'bearer' || config.authentication.credentials.length > 512)))
+            throw new RequestMalformedError('A2A callback authentication is unsupported');
+        if (!config.id)
+            config.id = randomUUID();
+        if (!/^[A-Za-z0-9._-]{1,128}$/.test(config.id))
+            throw new RequestMalformedError('A2A callback ID is invalid');
+        const count = z.object({ count: z.number() }).parse(this.db.prepare('SELECT COUNT(*) AS count FROM a2a_push_configs WHERE task_id=? AND tenant=? AND caller=?').get(taskId, owner.tenant, owner.caller)).count;
+        const exists = this.db.prepare('SELECT 1 FROM a2a_push_configs WHERE task_id=? AND tenant=? AND caller=? AND id=?').get(taskId, owner.tenant, owner.caller, config.id);
+        if (!exists && count >= 5)
+            throw new RequestMalformedError('A2A callback limit reached');
+        const stored = PushCodec.toJSON({ ...config, url, tenant: owner.tenant });
+        this.db.prepare(`INSERT INTO a2a_push_configs(task_id,tenant,caller,id,config_json,wire_version,created_ms) VALUES (?,?,?,?,?,?,?)
+      ON CONFLICT(task_id,tenant,caller,id) DO UPDATE SET config_json=excluded.config_json,wire_version=excluded.wire_version`)
+            .run(taskId, owner.tenant, owner.caller, config.id, JSON.stringify(stored), context.requestedVersion || '1.0', Date.now());
+    }
+    async load(taskId, context) {
+        return (await this.loadWithMetadata(taskId, context)).map(item => item.config);
+    }
+    async loadWithMetadata(taskId, context) {
+        const owner = scope(context);
+        return this.db.prepare('SELECT config_json,wire_version FROM a2a_push_configs WHERE task_id=? AND tenant=? AND caller=? ORDER BY created_ms,id')
+            .all(taskId, owner.tenant, owner.caller).map(row => {
+            const parsed = Row.parse(row);
+            const value = JSON.parse(parsed.config_json);
+            return { config: PushCodec.fromJSON(value), wireVersion: parsed.wire_version };
+        });
+    }
+    async delete(taskId, context, configId) {
+        const owner = scope(context);
+        if (configId)
+            this.db.prepare('DELETE FROM a2a_push_configs WHERE task_id=? AND tenant=? AND caller=? AND id=?').run(taskId, owner.tenant, owner.caller, configId);
+        else
+            this.db.prepare('DELETE FROM a2a_push_configs WHERE task_id=? AND tenant=? AND caller=?').run(taskId, owner.tenant, owner.caller);
+    }
+    claimDelivery(id, taskId, context, configId) {
+        const owner = scope(context);
+        const result = this.db.prepare("INSERT OR IGNORE INTO a2a_push_deliveries(id,task_id,tenant,caller,config_id,state,http_status,error,created_ms,updated_ms) VALUES (?,?,?,?,?,'queued',NULL,NULL,?,?)")
+            .run(id, taskId, owner.tenant, owner.caller, configId, Date.now(), Date.now());
+        return result.changes === 1;
+    }
+    deliveryState(id) {
+        const row = this.db.prepare('SELECT state FROM a2a_push_deliveries WHERE id=?').get(id);
+        return row ? Delivery.parse(row).state : undefined;
+    }
+    setDelivery(id, state, httpStatus, error) {
+        this.db.prepare('UPDATE a2a_push_deliveries SET state=?,http_status=?,error=?,updated_ms=? WHERE id=?').run(state, httpStatus ?? null, error?.slice(0, 300) ?? null, Date.now(), id);
+    }
+}
+/** Thrown by a `beforeDelivery` hook to refuse a push deterministically (recorded as failed, not unknown). */
+export class DeliveryVetoError extends Error {
+}
+export class SafeA2APushSender {
+    store;
+    beforeDelivery;
+    #chains = new Map();
+    constructor(store, beforeDelivery) {
+        this.store = store;
+        this.beforeDelivery = beforeDelivery;
+    }
+    async drain() {
+        for (let pass = 0; pass < 3; pass++) {
+            await Promise.allSettled([...this.#chains.values()]);
+            await new Promise(resolve => setImmediate(resolve));
+            if (!this.#chains.size)
+                return;
+        }
+        throw new Error('A2A push delivery remains unsettled');
+    }
+    async send(event, context, _task) {
+        const payload = event.payload;
+        if (!payload)
+            throw new Error('A2A push event is missing payload');
+        const taskId = payload.$case === 'task' ? payload.value.id : payload.value.taskId;
+        if (!taskId)
+            return;
+        const prior = this.#chains.get(taskId) ?? Promise.resolve();
+        const next = prior.catch(() => { }).then(async () => {
+            const body = JSON.stringify(StreamCodec.toJSON(event));
+            if (Buffer.byteLength(body) > 2 * 1024 * 1024)
+                return;
+            const owner = scope(context);
+            const configs = await this.store.loadWithMetadata(taskId, context);
+            for (const { config, wireVersion } of configs) {
+                if (wireVersion !== '1.0')
+                    continue;
+                const id = createHash('sha256').update(JSON.stringify([owner.tenant, owner.caller, taskId, config.id, body])).digest('hex');
+                if (!this.store.claimDelivery(id, taskId, context, config.id))
+                    continue;
+                const headers = { 'Content-Type': 'application/a2a+json', 'A2A-Version': '1.0' };
+                if (config.authentication)
+                    headers['Authorization'] = `${config.authentication.scheme} ${config.authentication.credentials}`;
+                else if (config.token)
+                    headers['X-A2A-Notification-Token'] = config.token;
+                try {
+                    for (let attempt = 0; attempt < 3; attempt++) {
+                        this.beforeDelivery?.(taskId);
+                        const response = await fetch(config.url, { method: 'POST', headers, body, redirect: 'error', signal: AbortSignal.timeout(5000) });
+                        if (response.ok) {
+                            this.store.setDelivery(id, 'sent', response.status);
+                            break;
+                        }
+                        if (response.status === 429 && attempt < 2) {
+                            const seconds = Number(response.headers.get('retry-after') ?? '1');
+                            await new Promise(resolve => setTimeout(resolve, Number.isFinite(seconds) ? Math.min(5, Math.max(1, seconds)) * 1000 : 1000));
+                            continue;
+                        }
+                        this.store.setDelivery(id, response.status >= 500 ? 'unknown' : 'failed', response.status);
+                        break;
+                    }
+                }
+                catch (error) {
+                    this.store.setDelivery(id, error instanceof DeliveryVetoError ? 'failed' : 'unknown', undefined, error instanceof Error ? error.message : 'Callback outcome unknown');
+                }
+            }
+        });
+        this.#chains.set(taskId, next);
+        try {
+            await next;
+        }
+        finally {
+            if (this.#chains.get(taskId) === next)
+                this.#chains.delete(taskId);
+        }
+    }
+}

package/dist/a2a-server.d.ts

@@ -0,0 +1,37 @@
+import { type Express } from 'express';
+import { Server as GrpcServer } from '@grpc/grpc-js';
+import { AgentCard } from '@a2a-js/sdk';
+import type { ArdentConfig } from './config.js';
+import { SafeA2APushSender } from './a2a-push.js';
+import { A2APushInbox } from './a2a-push-inbox.js';
+import type { ArdentRuntime } from './runtime.js';
+import { hermesTeamCard } from './hermes-compat.js';
+export type A2ASurface = {
+    app: Express;
+    grpcServer: GrpcServer;
+    card: AgentCard;
+    grpcAddress: string;
+    grpcListenPort: number;
+    pushSender: SafeA2APushSender;
+    pushInbox: A2APushInbox;
+};
+/** Refresh only discovery freshness; the reviewed runtime identity and digests stay pinned to this process. */
+export declare function freshHermesTeamCard(source: Awaited<ReturnType<typeof hermesTeamCard>>, now?: number): {
+    metadata: {
+        hermesTeam: {
+            discovery: {
+                observedAt: number;
+                expiresAt: number;
+            };
+        };
+    };
+    description: string;
+    skills: Array<{
+        id: string;
+        name: string;
+        description: string;
+        tags: string[];
+    }>;
+};
+export declare function createA2ASurface(runtime: ArdentRuntime, config: ArdentConfig, env?: NodeJS.ProcessEnv): Promise<A2ASurface>;
+export declare function startA2AGrpc(surface: A2ASurface, host?: string): Promise<void>;

package/dist/a2a-server.js

@@ -0,0 +1,186 @@
+import express from 'express';
+import { z } from 'zod';
+import { Server as GrpcServer, ServerCredentials } from '@grpc/grpc-js';
+import { A2A_PROTOCOL_VERSION, AGENT_CARD_PATH, AgentCard } from '@a2a-js/sdk';
+import { jsonRpcHandler, restHandler } from '@a2a-js/sdk/server/express';
+import { legacyAgentCardRouter } from '@a2a-js/sdk/compat/v0_3/server/express';
+import { A2AService, grpcService } from '@a2a-js/sdk/server/grpc';
+import { resolveReference } from './config.js';
+import { loadPeers } from './a2a-peers.js';
+import { ArdentA2AExecutor } from './a2a.js';
+import { SqliteA2ATaskStore } from './a2a-store.js';
+import { SafeA2APushSender, SqliteA2APushStore } from './a2a-push.js';
+import { A2APushInbox } from './a2a-push-inbox.js';
+import { hermesTeamCard } from './hermes-compat.js';
+import { IdempotentA2AHandler } from './a2a-idempotency.js';
+import { hermesAlias } from './a2a-hermes-alias.js';
+import { ARDENT_VERSION } from './version.js';
+import { TeamArtifacts } from './team-artifacts.js';
+/** Refresh only discovery freshness; the reviewed runtime identity and digests stay pinned to this process. */
+export function freshHermesTeamCard(source, now = Date.now()) {
+    const team = z.object({ discovery: z.object({ observedAt: z.number().int(), expiresAt: z.number().int() }).passthrough() })
+        .passthrough().parse(source.metadata.hermesTeam);
+    if (!Number.isSafeInteger(now) || now < 0)
+        throw new Error('Team-card clock is invalid');
+    const observedAt = Math.floor(now / 1000);
+    return { ...source, metadata: { hermesTeam: { ...team,
+                discovery: { ...team.discovery, observedAt, expiresAt: observedAt + 300 } } } };
+}
+export async function createA2ASurface(runtime, config, env = process.env) {
+    const publicAddress = resolveReference(config.a2a.public_url, env);
+    if (!publicAddress)
+        throw new Error('A2A public URL is unconfigured');
+    const publicUrl = new URL(publicAddress);
+    if (!['http:', 'https:'].includes(publicUrl.protocol) || publicUrl.username || publicUrl.password)
+        throw new Error('Invalid A2A public URL');
+    const { authenticate, peers } = await loadPeers(runtime.profileDir, config, env);
+    const teamCard = config.a2a.hermes_compat ? await hermesTeamCard(runtime, config) : undefined;
+    const grpcPort = Number(publicUrl.port || (publicUrl.protocol === 'https:' ? 443 : 80)) + 1;
+    if (grpcPort > 65535)
+        throw new Error('A2A gRPC port is unavailable');
+    const listenPort = config.a2a.listen_port ?? Number(publicUrl.port || (publicUrl.protocol === 'https:' ? 443 : 80));
+    if (listenPort >= 65535)
+        throw new Error('A2A local gRPC port is unavailable');
+    const grpcAddress = `${publicUrl.hostname}:${grpcPort}`;
+    const jsonRpcUrl = new URL('/a2a/jsonrpc', publicUrl).href;
+    const restUrl = new URL('/a2a/rest', publicUrl).href;
+    const interfaces = [];
+    for (const binding of config.a2a.bindings) {
+        if (binding === 'jsonrpc')
+            interfaces.push({ url: jsonRpcUrl, protocolBinding: 'JSONRPC', protocolVersion: A2A_PROTOCOL_VERSION, tenant: '' });
+        else if (binding === 'http-json')
+            interfaces.push({ url: restUrl, protocolBinding: 'HTTP+JSON', protocolVersion: A2A_PROTOCOL_VERSION, tenant: '' });
+        else
+            interfaces.push({ url: grpcAddress, protocolBinding: 'GRPC', protocolVersion: A2A_PROTOCOL_VERSION, tenant: '' });
+    }
+    if (config.a2a.bindings.includes('jsonrpc'))
+        interfaces.push({ url: jsonRpcUrl, protocolBinding: 'JSONRPC', protocolVersion: '0.3', tenant: '' });
+    const bearerRequirement = [{ schemes: { Bearer: { list: [] } } }];
+    const skill = config.a2a.skill ?? { id: 'general-assistance', name: 'General assistance',
+        description: 'Answer bounded tasks with the tools this profile enables', tags: ['assistant'], example: 'Summarize the latest update on this topic' };
+    const card = {
+        name: config.name,
+        description: teamCard?.description ?? skill.description,
+        supportedInterfaces: interfaces,
+        provider: { organization: 'Magnus', url: 'https://github.com/ChefTaco/magnus' },
+        version: ARDENT_VERSION,
+        capabilities: { streaming: true, pushNotifications: true, extendedAgentCard: true, extensions: [] },
+        securitySchemes: { Bearer: { scheme: { $case: 'httpAuthSecurityScheme', value: { description: 'Peer bearer token', scheme: 'bearer', bearerFormat: '' } } } },
+        securityRequirements: bearerRequirement,
+        defaultInputModes: ['text/plain', 'text/markdown', 'application/json'],
+        defaultOutputModes: ['text/plain', 'application/json'],
+        skills: [{ id: skill.id, name: skill.name, description: skill.description, tags: [...skill.tags], examples: skill.example ? [skill.example] : [], inputModes: ['text/plain'], outputModes: ['text/plain', 'application/json'], securityRequirements: bearerRequirement }],
+        documentationUrl: '', signatures: []
+    };
+    const pushStore = new SqliteA2APushStore(runtime.store.db, peers);
+    const pushSender = new SafeA2APushSender(pushStore);
+    const pushInbox = new A2APushInbox(runtime.store.db, peers, publicAddress);
+    const artifactTransfers = new TeamArtifacts(runtime, config, env);
+    const taskStore = new SqliteA2ATaskStore(runtime.store.db);
+    const handler = new IdempotentA2AHandler(runtime.store.db, taskStore, card, taskStore, new ArdentA2AExecutor(runtime, env), undefined, pushStore, pushSender, async (context) => {
+        const peerId = context.user?.userName;
+        if (!context.user?.isAuthenticated || !peerId || !peers.some(peer => peer.id === peerId && peer.enabled))
+            throw new Error('Authenticated configured peer required');
+        return {
+            ...card,
+            description: `${card.description}. Authenticated peer ${peerId} may submit bounded ${config.profile} tasks.`,
+            skills: [...card.skills, { id: `${config.profile}-team-result`, name: 'Validated team result', description: 'Return a mission-bound specialist result for an authenticated team envelope', tags: ['team', config.profile], examples: ['Return a scoped result with evidence'], inputModes: ['text/plain', 'application/json'], outputModes: ['application/json'], securityRequirements: bearerRequirement }]
+        };
+    });
+    const app = express();
+    app.get('/team/artifacts/:id', async (req, res) => {
+        const peer = authenticate(req.header('Authorization'));
+        if (!peer) {
+            res.status(401).json({ error: 'Authenticated A2A peer required' });
+            return;
+        }
+        try {
+            const result = await artifactTransfers.serve(peer, req.params.id ?? '', String(req.query.context ?? ''));
+            if (result.status !== 200 || !result.bytes || !result.descriptor) {
+                res.status(result.status).json({ error: result.status === 410 ? 'Artifact export revoked or expired' : 'Artifact unavailable' });
+                return;
+            }
+            const descriptor = result.descriptor;
+            res.status(200).set({ 'Content-Type': descriptor.mime, 'Content-Length': String(result.bytes.byteLength),
+                'X-Artifact-Name': encodeURIComponent(descriptor.name), 'X-Hermes-Task-Id': descriptor.producer_task_id,
+                'X-Hermes-Artifact-Manifest': Buffer.from(JSON.stringify(descriptor.artifact_manifest)).toString('base64url'),
+                'X-Content-Type-Options': 'nosniff', 'Cache-Control': 'private, no-store' }).end(Buffer.from(result.bytes));
+        }
+        catch {
+            res.status(503).json({ error: 'Artifact export state is unavailable' });
+        }
+    });
+    app.post('/a2a/push/:peerId', express.json({ limit: '2mb', type: ['application/json', 'application/a2a+json'] }), (req, res) => {
+        try {
+            const result = pushInbox.accept(req.params.peerId ?? '', req.header('X-A2A-Notification-Token'), req.body);
+            res.status(202).json({ accepted: true, duplicate: result.duplicate });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Invalid A2A push';
+            res.status(/unauthorized/i.test(message) ? 401 : /exceeds/i.test(message) ? 413 : 400).json({ error: message.slice(0, 200) });
+        }
+    });
+    // Serve the explicit v0.3 compatibility card only for legacy-version
+    // discovery. The SDK's v1 Express card helper stringifies internal oneofs,
+    // so the canonical v1 card goes through the generated protobuf JSON codec.
+    app.get(`/${AGENT_CARD_PATH}`, (req, res, next) => {
+        if (req.header('A2A-Version')?.startsWith('0.3')) {
+            next();
+            return;
+        }
+        const encoded = AgentCard.toJSON(card);
+        if (!encoded || typeof encoded !== 'object' || Array.isArray(encoded))
+            throw new Error('A2A Agent Card encoding failed');
+        res.json(encoded);
+    });
+    app.use(`/${AGENT_CARD_PATH}`, legacyAgentCardRouter({ agentCardProvider: handler }));
+    if (teamCard)
+        app.get('/.well-known/hermes-team-card.json', (req, res) => {
+            if (!authenticate(req.header('Authorization'))) {
+                res.status(401).json({ error: 'Authenticated configured peer required' });
+                return;
+            }
+            const encoded = AgentCard.toJSON(card);
+            if (!encoded || typeof encoded !== 'object' || Array.isArray(encoded))
+                throw new Error('A2A Agent Card encoding failed');
+            res.set('Cache-Control', 'private, no-store').json({ ...encoded, ...freshHermesTeamCard(teamCard) });
+        });
+    const auth = (req, res, next) => {
+        if (!authenticate(req.header('Authorization'))) {
+            res.status(401).json({ error: 'Authenticated A2A peer required' });
+            return;
+        }
+        next();
+    };
+    const userBuilder = async (req) => {
+        const id = authenticate(req.header('Authorization'));
+        return { isAuthenticated: Boolean(id), userName: id ?? '' };
+    };
+    const aliases = config.a2a.hermes_compat ? hermesAlias : (_req, _res, next) => next();
+    if (config.a2a.bindings.includes('jsonrpc'))
+        app.use('/a2a/jsonrpc', auth, express.json({ limit: '1mb' }), aliases, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
+    if (config.a2a.bindings.includes('http-json'))
+        app.use('/a2a/rest', auth, restHandler({ requestHandler: handler, userBuilder }));
+    // Hermes Agent's team router posts to the peer origin itself. Keep that
+    // optional compatibility route separate from the advertised v1 interface.
+    if (config.a2a.hermes_compat && config.a2a.bindings.includes('jsonrpc')) {
+        const rootCompat = express.Router();
+        rootCompat.use((req, _res, next) => { if (!req.header('A2A-Version'))
+            req.headers['a2a-version'] = '1.0'; next(); });
+        rootCompat.use(auth, express.json({ limit: '1mb' }), hermesAlias, jsonRpcHandler({ requestHandler: handler, userBuilder, legacyCompat: { enabled: true } }));
+        app.use('/', (req, res, next) => req.path === '/' ? rootCompat(req, res, next) : next());
+    }
+    const grpcServer = new GrpcServer();
+    if (config.a2a.bindings.includes('grpc'))
+        grpcServer.addService(A2AService, grpcService({ requestHandler: handler, userBuilder: async (call) => {
+                const raw = call.metadata.get('authorization')[0];
+                const id = authenticate(typeof raw === 'string' ? raw : undefined);
+                return { isAuthenticated: Boolean(id), userName: id ?? '' };
+            } }));
+    return { app, grpcServer, card, grpcAddress, grpcListenPort: listenPort + 1, pushSender, pushInbox };
+}
+export async function startA2AGrpc(surface, host = '127.0.0.1') {
+    await new Promise((resolve, reject) => {
+        surface.grpcServer.bindAsync(`${host}:${surface.grpcListenPort}`, ServerCredentials.createInsecure(), error => error ? reject(error) : resolve());
+    });
+}

package/dist/a2a-store.d.ts

@@ -0,0 +1,10 @@
+import { type ListTasksRequest, type ListTasksResponse, type Task } from '@a2a-js/sdk';
+import type { ServerCallContext, TaskStore as A2ATaskStore } from '@a2a-js/sdk/server';
+import type Database from 'better-sqlite3';
+export declare class SqliteA2ATaskStore implements A2ATaskStore {
+    readonly db: Database.Database;
+    constructor(db: Database.Database);
+    save(task: Task, context: ServerCallContext): Promise<void>;
+    load(taskId: string, context: ServerCallContext): Promise<Task | undefined>;
+    list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
+}

package/dist/a2a-store.js

@@ -0,0 +1,122 @@
+import { Task as TaskCodec, TaskState } from '@a2a-js/sdk';
+import { z } from 'zod';
+const StoredTask = z.object({ id: z.string().min(1), contextId: z.string(), status: z.object({ state: z.string(), timestamp: z.string().optional() }).nullable().optional(), artifacts: z.array(z.unknown()).optional(), history: z.array(z.unknown()).optional() }).passthrough();
+const Row = z.object({ task_json: z.string() });
+const Cursor = z.object({ timestamp: z.string(), id: z.string() });
+function owner(context) {
+    const user = context.user;
+    if (!user?.isAuthenticated || !user.userName)
+        throw new Error('Authenticated A2A caller required');
+    return { tenant: context.tenant ?? '', caller: user.userName };
+}
+function readTask(json) {
+    const raw = JSON.parse(json);
+    StoredTask.parse(raw);
+    return TaskCodec.fromJSON(raw);
+}
+export class SqliteA2ATaskStore {
+    db;
+    constructor(db) {
+        this.db = db;
+        db.exec(`CREATE TABLE IF NOT EXISTS a2a_tasks (
+      id TEXT PRIMARY KEY, tenant TEXT NOT NULL, caller TEXT NOT NULL,
+      context_id TEXT NOT NULL, status TEXT NOT NULL, status_timestamp TEXT NOT NULL,
+      task_json TEXT NOT NULL, updated_ms INTEGER NOT NULL);
+      CREATE INDEX IF NOT EXISTS a2a_tasks_scope ON a2a_tasks(tenant, caller, status_timestamp DESC, id DESC);
+      CREATE INDEX IF NOT EXISTS a2a_tasks_scope_context ON a2a_tasks(tenant, caller, context_id, status_timestamp DESC, id DESC);`);
+        db.exec(`CREATE TABLE IF NOT EXISTS a2a_request_receipts (
+      tenant TEXT NOT NULL, caller TEXT NOT NULL, message_id TEXT NOT NULL,
+      request_sha256 TEXT NOT NULL, task_id TEXT, created_ms INTEGER NOT NULL,
+      PRIMARY KEY(tenant, caller, message_id));`);
+    }
+    async save(task, context) {
+        const scope = owner(context);
+        if (!task.id || !task.contextId)
+            throw new Error('A2A task id/context required');
+        const prior = this.db.prepare('SELECT tenant, caller FROM a2a_tasks WHERE id=?').get(task.id);
+        if (prior) {
+            const bound = z.object({ tenant: z.string(), caller: z.string() }).parse(prior);
+            if (bound.tenant !== scope.tenant || bound.caller !== scope.caller)
+                throw new Error('A2A task owner mismatch');
+        }
+        this.db.prepare(`INSERT INTO a2a_tasks(id,tenant,caller,context_id,status,status_timestamp,task_json,updated_ms)
+      VALUES (?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET context_id=excluded.context_id,status=excluded.status,
+      status_timestamp=excluded.status_timestamp,task_json=excluded.task_json,updated_ms=excluded.updated_ms`)
+            .run(task.id, scope.tenant, scope.caller, task.contextId, task.status?.state ?? TaskState.TASK_STATE_UNSPECIFIED, task.status?.timestamp ?? '', JSON.stringify(TaskCodec.toJSON(task)), Date.now());
+        const newest = task.history?.at(-1)?.messageId;
+        if (newest)
+            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(task.id, scope.tenant, scope.caller, newest, task.id);
+    }
+    async load(taskId, context) {
+        const scope = owner(context);
+        const row = this.db.prepare('SELECT task_json FROM a2a_tasks WHERE id=? AND tenant=? AND caller=?').get(taskId, scope.tenant, scope.caller);
+        return row ? readTask(Row.parse(row).task_json) : undefined;
+    }
+    async list(params, context) {
+        const scope = owner(context);
+        const size = params.pageSize ?? 50;
+        if (!Number.isInteger(size) || size < 1 || size > 100)
+            throw new Error('Invalid A2A pageSize');
+        // The context and timestamp columns are written from the same task as
+        // task_json, so these SQL filters, ordering and cursor match the former
+        // in-memory evaluation. The status column's encoding depends on the SQLite
+        // driver's number binding, so a status filter is still applied to parsed tasks.
+        const where = ['tenant=?', 'caller=?'];
+        const values = [scope.tenant, scope.caller];
+        if (params.contextId) {
+            where.push('context_id=?');
+            values.push(params.contextId);
+        }
+        if (params.statusTimestampAfter) {
+            where.push("status_timestamp!='' AND status_timestamp>?");
+            values.push(params.statusTimestampAfter);
+        }
+        const filter = where.join(' AND ');
+        let cursor;
+        if (params.pageToken) {
+            try {
+                cursor = Cursor.parse(JSON.parse(Buffer.from(params.pageToken, 'base64url').toString('utf8')));
+            }
+            catch {
+                throw new Error('Invalid A2A pageToken');
+            }
+        }
+        let page;
+        let total;
+        let more;
+        if (params.status !== undefined && params.status !== TaskState.TASK_STATE_UNSPECIFIED) {
+            const filtered = this.db.prepare(`SELECT task_json FROM a2a_tasks WHERE ${filter} ORDER BY status_timestamp DESC,id DESC`).all(...values)
+                .map(row => readTask(Row.parse(row).task_json)).filter(task => task.status?.state === params.status);
+            let start = 0;
+            if (cursor) {
+                const found = filtered.findIndex(task => task.id === cursor.id && (task.status?.timestamp ?? '') === cursor.timestamp);
+                if (found < 0)
+                    throw new Error('A2A page cursor was not found');
+                start = found + 1;
+            }
+            page = filtered.slice(start, start + size);
+            total = filtered.length;
+            more = start + size < filtered.length;
+        }
+        else {
+            total = z.object({ total: z.number().int() }).parse(this.db.prepare(`SELECT count(*) AS total FROM a2a_tasks WHERE ${filter}`).get(...values)).total;
+            let after = '';
+            const afterValues = [];
+            if (cursor) {
+                if (!this.db.prepare(`SELECT 1 FROM a2a_tasks WHERE ${filter} AND id=? AND status_timestamp=?`).get(...values, cursor.id, cursor.timestamp))
+                    throw new Error('A2A page cursor was not found');
+                after = ' AND (status_timestamp<? OR (status_timestamp=? AND id<?))';
+                afterValues.push(cursor.timestamp, cursor.timestamp, cursor.id);
+            }
+            const rows = this.db.prepare(`SELECT task_json FROM a2a_tasks WHERE ${filter}${after} ORDER BY status_timestamp DESC,id DESC LIMIT ?`)
+                .all(...values, ...afterValues, size + 1).map(row => readTask(Row.parse(row).task_json));
+            page = rows.slice(0, size);
+            more = rows.length > size;
+        }
+        const last = page.at(-1);
+        const nextPageToken = last && more
+            ? Buffer.from(JSON.stringify({ timestamp: last.status?.timestamp ?? '', id: last.id })).toString('base64url') : '';
+        return { tasks: page.map(task => params.includeArtifacts ? task : { ...task, artifacts: [] }), nextPageToken, pageSize: size, totalSize: total };
+    }
+}

package/dist/a2a.d.ts

@@ -0,0 +1,19 @@
+import { type AgentExecutor, type ExecutionEventBus, type RequestContext } from '@a2a-js/sdk/server';
+import type { ArdentRuntime } from './runtime.js';
+/** An extracted article is an owner read when its connector result binds the
+ * exact request URL, source URL, retrieval time, and content digest. It remains
+ * unverified reporting, but its URL can support a read-only team check. */
+export declare function observedOwnerSourceReference(name: string, value: Record<string, unknown>): string | null;
+export declare function observedOwnerToolResult(detail: unknown): {
+    name: string;
+    value: Record<string, unknown>;
+    reference: string | null;
+} | null;
+export declare class ArdentA2AExecutor implements AgentExecutor {
+    #private;
+    readonly runtime: ArdentRuntime;
+    readonly env: NodeJS.ProcessEnv;
+    constructor(runtime: ArdentRuntime, env?: NodeJS.ProcessEnv);
+    execute(request: RequestContext, bus: ExecutionEventBus): Promise<void>;
+    cancelTask(taskId: string, bus: ExecutionEventBus): Promise<void>;
+}