@renseiai/agentfactory 0.8.0

package/dist/src/providers/a2a-auth.js

@@ -0,0 +1,188 @@
+/**
+ * A2A Authentication Utilities
+ *
+ * Client-side: resolve credentials from env vars and build HTTP auth headers
+ * for outbound requests to remote A2A agents.
+ *
+ * Server-side: validate inbound A2A request auth using timing-safe comparison,
+ * following the same pattern as worker-auth.ts.
+ */
+import crypto from 'crypto';
+// ---------------------------------------------------------------------------
+// Client-side: credential resolution
+// ---------------------------------------------------------------------------
+/**
+ * Normalise a hostname into an env-var suffix.
+ *
+ * - Uppercases
+ * - Replaces dots and hyphens with underscores
+ *
+ * Example: "spring-agent.example.com" -> "SPRING_AGENT_EXAMPLE_COM"
+ */
+function hostnameToEnvSuffix(hostname) {
+    return hostname.toUpperCase().replace(/[.\-]/g, '_');
+}
+/**
+ * Resolve credentials from environment variables for outbound A2A requests.
+ *
+ * Resolution order:
+ * 1. If agentUrl is provided, try host-specific env vars first:
+ *    - A2A_API_KEY_{HOSTNAME}
+ *    - A2A_BEARER_TOKEN_{HOSTNAME}
+ * 2. Fall back to generic env vars:
+ *    - A2A_API_KEY
+ *    - A2A_BEARER_TOKEN
+ *
+ * @param env - Environment variable map (e.g. process.env)
+ * @param agentUrl - Optional URL of the remote agent for host-specific lookup
+ * @returns Resolved credentials (may be empty if no env vars are set)
+ */
+export function resolveA2aCredentials(env, agentUrl) {
+    const creds = {};
+    let hostSuffix;
+    if (agentUrl) {
+        try {
+            const url = new URL(agentUrl);
+            hostSuffix = hostnameToEnvSuffix(url.hostname);
+        }
+        catch {
+            // Invalid URL — skip host-specific lookup
+        }
+    }
+    // Resolve API key: host-specific first, then generic
+    if (hostSuffix) {
+        const hostKey = env[`A2A_API_KEY_${hostSuffix}`];
+        if (hostKey) {
+            creds.apiKey = hostKey;
+        }
+    }
+    if (!creds.apiKey) {
+        const genericKey = env['A2A_API_KEY'];
+        if (genericKey) {
+            creds.apiKey = genericKey;
+        }
+    }
+    // Resolve bearer token: host-specific first, then generic
+    if (hostSuffix) {
+        const hostToken = env[`A2A_BEARER_TOKEN_${hostSuffix}`];
+        if (hostToken) {
+            creds.bearerToken = hostToken;
+        }
+    }
+    if (!creds.bearerToken) {
+        const genericToken = env['A2A_BEARER_TOKEN'];
+        if (genericToken) {
+            creds.bearerToken = genericToken;
+        }
+    }
+    return creds;
+}
+// ---------------------------------------------------------------------------
+// Client-side: auth header construction
+// ---------------------------------------------------------------------------
+/**
+ * Build HTTP headers for authenticating an outbound A2A request.
+ *
+ * When auth schemes are provided (from the remote agent's AgentCard), the
+ * function matches credentials to the first compatible scheme:
+ * - apiKey scheme  -> sets header {scheme.name}: {key}  (default: x-api-key)
+ * - http + bearer  -> sets Authorization: Bearer {token}
+ *
+ * When no auth schemes are provided, auto-detection is used:
+ * - bearerToken -> Authorization: Bearer {token}
+ * - apiKey      -> x-api-key: {key}
+ *
+ * @param credentials - Resolved credentials
+ * @param authSchemes - Optional auth schemes from the remote agent's card
+ * @returns Headers object (may be empty)
+ */
+export function buildA2aAuthHeaders(credentials, authSchemes) {
+    const headers = {};
+    if (authSchemes && authSchemes.length > 0) {
+        // Match credentials to declared auth schemes
+        for (const scheme of authSchemes) {
+            if (scheme.type === 'apiKey' && credentials.apiKey) {
+                const headerName = scheme.name || 'x-api-key';
+                headers[headerName] = credentials.apiKey;
+                return headers;
+            }
+            if (scheme.type === 'http' && scheme.scheme === 'bearer' && credentials.bearerToken) {
+                headers['Authorization'] = `Bearer ${credentials.bearerToken}`;
+                return headers;
+            }
+        }
+        // No scheme matched — return empty
+        return headers;
+    }
+    // Auto-detect: no auth schemes provided
+    if (credentials.bearerToken) {
+        headers['Authorization'] = `Bearer ${credentials.bearerToken}`;
+    }
+    else if (credentials.apiKey) {
+        headers['x-api-key'] = credentials.apiKey;
+    }
+    return headers;
+}
+// ---------------------------------------------------------------------------
+// Server-side: inbound request validation
+// ---------------------------------------------------------------------------
+/**
+ * Extract a bearer token or raw key from an Authorization header.
+ *
+ * Supports:
+ * - "Bearer <token>" -> returns the token
+ * - Raw value (no prefix) -> returns the value as-is
+ */
+function extractToken(authHeader) {
+    if (authHeader.startsWith('Bearer ')) {
+        return authHeader.slice(7);
+    }
+    return authHeader;
+}
+/**
+ * Validate an incoming A2A request's auth header using timing-safe comparison.
+ *
+ * Resolution of expected key:
+ * 1. config.apiKey (explicit value)
+ * 2. env var named by config.apiKeyEnvVar
+ * 3. A2A_SERVER_API_KEY env var
+ * 4. WORKER_API_KEY env var (fallback for backward compat)
+ *
+ * If no expected key is configured, returns false (fail closed).
+ *
+ * @param authHeader - The Authorization header value from the request
+ * @param config - Optional auth configuration
+ * @returns true if the auth is valid
+ */
+export function validateA2aAuth(authHeader, config) {
+    if (!authHeader) {
+        return false;
+    }
+    const providedKey = extractToken(authHeader);
+    if (!providedKey) {
+        return false;
+    }
+    // Resolve expected key
+    let expectedKey;
+    if (config?.apiKey) {
+        expectedKey = config.apiKey;
+    }
+    else if (config?.apiKeyEnvVar) {
+        expectedKey = process.env[config.apiKeyEnvVar];
+    }
+    else {
+        // Default env var resolution chain
+        expectedKey = process.env.A2A_SERVER_API_KEY ?? process.env.WORKER_API_KEY;
+    }
+    if (!expectedKey) {
+        return false;
+    }
+    // Use timing-safe comparison to prevent timing attacks
+    try {
+        return crypto.timingSafeEqual(Buffer.from(providedKey), Buffer.from(expectedKey));
+    }
+    catch {
+        // Buffers have different lengths
+        return false;
+    }
+}

