feat: default to 0.3 if version not provided (#511)

# Description

This pull request enhances the v0.3 compatibility ("legacyCompat")
layer, making it easier for operators to support legacy clients without
duplicating interface declarations. The main improvement is that, when
`legacyCompat` is enabled, servers can serve v0.3 clients using only
v1.0 interface declarations—both for request validation and for the
discoverable agent card endpoint. The changes also clarify and document
this behavior, update validation logic, and add/refine tests.

Closes #474  🦕

Author: JakubWorek

src/client/card-resolver.ts

@@ -1,4 +1,4 @@
-import { AGENT_CARD_PATH } from '../constants.js';
+import { A2A_PROTOCOL_VERSION, A2A_VERSION_HEADER, AGENT_CARD_PATH } from '../constants.js';
 import { AgentCard } from '../index.js';
 import { isLegacyAgentCard, parseLegacyAgentCard } from '../compat/v0_3/client/card-resolver.js';
 
@@ -11,14 +11,21 @@ export interface AgentCardResolverOptions {
    * When enabled, the resolver inspects each fetched agent-card
    * payload; if its shape matches v0.3 (top-level `url` without
    * `supportedInterfaces`, `preferredTransport`,
-   * `additionalInterfaces`, `supportsAuthenticatedExtendedCard`, or
-   * a `protocolVersion` in `[0.3, 1.0)`), it is translated to the
-   * v1.0 proto shape via `toCoreAgentCard`. Each synthesized
-   * `AgentInterface` is stamped with `protocolVersion: '0.3'` so
-   * that a {@link JsonRpcTransportFactory} configured with
+   * `additionalInterfaces`, `supportsAuthenticatedExtendedCard`, or a
+   * `protocolVersion` in `[0.3, 1.0)`), it is translated to the v1.0
+   * proto shape via `toCoreAgentCard`. Each synthesized
+   * `AgentInterface` is stamped with `protocolVersion: '0.3'` so that
+   * a `JsonRpcTransportFactory` configured with
    * `legacyCompat: { enabled: true }` selects the compat transport
    * automatically.
    *
+   * The discovery request itself always announces the SDK's native
+   * v1.0 in the `A2A-Version` header — detection of v0.3 servers is
+   * based on the response shape (see {@link resolve}), not on the
+   * request value. This avoids a downgrade dance when both client
+   * and server speak v1.0 natively but both have legacyCompat
+   * enabled.
+   *
    * Default: omitted (treated as disabled). When disabled, the v0.3
    * compat module is never loaded.
    */
@@ -44,7 +51,9 @@ export class DefaultAgentCardResolver implements AgentCardResolver {
    */
   async resolve(baseUrl: string, path?: string): Promise<AgentCard> {
     const agentCardUrl = new URL(path ?? this.options?.path ?? AGENT_CARD_PATH, baseUrl);
-    const response = await this.fetchImpl(agentCardUrl);
+    const response = await this.fetchImpl(agentCardUrl, {
+      headers: { [A2A_VERSION_HEADER]: A2A_PROTOCOL_VERSION },
+    });
     if (!response.ok) {
       throw new Error(`Failed to fetch Agent Card from ${agentCardUrl}: ${response.status}`);
     }

src/compat/v0_3/README.md

@@ -44,7 +44,18 @@ Notable policy decisions:
 - The v1.0 `OAuthFlows.deviceCode` flow is silently dropped going v1.0 → v0.3 (v0.3 has no equivalent).
 - `TaskStatusUpdateEvent.final` is computed from the status state going v1.0 → v0.3 (`true` for `completed`, `canceled`, `failed`, `rejected`).
 - `SendMessageConfiguration.returnImmediately` ↔ `MessageSendConfiguration.blocking` with inverted polarity.
-- `toCompatAgentCard` filters `supportedInterfaces` to those whose `protocolVersion` is empty or in `[0.3, 1.0)` and throws `VersionNotSupportedError` if none qualify.
+- `toCompatAgentCard(card)` (strict mode, default) filters `supportedInterfaces` to those whose `protocolVersion` is empty or in `[0.3, 1.0)` and throws `VersionNotSupportedError` if none qualify.
+- `toCompatAgentCard(card, { synthesize: true })` (synthesis mode) accepts every interface in `supportedInterfaces` regardless of `protocolVersion` and emits `protocolVersion: '0.3'` on the result. Used by `legacyAgentCardRouter` to serve a discoverable v0.3 card when the operator has opted into `legacyCompat` but only declared v1.0 interfaces; the same v1.0 interface URLs are presented under the v0.3 protocol version.
+
+## Version negotiation under `legacyCompat`
+
+Per A2A spec §3.6.2, clients that omit the `A2A-Version` header are treated as v0.3 requests. Without an opt-in, the SDK's strict validator rejects header-less requests against a v1.0-only agent card with `VersionNotSupportedError`. When `legacyCompat: { enabled: true }` is passed to a handler, two pieces work together to honor §3.6.2 without requiring operators to duplicate every v1.0 `supportedInterfaces` entry with a v0.3 stub:
+
+1. **Implicit v0.3 in `validateVersion`.** When called with `{ legacyCompat: true }`, the validator adds the legacy `'0.3'` version to the supported set for any binding the agent card already exposes at least one interface for. A header-less or `A2A-Version: 0.3` request therefore routes through the legacy handler chain (`LegacyJsonRpcTransportHandler`, `LegacyRestTransportHandler`, `legacyGrpcService`) even when the card declares only v1.0 interfaces. Requests for bindings the card doesn't expose at all are still rejected.
+
+2. **Synthesized v0.3 card.** The `legacyAgentCardRouter` calls `toCompatAgentCard(card, { synthesize: true })` so the well-known endpoint returns a discoverable v0.3-shaped card whose `(url, preferredTransport, additionalInterfaces)` reflect the v1.0 `supportedInterfaces` entries but whose `protocolVersion` is stamped as `'0.3'`. v0.3 clients can therefore both discover and use a v1.0-only server when the operator has opted into the compat layer.
+
+The v1.0 gRPC service factory (`src/server/grpc/grpc_service.ts`) intentionally does **not** carry a `legacyCompat` option; v0.3 gRPC clients are served by registering `legacyGrpcService` alongside the v1.0 `grpcService` on the same `Server`.
 
 ## Push Notifications
 

src/compat/v0_3/server/express/agent_card_handler.ts

@@ -110,7 +110,14 @@ export function legacyAgentCardRouter(options: LegacyAgentCardHandlerOptions): R
       const coreCard = await provider();
       let compatCard: legacy.AgentCard;
       try {
-        compatCard = toCompatAgentCard(coreCard);
+        // `synthesize: true` lets the legacy endpoint serve a
+        // discoverable v0.3 card even when the operator only declared
+        // v1.0 interfaces in `supportedInterfaces` — symmetric with
+        // the request handlers' implicit-v0.3 acceptance under
+        // `legacyCompat`. Strict filtering would force operators to
+        // duplicate every v1.0 entry with a v0.3 stub just to get a
+        // discoverable v0.3 surface; this avoids that.
+        compatCard = toCompatAgentCard(coreCard, { synthesize: true });
       } catch (error) {
         if (error instanceof VersionNotSupportedError) {
           res.append('Vary', A2A_VERSION_HEADER);

src/compat/v0_3/server/express/rest_handler.ts

@@ -176,7 +176,15 @@ export function legacyRestRouter(options: LegacyRestHandlerOptions): RequestHand
       tenant: (req.params.tenant as string) || undefined,
     });
     const agentCard = await transportHandler.getAgentCard();
-    validateVersion(context.requestedVersion, agentCard, 'HTTP+JSON');
+    // This router is only mounted when the operator opted into
+    // `legacyCompat`, so the validator implicitly accepts '0.3' for
+    // any binding the card already exposes (per §3.6.2). This lets a
+    // v1.0-only card serve legacy clients without forcing operators
+    // to duplicate every v1.0 `supportedInterfaces` entry with a v0.3
+    // stub.
+    validateVersion(context.requestedVersion, agentCard, 'HTTP+JSON', {
+      legacyCompat: { enabled: true },
+    });
     return context;
   };
 

src/compat/v0_3/server/grpc/grpc_service.ts

@@ -573,7 +573,15 @@ const _buildContext = async (
   });
 
   const agentCard = await requestHandler.getAgentCard();
-  validateVersion(context.requestedVersion, agentCard, 'GRPC');
+  // `legacyGrpcService` is only registered alongside the v1.0
+  // `grpcService` when the operator opts into the v0.3 compat layer,
+  // so the validator implicitly accepts '0.3' for any binding the
+  // card already exposes (per §3.6.2). A v1.0-only card therefore
+  // serves legacy gRPC clients without forcing operators to declare a
+  // duplicate v0.3 `supportedInterfaces` entry.
+  validateVersion(context.requestedVersion, agentCard, 'GRPC', {
+    legacyCompat: { enabled: true },
+  });
 
   return context;
 };

