fix: normalize legacy cards in createFromAgentCard (#602)

# Description

## Summary

`ClientFactory.createFromAgentCard()` selected transports directly from
`supportedInterfaces`, while the URL path first normalized cards through
the
configured `AgentCardResolver`. As a result, a pure v0.3 card with a
top-level
`url` still failed with `No compatible transport found` even when both
documented
legacy compatibility options were enabled.

## Changes

This change exposes the default resolver's existing agent-card
normalizer as an
optional resolver capability and applies it to direct-card creation
before
transport selection. The URL path continues to consume the
already-resolved
card without a second normalization pass. The normalized card is also
passed to
the transport factory and retained by the returned client.

Compatibility remains opt-in: disabling resolver compatibility still
rejects a
pure v0.3 card, and custom resolvers that only implement `resolve()`
keep their
existing behavior. The compatibility guide now includes the custom-fetch
plus
`createFromAgentCard()` workflow.

## Verification

```bash
npm run lint:ci
npm run build
npm run test-build
npm test
npm run test:edge
npm run test:integration
```

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- [x] Ensure the tests and linter pass
- [x] Appropriate docs were updated (if necessary)

Fixes #601

Signed-off-by: King Star <mcxin.y@gmail.com>

Author: jstar0

docs/compatibility-v0_3.md

@@ -153,9 +153,19 @@ const factory = new ClientFactory(
 const client = await factory.createFromUrl(serverUrl);
 ```
 
+If the card is fetched through an application-specific path, the same factory
+configuration also normalizes it before direct client creation:
+
+```ts
+const response = await fetch(customAgentCardUrl);
+const card = await response.json();
+const client = await factory.createFromAgentCard(card);
+```
+
 With those flags set:
 
-- `DefaultAgentCardResolver` inspects every fetched card. A pure v0.3 card
+- `DefaultAgentCardResolver` inspects fetched cards and cards passed directly to
+  `ClientFactory.createFromAgentCard`. A pure v0.3 card
   (top-level `url`, no `supportedInterfaces[]`, or a `protocolVersion` in
   `[0.3, 1.0)`) is translated to a v1.0 representation with
   `protocolVersion: '0.3'` stamped on each synthesized `AgentInterface`. A

src/client/card-resolver.ts

@@ -24,6 +24,9 @@ export interface AgentCardResolverOptions {
 
 export interface AgentCardResolver {
   resolve(baseUrl: string, path?: string): Promise<AgentCard>;
+
+  /** Normalizes an already-fetched card before client transport selection. */
+  normalizeAgentCard?(card: unknown): AgentCard;
 }
 
 export class DefaultAgentCardResolver implements AgentCardResolver {
@@ -52,7 +55,7 @@ export class DefaultAgentCardResolver implements AgentCardResolver {
     return fetch(...args);
   }
 
-  /*
+  /**
    * In v0.3 there was structural drift between the JSON Schema data
    * model and the Protobuf-based data model for AgentCards: JSON Schema
    * uses a `"type"` discriminator, while Protobuf JSON uses the `oneof`
@@ -62,7 +65,7 @@ export class DefaultAgentCardResolver implements AgentCardResolver {
    * When `legacyCompat: { enabled: true }`, this method also detects
    * v0.3-shaped cards and translates them via the compat module.
    */
-  private normalizeAgentCard(card: unknown): AgentCard {
+  normalizeAgentCard(card: unknown): AgentCard {
     if (this.options?.legacyCompat?.enabled) {
       if (isLegacyAgentCard(card)) {
         return parseLegacyAgentCard(card);

src/client/factory.ts

@@ -90,12 +90,18 @@ export class ClientFactory {
   }
 
   /**
-   * Creates a new client from the provided agent card. When the selected
-   * `AgentInterface` declares a non-empty `tenant`, the transport is
-   * wrapped with a {@link TenantTransportDecorator} so the default tenant
-   * is applied to every request.
+   * Creates a new client from the provided agent card. The configured resolver
+   * may normalize an already-fetched card before transport selection. When the
+   * selected `AgentInterface` declares a non-empty `tenant`, the transport is
+   * wrapped with a {@link TenantTransportDecorator} so the default tenant is
+   * applied to every request.
    */
   async createFromAgentCard(agentCard: AgentCard): Promise<Client> {
+    const normalizedAgentCard = this.agentCardResolver.normalizeAgentCard?.(agentCard) ?? agentCard;
+    return this.createFromNormalizedAgentCard(normalizedAgentCard);
+  }
+
+  private async createFromNormalizedAgentCard(agentCard: AgentCard): Promise<Client> {
     const interfaces = agentCard.supportedInterfaces ?? [];
 
     const bestInterfacePerProtocol = new CaseInsensitiveMap<(typeof interfaces)[number]>();
@@ -146,7 +152,7 @@ export class ClientFactory {
    */
   async createFromUrl(baseUrl: string, path?: string): Promise<Client> {
     const agentCard = await this.agentCardResolver.resolve(baseUrl, path);
-    return this.createFromAgentCard(agentCard);
+    return this.createFromNormalizedAgentCard(agentCard);
   }
 }
 

test/client/factory.spec.ts

@@ -10,6 +10,7 @@ import {
   JsonRpcTransportFactory,
 } from '../../src/client/transports/json_rpc_transport.js';
 import { LegacyJsonRpcTransport } from '../../src/compat/v0_3/client/transports/json_rpc_transport.js';
+import { DefaultAgentCardResolver } from '../../src/client/card-resolver.js';
 
 describe('ClientFactory', () => {
   let mockTransportFactory1: { protocolName: string; create: Mock };
@@ -270,6 +271,21 @@ describe('ClientFactory', () => {
       expect(jsonRpcFactory.create).toHaveBeenCalledTimes(1);
     });
 
+    it('preserves direct-card behavior for resolvers without a card normalizer', async () => {
+      const cardResolver = {
+        resolve: vi.fn().mockResolvedValue(agentCard),
+      };
+      const factory = new ClientFactory({
+        transports: [mockTransportFactory1],
+        cardResolver,
+      });
+
+      const client = await factory.createFromAgentCard(agentCard);
+
+      expect(client).to.be.instanceOf(Client);
+      expect(mockTransportFactory1.create).toHaveBeenCalledTimes(1);
+    });
+
     it('should use card resolver with default path', async () => {
       const cardResolver = {
         resolve: vi.fn().mockResolvedValue(agentCard),
@@ -399,6 +415,67 @@ describe('ClientFactory', () => {
       expect(client.transport).to.be.instanceOf(LegacyJsonRpcTransport);
       expect(client.protocolVersion).to.equal('0.3');
     });
+
+    it('normalizes a pure v0.3 card through the configured resolver', async () => {
+      const factory = new ClientFactory(
+        ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+          cardResolver: new DefaultAgentCardResolver({ legacyCompat: { enabled: true } }),
+          transports: [new JsonRpcTransportFactory({ legacyCompat: { enabled: true } })],
+        })
+      );
+      const legacyCard: Record<string, unknown> = {
+        name: 'Legacy Agent',
+        description: 'A v0.3 agent',
+        protocolVersion: '0.3.0',
+        version: '1.0.0',
+        url: 'https://v03.example/rpc',
+        skills: [],
+        capabilities: {
+          streaming: true,
+          pushNotifications: true,
+          stateTransitionHistory: false,
+        },
+        defaultInputModes: ['text'],
+        defaultOutputModes: ['text'],
+      };
+
+      const client = await factory.createFromAgentCard(legacyCard as unknown as AgentCard);
+
+      expect(client.transport).to.be.instanceOf(LegacyJsonRpcTransport);
+      expect(client.protocolVersion).to.equal('0.3');
+      expect((await client.getAgentCard()).supportedInterfaces).to.deep.equal([
+        {
+          url: 'https://v03.example/rpc',
+          protocolBinding: 'JSONRPC',
+          tenant: '',
+          protocolVersion: '0.3.0',
+        },
+      ]);
+    });
+
+    it('does not normalize a pure v0.3 card when resolver compatibility is disabled', async () => {
+      const factory = new ClientFactory(
+        ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+          cardResolver: new DefaultAgentCardResolver(),
+          transports: [new JsonRpcTransportFactory({ legacyCompat: { enabled: true } })],
+        })
+      );
+      const legacyCard: Record<string, unknown> = {
+        name: 'Legacy Agent',
+        description: 'A v0.3 agent',
+        protocolVersion: '0.3.0',
+        version: '1.0.0',
+        url: 'https://v03.example/rpc',
+        skills: [],
+        capabilities: {},
+        defaultInputModes: ['text'],
+        defaultOutputModes: ['text'],
+      };
+
+      await expect(factory.createFromAgentCard(legacyCard as unknown as AgentCard)).rejects.toThrow(
+        'No compatible transport found'
+      );
+    });
   });
 
   describe('ClientFactoryOptions.createFrom', () => {