package/dist/src/providers/a2a-auth.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=a2a-auth.test.d.ts.map

package/dist/src/providers/a2a-auth.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-auth.test.d.ts","sourceRoot":"","sources":["../../../src/providers/a2a-auth.test.ts"],"names":[],"mappings":""}

package/dist/src/providers/a2a-auth.test.js

@@ -0,0 +1,232 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { resolveA2aCredentials, buildA2aAuthHeaders, validateA2aAuth, } from './a2a-auth.js';
+// ---------------------------------------------------------------------------
+// resolveA2aCredentials
+// ---------------------------------------------------------------------------
+describe('resolveA2aCredentials', () => {
+    it('returns empty credentials when no env vars set', () => {
+        const result = resolveA2aCredentials({});
+        expect(result).toEqual({});
+    });
+    it('reads generic A2A_API_KEY', () => {
+        const result = resolveA2aCredentials({ A2A_API_KEY: 'my-api-key' });
+        expect(result.apiKey).toBe('my-api-key');
+    });
+    it('reads generic A2A_BEARER_TOKEN', () => {
+        const result = resolveA2aCredentials({ A2A_BEARER_TOKEN: 'my-token' });
+        expect(result.bearerToken).toBe('my-token');
+    });
+    it('reads both generic keys simultaneously', () => {
+        const result = resolveA2aCredentials({
+            A2A_API_KEY: 'key-1',
+            A2A_BEARER_TOKEN: 'token-1',
+        });
+        expect(result.apiKey).toBe('key-1');
+        expect(result.bearerToken).toBe('token-1');
+    });
+    it('reads host-specific keys when agentUrl provided', () => {
+        const result = resolveA2aCredentials({ A2A_API_KEY_EXAMPLE_COM: 'host-key' }, 'https://example.com/agent');
+        expect(result.apiKey).toBe('host-key');
+    });
+    it('host-specific takes precedence over generic', () => {
+        const result = resolveA2aCredentials({
+            A2A_API_KEY: 'generic-key',
+            A2A_API_KEY_EXAMPLE_COM: 'host-key',
+            A2A_BEARER_TOKEN: 'generic-token',
+            A2A_BEARER_TOKEN_EXAMPLE_COM: 'host-token',
+        }, 'https://example.com/agent');
+        expect(result.apiKey).toBe('host-key');
+        expect(result.bearerToken).toBe('host-token');
+    });
+    it('falls back to generic when host-specific not set', () => {
+        const result = resolveA2aCredentials({
+            A2A_API_KEY: 'generic-key',
+            A2A_BEARER_TOKEN: 'generic-token',
+        }, 'https://example.com/agent');
+        expect(result.apiKey).toBe('generic-key');
+        expect(result.bearerToken).toBe('generic-token');
+    });
+    it('handles URLs with ports correctly (port is not in hostname)', () => {
+        const result = resolveA2aCredentials({ A2A_API_KEY_LOCALHOST: 'local-key' }, 'http://localhost:8080/agent');
+        expect(result.apiKey).toBe('local-key');
+    });
+    it('handles hostnames with hyphens', () => {
+        const result = resolveA2aCredentials({ A2A_API_KEY_SPRING_AGENT_EXAMPLE_COM: 'spring-key' }, 'http://spring-agent.example.com:8080/');
+        expect(result.apiKey).toBe('spring-key');
+    });
+    it('handles hostnames with multiple dots and hyphens', () => {
+        const result = resolveA2aCredentials({ A2A_BEARER_TOKEN_MY_AGENT_US_EAST_1_EXAMPLE_IO: 'region-token' }, 'https://my-agent.us-east-1.example.io/a2a');
+        expect(result.bearerToken).toBe('region-token');
+    });
+    it('ignores invalid agentUrl and falls back to generic', () => {
+        const result = resolveA2aCredentials({ A2A_API_KEY: 'generic-key' }, 'not-a-url');
+        expect(result.apiKey).toBe('generic-key');
+    });
+    it('returns empty when agentUrl is invalid and no generic keys', () => {
+        const result = resolveA2aCredentials({}, 'not-a-url');
+        expect(result).toEqual({});
+    });
+});
+// ---------------------------------------------------------------------------
+// buildA2aAuthHeaders
+// ---------------------------------------------------------------------------
+describe('buildA2aAuthHeaders', () => {
+    it('returns empty object when no credentials', () => {
+        const result = buildA2aAuthHeaders({});
+        expect(result).toEqual({});
+    });
+    it('sets bearer token in Authorization header (auto-detect)', () => {
+        const result = buildA2aAuthHeaders({ bearerToken: 'my-token' });
+        expect(result).toEqual({ Authorization: 'Bearer my-token' });
+    });
+    it('sets API key in x-api-key header (auto-detect)', () => {
+        const result = buildA2aAuthHeaders({ apiKey: 'my-key' });
+        expect(result).toEqual({ 'x-api-key': 'my-key' });
+    });
+    it('prefers bearer token over API key in auto-detect mode', () => {
+        const result = buildA2aAuthHeaders({
+            bearerToken: 'my-token',
+            apiKey: 'my-key',
+        });
+        expect(result).toEqual({ Authorization: 'Bearer my-token' });
+    });
+    it('respects apiKey auth scheme with custom header name', () => {
+        const schemes = [
+            { type: 'apiKey', in: 'header', name: 'X-Custom-Key' },
+        ];
+        const result = buildA2aAuthHeaders({ apiKey: 'my-key' }, schemes);
+        expect(result).toEqual({ 'X-Custom-Key': 'my-key' });
+    });
+    it('uses default x-api-key header when scheme has no name', () => {
+        const schemes = [
+            { type: 'apiKey', in: 'header' },
+        ];
+        const result = buildA2aAuthHeaders({ apiKey: 'my-key' }, schemes);
+        expect(result).toEqual({ 'x-api-key': 'my-key' });
+    });
+    it('respects http bearer auth scheme', () => {
+        const schemes = [
+            { type: 'http', scheme: 'bearer' },
+        ];
+        const result = buildA2aAuthHeaders({ bearerToken: 'my-token' }, schemes);
+        expect(result).toEqual({ Authorization: 'Bearer my-token' });
+    });
+    it('returns empty when scheme requires apiKey but only bearerToken provided', () => {
+        const schemes = [
+            { type: 'apiKey', in: 'header', name: 'x-api-key' },
+        ];
+        const result = buildA2aAuthHeaders({ bearerToken: 'my-token' }, schemes);
+        expect(result).toEqual({});
+    });
+    it('returns empty when scheme requires bearer but only apiKey provided', () => {
+        const schemes = [
+            { type: 'http', scheme: 'bearer' },
+        ];
+        const result = buildA2aAuthHeaders({ apiKey: 'my-key' }, schemes);
+        expect(result).toEqual({});
+    });
+    it('matches first compatible scheme when multiple provided', () => {
+        const schemes = [
+            { type: 'http', scheme: 'bearer' },
+            { type: 'apiKey', in: 'header', name: 'x-api-key' },
+        ];
+        const creds = { bearerToken: 'my-token', apiKey: 'my-key' };
+        const result = buildA2aAuthHeaders(creds, schemes);
+        // First scheme (bearer) should match
+        expect(result).toEqual({ Authorization: 'Bearer my-token' });
+    });
+    it('falls to second scheme when first does not match', () => {
+        const schemes = [
+            { type: 'http', scheme: 'bearer' },
+            { type: 'apiKey', in: 'header', name: 'x-api-key' },
+        ];
+        const creds = { apiKey: 'my-key' };
+        const result = buildA2aAuthHeaders(creds, schemes);
+        // Only apiKey scheme matches
+        expect(result).toEqual({ 'x-api-key': 'my-key' });
+    });
+    it('returns empty when auth schemes array is empty (treated as no schemes)', () => {
+        const result = buildA2aAuthHeaders({ apiKey: 'my-key' }, []);
+        // Empty array means no schemes -> auto-detect
+        expect(result).toEqual({ 'x-api-key': 'my-key' });
+    });
+    it('ignores unsupported oauth2 scheme and returns empty', () => {
+        const schemes = [
+            { type: 'oauth2' },
+        ];
+        const result = buildA2aAuthHeaders({ bearerToken: 'my-token' }, schemes);
+        expect(result).toEqual({});
+    });
+});
+// ---------------------------------------------------------------------------
+// validateA2aAuth
+// ---------------------------------------------------------------------------
+describe('validateA2aAuth', () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv };
+        // Clear relevant env vars
+        delete process.env.A2A_SERVER_API_KEY;
+        delete process.env.WORKER_API_KEY;
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it('returns false when no auth header provided', () => {
+        expect(validateA2aAuth(undefined, { apiKey: 'expected' })).toBe(false);
+    });
+    it('returns false when no expected key configured', () => {
+        expect(validateA2aAuth('Bearer some-token')).toBe(false);
+    });
+    it('returns true for matching bearer token', () => {
+        const result = validateA2aAuth('Bearer secret-key', { apiKey: 'secret-key' });
+        expect(result).toBe(true);
+    });
+    it('returns true for matching raw API key (no Bearer prefix)', () => {
+        const result = validateA2aAuth('secret-key', { apiKey: 'secret-key' });
+        expect(result).toBe(true);
+    });
+    it('returns false for mismatched key (timing-safe)', () => {
+        const result = validateA2aAuth('Bearer wrong-key', { apiKey: 'correct-key' });
+        expect(result).toBe(false);
+    });
+    it('returns false for mismatched key of different length', () => {
+        const result = validateA2aAuth('Bearer short', { apiKey: 'a-much-longer-key' });
+        expect(result).toBe(false);
+    });
+    it('resolves expected key from A2A_SERVER_API_KEY env var', () => {
+        process.env.A2A_SERVER_API_KEY = 'env-key';
+        const result = validateA2aAuth('Bearer env-key');
+        expect(result).toBe(true);
+    });
+    it('falls back to WORKER_API_KEY env var', () => {
+        process.env.WORKER_API_KEY = 'worker-key';
+        const result = validateA2aAuth('Bearer worker-key');
+        expect(result).toBe(true);
+    });
+    it('A2A_SERVER_API_KEY takes precedence over WORKER_API_KEY', () => {
+        process.env.A2A_SERVER_API_KEY = 'a2a-key';
+        process.env.WORKER_API_KEY = 'worker-key';
+        expect(validateA2aAuth('Bearer a2a-key')).toBe(true);
+        expect(validateA2aAuth('Bearer worker-key')).toBe(false);
+    });
+    it('uses custom env var name from config', () => {
+        process.env.MY_CUSTOM_KEY = 'custom-value';
+        const result = validateA2aAuth('Bearer custom-value', {
+            apiKeyEnvVar: 'MY_CUSTOM_KEY',
+        });
+        expect(result).toBe(true);
+        // Clean up
+        delete process.env.MY_CUSTOM_KEY;
+    });
+    it('explicit apiKey in config takes precedence over env vars', () => {
+        process.env.A2A_SERVER_API_KEY = 'env-key';
+        const result = validateA2aAuth('Bearer explicit-key', { apiKey: 'explicit-key' });
+        expect(result).toBe(true);
+    });
+    it('returns false for empty auth header string', () => {
+        // extractToken with "Bearer " prefix but nothing after gives empty string
+        // but "" still gets compared — and empty provided vs non-empty expected -> false
+        expect(validateA2aAuth('', { apiKey: 'expected' })).toBe(false);
+    });
+});

