@inkeep/agents-run-api 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# Inkeep Execution API
+
+The Execution API is responsible for runtime agent operations, including Agent-to-Agent (A2A) communication, chat completions, and MCP (Model Context Protocol) tool integrations.
+
+## Overview
+
+This API handles the execution layer of the Inkeep Agent Framework:
+- **A2A Communication**: JSON-RPC based agent-to-agent communication following Google's A2A specification
+- **Chat Completions**: OpenAI-compatible chat API with multi-agent orchestration
+- **MCP Integration**: Model Context Protocol tools and external integrations
+- **Task Execution**: Real-time task processing and delegation workflows
+
+## Architecture
+
+### Core Components
+
+- **A2A Protocol**: Agent communication via JSON-RPC methods (`tasks/send`, `tasks/get`, `tasks/cancel`)
+- **Chat API**: OpenAI-compatible endpoints with agent routing and context preservation
+- **MCP Tools**: Dynamic tool discovery and execution from multiple transport types (stdio, SSE, HTTP)
+- **Task Management**: Hierarchical task execution with parent-child relationships
+
+### Key Features
+
+- **Context Preservation**: Maintains conversation state across agent transfers and delegations
+- **Multi-Agent Orchestration**: Hub-and-spoke and graph-based agent networks
+- **Real-time Communication**: WebSocket and HTTP-based agent interactions
+- **Tool Health Monitoring**: Automated health checks for external MCP tools
+
+## Development
+
+### Setup
+If you do not have the db setup:
+```bash 
+cd packages/core
+pnpm db:push
+```
+
+Then:
+```bash
+cd inkeep-execution-api
+pnpm install
+```
+
+
+### Environment Variables
+```env
+ENVIRONMENT=development|production|test
+PORT=3003
+DB_FILE_NAME=path/to/sqlite.db
+ANTHROPIC_API_KEY=required
+OPENAI_API_KEY=optional
+LOG_LEVEL=debug|info|warn|error
+```
+
+### Development Commands
+```bash
+pnpm dev              # Start development server
+pnpm test             # Run test suite
+pnpm test:coverage    # Run tests with coverage
+pnpm build           # Build for production
+pnpm lint            # Run linting
+pnpm format          # Format code
+```
+
+### Testing
+All tests are located in `src/__tests__/` and use Vitest with 60-second timeouts for A2A interactions.
+
+```bash
+pnpm test                    # Run all tests
+pnpm test:coverage          # Run with coverage report
+pnpm test src/__tests__/a2a/ # Run A2A-specific tests
+```
+
+## Configuration
+
+The API uses environment-based configuration with defaults for local development. Key configuration areas:
+
+- **Database**: SQLite connection via `DB_FILE_NAME`
+- **AI Models**: Anthropic and OpenAI API keys
+- **Observability**: OpenTelemetry tracing support
+- **CORS**: Configurable for web clients
+
+## Integration
+
+### With Management API
+The Execution API reads agent configurations and relationships created by the Management API but doesn't modify them during runtime.
+
+### With MCP Tools
+Supports multiple MCP transport types:
+- **stdio**: Local process-based tools  
+- **SSE**: Server-sent events for streaming tools
+- **HTTP**: REST-based tool integrations
+
+### With Agent Builder
+Provides runtime execution for agents configured via the Agent Builder UI.
+
+## Observability
+
+- **Structured Logging**: JSON-formatted logs with correlation IDs
+- **OpenTelemetry**: Distributed tracing for agent interactions
+- **Health Checks**: Endpoint monitoring and tool availability
+- **Performance Metrics**: Request timing and success rates
+
+## Error Handling
+
+The API implements comprehensive error handling:
+- **Validation Errors**: Request schema validation
+- **Agent Errors**: Agent execution failures and timeouts
+- **Tool Errors**: MCP tool failures and recovery
+- **Network Errors**: Resilient communication patterns
+
+## Security
+
+- **API Key Authentication**: Configurable authentication methods
+- **Input Validation**: Request sanitization and type checking  
+- **CORS**: Configurable cross-origin policies
+- **Rate Limiting**: Configurable request throttling

package/dist/AgentExecutionServer.d.ts

