@adcp/sdk 14.0.0-beta.10 → 14.0.0-beta.12

package/dist/lib/server/a2a-adapter.mjs

@@ -1,11 +1,30 @@
 import {
   DefaultRequestHandler,
   InMemoryTaskStore as SdkInMemoryTaskStore,
-  DefaultExecutionEventBusManager
+  DefaultExecutionEventBusManager,
+  AgentEvent
 } from "@a2a-js/sdk/server";
 import { jsonRpcHandler, agentCardHandler } from "@a2a-js/sdk/server/express";
+import { AgentCard, Role, TaskState } from "@a2a-js/sdk";
+import { duplicateInterfacesForLegacy } from "@a2a-js/sdk/compat/v0_3";
 import { randomUUID } from "node:crypto";
+import { redactSecrets } from "../utils/redact-secrets.mjs";
 import { getSdkServer, listRegisteredToolNames } from "./adcp-server.mjs";
+class RedactingA2ATaskStore {
+  constructor(delegate) {
+    this.delegate = delegate;
+  }
+  delegate;
+  save(task, context) {
+    return this.delegate.save(redactSecrets(task), context);
+  }
+  load(taskId, context) {
+    return this.delegate.load(taskId, context);
+  }
+  list(params, context) {
+    return this.delegate.list(params, context);
+  }
+}
 function buildAuthenticatedUser(authInfo) {
   const clientId = authInfo.clientId;
   return {
@@ -32,11 +51,13 @@ function getAdcpAuthInfo(context) {
   const user = context?.user;
   return user?.adcpAuthInfo;
 }
-function extractInvocation(message) {
+function extractInvocation(message, allowLegacyParameters = false) {
   if (!Array.isArray(message.parts) || message.parts.length === 0) {
     throw new A2AInvocationError("Message must carry at least one part with a `data` kind.");
   }
-  const dataParts = message.parts.filter((p) => p?.kind === "data");
+  const dataParts = message.parts.filter(
+    (part) => part.content?.$case === "data"
+  );
   if (dataParts.length === 0) {
     throw new A2AInvocationError(
       "Message must include a DataPart with { skill, input } \u2014 text-only messages aren't routable to AdCP tools."
@@ -44,24 +65,27 @@ function extractInvocation(message) {
   }
   if (dataParts.length > 1) {
     throw new A2AInvocationError(
-      "Message must include exactly one DataPart \u2014 multi-part invocations are not supported in v0."
+      "Message must include exactly one DataPart \u2014 multi-part invocations are not supported."
     );
   }
   const firstDataPart = dataParts[0];
-  const rawData = firstDataPart.data;
+  const rawData = firstDataPart.content.value;
   if (rawData == null || typeof rawData !== "object" || Array.isArray(rawData)) {
     throw new A2AInvocationError("DataPart `data` must be an object containing { skill, input }.");
   }
   const payload = rawData;
   const skill = payload.skill;
-  const input = payload.input ?? payload.parameters;
+  const input = payload.input ?? (allowLegacyParameters ? payload.parameters : void 0);
   if (typeof skill !== "string" || skill.length === 0) {
     throw new A2AInvocationError("DataPart must include a non-empty string `skill` field naming the AdCP tool.");
   }
   if (input != null && (typeof input !== "object" || Array.isArray(input))) {
-    throw new A2AInvocationError("DataPart `input` (or legacy `parameters`) must be an object (or omitted).");
+    throw new A2AInvocationError("DataPart `input` must be an object.");
+  }
+  if (input == null) {
+    throw new A2AInvocationError("DataPart must include an `input` object.");
   }
-  return { skill, input: input ?? {} };
+  return { skill, input };
 }
 class A2AInvocationError extends Error {
   constructor(message) {
@@ -107,12 +131,25 @@ class AdcpA2AAgentExecutor {
   async execute(requestContext, eventBus) {
     const { taskId, contextId, userMessage } = requestContext;
     const authInfo = getAdcpAuthInfo(requestContext.context);
+    const requestedExtensions = requestContext.context.requestedExtensions;
+    const requestedAdcpExtension = Array.isArray(requestedExtensions) && requestedExtensions.some((extension) => extension === ADCP_A2A_EXTENSION);
+    const legacyWire = requestContext.context.requestedVersion.startsWith("0.");
     this.taskContextIds.set(taskId, contextId);
     try {
       this.publishInitialTask(eventBus, taskId, contextId, userMessage);
+      if (!legacyWire) {
+        if (!requestedAdcpExtension) {
+          this.emitFailure(eventBus, taskId, contextId, {
+            reason: "REQUIRED_EXTENSION_MISSING",
+            message: `A2A requests must activate ${ADCP_A2A_EXTENSION}`
+          });
+          return;
+        }
+        requestContext.context.addActivatedExtension(ADCP_A2A_EXTENSION);
+      }
       let invocation;
       try {
-        invocation = extractInvocation(userMessage);
+        invocation = extractInvocation(userMessage, legacyWire);
       } catch (err) {
         const message = err instanceof Error ? err.message : "Invalid A2A invocation";
         this.emitFailure(eventBus, taskId, contextId, {
@@ -152,7 +189,7 @@ class AdcpA2AAgentExecutor {
         });
         this.emitFailure(eventBus, taskId, contextId, {
           reason: "HANDLER_THREW",
-          message
+          message: "The A2A tool invocation failed."
         });
         return;
       }
@@ -164,17 +201,16 @@ class AdcpA2AAgentExecutor {
         return;
       }
       if (this.canceled.has(taskId)) {
-        this.publishStatus(eventBus, taskId, contextId, "canceled", true);
+        this.publishStatus(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED);
         return;
       }
       const classified = classifyResponse(response);
-      this.publishArtifact(eventBus, taskId, contextId, classified);
+      this.publishArtifact(eventBus, taskId, contextId, classified, legacyWire);
       this.publishStatus(
         eventBus,
         taskId,
         contextId,
-        classified.kind === "success" || classified.kind === "submitted" || classified.kind === "paused" ? "completed" : "failed",
-        true
+        classified.kind === "success" || classified.kind === "submitted" || classified.kind === "paused" || !legacyWire && classified.kind === "error_arm" ? TaskState.TASK_STATE_COMPLETED : TaskState.TASK_STATE_FAILED
       );
     } finally {
       this.canceled.delete(taskId);
@@ -185,80 +221,98 @@ class AdcpA2AAgentExecutor {
   async cancelTask(taskId, eventBus) {
     this.canceled.add(taskId);
     const contextId = this.taskContextIds.get(taskId) ?? "";
-    this.publishStatus(eventBus, taskId, contextId, "canceled", true);
+    this.publishStatus(eventBus, taskId, contextId, TaskState.TASK_STATE_CANCELED);
   }
   publishInitialTask(eventBus, taskId, contextId, userMessage) {
     const task = {
-      kind: "task",
       id: taskId,
       contextId,
       status: {
-        state: "working",
+        state: TaskState.TASK_STATE_WORKING,
+        message: void 0,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       },
-      history: [userMessage]
+      artifacts: [],
+      history: [userMessage],
+      metadata: void 0
     };
-    eventBus.publish(task);
+    eventBus.publish(AgentEvent.task(task));
   }
-  publishStatus(eventBus, taskId, contextId, state, final, messageData) {
+  publishStatus(eventBus, taskId, contextId, state, messageData) {
     const event = {
-      kind: "status-update",
       taskId,
       contextId,
       status: {
         state,
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-        ...messageData && {
-          message: {
-            kind: "message",
-            messageId: randomUUID(),
-            role: "agent",
-            parts: [{ kind: "data", data: messageData }]
-          }
-        }
+        message: messageData ? {
+          messageId: randomUUID(),
+          contextId,
+          taskId,
+          role: Role.ROLE_AGENT,
+          parts: [dataPart(messageData)],
+          metadata: void 0,
+          extensions: [],
+          referenceTaskIds: []
+        } : void 0
       },
-      final
+      metadata: void 0
     };
-    eventBus.publish(event);
+    eventBus.publish(AgentEvent.statusUpdate(event));
   }
-  publishArtifact(eventBus, taskId, contextId, classified) {
+  publishArtifact(eventBus, taskId, contextId, classified, legacyWire) {
     const artifactName = classified.kind === "success" ? "result" : classified.kind === "submitted" ? "submitted" : classified.kind === "paused" ? "result" : "error";
     const artifact = {
       artifactId: randomUUID(),
       name: artifactName,
-      parts: [{ kind: "data", data: classified.data }],
-      metadata: {
+      description: "",
+      parts: [dataPart(classified.data)],
+      metadata: legacyWire ? {
         adcp_status: classified.kind === "submitted" ? "submitted" : classified.kind === "paused" ? classified.status : classified.kind === "success" ? "completed" : "failed",
         ...classified.kind === "submitted" && { adcp_task_id: classified.adcpTaskId }
-      }
+      } : void 0,
+      extensions: []
     };
     const event = {
-      kind: "artifact-update",
       taskId,
       contextId,
       artifact,
       append: false,
-      lastChunk: true
+      lastChunk: true,
+      metadata: void 0
     };
-    eventBus.publish(event);
+    eventBus.publish(AgentEvent.artifactUpdate(event));
   }
   emitFailure(eventBus, taskId, contextId, payload) {
     const artifact = {
       artifactId: randomUUID(),
       name: "error",
-      parts: [{ kind: "data", data: payload }]
+      description: "",
+      parts: [dataPart(payload)],
+      metadata: void 0,
+      extensions: []
     };
-    eventBus.publish({
-      kind: "artifact-update",
-      taskId,
-      contextId,
-      artifact,
-      append: false,
-      lastChunk: true
-    });
-    this.publishStatus(eventBus, taskId, contextId, "failed", true);
+    eventBus.publish(
+      AgentEvent.artifactUpdate({
+        taskId,
+        contextId,
+        artifact,
+        append: false,
+        lastChunk: true,
+        metadata: void 0
+      })
+    );
+    this.publishStatus(eventBus, taskId, contextId, TaskState.TASK_STATE_FAILED);
   }
 }
+function dataPart(value) {
+  return {
+    content: { $case: "data", value },
+    metadata: void 0,
+    filename: "",
+    mediaType: "application/json"
+  };
+}
 function isToolNotRegistered(err, toolName) {
   return err instanceof Error && err.message.includes(`tool "${toolName}" is not registered`);
 }
@@ -266,7 +320,8 @@ function a2aSkillToServerToolNames(skill) {
   return skill === "tasks/get" ? ["tasks_get", "tasks/get"] : [skill];
 }
 const DEFAULT_MODES = ["application/json"];
-const DEFAULT_PROTOCOL_VERSION = "0.3.0";
+const DEFAULT_PROTOCOL_VERSION = "1.0";
+const ADCP_A2A_EXTENSION = "https://adcontextprotocol.org/extensions/adcp/v3";
 const PUBLIC_AGENT_CARD_EXCLUDED_SKILLS = /* @__PURE__ */ new Set(["comply_test_controller"]);
 function deriveSkills(toolNames) {
   const publicNames = new Set(toolNames.map(toA2ASkillName));
@@ -274,7 +329,11 @@ function deriveSkills(toolNames) {
     id: name,
     name,
     description: `AdCP tool: ${name}. Send { skill: "${name}", input: { ... } } as a DataPart.`,
-    tags: ["adcp"]
+    tags: ["adcp"],
+    examples: [],
+    inputModes: [],
+    outputModes: [],
+    securityRequirements: []
   }));
 }
 function toA2ASkillName(toolName) {
@@ -292,42 +351,177 @@ function filterPublicAgentCardSkills(skills) {
     return !(id != null && PUBLIC_AGENT_CARD_EXCLUDED_SKILLS.has(id) || name != null && PUBLIC_AGENT_CARD_EXCLUDED_SKILLS.has(name));
   });
 }
+function normalizeAgentCardSkills(skills) {
+  return skills.map((skill) => ({
+    ...skill,
+    examples: skill.examples ?? [],
+    inputModes: skill.inputModes ?? [],
+    outputModes: skill.outputModes ?? [],
+    securityRequirements: skill.securityRequirements ?? []
+  }));
+}
 function buildAgentCard(server, overrides) {
+  if (overrides.preferredTransport && overrides.preferredTransport.toUpperCase() !== "JSONRPC") {
+    throw new Error("createA2AAdapter: only the JSONRPC A2A transport is supported");
+  }
   const tools = listRegisteredTools(server);
-  const skills = filterPublicAgentCardSkills(overrides.skills ?? deriveSkills(tools));
+  const skills = filterPublicAgentCardSkills(
+    overrides.skills ? normalizeAgentCardSkills(overrides.skills) : deriveSkills(tools)
+  );
   if (tools.includes("get_adcp_capabilities") && !skills.some((skill) => skill.id === "get_adcp_capabilities" || skill.name === "get_adcp_capabilities")) {
     skills.push(...deriveSkills(["get_adcp_capabilities"]));
   }
   const card = {
     name: overrides.name,
     description: overrides.description,
-    url: overrides.url,
+    supportedInterfaces: duplicateInterfacesForLegacy(
+      [
+        {
+          url: overrides.url,
+          protocolBinding: "JSONRPC",
+          protocolVersion: DEFAULT_PROTOCOL_VERSION,
+          tenant: ""
+        }
+      ],
+      ["JSONRPC"]
+    ),
     version: overrides.version,
-    protocolVersion: overrides.protocolVersion ?? DEFAULT_PROTOCOL_VERSION,
     defaultInputModes: overrides.defaultInputModes ?? [...DEFAULT_MODES],
     defaultOutputModes: overrides.defaultOutputModes ?? [...DEFAULT_MODES],
-    capabilities: overrides.capabilities ?? {
-      streaming: false,
-      pushNotifications: false
+    capabilities: {
+      streaming: overrides.capabilities?.streaming ?? false,
+      pushNotifications: overrides.capabilities?.pushNotifications ?? false,
+      extendedAgentCard: overrides.capabilities?.extendedAgentCard,
+      extensions: [
+        ...(overrides.capabilities?.extensions ?? []).filter((extension) => extension.uri !== ADCP_A2A_EXTENSION),
+        {
+          uri: ADCP_A2A_EXTENSION,
+          description: "AdCP structured task invocation profile",
+          required: true,
+          params: void 0
+        }
+      ]
     },
     skills,
-    ...overrides.provider && { provider: overrides.provider },
+    provider: overrides.provider,
+    securitySchemes: normalizeSecuritySchemes(overrides.securitySchemes),
+    securityRequirements: (overrides.security ?? []).map((requirement) => ({
+      schemes: Object.fromEntries(Object.entries(requirement).map(([name, scopes]) => [name, { list: scopes }]))
+    })),
+    signatures: [],
     ...overrides.documentationUrl && { documentationUrl: overrides.documentationUrl },
-    ...overrides.iconUrl && { iconUrl: overrides.iconUrl },
-    ...overrides.securitySchemes && { securitySchemes: overrides.securitySchemes },
-    ...overrides.security && { security: overrides.security },
-    ...overrides.preferredTransport && { preferredTransport: overrides.preferredTransport }
+    ...overrides.iconUrl && { iconUrl: overrides.iconUrl }
   };
+  Object.defineProperties(card, {
+    url: { value: overrides.url, enumerable: false },
+    protocolVersion: { value: DEFAULT_PROTOCOL_VERSION, enumerable: false },
+    // The SDK's Express card middleware currently calls JSON.stringify on the
+    // ts-proto in-memory shape. Supply the official JSON projection so v1
+    // security-scheme unions serialize as `type`/`scheme`, not `$case`.
+    toJSON: { value: () => AgentCard.toJSON(card), enumerable: false }
+  });
   validateAgentCard(card);
   return card;
 }
+function normalizeSecuritySchemes(schemes) {
+  return Object.fromEntries(
+    Object.entries(schemes ?? {}).map(([name, value]) => {
+      const candidate = value;
+      if (candidate.scheme && typeof candidate.scheme === "object" && "$case" in candidate.scheme) {
+        return [name, value];
+      }
+      const legacy = value;
+      switch (legacy.type) {
+        case "apiKey":
+          return [
+            name,
+            {
+              scheme: {
+                $case: "apiKeySecurityScheme",
+                value: { description: legacy.description ?? "", location: legacy.in, name: legacy.name }
+              }
+            }
+          ];
+        case "http":
+          return [
+            name,
+            {
+              scheme: {
+                $case: "httpAuthSecurityScheme",
+                value: {
+                  description: legacy.description ?? "",
+                  scheme: legacy.scheme,
+                  bearerFormat: legacy.bearerFormat ?? ""
+                }
+              }
+            }
+          ];
+        case "oauth2":
+          return [
+            name,
+            {
+              scheme: {
+                $case: "oauth2SecurityScheme",
+                value: {
+                  description: legacy.description ?? "",
+                  oauth2MetadataUrl: legacy.oauth2MetadataUrl ?? "",
+                  flows: normalizeLegacyOAuthFlows(legacy.flows)
+                }
+              }
+            }
+          ];
+        case "openIdConnect":
+          return [
+            name,
+            {
+              scheme: {
+                $case: "openIdConnectSecurityScheme",
+                value: {
+                  description: legacy.description ?? "",
+                  openIdConnectUrl: legacy.openIdConnectUrl
+                }
+              }
+            }
+          ];
+        case "mutualTLS":
+          return [
+            name,
+            {
+              scheme: {
+                $case: "mtlsSecurityScheme",
+                value: { description: legacy.description ?? "" }
+              }
+            }
+          ];
+      }
+      throw new Error(`createA2AAdapter: unsupported security scheme shape for "${name}"`);
+    })
+  );
+}
+function normalizeLegacyOAuthFlows(flows) {
+  const selected = flows.authorizationCode ? ["authorizationCode", flows.authorizationCode] : flows.clientCredentials ? ["clientCredentials", flows.clientCredentials] : flows.implicit ? ["implicit", flows.implicit] : flows.password ? ["password", flows.password] : void 0;
+  if (!selected) return void 0;
+  const [kind, flow] = selected;
+  return {
+    flow: {
+      $case: kind,
+      value: {
+        authorizationUrl: flow.authorizationUrl ?? "",
+        tokenUrl: flow.tokenUrl ?? "",
+        refreshUrl: flow.refreshUrl ?? "",
+        scopes: flow.scopes,
+        ...kind === "authorizationCode" && { pkceRequired: false }
+      }
+    }
+  };
+}
 function validateAgentCard(card) {
   const missing = [];
   if (!card.name) missing.push("name");
   if (!card.description) missing.push("description");
-  if (!card.url) missing.push("url");
+  if (!card.supportedInterfaces?.[0]?.url) missing.push("supportedInterfaces[0].url");
   if (!card.version) missing.push("version");
-  if (!card.protocolVersion) missing.push("protocolVersion");
+  if (card.supportedInterfaces?.[0]?.protocolVersion !== DEFAULT_PROTOCOL_VERSION) missing.push("protocolVersion=1.0");
   if (!card.capabilities) missing.push("capabilities");
   if (!Array.isArray(card.defaultInputModes) || card.defaultInputModes.length === 0) {
     missing.push("defaultInputModes");
@@ -356,10 +550,22 @@ const DEFAULT_LOGGER = {
 function createA2AAdapter(options) {
   const logger = options.logger ?? DEFAULT_LOGGER;
   const card = buildAgentCard(options.server, options.agentCard);
-  const taskStore = options.taskStore ?? new SdkInMemoryTaskStore();
+  const handlerCard = structuredClone(card);
+  if (handlerCard.capabilities?.extensions) {
+    handlerCard.capabilities.extensions = handlerCard.capabilities.extensions.map(
+      (extension) => extension.uri === ADCP_A2A_EXTENSION ? { ...extension, required: false } : extension
+    );
+  }
+  const development = process.env.NODE_ENV === "test" || process.env.NODE_ENV === "development";
+  if (!options.taskStore && !development) {
+    throw new Error(
+      "createA2AAdapter: production requires a bounded durable taskStore; the SDK in-memory store is available only under NODE_ENV=test or NODE_ENV=development"
+    );
+  }
+  const taskStore = new RedactingA2ATaskStore(options.taskStore ?? new SdkInMemoryTaskStore());
   const executor = new AdcpA2AAgentExecutor(options.server, logger);
   const eventBusManager = new DefaultExecutionEventBusManager();
-  const requestHandler = new DefaultRequestHandler(card, taskStore, executor, eventBusManager);
+  const requestHandler = new DefaultRequestHandler(handlerCard, taskStore, executor, eventBusManager);
   const userBuilder = async (req) => {
     if (!options.authenticate) return buildAnonymousUser();
     const authInfo = await options.authenticate(req);
@@ -368,11 +574,17 @@ function createA2AAdapter(options) {
     }
     return buildAuthenticatedUser(authInfo);
   };
-  const jsonRpc = jsonRpcHandler({ requestHandler, userBuilder });
-  const agentCardMiddleware = agentCardHandler({ agentCardProvider: requestHandler });
+  const legacyCompat = { enabled: true };
+  const jsonRpc = jsonRpcHandler({ requestHandler, userBuilder, legacyCompat });
+  const nativeAgentCardMiddleware = agentCardHandler({ agentCardProvider: async () => card });
+  const legacyAgentCardMiddleware = agentCardHandler({ agentCardProvider: async () => handlerCard, legacyCompat });
+  const agentCardMiddleware = (req, res, next) => {
+    const requestedVersion = req.header("A2A-Version");
+    return requestedVersion && !requestedVersion.startsWith("0.") ? nativeAgentCardMiddleware(req, res, next) : legacyAgentCardMiddleware(req, res, next);
+  };
   const defaultBasePath = (() => {
     try {
-      const parsed = new URL(card.url);
+      const parsed = new URL(card.supportedInterfaces[0].url);
       const pathname = parsed.pathname.replace(/\/+$/, "");
       return pathname.length > 0 ? pathname : "/a2a";
     } catch {