@illuma-ai/agents 1.3.2 → 1.4.0-alpha.1

package/src/providers/a2a/__tests__/A2ACapabilityProvider.test.ts

@@ -0,0 +1,460 @@
+/**
+ * Unit tests for A2ACapabilityProvider. Uses a mocked A2AClient so the
+ * provider can be exercised without spinning up a real remote agent.
+ * The integration test file covers the live HTTP path.
+ */
+
+import {
+  A2ACapabilityProvider,
+  coerceInputToA2AMessage,
+  formatCapabilityName,
+  parseCapabilityName,
+  skillToCapability,
+} from '../A2ACapabilityProvider';
+import { extractTaskText } from '../client';
+import { CapabilityKind } from '../../types';
+import type { A2AAgentCard, A2ATask } from '../types';
+
+// ---------------------------------------------------------------------------
+// A2AClient mock — replaced via jest.mock of ./client
+// ---------------------------------------------------------------------------
+
+const clientFetchCard = jest.fn();
+const clientSendTask = jest.fn();
+
+jest.mock('../client', () => {
+  const actual = jest.requireActual('../client');
+  return {
+    ...actual,
+    A2AClient: jest.fn().mockImplementation(() => ({
+      fetchAgentCard: clientFetchCard,
+      sendTask: clientSendTask,
+    })),
+  };
+});
+
+const resetMocks = (): void => {
+  clientFetchCard.mockReset();
+  clientSendTask.mockReset();
+};
+
+beforeEach(resetMocks);
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const makeCard = (
+  name: string,
+  skills: Array<{
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+  }> = []
+): A2AAgentCard => ({
+  name,
+  description: `${name} description`,
+  url: `http://${name}/`,
+  version: '1.0.0',
+  capabilities: { streaming: true },
+  defaultInputModes: ['text/plain'],
+  defaultOutputModes: ['text/plain'],
+  skills,
+});
+
+const makeCompletedTask = (text: string): A2ATask => ({
+  id: 'task-1',
+  status: { state: 'completed', timestamp: new Date().toISOString() },
+  artifacts: [{ parts: [{ type: 'text', text }] }],
+});
+
+// ---------------------------------------------------------------------------
+// Helper tests
+// ---------------------------------------------------------------------------
+
+describe('helpers', () => {
+  describe('formatCapabilityName / parseCapabilityName', () => {
+    it('joins and splits server + skill', () => {
+      const name = formatCapabilityName('research', 'search');
+      expect(name).toBe('research__search');
+      const parsed = parseCapabilityName(name);
+      expect(parsed).toEqual({ remoteName: 'research', skillId: 'search' });
+    });
+
+    it('handles no-skill case (flattened agents)', () => {
+      const name = formatCapabilityName('research');
+      expect(name).toBe('research');
+      const parsed = parseCapabilityName(name);
+      expect(parsed).toEqual({ remoteName: 'research' });
+    });
+
+    it('parseCapabilityName returns null on empty input', () => {
+      expect(parseCapabilityName('')).toBeNull();
+    });
+  });
+
+  describe('skillToCapability', () => {
+    it('produces an A2A Capability with metadata tags', () => {
+      const cap = skillToCapability('research', {
+        id: 'web_search',
+        name: 'Web Search',
+        description: 'Search the web',
+        tags: ['search'],
+      });
+      expect(cap.kind).toBe(CapabilityKind.A2A);
+      expect(cap.name).toBe('research__web_search');
+      expect(cap.description).toBe('Search the web');
+      expect(cap.metadata.tags).toEqual(['research', 'search']);
+    });
+  });
+
+  describe('coerceInputToA2AMessage', () => {
+    it('wraps a string directly', () => {
+      const msg = coerceInputToA2AMessage('hello');
+      expect(msg).toEqual({
+        role: 'user',
+        parts: [{ type: 'text', text: 'hello' }],
+      });
+    });
+
+    it('unwraps a { message } object', () => {
+      const msg = coerceInputToA2AMessage({ message: 'hi' });
+      expect(msg.parts[0].text).toBe('hi');
+    });
+
+    it('prepends skill marker when skillId is provided', () => {
+      const msg = coerceInputToA2AMessage('go', 'search');
+      expect(msg.parts[0].text).toBe('[skill: search]\ngo');
+    });
+
+    it('JSON-stringifies other shapes', () => {
+      const msg = coerceInputToA2AMessage({ foo: 'bar' });
+      expect(msg.parts[0].text).toBe('{"foo":"bar"}');
+    });
+  });
+
+  describe('extractTaskText', () => {
+    it('joins all text parts from completed artifacts', () => {
+      const text = extractTaskText({
+        id: 'x',
+        status: { state: 'completed', timestamp: 't' },
+        artifacts: [
+          { parts: [{ type: 'text', text: 'a' }] },
+          { parts: [{ type: 'text', text: 'b' }] },
+        ],
+      });
+      expect(text).toBe('a\n\nb');
+    });
+
+    it('throws when status is failed', () => {
+      expect(() =>
+        extractTaskText({
+          id: 'x',
+          status: { state: 'failed', timestamp: 't' },
+          error: { code: 1, message: 'boom' },
+        })
+      ).toThrow(/boom/);
+    });
+
+    it('throws when status is not completed', () => {
+      expect(() =>
+        extractTaskText({
+          id: 'x',
+          status: { state: 'working', timestamp: 't' },
+        })
+      ).toThrow(/not completed/);
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+
+describe('A2ACapabilityProvider construction', () => {
+  it('rejects empty remotes map', () => {
+    expect(() => new A2ACapabilityProvider({ remotes: {} })).toThrow(
+      /at least one remote/
+    );
+  });
+
+  it('providerId includes sorted remote names', () => {
+    const p = new A2ACapabilityProvider({
+      remotes: {
+        zeta: { url: 'http://z/' },
+        alpha: { url: 'http://a/' },
+      },
+    });
+    expect(p.providerId).toBe('a2a:alpha,zeta');
+  });
+
+  it('reads client identity from env when not provided', () => {
+    const prev = process.env.A2A_CLIENT_NAME;
+    process.env.A2A_CLIENT_NAME = 'test-client';
+    try {
+      const p = new A2ACapabilityProvider({
+        remotes: { r: { url: 'http://r/' } },
+      });
+      expect(p.providerId).toContain('r');
+    } finally {
+      if (prev === undefined) delete process.env.A2A_CLIENT_NAME;
+      else process.env.A2A_CLIENT_NAME = prev;
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fetchManifest
+// ---------------------------------------------------------------------------
+
+describe('fetchManifest', () => {
+  it('returns one Capability per skill by default', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('research', [
+        { id: 'web_search', name: 'Web', description: 'Search the web' },
+        { id: 'summarize', name: 'Summarize', description: 'Summarize text' },
+      ])
+    );
+
+    const p = new A2ACapabilityProvider({
+      remotes: { research: { url: 'http://r/' } },
+    });
+    const caps = await p.fetchManifest();
+
+    expect(caps).toHaveLength(2);
+    expect(caps[0].kind).toBe(CapabilityKind.A2A);
+    expect(caps[0].name).toBe('research__web_search');
+    expect(caps[1].name).toBe('research__summarize');
+  });
+
+  it('returns one Capability per remote when flattenAsSingleTool', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('research', [
+        { id: 'web_search', name: 'Web', description: 'Search' },
+      ])
+    );
+
+    const p = new A2ACapabilityProvider({
+      remotes: { research: { url: 'http://r/', flattenAsSingleTool: true } },
+    });
+    const caps = await p.fetchManifest();
+
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe('research');
+    expect(caps[0].metadata.tags).toContain('web_search');
+  });
+
+  it('exposes a single free-form capability when the card has no skills', async () => {
+    clientFetchCard.mockResolvedValue(makeCard('bare'));
+
+    const p = new A2ACapabilityProvider({
+      remotes: { bare: { url: 'http://b/' } },
+    });
+    const caps = await p.fetchManifest();
+
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe('bare');
+  });
+
+  it('merges capabilities from multiple remotes', async () => {
+    clientFetchCard
+      .mockResolvedValueOnce(
+        makeCard('a', [{ id: 's1', name: 'S1', description: 'd' }])
+      )
+      .mockResolvedValueOnce(
+        makeCard('b', [{ id: 's2', name: 'S2', description: 'd' }])
+      );
+
+    const p = new A2ACapabilityProvider({
+      remotes: {
+        a: { url: 'http://a/' },
+        b: { url: 'http://b/' },
+      },
+    });
+    const caps = await p.fetchManifest();
+    expect(caps.map((c) => c.name).sort()).toEqual(['a__s1', 'b__s2']);
+  });
+
+  it('continues when one remote fails', async () => {
+    clientFetchCard
+      .mockRejectedValueOnce(new Error('boom'))
+      .mockResolvedValueOnce(
+        makeCard('ok', [{ id: 'go', name: 'Go', description: 'g' }])
+      );
+
+    const p = new A2ACapabilityProvider({
+      remotes: {
+        broken: { url: 'http://x/' },
+        ok: { url: 'http://ok/' },
+      },
+    });
+    const caps = await p.fetchManifest();
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe('ok__go');
+  });
+
+  it('short-circuits when filter excludes a2a kind', async () => {
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const caps = await p.fetchManifest({ kind: CapabilityKind.TOOL });
+    expect(caps).toEqual([]);
+    expect(clientFetchCard).not.toHaveBeenCalled();
+  });
+
+  it('applies name filter', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('r', [
+        { id: 's1', name: 'S1', description: 'd' },
+        { id: 's2', name: 'S2', description: 'd' },
+      ])
+    );
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const caps = await p.fetchManifest({ names: ['r__s2'] });
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe('r__s2');
+  });
+
+  it('calls getAuthHeaders once per remote', async () => {
+    clientFetchCard.mockResolvedValue(makeCard('r'));
+    const getAuthHeaders = jest
+      .fn()
+      .mockResolvedValue({ Authorization: 'Bearer x' });
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+      getAuthHeaders,
+    });
+    await p.fetchManifest();
+
+    expect(getAuthHeaders).toHaveBeenCalledTimes(1);
+    expect(getAuthHeaders).toHaveBeenCalledWith('r');
+  });
+
+  it('caches the card fetch across calls', async () => {
+    clientFetchCard.mockResolvedValue(makeCard('r'));
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    await p.fetchManifest();
+    await p.fetchManifest();
+    expect(clientFetchCard).toHaveBeenCalledTimes(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createRunnables
+// ---------------------------------------------------------------------------
+
+describe('createRunnables', () => {
+  it('builds one StructuredTool per A2A capability', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('r', [
+        { id: 's1', name: 'S1', description: 'd' },
+        { id: 's2', name: 'S2', description: 'd' },
+      ])
+    );
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const caps = await p.fetchManifest();
+    const runnables = await p.createRunnables(caps, {});
+    expect(runnables).toHaveLength(2);
+    expect(runnables[0].name).toBe('r__s1');
+  });
+
+  it('skips non-A2A capabilities', async () => {
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const runnables = await p.createRunnables(
+      [
+        {
+          kind: CapabilityKind.TOOL,
+          name: 'other',
+          description: 'other',
+          authConfig: [],
+          metadata: {},
+        },
+      ],
+      {}
+    );
+    expect(runnables).toHaveLength(0);
+  });
+
+  it('proxy tool sends a task to the remote and returns its text', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('r', [{ id: 'echo', name: 'Echo', description: 'Echo' }])
+    );
+    clientSendTask.mockResolvedValue(makeCompletedTask('received: hi'));
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const caps = await p.fetchManifest();
+    const [runnable] = await p.createRunnables(caps, {});
+    const result = await runnable.invoke({ message: 'hi' });
+
+    expect(result).toBe('received: hi');
+    expect(clientSendTask).toHaveBeenCalledTimes(1);
+    const sentParams = clientSendTask.mock.calls[0][0];
+    expect(sentParams.message.parts[0].text).toContain('[skill: echo]');
+    expect(sentParams.message.parts[0].text).toContain('hi');
+  });
+
+  it('proxy tool throws when task fails', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('r', [{ id: 'fail', name: 'F', description: 'F' }])
+    );
+    clientSendTask.mockResolvedValue({
+      id: 't',
+      status: { state: 'failed', timestamp: 't' },
+      error: { code: 500, message: 'backend exploded' },
+    });
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const [runnable] = await p.createRunnables(await p.fetchManifest(), {});
+    await expect(runnable.invoke({ message: 'hi' })).rejects.toThrow(
+      /backend exploded/
+    );
+  });
+
+  it('proxy tool coerces string input into an A2A message', async () => {
+    clientFetchCard.mockResolvedValue(
+      makeCard('r', [{ id: 'echo', name: 'Echo', description: 'd' }])
+    );
+    clientSendTask.mockResolvedValue(makeCompletedTask('ok'));
+
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    const [runnable] = await p.createRunnables(await p.fetchManifest(), {});
+    const result = await runnable.invoke({ message: 'plain string' });
+    expect(result).toBe('ok');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// close
+// ---------------------------------------------------------------------------
+
+describe('close', () => {
+  it('clears cached connections', async () => {
+    clientFetchCard.mockResolvedValue(makeCard('r'));
+    const p = new A2ACapabilityProvider({
+      remotes: { r: { url: 'http://r/' } },
+    });
+    await p.fetchManifest();
+    await p.close();
+    // Next fetchManifest should re-fetch the card.
+    await p.fetchManifest();
+    expect(clientFetchCard).toHaveBeenCalledTimes(2);
+  });
+});

package/src/providers/a2a/client.ts

@@ -0,0 +1,115 @@
+/**
+ * A2A HTTP client — thin wrappers for the two operations the provider
+ * needs: fetching the agent card and sending JSON-RPC task requests.
+ *
+ * Uses axios (already in deps) via the shared httpClient utility so
+ * proxy config + headers work consistently with the tools-server provider.
+ */
+
+import { createHttpClient, assertOk } from '@/utils/httpClient';
+import type {
+  A2AAgentCard,
+  A2ATask,
+  A2ATaskParams,
+  JsonRpcRequest,
+  JsonRpcResponse,
+} from './types';
+
+const DEFAULT_CARD_PATH = '/.well-known/agent.json';
+const DEFAULT_RPC_PATH = '/';
+const JSON_RPC_VERSION = '2.0';
+
+/** Options for constructing a single-remote A2A client. */
+export interface A2AClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+  timeoutMs?: number;
+  cardPath?: string;
+  rpcPath?: string;
+}
+
+/**
+ * Lightweight single-remote A2A client. One instance per remote; the
+ * provider builds one per spec entry and caches them.
+ */
+export class A2AClient {
+  private readonly http: ReturnType<typeof createHttpClient>;
+  private readonly cardPath: string;
+  private readonly rpcPath: string;
+
+  constructor(opts: A2AClientOptions) {
+    this.http = createHttpClient({
+      baseURL: opts.baseUrl,
+      headers: opts.headers,
+      timeoutMs: opts.timeoutMs,
+    });
+    this.cardPath = opts.cardPath ?? DEFAULT_CARD_PATH;
+    this.rpcPath = opts.rpcPath ?? DEFAULT_RPC_PATH;
+  }
+
+  /** GET /.well-known/agent.json (or the configured override). */
+  async fetchAgentCard(): Promise<A2AAgentCard> {
+    const res = await this.http.get<A2AAgentCard>(this.cardPath);
+    assertOk(res.status, this.cardPath, res.data);
+    return res.data;
+  }
+
+  /**
+   * POST a JSON-RPC `tasks/send` request and return the resulting Task.
+   * The caller supplies the params (id, sessionId, message); this helper
+   * wraps it in the JSON-RPC envelope, dispatches, and unwraps.
+   */
+  async sendTask(params: A2ATaskParams): Promise<A2ATask> {
+    const result = await this.rpc<A2ATaskParams, A2ATask>('tasks/send', params);
+    return result;
+  }
+
+  /** Low-level JSON-RPC dispatcher — exposed for tests / advanced callers. */
+  async rpc<P, R>(method: string, params: P): Promise<R> {
+    const body: JsonRpcRequest<P> = {
+      jsonrpc: JSON_RPC_VERSION,
+      id: generateRpcId(),
+      method,
+      params,
+    };
+    const res = await this.http.post<JsonRpcResponse<R>>(this.rpcPath, body);
+    assertOk(res.status, this.rpcPath, res.data);
+
+    const data = res.data;
+    if (data && 'error' in data && data.error) {
+      throw new Error(
+        `A2A ${method} error: ${data.error.message} (code ${data.error.code})`
+      );
+    }
+    if (data && 'result' in data) return data.result;
+    throw new Error(`A2A ${method}: malformed response (no result)`);
+  }
+}
+
+/**
+ * Generate a short opaque id for JSON-RPC requests. Not cryptographic —
+ * just unique enough to pair request/response in logs.
+ */
+export function generateRpcId(): string {
+  return `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * Extract the plain-text output from a completed Task's artifacts. If
+ * the task isn't `completed`, throws. If there are no text parts, returns
+ * an empty string rather than null so callers always get a string.
+ */
+export function extractTaskText(task: A2ATask): string {
+  if (task.status.state === 'failed') {
+    throw new Error(
+      `A2A task ${task.id} failed: ${task.error?.message ?? 'unknown error'}`
+    );
+  }
+  if (task.status.state !== 'completed') {
+    throw new Error(
+      `A2A task ${task.id} not completed (state=${task.status.state})`
+    );
+  }
+  const parts = task.artifacts?.flatMap((a) => a.parts) ?? [];
+  return parts.map((p) => p.text ?? '').join('\n\n');
+}

package/src/providers/a2a/config.ts

@@ -0,0 +1,40 @@
+/**
+ * Environment-driven defaults + default logger for the A2A provider.
+ *
+ * Mirrors the MCP provider's config.ts so the two providers have the same
+ * override story for hosts.
+ */
+
+import type { A2ALogger } from './types';
+
+/**
+ * Read env values with fallbacks. Evaluated lazily so tests that mutate
+ * process.env get the current value.
+ */
+export function getA2AEnvDefaults(): {
+  clientName: string;
+  clientVersion: string;
+  timeoutMs: number;
+} {
+  return {
+    /**
+     * Identity sent to A2A-served remotes in user-agent / request headers.
+     * Precedence: constructor config → env var → library default.
+     */
+    clientName: process.env.A2A_CLIENT_NAME ?? 'illuma-agents',
+    clientVersion: process.env.A2A_CLIENT_VERSION ?? '1.0.0',
+    timeoutMs: Number(process.env.A2A_REQUEST_TIMEOUT_MS ?? 30_000),
+  };
+}
+
+/** Console-routed default logger. */
+export const consoleLogger: A2ALogger = {
+  // eslint-disable-next-line no-console
+  debug: (...args) => console.debug('[a2a]', ...args),
+  // eslint-disable-next-line no-console
+  info: (...args) => console.info('[a2a]', ...args),
+  // eslint-disable-next-line no-console
+  warn: (...args) => console.warn('[a2a]', ...args),
+  // eslint-disable-next-line no-console
+  error: (...args) => console.error('[a2a]', ...args),
+};

package/src/providers/a2a/index.ts

@@ -0,0 +1,29 @@
+export { A2ACapabilityProvider } from './A2ACapabilityProvider';
+export {
+  CAPABILITY_NAME_SEPARATOR,
+  formatCapabilityName,
+  parseCapabilityName,
+  skillToCapability,
+  coerceInputToA2AMessage,
+  MESSAGE_INPUT_SCHEMA,
+} from './A2ACapabilityProvider';
+export { A2AClient, extractTaskText, generateRpcId } from './client';
+export type { A2AClientOptions } from './client';
+export { consoleLogger as a2aConsoleLogger, getA2AEnvDefaults } from './config';
+export type {
+  A2AAgentCard,
+  A2ACardCapabilities,
+  A2ALogger,
+  A2AMessage,
+  A2AProviderConfig,
+  A2ARemoteSpec,
+  A2ASkill,
+  A2ATask,
+  A2ATaskParams,
+  A2ATaskState,
+  A2ATaskStatus,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcSuccess,
+  JsonRpcErrorResponse,
+} from './types';