package/dist/src/providers/a2a-provider.d.ts

@@ -0,0 +1,254 @@
+/**
+ * A2A (Agent-to-Agent) Client Provider
+ *
+ * Invokes external A2A-compliant agents over HTTP using the Google A2A protocol.
+ * Uses JSON-RPC 2.0 for requests and SSE streaming for responses.
+ *
+ * A2A Protocol overview:
+ *   - Agent discovery via GET /.well-known/agent-card.json
+ *   - Task creation via POST /a2a with JSON-RPC method "message/send" or "message/stream"
+ *   - Task lifecycle: submitted → working → completed/failed/canceled
+ *   - Input-required is a paused state requesting user input
+ *   - SSE events: TaskStatusUpdateEvent, TaskArtifactUpdateEvent
+ *
+ * Env vars:
+ *   A2A_AGENT_URL           — base URL of the A2A agent (e.g., https://agent.example.com)
+ *   A2A_AGENT_URL_{WORKTYPE} — work-type-specific override (e.g., A2A_AGENT_URL_RESEARCH)
+ *   A2A_API_KEY             — API key for authentication (sent as x-api-key header)
+ *   A2A_BEARER_TOKEN        — Bearer token for authentication (sent as Authorization header)
+ */
+import type { AgentProvider, AgentSpawnConfig, AgentHandle, AgentEvent } from './types.js';
+/** A2A message part: plain text */
+export interface A2aTextPart {
+    /** Part type discriminator */
+    type: 'text';
+    /** The text content */
+    text: string;
+}
+/** A2A message part: file (inline or by URI) */
+export interface A2aFilePart {
+    /** Part type discriminator */
+    type: 'file';
+    /** File metadata */
+    file: {
+        /** File name */
+        name?: string;
+        /** MIME type */
+        mimeType?: string;
+        /** Base64-encoded file content (mutually exclusive with uri) */
+        bytes?: string;
+        /** URI to the file (mutually exclusive with bytes) */
+        uri?: string;
+    };
+}
+/** A2A message part: structured data */
+export interface A2aDataPart {
+    /** Part type discriminator */
+    type: 'data';
+    /** Arbitrary structured data */
+    data: Record<string, unknown>;
+}
+/** Union of all A2A message part types */
+export type A2aPart = A2aTextPart | A2aFilePart | A2aDataPart;
+/** A2A message with role and content parts */
+export interface A2aMessage {
+    /** The role of the message sender */
+    role: 'user' | 'agent';
+    /** Content parts of the message */
+    parts: A2aPart[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** Task status values in the A2A protocol */
+export type A2aTaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'failed' | 'canceled';
+/** A2A task status object */
+export interface A2aTaskStatusObject {
+    /** Current task state */
+    state: A2aTaskStatus;
+    /** Optional message associated with the status */
+    message?: A2aMessage;
+    /** Timestamp of the status update */
+    timestamp?: string;
+}
+/** A2A artifact produced by the agent */
+export interface A2aArtifact {
+    /** Artifact name */
+    name?: string;
+    /** Artifact description */
+    description?: string;
+    /** Content parts of the artifact */
+    parts: A2aPart[];
+    /** Artifact index (for ordering) */
+    index?: number;
+    /** Whether this is the last chunk of a streaming artifact */
+    lastChunk?: boolean;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** A2A task object */
+export interface A2aTask {
+    /** Task identifier */
+    id: string;
+    /** Session identifier for multi-turn conversations */
+    sessionId?: string;
+    /** Current task status */
+    status: A2aTaskStatusObject;
+    /** Messages exchanged in the task */
+    messages?: A2aMessage[];
+    /** Artifacts produced by the agent */
+    artifacts?: A2aArtifact[];
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** SSE event: task status update */
+export interface A2aTaskStatusUpdateEvent {
+    /** Event type discriminator */
+    type: 'TaskStatusUpdate';
+    /** Task ID */
+    id: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Updated status */
+    status: A2aTaskStatusObject;
+    /** Whether this is the final event */
+    final?: boolean;
+}
+/** SSE event: task artifact update */
+export interface A2aTaskArtifactUpdateEvent {
+    /** Event type discriminator */
+    type: 'TaskArtifactUpdate';
+    /** Task ID */
+    id: string;
+    /** Session ID */
+    sessionId?: string;
+    /** The artifact being updated */
+    artifact: A2aArtifact;
+}
+/** Union of all A2A SSE task event types */
+export type A2aTaskEvent = A2aTaskStatusUpdateEvent | A2aTaskArtifactUpdateEvent;
+/**
+ * A2A Agent Card — describes the agent's capabilities and metadata.
+ * Fetched from GET {baseUrl}/.well-known/agent-card.json
+ */
+export interface A2aAgentCard {
+    /** Agent name */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Base URL of the agent */
+    url: string;
+    /** Agent version */
+    version?: string;
+    /** Skills the agent supports */
+    skills?: A2aAgentSkill[];
+    /** Authentication schemes supported */
+    authSchemes?: A2aAuthScheme[];
+    /** Agent capabilities */
+    capabilities?: A2aAgentCapabilities;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/** A2A agent skill descriptor */
+export interface A2aAgentSkill {
+    /** Skill identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the skill */
+    description?: string;
+    /** Input content types */
+    inputContentTypes?: string[];
+    /** Output content types */
+    outputContentTypes?: string[];
+}
+/** A2A authentication scheme */
+export interface A2aAuthScheme {
+    /** Auth scheme type (e.g., "apiKey", "bearer", "oauth2") */
+    type: string;
+    /** Additional scheme-specific configuration */
+    [key: string]: unknown;
+}
+/** A2A agent capabilities */
+export interface A2aAgentCapabilities {
+    /** Whether the agent supports SSE streaming */
+    streaming?: boolean;
+    /** Whether the agent supports push notifications */
+    pushNotifications?: boolean;
+    /** Whether the agent supports multi-turn conversations */
+    multiTurn?: boolean;
+}
+/** JSON-RPC 2.0 request */
+export interface A2aJsonRpcRequest {
+    /** JSON-RPC version — always "2.0" */
+    jsonrpc: '2.0';
+    /** Request identifier */
+    id: string;
+    /** Method name */
+    method: string;
+    /** Method parameters */
+    params: Record<string, unknown>;
+}
+/** JSON-RPC 2.0 success response */
+export interface A2aJsonRpcResponse {
+    /** JSON-RPC version — always "2.0" */
+    jsonrpc: '2.0';
+    /** Request identifier (matches request) */
+    id: string;
+    /** Result payload */
+    result?: unknown;
+    /** Error payload */
+    error?: A2aJsonRpcError;
+}
+/** JSON-RPC 2.0 error object */
+export interface A2aJsonRpcError {
+    /** Error code */
+    code: number;
+    /** Error message */
+    message: string;
+    /** Optional error data */
+    data?: unknown;
+}
+/**
+ * Fetch and parse the A2A Agent Card from the well-known endpoint.
+ *
+ * @param baseUrl - Base URL of the A2A agent (e.g., "https://agent.example.com")
+ * @returns Parsed agent card
+ * @throws Error if the fetch fails or the response is not valid JSON
+ */
+export declare function fetchAgentCard(baseUrl: string): Promise<A2aAgentCard>;
+/**
+ * Mutable state tracked across A2A task events for a single session.
+ * Passed into mapA2aTaskEvent to accumulate session-level data.
+ */
+export interface A2aEventMapperState {
+    /** Session ID from the A2A task */
+    sessionId: string | null;
+    /** Task ID from the A2A task */
+    taskId: string | null;
+    /** Accumulated input tokens */
+    totalInputTokens: number;
+    /** Accumulated output tokens */
+    totalOutputTokens: number;
+    /** Number of turns/interactions */
+    turnCount: number;
+}
+/**
+ * Map a single A2A task event to one or more normalized AgentEvents.
+ * Exported for unit testing — the AgentHandle uses this internally.
+ *
+ * @param event - The A2A SSE task event
+ * @param state - Mutable state accumulator for the session
+ * @returns Array of normalized AgentEvent objects
+ */
+export declare function mapA2aTaskEvent(event: A2aTaskEvent, state: A2aEventMapperState): AgentEvent[];
+export declare class A2aProvider implements AgentProvider {
+    readonly name: "a2a";
+    spawn(config: AgentSpawnConfig): AgentHandle;
+    resume(sessionId: string, config: AgentSpawnConfig): AgentHandle;
+    private createHandle;
+}
+/**
+ * Create a new A2A provider instance.
+ */
+export declare function createA2aProvider(): A2aProvider;
+//# sourceMappingURL=a2a-provider.d.ts.map