@illuma-ai/agents 1.3.1 → 1.4.0-alpha.0

package/src/providers/a2a/__tests__/A2ACapabilityProvider.integration.spec.ts

@@ -0,0 +1,345 @@
+/**
+ * Integration test — exercises A2ACapabilityProvider against a local HTTP
+ * server that implements the A2A protocol.
+ *
+ * The harness is a minimal pure-http A2A-compliant server:
+ *   - GET /.well-known/agent.json  → agent card
+ *   - POST /                        → JSON-RPC dispatcher (tasks/send)
+ *
+ * Validates the same surface a real A2A-served agent exposes, without
+ * needing to boot the full CLI runner.
+ */
+
+import { createServer, type Server as HttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import {
+  A2ACapabilityProvider,
+  formatCapabilityName,
+} from '../A2ACapabilityProvider';
+import { CapabilityKind } from '../../types';
+import type { A2AAgentCard, A2ATaskParams } from '../types';
+
+// ---------------------------------------------------------------------------
+// Minimal A2A HTTP harness
+// ---------------------------------------------------------------------------
+
+interface Harness {
+  url: string;
+  httpServer: HttpServer;
+  lastHeaders: Record<string, string>;
+  lastTaskMessage: string | undefined;
+  close: () => Promise<void>;
+}
+
+const CARD_FIXTURE: A2AAgentCard = {
+  name: 'research-assistant',
+  description: 'A test agent that echoes inbound messages.',
+  url: 'http://placeholder/', // overwritten after listen()
+  version: '1.0.0',
+  capabilities: { streaming: true },
+  defaultInputModes: ['text/plain'],
+  defaultOutputModes: ['text/plain'],
+  skills: [
+    {
+      id: 'echo',
+      name: 'Echo',
+      description: 'Return the inbound message as the response.',
+      tags: ['echo'],
+    },
+    {
+      id: 'upper',
+      name: 'Uppercase',
+      description: 'Return the inbound message in uppercase.',
+      tags: ['transform'],
+    },
+  ],
+};
+
+async function startLocalA2AServer(
+  opts: { requireAuth?: boolean } = {}
+): Promise<Harness> {
+  const lastHeaders: Record<string, string> = {};
+  let lastTaskMessage: string | undefined;
+
+  const httpServer = createServer(async (req, res) => {
+    for (const [k, v] of Object.entries(req.headers)) {
+      if (typeof v === 'string') lastHeaders[k.toLowerCase()] = v;
+    }
+
+    if (opts.requireAuth) {
+      const auth = req.headers['authorization'];
+      if (typeof auth !== 'string' || !auth.startsWith('Bearer ')) {
+        res.writeHead(401, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'unauthorized' }));
+        return;
+      }
+    }
+
+    const url = req.url ?? '';
+
+    // Agent card endpoint
+    if (req.method === 'GET' && url === '/.well-known/agent.json') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          ...CARD_FIXTURE,
+          url: `http://127.0.0.1:${(req.socket.localPort ?? 0).toString()}/`,
+        })
+      );
+      return;
+    }
+
+    // JSON-RPC endpoint
+    if (req.method === 'POST' && (url === '/' || url === '')) {
+      const chunks: Buffer[] = [];
+      for await (const chunk of req) chunks.push(chunk as Buffer);
+      const body = Buffer.concat(chunks).toString('utf8');
+
+      let parsed: {
+        jsonrpc: '2.0';
+        id: string | number | null;
+        method: string;
+        params: A2ATaskParams;
+      };
+      try {
+        parsed = JSON.parse(body);
+      } catch {
+        res.writeHead(400, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ error: 'invalid JSON' }));
+        return;
+      }
+
+      if (parsed.method !== 'tasks/send') {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: parsed.id,
+            error: {
+              code: -32601,
+              message: `Method not found: ${parsed.method}`,
+            },
+          })
+        );
+        return;
+      }
+
+      const text = parsed.params.message.parts[0]?.text ?? '';
+      lastTaskMessage = text;
+
+      const isUpper = text.includes('[skill: upper]');
+      // Strip the leading `[skill: xxx]\n` prefix before echoing.
+      const cleanText = text.replace(/^\[skill: [^\]]+\]\n?/, '');
+      const responseText = isUpper ? cleanText.toUpperCase() : cleanText;
+
+      const isFailSignal = cleanText === '__FAIL__';
+      if (isFailSignal) {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            id: parsed.id,
+            result: {
+              id: parsed.params.id,
+              status: { state: 'failed', timestamp: new Date().toISOString() },
+              error: { code: 500, message: 'intentional failure' },
+            },
+          })
+        );
+        return;
+      }
+
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(
+        JSON.stringify({
+          jsonrpc: '2.0',
+          id: parsed.id,
+          result: {
+            id: parsed.params.id,
+            status: { state: 'completed', timestamp: new Date().toISOString() },
+            artifacts: [{ parts: [{ type: 'text', text: responseText }] }],
+          },
+        })
+      );
+      return;
+    }
+
+    res.writeHead(404);
+    res.end();
+  });
+
+  await new Promise<void>((resolve) =>
+    httpServer.listen(0, '127.0.0.1', resolve)
+  );
+  const port = (httpServer.address() as AddressInfo).port;
+  const url = `http://127.0.0.1:${port}/`;
+
+  return {
+    url,
+    httpServer,
+    lastHeaders,
+    get lastTaskMessage() {
+      return lastTaskMessage;
+    },
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        httpServer.close((err) => (err ? reject(err) : resolve()));
+      }),
+  } as unknown as Harness;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('A2ACapabilityProvider (live HTTP)', () => {
+  let harness: Harness;
+  let provider: A2ACapabilityProvider;
+
+  beforeAll(async () => {
+    harness = await startLocalA2AServer();
+  });
+
+  afterAll(async () => {
+    await provider?.close();
+    await harness.close();
+  });
+
+  it('fetches agent card and exposes one Capability per skill', async () => {
+    provider = new A2ACapabilityProvider({
+      remotes: { research: { url: harness.url } },
+    });
+
+    const caps = await provider.fetchManifest();
+    const names = caps.map((c) => c.name).sort();
+    expect(names).toEqual([
+      formatCapabilityName('research', 'echo'),
+      formatCapabilityName('research', 'upper'),
+    ]);
+    expect(caps[0].kind).toBe(CapabilityKind.A2A);
+  });
+
+  it('invokes a skill end-to-end and returns the remote response', async () => {
+    const caps = await provider.fetchManifest({
+      names: [formatCapabilityName('research', 'echo')],
+    });
+    expect(caps).toHaveLength(1);
+
+    const [runnable] = await provider.createRunnables(caps, {});
+    const result = await runnable.invoke({ message: 'hello world' });
+    expect(result).toBe('hello world');
+  });
+
+  it('routes skill-specific behavior via the skillId marker', async () => {
+    const caps = await provider.fetchManifest({
+      names: [formatCapabilityName('research', 'upper')],
+    });
+    const [runnable] = await provider.createRunnables(caps, {});
+    const result = await runnable.invoke({ message: 'hi' });
+    expect(result).toBe('HI');
+  });
+
+  it('surfaces a failed task as a thrown error', async () => {
+    const caps = await provider.fetchManifest({
+      names: [formatCapabilityName('research', 'echo')],
+    });
+    const [runnable] = await provider.createRunnables(caps, {});
+    await expect(runnable.invoke({ message: '__FAIL__' })).rejects.toThrow(
+      /intentional failure/
+    );
+  });
+});
+
+describe('A2ACapabilityProvider — auth header forwarding', () => {
+  let harness: Harness;
+  let provider: A2ACapabilityProvider;
+
+  beforeAll(async () => {
+    harness = await startLocalA2AServer({ requireAuth: true });
+  });
+
+  afterAll(async () => {
+    await provider?.close();
+    await harness.close();
+  });
+
+  it('rejects without auth (server 401 → empty manifest)', async () => {
+    provider = new A2ACapabilityProvider({
+      remotes: { secure: { url: harness.url } },
+    });
+    const caps = await provider.fetchManifest();
+    expect(caps).toEqual([]);
+  });
+
+  it('succeeds when getAuthHeaders supplies a Bearer token', async () => {
+    provider = new A2ACapabilityProvider({
+      remotes: { secure: { url: harness.url } },
+      getAuthHeaders: () => ({ Authorization: 'Bearer a2a-test-token' }),
+    });
+    const caps = await provider.fetchManifest();
+    expect(caps.length).toBeGreaterThan(0);
+    expect(harness.lastHeaders['authorization']).toBe('Bearer a2a-test-token');
+  });
+});
+
+describe('A2ACapabilityProvider — config-source patterns', () => {
+  let harness: Harness;
+
+  beforeAll(async () => {
+    harness = await startLocalA2AServer();
+  });
+
+  afterAll(async () => {
+    await harness.close();
+  });
+
+  const verifyRemote = async (p: A2ACapabilityProvider): Promise<void> => {
+    const caps = await p.fetchManifest();
+    expect(caps.length).toBeGreaterThan(0);
+    const echoCap = caps.find((c) => c.name.endsWith('__echo'));
+    expect(echoCap).toBeDefined();
+    const [runnable] = await p.createRunnables([echoCap!], {});
+    const result = await runnable.invoke({ message: 'ok' });
+    expect(result).toBe('ok');
+    await p.close();
+  };
+
+  it('direct programmatic spec', async () => {
+    const p = new A2ACapabilityProvider({
+      remotes: { mine: { url: harness.url } },
+    });
+    await verifyRemote(p);
+  });
+
+  it('YAML-derived spec (simulated)', async () => {
+    const yamlLike = {
+      remote_agents: [{ name: 'from-yaml', url: harness.url }],
+    };
+    const remotes: Record<string, { url: string }> = {};
+    for (const entry of yamlLike.remote_agents) {
+      remotes[entry.name] = { url: entry.url };
+    }
+    const p = new A2ACapabilityProvider({ remotes });
+    await verifyRemote(p);
+  });
+
+  it('marketplace-catalog-derived spec (simulated)', async () => {
+    const marketplaceEntry = {
+      id: 'market-agent',
+      name: 'Market Agent',
+      transport: 'a2a' as const,
+      url: harness.url,
+      authConfig: [{ authField: 'A2A_MARKET_TOKEN', required: false }],
+    };
+    const p = new A2ACapabilityProvider({
+      remotes: {
+        [marketplaceEntry.id]: { url: marketplaceEntry.url },
+      },
+      getAuthHeaders: () => ({
+        'x-market-token': 'resolved-by-host',
+      }),
+    });
+    await verifyRemote(p);
+  });
+});