@a2a-js/sdk 0.2.1

package/build/src/server/a2a_express_app.d.ts

@@ -0,0 +1,14 @@
+import { Express } from 'express';
+import { A2ARequestHandler } from "./request_handler/a2a_request_handler.js";
+export declare class A2AExpressApp {
+    private requestHandler;
+    private jsonRpcTransportHandler;
+    constructor(requestHandler: A2ARequestHandler);
+    /**
+     * Adds A2A routes to an existing Express app.
+     * @param app Optional existing Express app.
+     * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
+     * @returns The Express app with A2A routes.
+     */
+    setupRoutes(app: Express, baseUrl?: string): Express;
+}

package/build/src/server/a2a_express_app.js

@@ -0,0 +1,98 @@
+import express from 'express';
+import { A2AError } from "./error.js";
+import { JsonRpcTransportHandler } from "./transports/jsonrpc_transport_handler.js";
+export class A2AExpressApp {
+    requestHandler; // Kept for getAgentCard
+    jsonRpcTransportHandler;
+    constructor(requestHandler) {
+        this.requestHandler = requestHandler; // DefaultRequestHandler instance
+        this.jsonRpcTransportHandler = new JsonRpcTransportHandler(requestHandler);
+    }
+    /**
+     * Adds A2A routes to an existing Express app.
+     * @param app Optional existing Express app.
+     * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
+     * @returns The Express app with A2A routes.
+     */
+    setupRoutes(app, baseUrl = '') {
+        app.use(express.json());
+        app.get(`${baseUrl}/.well-known/agent.json`, async (req, res) => {
+            try {
+                // getAgentCard is on A2ARequestHandler, which DefaultRequestHandler implements
+                const agentCard = await this.requestHandler.getAgentCard();
+                res.json(agentCard);
+            }
+            catch (error) {
+                console.error("Error fetching agent card:", error);
+                res.status(500).json({ error: "Failed to retrieve agent card" });
+            }
+        });
+        app.post(baseUrl, async (req, res) => {
+            try {
+                const rpcResponseOrStream = await this.jsonRpcTransportHandler.handle(req.body);
+                // Check if it's an AsyncGenerator (stream)
+                if (typeof rpcResponseOrStream?.[Symbol.asyncIterator] === 'function') {
+                    const stream = rpcResponseOrStream;
+                    res.setHeader('Content-Type', 'text/event-stream');
+                    res.setHeader('Cache-Control', 'no-cache');
+                    res.setHeader('Connection', 'keep-alive');
+                    res.flushHeaders();
+                    try {
+                        for await (const event of stream) {
+                            // Each event from the stream is already a JSONRPCResult
+                            res.write(`id: ${new Date().getTime()}\n`);
+                            res.write(`data: ${JSON.stringify(event)}\n\n`);
+                        }
+                    }
+                    catch (streamError) {
+                        console.error(`Error during SSE streaming (request ${req.body?.id}):`, streamError);
+                        // If the stream itself throws an error, send a final JSONRPCErrorResponse
+                        const a2aError = streamError instanceof A2AError ? streamError : A2AError.internalError(streamError.message || 'Streaming error.');
+                        const errorResponse = {
+                            jsonrpc: '2.0',
+                            id: req.body?.id || null, // Use original request ID if available
+                            error: a2aError.toJSONRPCError(),
+                        };
+                        if (!res.headersSent) { // Should not happen if flushHeaders worked
+                            res.status(500).json(errorResponse); // Should be JSON, not SSE here
+                        }
+                        else {
+                            // Try to send as last SSE event if possible, though client might have disconnected
+                            res.write(`id: ${new Date().getTime()}\n`);
+                            res.write(`event: error\n`); // Custom event type for client-side handling
+                            res.write(`data: ${JSON.stringify(errorResponse)}\n\n`);
+                        }
+                    }
+                    finally {
+                        if (!res.writableEnded) {
+                            res.end();
+                        }
+                    }
+                }
+                else { // Single JSON-RPC response
+                    const rpcResponse = rpcResponseOrStream;
+                    res.status(200).json(rpcResponse);
+                }
+            }
+            catch (error) { // Catch errors from jsonRpcTransportHandler.handle itself (e.g., initial parse error)
+                console.error("Unhandled error in A2AExpressApp POST handler:", error);
+                const a2aError = error instanceof A2AError ? error : A2AError.internalError('General processing error.');
+                const errorResponse = {
+                    jsonrpc: '2.0',
+                    id: req.body?.id || null,
+                    error: a2aError.toJSONRPCError(),
+                };
+                if (!res.headersSent) {
+                    res.status(500).json(errorResponse);
+                }
+                else if (!res.writableEnded) {
+                    // If headers sent (likely during a stream attempt that failed early), try to end gracefully
+                    res.end();
+                }
+            }
+        });
+        // The separate /stream endpoint is no longer needed.
+        return app;
+    }
+}
+//# sourceMappingURL=a2a_express_app.js.map

