@ap3x/a2a 1.0.0 → 2.0.0

package/dist/index.js

@@ -0,0 +1,454 @@
+import {
+  A2A_CARD_PROTOCOL_VERSION,
+  A2A_ERROR_CODES,
+  A2A_PROTOCOL_VERSION,
+  A2A_REST_ROUTES,
+  A2A_RPC_METHODS,
+  A2A_RPC_METHOD_ALIASES,
+  A2A_VERSION_HEADER,
+  A2aClient,
+  A2aClientError,
+  A2aExecutor,
+  A2aServer,
+  AGENT_CARD_PATH,
+  AgentCapabilitiesSchema,
+  AgentCardSchema,
+  AgentInterfaceSchema,
+  AgentProviderSchema,
+  AgentSkillSchema,
+  ArtifactSchema,
+  BearerSecuritySchemeSchema,
+  DEFAULT_TIMEOUT_MS,
+  DataPartSchema,
+  IllegalTaskTransitionError,
+  JsonRpcRequestSchema,
+  MessageSchema,
+  MessageSendParamsSchema,
+  PartSchema,
+  RawPartSchema,
+  RemoteAgentCardSchema,
+  RemoteAgentInterfaceSchema,
+  RestErrorBodySchema,
+  TASK_STATES,
+  TERMINAL_TASK_STATES,
+  TaskArtifactUpdateEventSchema,
+  TaskIdParamsSchema,
+  TaskListParamsSchema,
+  TaskNotFoundError,
+  TaskSchema,
+  TaskStateSchema,
+  TaskStatusSchema,
+  TaskStatusUpdateEventSchema,
+  TaskStore,
+  TextPartSchema,
+  UrlPartSchema,
+  agentMessageText,
+  constantTimeEqual,
+  handleJsonRpc,
+  handleRest,
+  isMessageFrame,
+  isStatusUpdateFrame,
+  isTaskFrame,
+  isTerminal,
+  messageText,
+  normalizeRemoteCard,
+  normalizeTaskState,
+  normalizeWireTaskStates,
+  resolveBlocking,
+  restStatusFor,
+  serveA2a,
+  startSse
+} from "./chunk-PYM7LV6R.js";
+
+// src/backend.ts
+import { uuidv7 } from "@ap3x/agent-core";
+function zeroUsage() {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+  };
+}
+var ABORTED_MESSAGE = "A2A run canceled: abort() requested";
+var DEFAULT_POLL_INITIAL_MS = 250;
+var DEFAULT_POLL_MAX_MS = 5e3;
+var DEFAULT_RUN_TIMEOUT_MS = 10 * 60 * 1e3;
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function makeEventStream(run) {
+  const queue = [];
+  const waiters = [];
+  let done = false;
+  const emit = (event) => {
+    const waiter = waiters.shift();
+    if (waiter) waiter({ value: event, done: false });
+    else queue.push(event);
+  };
+  const resultPromise = run(emit).finally(() => {
+    done = true;
+    while (waiters.length > 0) {
+      waiters.shift()?.({ value: void 0, done: true });
+    }
+  });
+  return {
+    result: () => resultPromise,
+    async *[Symbol.asyncIterator]() {
+      while (true) {
+        if (queue.length > 0) {
+          yield queue.shift();
+        } else if (done) {
+          return;
+        } else {
+          const next = await new Promise((resolve) => {
+            waiters.push(resolve);
+          });
+          if (next.done) return;
+          yield next.value;
+        }
+      }
+    }
+  };
+}
+var A2aBackend = class _A2aBackend {
+  card;
+  /** Present only when the card declares `capabilities.streaming`. */
+  runStream;
+  client;
+  options;
+  pollInitialDelayMs;
+  pollMaxDelayMs;
+  timeoutMs;
+  sleep;
+  now;
+  /** One conversational thread per instance; adopted from the first answer. */
+  contextId;
+  currentTaskId;
+  /** Aborts the in-flight HTTP request of the current run/stream. */
+  runAbort;
+  closed = false;
+  /** Clones share the client (one grpc channel); the channel closes at zero. */
+  clientRefs;
+  constructor(client, options = {}, refs) {
+    this.client = client;
+    this.card = client.card;
+    this.options = options;
+    this.clientRefs = refs ?? { count: 1 };
+    this.pollInitialDelayMs = Math.max(1, options.pollInitialDelayMs ?? DEFAULT_POLL_INITIAL_MS);
+    this.pollMaxDelayMs = Math.max(
+      this.pollInitialDelayMs,
+      options.pollMaxDelayMs ?? DEFAULT_POLL_MAX_MS
+    );
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_RUN_TIMEOUT_MS;
+    this.sleep = options.sleep ?? defaultSleep;
+    this.now = options.now ?? (() => Date.now());
+    if (this.card.capabilities.streaming) {
+      this.runStream = (task, opts) => this.streamRun(task, opts);
+    }
+  }
+  async run(task, opts) {
+    const controller = new AbortController();
+    this.runAbort = controller;
+    const onAbort = () => this.abort();
+    opts?.signal?.addEventListener("abort", onAbort, { once: true });
+    if (opts?.signal?.aborted) this.abort();
+    try {
+      const message = this.outbound(task);
+      const answer = await this.client.sendMessage(message, void 0, controller.signal);
+      if (!("status" in answer)) {
+        if (answer.contextId !== void 0) this.contextId ??= answer.contextId;
+        const finalText = messageText(answer);
+        return {
+          messages: [this.assistant(finalText, "stop")],
+          finalText,
+          usage: zeroUsage(),
+          stopReason: "stop"
+        };
+      }
+      let remote = answer;
+      this.adopt(remote.id, remote.contextId);
+      const deadline = this.now() + this.timeoutMs;
+      let delay = this.pollInitialDelayMs;
+      while (!isTerminal(remote.status.state)) {
+        if (this.now() >= deadline) {
+          void this.cancelRemote();
+          return this.failure(`A2A task ${remote.id} timed out after ${this.timeoutMs}ms`);
+        }
+        await this.sleep(delay);
+        delay = Math.min(delay * 2, this.pollMaxDelayMs);
+        remote = await this.client.getTask(remote.id, controller.signal);
+      }
+      return this.toRunResult(remote, message.messageId);
+    } catch (error) {
+      if (controller.signal.aborted) return this.failure(ABORTED_MESSAGE);
+      return this.failure(error instanceof Error ? error.message : String(error));
+    } finally {
+      this.currentTaskId = void 0;
+      this.runAbort = void 0;
+      opts?.signal?.removeEventListener("abort", onAbort);
+    }
+  }
+  /**
+   * Cancel the current run: aborts the in-flight HTTP request (even a blocking
+   * send with no task id yet) and, when a task id is known, issues a
+   * best-effort remote CancelTask.
+   */
+  abort() {
+    void this.cancelRemote();
+    this.runAbort?.abort();
+  }
+  /** A new backend over the SAME client/card (a remote agent is one endpoint). */
+  clone() {
+    this.clientRefs.count += 1;
+    return new _A2aBackend(this.client, this.options, this.clientRefs);
+  }
+  /**
+   * Release the shared client once EVERY clone has closed (refcounted): the
+   * underlying transport (the grpc channel, when negotiated) is released only
+   * when the last backend over it closes. Idempotent per backend.
+   */
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.clientRefs.count -= 1;
+    if (this.clientRefs.count === 0) this.client.close();
+  }
+  [Symbol.dispose]() {
+    this.close();
+  }
+  async [Symbol.asyncDispose]() {
+    this.close();
+  }
+  supports(capability) {
+    switch (capability) {
+      case "stream":
+        return this.card.capabilities.streaming;
+      case "abort":
+      case "clone":
+        return true;
+      default:
+        return false;
+    }
+  }
+  async cancelRemote() {
+    const id = this.currentTaskId;
+    if (id === void 0) return;
+    try {
+      await this.client.cancelTask(id);
+    } catch {
+    }
+  }
+  adopt(taskId, contextId) {
+    this.currentTaskId = taskId;
+    this.contextId ??= contextId;
+  }
+  outbound(task) {
+    const text = typeof task === "string" ? task : task.map((message) => agentMessageText(message)).filter((chunk) => chunk.length > 0).join("\n");
+    return {
+      messageId: uuidv7(),
+      role: "user",
+      parts: [{ kind: "text", text }],
+      ...this.contextId !== void 0 ? { contextId: this.contextId } : {}
+    };
+  }
+  assistant(text, stopReason, errorMessage) {
+    return {
+      role: "assistant",
+      content: [{ type: "text", text }],
+      api: "a2a",
+      provider: "a2a",
+      model: this.card.name,
+      usage: zeroUsage(),
+      stopReason,
+      ...errorMessage !== void 0 ? { errorMessage } : {},
+      timestamp: this.now()
+    };
+  }
+  inbound(message) {
+    if (message.role === "user") {
+      return { role: "user", content: messageText(message), timestamp: this.now() };
+    }
+    return this.assistant(messageText(message), "stop");
+  }
+  failure(errorMessage) {
+    return {
+      messages: [this.assistant("", "error", errorMessage)],
+      finalText: "",
+      usage: zeroUsage(),
+      stopReason: "error",
+      errorMessage
+    };
+  }
+  /** Map a TERMINAL remote task back to the uniform backend result. */
+  toRunResult(remote, sentMessageId) {
+    const statusText = remote.status.message ? messageText(remote.status.message) : "";
+    if (remote.status.state !== "completed") {
+      return this.failure(statusText || `A2A task ${remote.id} ${remote.status.state}`);
+    }
+    const messages = (remote.history ?? []).filter((message) => message.messageId !== sentMessageId).map((message) => this.inbound(message));
+    const lastAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+    const finalText = statusText || (lastAssistant?.content ?? []).filter((block) => block.type === "text").map((block) => block.text).join("\n");
+    if (!lastAssistant) messages.push(this.assistant(finalText, "stop"));
+    return { messages, finalText, usage: zeroUsage(), stopReason: "stop" };
+  }
+  streamRun(task, opts) {
+    return makeEventStream(async (emit) => {
+      const controller = new AbortController();
+      this.runAbort = controller;
+      const onAbort = () => this.abort();
+      opts?.signal?.addEventListener("abort", onAbort, { once: true });
+      if (opts?.signal?.aborted) this.abort();
+      try {
+        emit({ type: "agent_start" });
+        const message = this.outbound(task);
+        let terminal;
+        let direct = false;
+        let accumulated = "";
+        for await (const frame of this.client.sendStreamingMessage(message, controller.signal)) {
+          if (isMessageFrame(frame)) {
+            if (frame.contextId !== void 0) this.contextId ??= frame.contextId;
+            const delta2 = messageText(frame);
+            if (delta2.length > 0) {
+              accumulated += delta2;
+              const partial = this.assistant(accumulated, "stop");
+              emit({
+                type: "message_update",
+                message: partial,
+                assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: delta2, partial }
+              });
+            }
+            direct = true;
+            break;
+          }
+          if (isTaskFrame(frame)) {
+            this.adopt(frame.id, frame.contextId);
+            if (isTerminal(frame.status.state)) {
+              terminal = { taskId: frame.id, status: frame.status };
+              break;
+            }
+            continue;
+          }
+          if (!isStatusUpdateFrame(frame)) continue;
+          this.adopt(frame.taskId, frame.contextId);
+          if (frame.final) {
+            terminal = { taskId: frame.taskId, status: frame.status };
+            break;
+          }
+          const delta = frame.status.message ? messageText(frame.status.message) : "";
+          if (frame.status.state === "working" && delta.length > 0) {
+            accumulated += delta;
+            const partial = this.assistant(accumulated, "stop");
+            emit({
+              type: "message_update",
+              message: partial,
+              assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta, partial }
+            });
+          }
+        }
+        let final;
+        if (direct) {
+          final = this.assistant(accumulated, "stop");
+        } else if (!terminal) {
+          final = this.assistant("", "error", "A2A stream ended without a terminal event");
+        } else if (terminal.status.state === "completed") {
+          const text = terminal.status.message ? messageText(terminal.status.message) : accumulated;
+          final = this.assistant(text, "stop");
+        } else {
+          const text = terminal.status.message ? messageText(terminal.status.message) : "";
+          final = this.assistant(
+            "",
+            "error",
+            text || `A2A task ${terminal.taskId} ${terminal.status.state}`
+          );
+        }
+        emit({ type: "message_end", message: final });
+        const messages = [final];
+        emit({ type: "agent_end", messages });
+        return messages;
+      } catch (error) {
+        const final = this.assistant(
+          "",
+          "error",
+          controller.signal.aborted ? ABORTED_MESSAGE : error instanceof Error ? error.message : String(error)
+        );
+        const messages = [final];
+        emit({ type: "agent_end", messages });
+        return messages;
+      } finally {
+        this.currentTaskId = void 0;
+        this.runAbort = void 0;
+        opts?.signal?.removeEventListener("abort", onAbort);
+      }
+    });
+  }
+};
+async function connectA2a(baseUrl, options = {}) {
+  const client = await A2aClient.connect(baseUrl, options);
+  return new A2aBackend(client, options);
+}
+export {
+  A2A_CARD_PROTOCOL_VERSION,
+  A2A_ERROR_CODES,
+  A2A_PROTOCOL_VERSION,
+  A2A_REST_ROUTES,
+  A2A_RPC_METHODS,
+  A2A_RPC_METHOD_ALIASES,
+  A2A_VERSION_HEADER,
+  A2aBackend,
+  A2aClient,
+  A2aClientError,
+  A2aExecutor,
+  A2aServer,
+  AGENT_CARD_PATH,
+  AgentCapabilitiesSchema,
+  AgentCardSchema,
+  AgentInterfaceSchema,
+  AgentProviderSchema,
+  AgentSkillSchema,
+  ArtifactSchema,
+  BearerSecuritySchemeSchema,
+  DEFAULT_TIMEOUT_MS,
+  DataPartSchema,
+  IllegalTaskTransitionError,
+  JsonRpcRequestSchema,
+  MessageSchema,
+  MessageSendParamsSchema,
+  PartSchema,
+  RawPartSchema,
+  RemoteAgentCardSchema,
+  RemoteAgentInterfaceSchema,
+  RestErrorBodySchema,
+  TASK_STATES,
+  TERMINAL_TASK_STATES,
+  TaskArtifactUpdateEventSchema,
+  TaskIdParamsSchema,
+  TaskListParamsSchema,
+  TaskNotFoundError,
+  TaskSchema,
+  TaskStateSchema,
+  TaskStatusSchema,
+  TaskStatusUpdateEventSchema,
+  TaskStore,
+  TextPartSchema,
+  UrlPartSchema,
+  agentMessageText,
+  connectA2a,
+  constantTimeEqual,
+  handleJsonRpc,
+  handleRest,
+  isMessageFrame,
+  isStatusUpdateFrame,
+  isTaskFrame,
+  isTerminal,
+  messageText,
+  normalizeRemoteCard,
+  normalizeTaskState,
+  normalizeWireTaskStates,
+  resolveBlocking,
+  restStatusFor,
+  serveA2a,
+  startSse
+};