@@ -0,0 +1,23 @@
+import { BaseServer, type AgentFrameworkServerConfig } from '@inkeep/agents-core';
+export declare const EXECUTION_API_PORT = 3003;
+/**
+ * Execution Server for chat, agent-to-agent communication, and MCP endpoints
+ * Extends BaseServer with Execution API specific functionality
+ */
+export declare class AgentExecutionServer extends BaseServer {
+    constructor(config?: AgentFrameworkServerConfig);
+    /**
+     * Initialize the Execution API application
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * Get default server options for Execution API
+     */
+    protected getServerOptions(): {
+        port: number;
+        keepAliveTimeout: number;
+        keepAlive: boolean;
+        requestTimeout: number;
+    };
+}
+//# sourceMappingURL=AgentExecutionServer.d.ts.map

package/dist/AgentExecutionServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentExecutionServer.d.ts","sourceRoot":"","sources":["../src/AgentExecutionServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAIlF,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,UAAU;gBACtC,MAAM,GAAE,0BAA+B;IAInD;;OAEG;cACa,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAK3C;;OAEG;IACH,SAAS,CAAC,gBAAgB;;;;;;CAS3B"}

package/dist/AgentExecutionServer.js

@@ -0,0 +1,32 @@
+import { BaseServer } from '@inkeep/agents-core';
+import { getLogger } from './logger.js';
+import app from './app.js';
+export const EXECUTION_API_PORT = 3003;
+/**
+ * Execution Server for chat, agent-to-agent communication, and MCP endpoints
+ * Extends BaseServer with Execution API specific functionality
+ */
+export class AgentExecutionServer extends BaseServer {
+    constructor(config = {}) {
+        super(config, getLogger('ExecutionServer'));
+    }
+    /**
+     * Initialize the Execution API application
+     */
+    async initialize() {
+        this.app = app;
+        this.logger.info('Execution API initialized');
+    }
+    /**
+     * Get default server options for Execution API
+     */
+    getServerOptions() {
+        return {
+            port: this.config.port || EXECUTION_API_PORT,
+            keepAliveTimeout: 60000,
+            keepAlive: true,
+            requestTimeout: 60000,
+            ...this.config.serverOptions,
+        };
+    }
+}

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,4 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+declare const sdk: NodeSDK;
+export { sdk };
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAYlD,QAAA,MAAM,GAAG,SAgBP,CAAC;AA6BH,OAAO,EAAE,GAAG,EAAE,CAAC"}

package/dist/__tests__/setup.js