package/build/src/server/agent_execution/agent_executor.d.ts

@@ -0,0 +1,18 @@
+import { ExecutionEventBus } from "../events/execution_event_bus.js";
+import { RequestContext } from "./request_context.js";
+export interface AgentExecutor {
+    /**
+     * Executes the agent logic based on the request context and publishes events.
+     * @param requestContext The context of the current request.
+     * @param eventBus The bus to publish execution events to.
+     */
+    execute: (requestContext: RequestContext, eventBus: ExecutionEventBus) => Promise<void>;
+    /**
+     * Method to explicitly cancel a running task.
+     * The implementation should handle the logic of stopping the execution
+     * and publishing the final 'canceled' status event on the provided event bus.
+     * @param taskId The ID of the task to cancel.
+     * @param eventBus The event bus associated with the task's execution.
+     */
+    cancelTask: (taskId: string, eventBus: ExecutionEventBus) => Promise<void>;
+}

package/build/src/server/agent_execution/agent_executor.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent_executor.js.map

package/build/src/server/agent_execution/request_context.d.ts

@@ -0,0 +1,9 @@
+import { Message, Task } from "../../types.js";
+export declare class RequestContext {
+    readonly userMessage: Message;
+    readonly task?: Task;
+    readonly referenceTasks?: Task[];
+    readonly taskId: string;
+    readonly contextId: string;
+    constructor(userMessage: Message, taskId: string, contextId: string, task?: Task, referenceTasks?: Task[]);
+}

package/build/src/server/agent_execution/request_context.js

@@ -0,0 +1,15 @@
+export class RequestContext {
+    userMessage;
+    task;
+    referenceTasks;
+    taskId;
+    contextId;
+    constructor(userMessage, taskId, contextId, task, referenceTasks) {
+        this.userMessage = userMessage;
+        this.taskId = taskId;
+        this.contextId = contextId;
+        this.task = task;
+        this.referenceTasks = referenceTasks;
+    }
+}
+//# sourceMappingURL=request_context.js.map

package/build/src/server/error.d.ts

@@ -0,0 +1,23 @@
+import * as schema from "../types.js";
+/**
+ * Custom error class for A2A server operations, incorporating JSON-RPC error codes.
+ */
+export declare class A2AError extends Error {
+    code: number;
+    data?: Record<string, unknown>;
+    taskId?: string;
+    constructor(code: number, message: string, data?: Record<string, unknown>, taskId?: string);
+    /**
+     * Formats the error into a standard JSON-RPC error object structure.
+     */
+    toJSONRPCError(): schema.JSONRPCError;
+    static parseError(message: string, data?: Record<string, unknown>): A2AError;
+    static invalidRequest(message: string, data?: Record<string, unknown>): A2AError;
+    static methodNotFound(method: string): A2AError;
+    static invalidParams(message: string, data?: Record<string, unknown>): A2AError;
+    static internalError(message: string, data?: Record<string, unknown>): A2AError;
+    static taskNotFound(taskId: string): A2AError;
+    static taskNotCancelable(taskId: string): A2AError;
+    static pushNotificationNotSupported(): A2AError;
+    static unsupportedOperation(operation: string): A2AError;
+}