src/compat/v0_3/translate/agent_card.ts

@@ -235,22 +235,63 @@ export function toCoreAgentCard(compat: legacy.AgentCard): V1AgentCard {
   return result;
 }
 
+/**
+ * Options for {@link toCompatAgentCard}.
+ */
+export interface ToCompatAgentCardOptions {
+  /**
+   * When `true`, accept every entry in `supportedInterfaces` regardless
+   * of its `protocolVersion` (skipping the `[0.3, 1.0)` filter) and
+   * stamp the emitted card's `protocolVersion` as
+   * {@link PROTOCOL_VERSION_0_3} regardless of the source value.
+   *
+   * Designed for the SDK's opt-in compat layer: when a server is
+   * configured with `legacyCompat: { enabled: true }` but only declares
+   * v1.0 interfaces on its agent card, the well-known endpoint can
+   * still serve a discoverable v0.3 card to legacy clients. The
+   * resulting card advertises the same interface URLs as the v1.0
+   * card but presents them under the v0.3 protocol version, mirroring
+   * the validator's implicit-v0.3 acceptance for request handling.
+   *
+   * Default: `false` (strict behavior: filter to legacy-range
+   * interfaces and throw `VersionNotSupportedError` if none qualify).
+   */
+  synthesize?: boolean;
+}
+
 /**
  * Converts a v1.0 proto `AgentCard` into a v0.3 JSON `AgentCard`.
  *
- * Filters `supportedInterfaces` to those whose `protocolVersion` is
- * empty or in `[0.3, 1.0)`; the first surviving entry becomes the v0.3
- * primary `(url, preferredTransport)`, and the rest become
- * `additionalInterfaces`. Throws `VersionNotSupportedError` if no
- * interface qualifies.
+ * In the default (strict) mode, filters `supportedInterfaces` to those
+ * whose `protocolVersion` is empty or in `[0.3, 1.0)`; the first
+ * surviving entry becomes the v0.3 primary `(url, preferredTransport)`,
+ * and the rest become `additionalInterfaces`. Throws
+ * `VersionNotSupportedError` if no interface qualifies.
+ *
+ * When called with `{ synthesize: true }`, accepts every interface
+ * unconditionally and emits `protocolVersion: '0.3'` on the result —
+ * used by the well-known agent-card endpoint when the operator has
+ * opted into the v0.3 compat layer but declared only v1.0 interfaces.
  *
  * `capabilities.extendedAgentCard` is pulled back out to the card-level
  * `supportsAuthenticatedExtendedCard` field.
  */