@@ -0,0 +1,50 @@
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { ConsoleMetricExporter, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
+/*instrumentation.ts*/
+import { NodeSDK } from '@opentelemetry/sdk-node';
+const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+import { sql } from 'drizzle-orm';
+import { migrate } from 'drizzle-orm/libsql/migrator';
+import { afterAll, afterEach, beforeAll } from 'vitest';
+import dbClient from '../data/db/dbClient.js';
+import { getLogger } from '@inkeep/agents-core';
+getLogger('Test Setup').debug({}, 'Setting up instrumentation');
+const sdk = new NodeSDK({
+    serviceName: 'inkeep-execution-api',
+    spanProcessors: [
+        new SimpleSpanProcessor(new OTLPTraceExporter({
+        // optional - default url is http://localhost:4318/v1/traces
+        // url: 'http://localhost:4318/v1/traces',
+        })),
+    ],
+    instrumentations: [getNodeAutoInstrumentations()],
+    // optional - default url is http://localhost:4318/v1/metrics
+    // url: 'http://localhost:4318/v1/metrics',
+    metricReader: new PeriodicExportingMetricReader({
+        exporter: new ConsoleMetricExporter(),
+    }),
+});
+sdk.start();
+// Initialize database schema for in-memory test databases using Drizzle migrations
+beforeAll(async () => {
+    const logger = getLogger('Test Setup');
+    try {
+        logger.debug({}, 'Applying database migrations to in-memory test database');
+        // Temporarily disable foreign key constraints for tests due to composite key issues
+        await dbClient.run(sql `PRAGMA foreign_keys = OFF`);
+        await migrate(dbClient, { migrationsFolder: '../packages/agents-core/drizzle' });
+        logger.debug({}, 'Database migrations applied successfully');
+    }
+    catch (error) {
+        logger.error({ error }, 'Failed to apply database migrations');
+        throw error;
+    }
+});
+afterEach(() => {
+    // Any cleanup if needed
+});
+afterAll(() => {
+    // Any final cleanup if needed
+});
+export { sdk };

package/dist/__tests__/utils/testProject.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Ensures a project exists for a given tenant ID.
+ * This is needed because of foreign key constraints in the database.
+ *
+ * @param tenantId - The tenant ID
+ * @param projectId - The project ID (defaults to 'default')
+ * @returns Promise that resolves when the project is created
+ */
+export declare function ensureTestProject(tenantId: string, projectId?: string): Promise<void>;
+/**
+ * Creates multiple test projects for a tenant.
+ *
+ * @param tenantId - The tenant ID
+ * @param projectIds - Array of project IDs to create
+ * @returns Promise that resolves when all projects are created
+ */
+export declare function ensureTestProjects(tenantId: string, projectIds: string[]): Promise<void>;
+//# sourceMappingURL=testProject.d.ts.map

package/dist/__tests__/utils/testProject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testProject.d.ts","sourceRoot":"","sources":["../../../src/__tests__/utils/testProject.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,SAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAK9F;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9F"}

package/dist/__tests__/utils/testProject.js

@@ -0,0 +1,26 @@
+import { sql } from 'drizzle-orm';
+import dbClient from '../../data/db/dbClient.js';
+/**
+ * Ensures a project exists for a given tenant ID.
+ * This is needed because of foreign key constraints in the database.
+ *
+ * @param tenantId - The tenant ID
+ * @param projectId - The project ID (defaults to 'default')
+ * @returns Promise that resolves when the project is created
+ */
+export async function ensureTestProject(tenantId, projectId = 'default') {
+    await dbClient.run(sql `
+    INSERT OR IGNORE INTO projects (tenant_id, id, name, description, created_at, updated_at)
+    VALUES (${tenantId}, ${projectId}, ${`Test Project ${projectId}`}, ${`Test project for ${projectId}`}, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+  `);
+}
+/**
+ * Creates multiple test projects for a tenant.
+ *
+ * @param tenantId - The tenant ID
+ * @param projectIds - Array of project IDs to create
+ * @returns Promise that resolves when all projects are created
+ */
+export async function ensureTestProjects(tenantId, projectIds) {
+    await Promise.all(projectIds.map((projectId) => ensureTestProject(tenantId, projectId)));
+}

package/dist/__tests__/utils/testRequest.d.ts

@@ -0,0 +1,8 @@
+export declare const makeRequest: (url: string, options?: RequestInit) => Promise<Response>;
+export declare const makeRequestWithContext: (url: string, context: {
+    tenantId?: string;
+    projectId?: string;
+    graphId?: string;
+    agentId?: string;
+}, options?: RequestInit) => Promise<Response>;
+//# sourceMappingURL=testRequest.d.ts.map

package/dist/__tests__/utils/testRequest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testRequest.d.ts","sourceRoot":"","sources":["../../../src/__tests__/utils/testRequest.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,WAAW,GAAU,KAAK,MAAM,EAAE,UAAS,WAAgB,sBAavE,CAAC;AAGF,eAAO,MAAM,sBAAsB,GACjC,KAAK,MAAM,EACX,SAAS;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,EACD,UAAS,WAAgB,sBAe1B,CAAC"}

package/dist/__tests__/utils/testRequest.js

@@ -0,0 +1,32 @@
+import app from '../../app.js';
+// Helper function to make requests with JSON headers and test authentication
+export const makeRequest = async (url, options = {}) => {
+    return app.request(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: 'Bearer test-api-key',
+            'x-inkeep-tenant-id': 'test-tenant',
+            'x-inkeep-project-id': 'default',
+            'x-inkeep-graph-id': 'test-graph',
+            'x-test-bypass-auth': 'true',
+            ...options.headers,
+        },
+    });
+};
+// Helper function to make requests with custom execution context
+export const makeRequestWithContext = async (url, context, options = {}) => {
+    return app.request(url, {
+        ...options,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: 'Bearer test-api-key',
+            'x-inkeep-tenant-id': context.tenantId || 'test-tenant',
+            'x-inkeep-project-id': context.projectId || 'test-project',
+            'x-inkeep-graph-id': context.graphId || 'test-graph',
+            'x-test-bypass-auth': 'true',
+            ...(context.agentId && { 'x-inkeep-agent-id': context.agentId }),
+            ...options.headers,
+        },
+    });
+};