package/build/src/server/error.js

@@ -0,0 +1,57 @@
+/**
+ * Custom error class for A2A server operations, incorporating JSON-RPC error codes.
+ */
+export class A2AError extends Error {
+    code;
+    data;
+    taskId; // Optional task ID context
+    constructor(code, message, data, taskId) {
+        super(message);
+        this.name = "A2AError";
+        this.code = code;
+        this.data = data;
+        this.taskId = taskId; // Store associated task ID if provided
+    }
+    /**
+     * Formats the error into a standard JSON-RPC error object structure.
+     */
+    toJSONRPCError() {
+        const errorObject = {
+            code: this.code,
+            message: this.message,
+        };
+        if (this.data !== undefined) {
+            errorObject.data = this.data;
+        }
+        return errorObject;
+    }
+    // Static factory methods for common errors
+    static parseError(message, data) {
+        return new A2AError(-32700, message, data);
+    }
+    static invalidRequest(message, data) {
+        return new A2AError(-32600, message, data);
+    }
+    static methodNotFound(method) {
+        return new A2AError(-32601, `Method not found: ${method}`);
+    }
+    static invalidParams(message, data) {
+        return new A2AError(-32602, message, data);
+    }
+    static internalError(message, data) {
+        return new A2AError(-32603, message, data);
+    }
+    static taskNotFound(taskId) {
+        return new A2AError(-32001, `Task not found: ${taskId}`, undefined, taskId);
+    }
+    static taskNotCancelable(taskId) {
+        return new A2AError(-32002, `Task not cancelable: ${taskId}`, undefined, taskId);
+    }
+    static pushNotificationNotSupported() {
+        return new A2AError(-32003, "Push Notification is not supported");
+    }
+    static unsupportedOperation(operation) {
+        return new A2AError(-32004, `Unsupported operation: ${operation}`);
+    }
+}
+//# sourceMappingURL=error.js.map

package/build/src/server/events/execution_event_bus.d.ts

@@ -0,0 +1,16 @@
+import { EventEmitter } from 'events';
+import { Message, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent } from "../../types.js";
+export type AgentExecutionEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+export interface ExecutionEventBus {
+    publish(event: AgentExecutionEvent): void;
+    on(eventName: 'event' | 'finished', listener: (event: AgentExecutionEvent) => void): this;
+    off(eventName: 'event' | 'finished', listener: (event: AgentExecutionEvent) => void): this;
+    once(eventName: 'event' | 'finished', listener: (event: AgentExecutionEvent) => void): this;
+    removeAllListeners(eventName?: 'event' | 'finished'): this;
+    finished(): void;
+}
+export declare class DefaultExecutionEventBus extends EventEmitter implements ExecutionEventBus {
+    constructor();
+    publish(event: AgentExecutionEvent): void;
+    finished(): void;
+}

package/build/src/server/events/execution_event_bus.js

@@ -0,0 +1,13 @@
+import { EventEmitter } from 'events';
+export class DefaultExecutionEventBus extends EventEmitter {
+    constructor() {
+        super();
+    }
+    publish(event) {
+        this.emit('event', event);
+    }
+    finished() {
+        this.emit('finished');
+    }
+}
+//# sourceMappingURL=execution_event_bus.js.map

package/build/src/server/events/execution_event_bus_manager.d.ts