-export function toCompatAgentCard(core: V1AgentCard): legacy.AgentCard {
-  const compatInterfaces = core.supportedInterfaces.filter(
+export function toCompatAgentCard(
+  core: V1AgentCard,
+  options?: ToCompatAgentCardOptions
+): legacy.AgentCard {
+  const allInterfaces = core.supportedInterfaces ?? [];
+  const legacyInterfaces = allInterfaces.filter(
     (intf) => !intf.protocolVersion || isLegacyVersion(intf.protocolVersion)
   );
+  // Under synthesis mode, fall back to *every* interface when none in
+  // the legacy range exist — this is the discoverable-card path for
+  // v1.0-only deployments that opted into `legacyCompat`. When legacy
+  // interfaces ARE declared, prefer them so existing dual-version
+  // deployments keep emitting the same v0.3 primary URL they did
+  // before the synthesize option was introduced.
+  const compatInterfaces =
+    options?.synthesize && legacyInterfaces.length === 0 ? allInterfaces : legacyInterfaces;
   if (compatInterfaces.length === 0) {
     throw new VersionNotSupportedError(
       'AgentCard must have at least one interface with a protocol version in [0.3, 1.0).'
@@ -278,13 +319,24 @@ export function toCompatAgentCard(core: V1AgentCard): legacy.AgentCard {
         )
       : undefined;
 
+  // Under synthesize-fallback (no legacy-range interfaces, so we
+  // accepted non-legacy entries) the primary interface may be v1.0
+  // (or any other non-legacy version); the emitted v0.3 card always
+  // presents itself as v0.3 regardless of the underlying interface's
+  // declared version. Under strict / dual-version modes, fall back to
+  // `PROTOCOL_VERSION_0_3` only when the source field is empty.
+  const synthesizedFallback = options?.synthesize && legacyInterfaces.length === 0;
+  const emittedProtocolVersion = synthesizedFallback
+    ? PROTOCOL_VERSION_0_3
+    : primary.protocolVersion || PROTOCOL_VERSION_0_3;
+
   const result: legacy.AgentCard = {
     name: core.name,
     description: core.description,
     version: core.version,
     url: primary.url,
     preferredTransport: primary.protocolBinding,
-    protocolVersion: primary.protocolVersion || PROTOCOL_VERSION_0_3,
+    protocolVersion: emittedProtocolVersion,
     capabilities,
     defaultInputModes: [...core.defaultInputModes],
     defaultOutputModes: [...core.defaultOutputModes],

src/server/express/json_rpc_handler.ts

@@ -106,10 +106,15 @@ export function jsonRpcHandler(options: JsonRpcHandlerOptions): RequestHandler {
       const agentCard = await options.requestHandler.getAgentCard();
       // The agent card is the single source of truth for which protocol
       // versions this transport accepts. `requestedVersion` defaults to
-      // '0.3' when the A2A-Version header is absent (§3.6.2), so a
-      // header-less legacy client will only succeed if the card declares
-      // a v0.3 JSONRPC interface.
-      validateVersion(context.requestedVersion, agentCard, 'JSONRPC');
+      // '0.3' when the A2A-Version header is absent (§3.6.2). When
+      // `legacyCompat` is enabled, the validator implicitly accepts
+      // '0.3' for any binding the card already exposes, so v0.3
+      // clients (and header-less clients) succeed without requiring
+      // operators to duplicate every v1.0 `supportedInterfaces` entry
+      // with a v0.3 stub.
+      validateVersion(context.requestedVersion, agentCard, 'JSONRPC', {
+        legacyCompat: options.legacyCompat,
+      });
       const transportHandler = useLegacy ? legacyJsonRpcTransportHandler : jsonRpcTransportHandler;
       const rpcResponseOrStream = await transportHandler.handle(req.body, context);
 

src/server/express/rest_handler.ts

@@ -175,7 +175,14 @@ export function restHandler(options: RestHandlerOptions): RequestHandler {
       tenant,
     });
     const agentCard = await restTransportHandler.getAgentCard();
-    validateVersion(context.requestedVersion, agentCard, 'HTTP+JSON');
+    // When `legacyCompat` is enabled, the validator implicitly accepts
+    // '0.3' for any binding the card already exposes (per §3.6.2),
+    // so v0.3 clients (and header-less clients) succeed without
+    // requiring operators to duplicate every v1.0 `supportedInterfaces`
+    // entry with a v0.3 stub.
+    validateVersion(context.requestedVersion, agentCard, 'HTTP+JSON', {
+      legacyCompat: options.legacyCompat,
+    });
     return context;
   };
 

src/server/version.ts

@@ -1,3 +1,4 @@
+import { A2A_LEGACY_PROTOCOL_VERSION } from '../constants.js';
 import { TransportProtocolName } from '../core.js';
 import { VersionNotSupportedError } from '../errors.js';
 import { AgentCard } from '../index.js';
@@ -30,24 +31,80 @@ export function getSupportedVersions(
   return versions;
 }
 
+/**
+ * Options for {@link validateVersion}.
+ */
+export interface ValidateVersionOptions {
+  /**
+   * Opt-in to v0.3 compatibility. When `{ enabled: true }`, the legacy
+   * v0.3 protocol version ({@link A2A_LEGACY_PROTOCOL_VERSION}) is
+   * treated as implicitly supported for any binding that the agent
+   * card exposes at least one interface for — even if the card itself
+   * doesn't declare a v0.3 `protocolVersion` entry.
+   *
+   * This honors the §3.6.2 default-to-`'0.3'` rule (clients that omit
+   * the `A2A-Version` header MUST be treated as v0.3 requests) under
+   * the SDK's opt-in compat layer. Operators that don't opt in
+   * (`legacyCompat: { enabled: false }` or omitted) keep the strict
+   * behavior — only explicitly declared versions are accepted.
+   *
+   * The `{ enabled: boolean }` shape mirrors the option used by every
+   * public handler / transport-factory option type that exposes
+   * legacy compat (`AgentCardHandlerOptions`, `JsonRpcHandlerOptions`,
+   * `RestHandlerOptions`, `AgentCardResolverOptions`,
+   * `JsonRpcTransportFactoryOptions`, `RestTransportFactoryOptions`,
+   * `GrpcTransportFactoryOptions`).
+   *
+   * Default: omitted (strict). Has no effect unless the agent card
+   * already advertises at least one interface for the requested
+   * binding; otherwise the implicit v0.3 entry would route requests
+   * to a binding the agent doesn't actually serve.
+   */
+  legacyCompat?: { enabled: boolean };
+}
+
 /**
  * Validates that the requested A2A protocol version is supported by the agent.
  *
  * Per §3.6.2: "Agents MUST process requests using the semantics of the
  * requested A2A-Version (matching Major.Minor). If the version is not
  * supported by the interface, agents MUST return a VersionNotSupportedError."
  *
+ * When `options.legacyCompat` is `true` AND the agent card exposes at
+ * least one interface for the requested binding, the legacy v0.3
+ * version is implicitly added to the supported set. This lets a v1.0
+ * server opted into the compat layer honor the §3.6.2 default-to-`'0.3'`
+ * rule (and explicit `A2A-Version: 0.3` requests) without forcing
+ * operators to duplicate every v1.0 `supportedInterfaces` entry with a
+ * matching v0.3 stub.
+ *
  * @param requestedVersion - The version requested by the client (from A2A-Version header).
  * @param agentCard - The agent card declaring supported interfaces/versions.
  * @param protocolBinding - The protocol binding to filter versions by.
+ * @param options - Validation options (see {@link ValidateVersionOptions}).
  * @throws {VersionNotSupportedError} If the requested version is not supported.
  */
 export function validateVersion(
   requestedVersion: string,
   agentCard: AgentCard,
-  protocolBinding?: TransportProtocolName
+  protocolBinding?: TransportProtocolName,
+  options?: ValidateVersionOptions
 ): void {
   const supported = getSupportedVersions(agentCard, protocolBinding);
+
+  if (options?.legacyCompat?.enabled) {
+    // Implicit v0.3 acceptance: only if the agent card actually
+    // exposes the requested binding (otherwise we'd accept v0.3 for a
+    // transport the agent doesn't serve, which would just defer the
+    // failure to the dispatcher with a less useful error).
+    const hasBindingInterface = (agentCard.supportedInterfaces ?? []).some(
+      (intf) => !protocolBinding || intf.protocolBinding === protocolBinding
+    );
+    if (hasBindingInterface) {
+      supported.add(A2A_LEGACY_PROTOCOL_VERSION);
+    }
+  }
+
   if (!supported.has(requestedVersion)) {
     throw new VersionNotSupportedError(
       `The requested A2A protocol version '${requestedVersion}' is not supported. ` +