package/dist/__tests__/utils/testTenant.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Creates a unique tenant ID for test isolation.
+ *
+ * Each test run gets its own tenant to ensure parallel tests don't interfere with each other.
+ * The generated tenant ID follows the format: test-tenant-{prefix}-{uuid} or test-tenant-{uuid}
+ *
+ * @param prefix - Optional prefix to include in the tenant ID (e.g., test file name)
+ * @returns A unique tenant ID for test isolation
+ *
+ * @example
+ * ```typescript
+ * import { createTestTenantId } from './utils/testTenant.js';
+ *
+ * describe('My test suite', () => {
+ *   const tenantId = createTestTenantId('agents');
+ *
+ *   it('should work with isolated tenant', async () => {
+ *     // Your test code using the unique tenant ID
+ *     console.log(tenantId); // e.g., "test-tenant-agents-123e4567-e89b-12d3-a456-426614174000"
+ *   });
+ * });
+ * ```
+ */
+export declare function createTestTenantId(prefix?: string): string;
+/**
+ * Creates multiple unique tenant IDs for test isolation.
+ *
+ * Useful when you need multiple tenants in a single test.
+ *
+ * @param count - Number of tenant IDs to generate
+ * @param prefix - Optional prefix to include in all tenant IDs
+ * @returns Array of unique tenant IDs
+ *
+ * @example
+ * ```typescript
+ * import { createTestTenantIds } from './utils/testTenant.js';
+ *
+ * describe('Multi-tenant test suite', () => {
+ *   const [tenantA, tenantB] = createTestTenantIds(2, 'multi-tenant');
+ *
+ *   it('should handle cross-tenant operations', async () => {
+ *     // Test operations across different tenants
+ *   });
+ * });
+ * ```
+ */
+export declare function createTestTenantIds(count: number, prefix?: string): string[];
+/**
+ * Checks if a tenant ID is a test tenant.
+ *
+ * @param tenantId - The tenant ID to check
+ * @returns True if the tenant ID is a test tenant
+ *
+ * @example
+ * ```typescript
+ * import { isTestTenant } from './utils/testTenant.js';
+ *
+ * const tenantId = createTestTenantId();
+ * console.log(isTestTenant(tenantId)); // true
+ * console.log(isTestTenant('production-tenant')); // false
+ * ```
+ */
+export declare function isTestTenant(tenantId: string): boolean;
+//# sourceMappingURL=testTenant.d.ts.map

package/dist/__tests__/utils/testTenant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testTenant.d.ts","sourceRoot":"","sources":["../../../src/__tests__/utils/testTenant.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEtD"}

package/dist/__tests__/utils/testTenant.js