@@ -0,0 +1,27 @@
+import { ExecutionEventBus } from "./execution_event_bus.js";
+export interface ExecutionEventBusManager {
+    createOrGetByTaskId(taskId: string): ExecutionEventBus;
+    getByTaskId(taskId: string): ExecutionEventBus | undefined;
+    cleanupByTaskId(taskId: string): void;
+}
+export declare class DefaultExecutionEventBusManager implements ExecutionEventBusManager {
+    private taskIdToBus;
+    /**
+     * Creates or retrieves an existing ExecutionEventBus based on the taskId.
+     * @param taskId The ID of the task.
+     * @returns An instance of IExecutionEventBus.
+     */
+    createOrGetByTaskId(taskId: string): ExecutionEventBus;
+    /**
+     * Retrieves an existing ExecutionEventBus based on the taskId.
+     * @param taskId The ID of the task.
+     * @returns An instance of IExecutionEventBus or undefined if not found.
+     */
+    getByTaskId(taskId: string): ExecutionEventBus | undefined;
+    /**
+     * Removes the event bus for a given taskId.
+     * This should be called when an execution flow is complete to free resources.
+     * @param taskId The ID of the task.
+     */
+    cleanupByTaskId(taskId: string): void;
+}

package/build/src/server/events/execution_event_bus_manager.js

@@ -0,0 +1,36 @@
+import { DefaultExecutionEventBus } from "./execution_event_bus.js";
+export class DefaultExecutionEventBusManager {
+    taskIdToBus = new Map();
+    /**
+     * Creates or retrieves an existing ExecutionEventBus based on the taskId.
+     * @param taskId The ID of the task.
+     * @returns An instance of IExecutionEventBus.
+     */
+    createOrGetByTaskId(taskId) {
+        if (!this.taskIdToBus.has(taskId)) {
+            this.taskIdToBus.set(taskId, new DefaultExecutionEventBus());
+        }
+        return this.taskIdToBus.get(taskId);
+    }
+    /**
+     * Retrieves an existing ExecutionEventBus based on the taskId.
+     * @param taskId The ID of the task.
+     * @returns An instance of IExecutionEventBus or undefined if not found.
+     */
+    getByTaskId(taskId) {
+        return this.taskIdToBus.get(taskId);
+    }
+    /**
+     * Removes the event bus for a given taskId.
+     * This should be called when an execution flow is complete to free resources.
+     * @param taskId The ID of the task.
+     */
+    cleanupByTaskId(taskId) {
+        const bus = this.taskIdToBus.get(taskId);
+        if (bus) {
+            bus.removeAllListeners();
+        }
+        this.taskIdToBus.delete(taskId);
+    }
+}
+//# sourceMappingURL=execution_event_bus_manager.js.map

package/build/src/server/events/execution_event_queue.d.ts

@@ -0,0 +1,24 @@
+import { ExecutionEventBus, AgentExecutionEvent } from "./execution_event_bus.js";
+/**
+ * An async queue that subscribes to an ExecutionEventBus for events
+ * and provides an async generator to consume them.
+ */
+export declare class ExecutionEventQueue {
+    private eventBus;
+    private eventQueue;
+    private resolvePromise?;
+    private stopped;
+    private boundHandleEvent;
+    constructor(eventBus: ExecutionEventBus);
+    private handleEvent;
+    private handleFinished;
+    /**
+     * Provides an async generator that yields events from the event bus.
+     * Stops when a Message event is received or a TaskStatusUpdateEvent with final=true is received.
+     */
+    events(): AsyncGenerator<AgentExecutionEvent, void, undefined>;
+    /**
+     * Stops the event queue from processing further events.
+     */
+    stop(): void;
+}

package/build/src/server/events/execution_event_queue.js

