@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

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

@@ -1,460 +0,0 @@
-/**
- * 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

@@ -1,115 +0,0 @@
-/**
- * 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

@@ -1,40 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-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';