@@ -0,0 +1,71 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Creates a unique tenant ID for test isolation.
+ *
+ * Each test run gets its own tenant to ensure parallel tests don't interfere with each other.
+ * The generated tenant ID follows the format: test-tenant-{prefix}-{uuid} or test-tenant-{uuid}
+ *
+ * @param prefix - Optional prefix to include in the tenant ID (e.g., test file name)
+ * @returns A unique tenant ID for test isolation
+ *
+ * @example
+ * ```typescript
+ * import { createTestTenantId } from './utils/testTenant.js';
+ *
+ * describe('My test suite', () => {
+ *   const tenantId = createTestTenantId('agents');
+ *
+ *   it('should work with isolated tenant', async () => {
+ *     // Your test code using the unique tenant ID
+ *     console.log(tenantId); // e.g., "test-tenant-agents-123e4567-e89b-12d3-a456-426614174000"
+ *   });
+ * });
+ * ```
+ */
+export function createTestTenantId(prefix) {
+    const uuid = randomUUID();
+    return prefix ? `test-tenant-${prefix}-${uuid}` : `test-tenant-${uuid}`;
+}
+/**
+ * Creates multiple unique tenant IDs for test isolation.
+ *
+ * Useful when you need multiple tenants in a single test.
+ *
+ * @param count - Number of tenant IDs to generate
+ * @param prefix - Optional prefix to include in all tenant IDs
+ * @returns Array of unique tenant IDs
+ *
+ * @example
+ * ```typescript
+ * import { createTestTenantIds } from './utils/testTenant.js';
+ *
+ * describe('Multi-tenant test suite', () => {
+ *   const [tenantA, tenantB] = createTestTenantIds(2, 'multi-tenant');
+ *
+ *   it('should handle cross-tenant operations', async () => {
+ *     // Test operations across different tenants
+ *   });
+ * });
+ * ```
+ */
+export function createTestTenantIds(count, prefix) {
+    return Array.from({ length: count }, () => createTestTenantId(prefix));
+}
+/**
+ * Checks if a tenant ID is a test tenant.
+ *
+ * @param tenantId - The tenant ID to check
+ * @returns True if the tenant ID is a test tenant
+ *
+ * @example
+ * ```typescript
+ * import { isTestTenant } from './utils/testTenant.js';
+ *
+ * const tenantId = createTestTenantId();
+ * console.log(isTestTenant(tenantId)); // true
+ * console.log(isTestTenant('production-tenant')); // false
+ * ```
+ */
+export function isTestTenant(tenantId) {
+    return tenantId.startsWith('test-tenant-');
+}

package/dist/a2a/client.d.ts