@@ -0,0 +1,63 @@
+/**
+ * An async queue that subscribes to an ExecutionEventBus for events
+ * and provides an async generator to consume them.
+ */
+export class ExecutionEventQueue {
+    eventBus;
+    eventQueue = [];
+    resolvePromise;
+    stopped = false;
+    boundHandleEvent;
+    constructor(eventBus) {
+        this.eventBus = eventBus;
+        this.eventBus.on('event', this.handleEvent);
+        this.eventBus.on('finished', this.handleFinished);
+    }
+    handleEvent = (event) => {
+        if (this.stopped)
+            return;
+        this.eventQueue.push(event);
+        if (this.resolvePromise) {
+            this.resolvePromise();
+            this.resolvePromise = undefined;
+        }
+    };
+    handleFinished = () => {
+        this.stop();
+    };
+    /**
+     * Provides an async generator that yields events from the event bus.
+     * Stops when a Message event is received or a TaskStatusUpdateEvent with final=true is received.
+     */
+    async *events() {
+        while (!this.stopped || this.eventQueue.length > 0) {
+            if (this.eventQueue.length > 0) {
+                const event = this.eventQueue.shift();
+                yield event;
+                if (event.kind === 'message' || (event.kind === 'status-update' &&
+                    event.final)) {
+                    this.handleFinished();
+                    break;
+                }
+            }
+            else if (!this.stopped) {
+                await new Promise((resolve) => {
+                    this.resolvePromise = resolve;
+                });
+            }
+        }
+    }
+    /**
+     * Stops the event queue from processing further events.
+     */
+    stop() {
+        this.stopped = true;
+        if (this.resolvePromise) {
+            this.resolvePromise(); // Unblock any pending await
+            this.resolvePromise = undefined;
+        }
+        this.eventBus.off('event', this.handleEvent);
+        this.eventBus.off('finished', this.handleFinished);
+    }
+}
+//# sourceMappingURL=execution_event_queue.js.map

package/build/src/server/request_handler/a2a_request_handler.d.ts

@@ -0,0 +1,11 @@
+import { Message, AgentCard, MessageSendParams, Task, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, TaskQueryParams, TaskIdParams, TaskPushNotificationConfig } from "../../types.js";
+export interface A2ARequestHandler {
+    getAgentCard(): Promise<AgentCard>;
+    sendMessage(params: MessageSendParams): Promise<Message | Task>;
+    sendMessageStream(params: MessageSendParams): AsyncGenerator<Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    getTask(params: TaskQueryParams): Promise<Task>;
+    cancelTask(params: TaskIdParams): Promise<Task>;
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
+    getTaskPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig>;
+    resubscribe(params: TaskIdParams): AsyncGenerator<Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+}

package/build/src/server/request_handler/a2a_request_handler.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=a2a_request_handler.js.map

package/build/src/server/request_handler/default_request_handler.d.ts

@@ -0,0 +1,22 @@
+import { Message, AgentCard, Task, MessageSendParams, TaskStatusUpdateEvent, TaskArtifactUpdateEvent, TaskQueryParams, TaskIdParams, TaskPushNotificationConfig } from "../../types.js";
+import { AgentExecutor } from "../agent_execution/agent_executor.js";
+import { ExecutionEventBusManager } from "../events/execution_event_bus_manager.js";
+import { TaskStore } from "../store.js";
+import { A2ARequestHandler } from "./a2a_request_handler.js";
+export declare class DefaultRequestHandler implements A2ARequestHandler {
+    private readonly agentCard;
+    private readonly taskStore;
+    private readonly agentExecutor;
+    private readonly eventBusManager;
+    private readonly pushNotificationConfigs;
+    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager);
+    getAgentCard(): Promise<AgentCard>;
+    private _createRequestContext;
+    sendMessage(params: MessageSendParams): Promise<Message | Task>;
+    sendMessageStream(params: MessageSendParams): AsyncGenerator<Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    getTask(params: TaskQueryParams): Promise<Task>;
+    cancelTask(params: TaskIdParams): Promise<Task>;
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig): Promise<TaskPushNotificationConfig>;
+    getTaskPushNotificationConfig(params: TaskIdParams): Promise<TaskPushNotificationConfig>;
+    resubscribe(params: TaskIdParams): AsyncGenerator<Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+}