@mailmodo/a2a 0.3.3 → 0.3.5

package/dist/client/index.mjs

@@ -0,0 +1,367 @@
+import {
+  A2AClient,
+  JsonRpcTransport,
+  JsonRpcTransportFactory,
+  PushNotificationNotSupportedError,
+  createAuthenticatingFetchWithRetry
+} from "../chunk-UBRSFN2J.mjs";
+import {
+  AGENT_CARD_PATH
+} from "../chunk-PHP7LM4Y.mjs";
+
+// src/client/card-resolver.ts
+var DefaultAgentCardResolver = class {
+  constructor(options) {
+    this.options = options;
+  }
+  /**
+   * Fetches the agent card based on provided base URL and path.
+   * Path is selected in the following order:
+   * 1) path parameter
+   * 2) path from options
+   * 3) .well-known/agent-card.json
+   */
+  async resolve(baseUrl, path) {
+    const agentCardUrl = new URL(path ?? this.options?.path ?? AGENT_CARD_PATH, baseUrl);
+    const response = await this.fetchImpl(agentCardUrl);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status}`);
+    }
+    return await response.json();
+  }
+  fetchImpl(...args) {
+    if (this.options?.fetchImpl) {
+      return this.options.fetchImpl(...args);
+    }
+    return fetch(...args);
+  }
+};
+var AgentCardResolver = {
+  Default: new DefaultAgentCardResolver()
+};
+
+// src/client/multitransport-client.ts
+var Client = class {
+  constructor(transport, agentCard, config) {
+    this.transport = transport;
+    this.agentCard = agentCard;
+    this.config = config;
+  }
+  /**
+   * Sends a message to an agent to initiate a new interaction or to continue an existing one.
+   * Uses blocking mode by default.
+   */
+  sendMessage(params, options) {
+    params = this.applyClientConfig({
+      params,
+      blocking: !(this.config?.polling ?? false)
+    });
+    return this.executeWithInterceptors(
+      { method: "sendMessage", value: params },
+      options,
+      this.transport.sendMessage.bind(this.transport)
+    );
+  }
+  /**
+   * Sends a message to an agent to initiate/continue a task AND subscribes the client to real-time updates for that task.
+   * Performs fallback to non-streaming if not supported by the agent.
+   */
+  async *sendMessageStream(params, options) {
+    const method = "sendMessageStream";
+    params = this.applyClientConfig({ params, blocking: true });
+    const beforeArgs = {
+      input: { method, value: params },
+      options
+    };
+    const beforeResult = await this.interceptBefore(beforeArgs);
+    if (beforeResult) {
+      const earlyReturn = beforeResult.earlyReturn.value;
+      const afterArgs = {
+        result: { method, value: earlyReturn },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs, beforeResult.executed);
+      yield afterArgs.result.value;
+      return;
+    }
+    if (!this.agentCard.capabilities.streaming) {
+      const result = await this.transport.sendMessage(beforeArgs.input.value, beforeArgs.options);
+      const afterArgs = {
+        result: { method, value: result },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs);
+      yield afterArgs.result.value;
+      return;
+    }
+    for await (const event of this.transport.sendMessageStream(
+      beforeArgs.input.value,
+      beforeArgs.options
+    )) {
+      const afterArgs = {
+        result: { method, value: event },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs);
+      yield afterArgs.result.value;
+      if (afterArgs.earlyReturn) {
+        return;
+      }
+    }
+  }
+  /**
+   * Sets or updates the push notification configuration for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  setTaskPushNotificationConfig(params, options) {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.executeWithInterceptors(
+      { method: "setTaskPushNotificationConfig", value: params },
+      options,
+      this.transport.setTaskPushNotificationConfig.bind(this.transport)
+    );
+  }
+  /**
+   * Retrieves the current push notification configuration for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  getTaskPushNotificationConfig(params, options) {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.executeWithInterceptors(
+      { method: "getTaskPushNotificationConfig", value: params },
+      options,
+      this.transport.getTaskPushNotificationConfig.bind(this.transport)
+    );
+  }
+  /**
+   * Retrieves the associated push notification configurations for a specified task.
+   * Requires the server to have AgentCard.capabilities.pushNotifications: true.
+   */
+  listTaskPushNotificationConfig(params, options) {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      throw new PushNotificationNotSupportedError();
+    }
+    return this.executeWithInterceptors(
+      { method: "listTaskPushNotificationConfig", value: params },
+      options,
+      this.transport.listTaskPushNotificationConfig.bind(this.transport)
+    );
+  }
+  /**
+   * Deletes an associated push notification configuration for a task.
+   */
+  deleteTaskPushNotificationConfig(params, options) {
+    return this.executeWithInterceptors(
+      { method: "deleteTaskPushNotificationConfig", value: params },
+      options,
+      this.transport.deleteTaskPushNotificationConfig.bind(this.transport)
+    );
+  }
+  /**
+   * Retrieves the current state (including status, artifacts, and optionally history) of a previously initiated task.
+   */
+  getTask(params, options) {
+    return this.executeWithInterceptors(
+      { method: "getTask", value: params },
+      options,
+      this.transport.getTask.bind(this.transport)
+    );
+  }
+  /**
+   * Requests the cancellation of an ongoing task. The server will attempt to cancel the task,
+   * but success is not guaranteed (e.g., the task might have already completed or failed, or cancellation might not be supported at its current stage).
+   */
+  cancelTask(params, options) {
+    return this.executeWithInterceptors(
+      { method: "cancelTask", value: params },
+      options,
+      this.transport.cancelTask.bind(this.transport)
+    );
+  }
+  /**
+   * Allows a client to reconnect to an updates stream for an ongoing task after a previous connection was interrupted.
+   */
+  async *resubscribeTask(params, options) {
+    const method = "resubscribeTask";
+    const beforeArgs = { input: { method, value: params }, options };
+    const beforeResult = await this.interceptBefore(beforeArgs);
+    if (beforeResult) {
+      const earlyReturn = beforeResult.earlyReturn.value;
+      const afterArgs = {
+        result: { method, value: earlyReturn },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs, beforeResult.executed);
+      yield afterArgs.result.value;
+      return;
+    }
+    for await (const event of this.transport.resubscribeTask(
+      beforeArgs.input.value,
+      beforeArgs.options
+    )) {
+      const afterArgs = {
+        result: { method, value: event },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs);
+      yield afterArgs.result.value;
+      if (afterArgs.earlyReturn) {
+        return;
+      }
+    }
+  }
+  applyClientConfig({
+    params,
+    blocking
+  }) {
+    const result = { ...params, configuration: params.configuration ?? {} };
+    if (!result.configuration.acceptedOutputModes && this.config?.acceptedOutputModes) {
+      result.configuration.acceptedOutputModes = this.config.acceptedOutputModes;
+    }
+    if (!result.configuration.pushNotificationConfig && this.config?.pushNotificationConfig) {
+      result.configuration.pushNotificationConfig = this.config.pushNotificationConfig;
+    }
+    result.configuration.blocking ??= blocking;
+    return result;
+  }
+  async executeWithInterceptors(input, options, transportCall) {
+    const beforeArgs = {
+      input,
+      options
+    };
+    const beforeResult = await this.interceptBefore(beforeArgs);
+    if (beforeResult) {
+      const afterArgs2 = {
+        result: {
+          method: input.method,
+          value: beforeResult.earlyReturn.value
+        },
+        options: beforeArgs.options
+      };
+      await this.interceptAfter(afterArgs2, beforeResult.executed);
+      return afterArgs2.result.value;
+    }
+    const result = await transportCall(beforeArgs.input.value, beforeArgs.options);
+    const afterArgs = {
+      result: { method: input.method, value: result },
+      options: beforeArgs.options
+    };
+    await this.interceptAfter(afterArgs);
+    return afterArgs.result.value;
+  }
+  async interceptBefore(args) {
+    if (!this.config?.interceptors || this.config.interceptors.length === 0) {
+      return;
+    }
+    const executed = [];
+    for (const interceptor of this.config.interceptors) {
+      await interceptor.before(args);
+      executed.push(interceptor);
+      if (args.earlyReturn) {
+        return {
+          earlyReturn: args.earlyReturn,
+          executed
+        };
+      }
+    }
+  }
+  async interceptAfter(args, interceptors) {
+    if (!this.config?.interceptors || this.config.interceptors.length === 0) {
+      return;
+    }
+    for (const interceptor of interceptors ?? this.config.interceptors) {
+      await interceptor.after(args);
+      if (args.earlyReturn) {
+        return;
+      }
+    }
+  }
+};
+
+// src/client/factory.ts
+var ClientFactoryOptions = {
+  Default: {
+    transports: [new JsonRpcTransportFactory()]
+  }
+};
+var ClientFactory = class {
+  constructor(options = ClientFactoryOptions.Default) {
+    this.options = options;
+    if (!options.transports || options.transports.length === 0) {
+      throw new Error("No transports provided");
+    }
+    for (const transport of options.transports) {
+      if (this.transportsByName.has(transport.protocolName)) {
+        throw new Error(`Duplicate transport name: ${transport.protocolName}`);
+      }
+      this.transportsByName.set(transport.protocolName, transport);
+    }
+    for (const transport of options.preferredTransports ?? []) {
+      const factory = this.options.transports.find((t) => t.protocolName === transport);
+      if (!factory) {
+        throw new Error(
+          `Unknown preferred transport: ${transport}, available transports: ${[...this.transportsByName.keys()].join()}`
+        );
+      }
+    }
+    this.agentCardResolver = options.cardResolver ?? AgentCardResolver.Default;
+  }
+  transportsByName = /* @__PURE__ */ new Map();
+  agentCardResolver;
+  /**
+   * Creates a new client from the provided agent card.
+   */
+  async createFromAgentCard(agentCard) {
+    const agentCardPreferred = agentCard.preferredTransport ?? JsonRpcTransportFactory.name;
+    const additionalInterfaces = agentCard.additionalInterfaces ?? [];
+    const urlsPerAgentTransports = new Map([
+      [agentCardPreferred, agentCard.url],
+      ...additionalInterfaces.map((i) => [i.transport, i.url])
+    ]);
+    const transportsByPreference = [
+      ...this.options.preferredTransports ?? [],
+      agentCardPreferred,
+      ...additionalInterfaces.map((i) => i.transport)
+    ];
+    for (const transport of transportsByPreference) {
+      if (!urlsPerAgentTransports.has(transport)) {
+        continue;
+      }
+      const factory = this.transportsByName.get(transport);
+      if (!factory) {
+        continue;
+      }
+      return new Client(
+        await factory.create(urlsPerAgentTransports.get(transport), agentCard),
+        agentCard,
+        this.options.clientConfig
+      );
+    }
+    throw new Error(
+      "No compatible transport found, available transports: " + [...this.transportsByName.keys()].join()
+    );
+  }
+  /**
+   * Downloads agent card using AgentCardResolver from options
+   * and creates a new client from the downloaded card.
+   */
+  async createFromAgentCardUrl(baseUrl, path) {
+    const agentCard = await this.agentCardResolver.resolve(baseUrl, path);
+    return await this.createFromAgentCard(agentCard);
+  }
+};
+export {
+  A2AClient,
+  AgentCardResolver,
+  Client,
+  ClientFactory,
+  ClientFactoryOptions,
+  DefaultAgentCardResolver,
+  JsonRpcTransport,
+  JsonRpcTransportFactory,
+  createAuthenticatingFetchWithRetry
+};

package/dist/error-DExKs0Q3.d.mts

@@ -0,0 +1,233 @@
+import { a as Message, T as Task, b as TaskStatusUpdateEvent, c as TaskArtifactUpdateEvent, V as PushNotificationConfig, A as AgentCard, M as MessageSendParams, i as TaskQueryParams, f as TaskIdParams, d as TaskPushNotificationConfig, a8 as GetTaskPushNotificationConfigParams, L as ListTaskPushNotificationConfigParams, D as DeleteTaskPushNotificationConfigParams, J as JSONRPCResponse, ax as JSONRPCError } from './types-Due_Cv6t.mjs';
+import { S as ServerCallContext, A as A2ARequestHandler } from './a2a_request_handler-DPkhsCMt.mjs';
+import { EventEmitter } from 'events';
+
+type AgentExecutionEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
+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;
+}
+declare class DefaultExecutionEventBus extends EventEmitter implements ExecutionEventBus {
+    constructor();
+    publish(event: AgentExecutionEvent): void;
+    finished(): void;
+}
+
+declare class RequestContext {
+    readonly userMessage: Message;
+    readonly taskId: string;
+    readonly contextId: string;
+    readonly task?: Task;
+    readonly referenceTasks?: Task[];
+    readonly context?: ServerCallContext;
+    constructor(userMessage: Message, taskId: string, contextId: string, task?: Task, referenceTasks?: Task[], context?: ServerCallContext);
+}
+
+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>;
+}
+
+interface ExecutionEventBusManager {
+    createOrGetByTaskId(taskId: string): ExecutionEventBus;
+    getByTaskId(taskId: string): ExecutionEventBus | undefined;
+    cleanupByTaskId(taskId: string): void;
+}
+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;
+}
+
+/**
+ * An async queue that subscribes to an ExecutionEventBus for events
+ * and provides an async generator to consume them.
+ */
+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;
+}
+
+/**
+ * Simplified interface for task storage providers.
+ * Stores and retrieves the task.
+ */
+interface TaskStore {
+    /**
+     * Saves a task.
+     * Overwrites existing data if the task ID exists.
+     * @param data An object containing the task.
+     * @returns A promise resolving when the save operation is complete.
+     */
+    save(task: Task): Promise<void>;
+    /**
+     * Loads a task by task ID.
+     * @param taskId The ID of the task to load.
+     * @returns A promise resolving to an object containing the Task, or undefined if not found.
+     */
+    load(taskId: string): Promise<Task | undefined>;
+}
+declare class InMemoryTaskStore implements TaskStore {
+    private store;
+    load(taskId: string): Promise<Task | undefined>;
+    save(task: Task): Promise<void>;
+}
+
+interface PushNotificationStore {
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+declare class InMemoryPushNotificationStore implements PushNotificationStore {
+    private store;
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+
+interface PushNotificationSender {
+    send(task: Task): Promise<void>;
+}
+
+declare class DefaultRequestHandler implements A2ARequestHandler {
+    private readonly agentCard;
+    private readonly taskStore;
+    private readonly agentExecutor;
+    private readonly eventBusManager;
+    private readonly pushNotificationStore?;
+    private readonly pushNotificationSender?;
+    private readonly extendedAgentCardProvider?;
+    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager, pushNotificationStore?: PushNotificationStore, pushNotificationSender?: PushNotificationSender, extendedAgentCardProvider?: AgentCard | ExtendedAgentCardProvider);
+    getAgentCard(): Promise<AgentCard>;
+    getAuthenticatedExtendedAgentCard(context?: ServerCallContext): Promise<AgentCard>;
+    private _createRequestContext;
+    private _processEvents;
+    sendMessage(params: MessageSendParams, context?: ServerCallContext): Promise<Message | Task>;
+    sendMessageStream(params: MessageSendParams, context?: ServerCallContext): AsyncGenerator<Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    getTask(params: TaskQueryParams, _context?: ServerCallContext): Promise<Task>;
+    cancelTask(params: TaskIdParams, _context?: ServerCallContext): Promise<Task>;
+    setTaskPushNotificationConfig(params: TaskPushNotificationConfig, _context?: ServerCallContext): Promise<TaskPushNotificationConfig>;
+    getTaskPushNotificationConfig(params: TaskIdParams | GetTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<TaskPushNotificationConfig>;
+    listTaskPushNotificationConfigs(params: ListTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<TaskPushNotificationConfig[]>;
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams, _context?: ServerCallContext): Promise<void>;
+    resubscribe(params: TaskIdParams, _context?: ServerCallContext): AsyncGenerator<Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    private _sendPushNotificationIfNeeded;
+    private _handleProcessingError;
+}
+type ExtendedAgentCardProvider = (context?: ServerCallContext) => Promise<AgentCard>;
+
+declare class ResultManager {
+    private taskStore;
+    private currentTask?;
+    private latestUserMessage?;
+    private finalMessageResult?;
+    constructor(taskStore: TaskStore);
+    setContext(latestUserMessage: Message): void;
+    /**
+     * Processes an agent execution event and updates the task store.
+     * @param event The agent execution event.
+     */
+    processEvent(event: AgentExecutionEvent): Promise<void>;
+    private saveCurrentTask;
+    /**
+     * Gets the final result, which could be a Message or a Task.
+     * This should be called after the event stream has been fully processed.
+     * @returns The final Message or the current Task.
+     */
+    getFinalResult(): Message | Task | undefined;
+    /**
+     * Gets the task currently being managed by this ResultManager instance.
+     * This task could be one that was started with or one created during agent execution.
+     * @returns The current Task or undefined if no task is active.
+     */
+    getCurrentTask(): Task | undefined;
+}
+
+/**
+ * Handles JSON-RPC transport layer, routing requests to A2ARequestHandler.
+ */
+declare class JsonRpcTransportHandler {
+    private requestHandler;
+    constructor(requestHandler: A2ARequestHandler);
+    /**
+     * Handles an incoming JSON-RPC request.
+     * For streaming methods, it returns an AsyncGenerator of JSONRPCResult.
+     * For non-streaming methods, it returns a Promise of a single JSONRPCMessage (Result or ErrorResponse).
+     */
+    handle(requestBody: any, context?: ServerCallContext): Promise<JSONRPCResponse | AsyncGenerator<JSONRPCResponse, void, undefined>>;
+    private isRequestValid;
+    private paramsAreValid;
+}
+
+/**
+ * Custom error class for A2A server operations, incorporating JSON-RPC error codes.
+ */
+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(): 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;
+    static authenticatedExtendedCardNotConfigured(): A2AError;
+}
+
+export { type AgentExecutor as A, DefaultExecutionEventBus as D, type ExecutionEventBus as E, InMemoryTaskStore as I, JsonRpcTransportHandler as J, type PushNotificationSender as P, RequestContext as R, type TaskStore as T, type PushNotificationStore as a, type AgentExecutionEvent as b, type ExecutionEventBusManager as c, DefaultExecutionEventBusManager as d, ExecutionEventQueue as e, DefaultRequestHandler as f, type ExtendedAgentCardProvider as g, ResultManager as h, A2AError as i, InMemoryPushNotificationStore as j };