@@ -0,0 +1,182 @@
+import type { AgentCard, CancelTaskResponse, GetTaskPushNotificationConfigResponse, GetTaskResponse, Message, MessageSendParams, SendMessageResponse, SetTaskPushNotificationConfigResponse, Task, TaskArtifactUpdateEvent, TaskIdParams, TaskPushNotificationConfig, TaskQueryParams, TaskStatusUpdateEvent } from '@inkeep/agents-core';
+type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+export type BackoffStrategy = {
+    initialInterval: number;
+    maxInterval: number;
+    exponent: number;
+    maxElapsedTime: number;
+};
+export type RetryConfig = {
+    strategy: 'none';
+} | {
+    strategy: 'backoff';
+    backoff?: BackoffStrategy;
+    retryConnectionErrors?: boolean;
+    statusCodes?: string[];
+};
+export interface A2AClientOptions {
+    retryConfig?: RetryConfig;
+    headers?: Record<string, string>;
+}
+/**
+ * A2AClient is a TypeScript HTTP client for interacting with A2A-compliant agents.
+ *
+ * Features:
+ * - Configurable retry behavior with exponential backoff
+ * - Automatic retry on network errors and configurable HTTP status codes
+ * - Support for custom retry strategies and timeouts
+ *
+ * Default retry behavior:
+ * - Retries on: 429, 500, 502, 503, 504 status codes and network errors
+ * - Initial delay: 500ms, max delay: 60s, exponential backoff (1.5x)
+ * - Max total retry time: 30 seconds
+ *
+ * @example
+ * // Default retry behavior
+ * const client = new A2AClient('https://agent.example.com');
+ *
+ * // Custom retry configuration
+ * const client = new A2AClient('https://agent.example.com', {
+ *   retryConfig: {
+ *     strategy: 'backoff',
+ *     retryConnectionErrors: true,
+ *     statusCodes: ['429', '502', '503', '504'],
+ *     backoff: {
+ *       initialInterval: 1000,
+ *       maxInterval: 30000,
+ *       exponent: 2,
+ *       maxElapsedTime: 60000
+ *     }
+ *   }
+ * });
+ *
+ * // Disable retries
+ * const client = new A2AClient('https://agent.example.com', {
+ *   retryConfig: { strategy: 'none' }
+ * });
+ */
+export declare class A2AClient {
+    private agentBaseUrl;
+    private agentCardPromise;
+    private requestIdCounter;
+    private serviceEndpointUrl?;
+    private options;
+    /**
+     * Constructs an A2AClient instance.
+     * It initiates fetching the agent card from the provided agent baseUrl.
+     * The Agent Card is expected at `${agentBaseUrl}/.well-known/agent.json`.
+     * The `url` field from the Agent Card will be used as the RPC service endpoint.
+     * @param agentBaseUrl The base URL of the A2A agent (e.g., https://agent.example.com).
+     * @param options Optional configuration including retry behavior.
+     */
+    constructor(agentBaseUrl: string, options?: A2AClientOptions);
+    /**
+     * Fetches the Agent Card from the agent's well-known URI and caches its service endpoint URL.
+     * This method is called by the constructor.
+     * @returns A Promise that resolves to the AgentCard.
+     */
+    private _fetchAndCacheAgentCard;
+    /**
+     * Retrieves the Agent Card.
+     * If an `agentBaseUrl` is provided, it fetches the card from that specific URL.
+     * Otherwise, it returns the card fetched and cached during client construction.
+     * @param agentBaseUrl Optional. The base URL of the agent to fetch the card from.
+     * If provided, this will fetch a new card, not use the cached one from the constructor's URL.
+     * @returns A Promise that resolves to the AgentCard.
+     */
+    getAgentCard(agentBaseUrl?: string): Promise<AgentCard>;
+    /**
+     * Gets the RPC service endpoint URL. Ensures the agent card has been fetched first.
+     * @returns A Promise that resolves to the service endpoint URL string.
+     */
+    private _getServiceEndpoint;
+    /**
+     * Retry utility functions
+     */
+    private retry;
+    private wrapFetcher;
+    private isRetryableResponse;
+    private isRetryableError;
+    private retryBackoff;
+    private retryIntervalFromResponse;
+    private delay;
+    /**
+     * Helper method to make a generic JSON-RPC POST request.
+     * @param method The RPC method name.
+     * @param params The parameters for the RPC method.
+     * @returns A Promise that resolves to the RPC response.
+     */
+    private _postRpcRequest;
+    /**
+     * Sends a message to the agent.
+     * The behavior (blocking/non-blocking) and push notification configuration
+     * are specified within the `params.configuration` object.
+     * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
+     * @param params The parameters for sending the message, including the message content and configuration.
+     * @returns A Promise resolving to SendMessageResponse, which can be a Message, Task, or an error.
+     */
+    sendMessage(params: MessageSendParams): Promise<SendMessageResponse>;
+    /**
+     * Sends a message to the agent and streams back responses using Server-Sent Events (SSE).
+     * Push notification configuration can be specified in `params.configuration`.
+     * Optionally, `params.message.contextId` or `params.message.taskId` can be provided.
+     * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
+     * @param params The parameters for sending the message.
+     * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
+     * The generator throws an error if streaming is not supported or if an HTTP/SSE error occurs.
+     */
+    sendMessageStream(params: MessageSendParams): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    /**
+     * Sets or updates the push notification configuration for a given task.
+     * Requires the agent to support push notifications (`capabilities.pushNotifications: true` in AgentCard).
+     * @param params Parameters containing the taskId and the TaskPushNotificationConfig.
+     * @returns A Promise resolving to SetTaskPushNotificationConfigResponse.
+     */
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig): Promise<SetTaskPushNotificationConfigResponse>;
+    /**
+     * Gets the push notification configuration for a given task.
+     * @param params Parameters containing the taskId.
+     * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
+     */
+    getTaskPushNotificationConfig(params: TaskIdParams): Promise<GetTaskPushNotificationConfigResponse>;
+    /**
+     * Retrieves a task by its ID.
+     * @param params Parameters containing the taskId and optional historyLength.
+     * @returns A Promise resolving to GetTaskResponse, which contains the Task object or an error.
+     */
+    getTask(params: TaskQueryParams): Promise<GetTaskResponse>;
+    /**
+     * Cancels a task by its ID.
+     * @param params Parameters containing the taskId.
+     * @returns A Promise resolving to CancelTaskResponse, which contains the updated Task object or an error.
+     */
+    cancelTask(params: TaskIdParams): Promise<CancelTaskResponse>;
+    /**
+     * Resubscribes to a task's event stream using Server-Sent Events (SSE).
+     * This is used if a previous SSE connection for an active task was broken.
+     * Requires the agent to support streaming (`capabilities.streaming: true` in AgentCard).
+     * @param params Parameters containing the taskId.
+     * @returns An AsyncGenerator yielding A2AStreamEventData (Message, Task, TaskStatusUpdateEvent, or TaskArtifactUpdateEvent).
+     */
+    resubscribeTask(params: TaskIdParams): AsyncGenerator<A2AStreamEventData, void, undefined>;
+    /**
+     * Parses an HTTP response body as an A2A Server-Sent Event stream.
+     * Each 'data' field of an SSE event is expected to be a JSON-RPC 2.0 Response object,
+     * specifically a SendStreamingMessageResponse (or similar structure for resubscribe).
+     * @param response The HTTP Response object whose body is the SSE stream.
+     * @param originalRequestId The ID of the client's JSON-RPC request that initiated this stream.
+     * Used to validate the `id` in the streamed JSON-RPC responses.
+     * @returns An AsyncGenerator yielding the `result` field of each valid JSON-RPC success response from the stream.
+     */
+    private _parseA2ASseStream;
+    /**
+     * Processes a single SSE event's data string, expecting it to be a JSON-RPC response.
+     * @param jsonData The string content from one or more 'data:' lines of an SSE event.
+     * @param originalRequestId The ID of the client's request that initiated the stream.
+     * @returns The `result` field of the parsed JSON-RPC success response.
+     * @throws Error if data is not valid JSON, not a valid JSON-RPC response, an error response, or ID mismatch.
+     */
+    private _processSseEventData;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/a2a/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/a2a/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,SAAS,EACT,kBAAkB,EAClB,qCAAqC,EACrC,eAAe,EAKf,OAAO,EACP,iBAAiB,EACjB,mBAAmB,EAGnB,qCAAqC,EACrC,IAAI,EACJ,uBAAuB,EACvB,YAAY,EACZ,0BAA0B,EAC1B,eAAe,EACf,qBAAqB,EACtB,MAAM,qBAAqB,CAAC;AAK7B,KAAK,kBAAkB,GAAG,OAAO,GAAG,IAAI,GAAG,qBAAqB,GAAG,uBAAuB,CAAC;AAG3F,MAAM,MAAM,eAAe,GAAG;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IACE,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEN,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,kBAAkB,CAAC,CAAS;IACpC,OAAO,CAAC,OAAO,CAAmB;IAElC;;;;;;;OAOG;gBACS,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB;IAc5D;;;;OAIG;YACW,uBAAuB;IA+BrC;;;;;;;OAOG;IACU,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAqBpE;;;OAGG;YACW,mBAAmB;IAgBjC;;OAEG;YACW,KAAK;IAgBnB,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,mBAAmB;IAuB3B,OAAO,CAAC,gBAAgB;YAiBV,YAAY;IAqE1B,OAAO,CAAC,yBAAyB;YAoBnB,KAAK;IAInB;;;;;OAKG;YACW,eAAe;IAyE7B;;;;;;;OAOG;IACU,WAAW,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIjF;;;;;;;;OAQG;IACW,iBAAiB,CAC7B,MAAM,EAAE,iBAAiB,GACxB,cAAc,CAAC,kBAAkB,EAAE,IAAI,EAAE,SAAS,CAAC;IA4DtD;;;;;OAKG;IACU,6BAA6B,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,qCAAqC,CAAC;IAcjD;;;;OAIG;IACU,6BAA6B,CACxC,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,qCAAqC,CAAC;IAQjD;;;;OAIG;IACU,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAIvE;;;;OAIG;IACU,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI1E;;;;;;OAMG;IACW,eAAe,CAC3B,MAAM,EAAE,YAAY,GACnB,cAAc,CAAC,kBAAkB,EAAE,IAAI,EAAE,SAAS,CAAC;IAyDtD;;;;;;;;OAQG;YACY,kBAAkB;IAoEjC;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;CA2D7B"}