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

package/src/providers/__tests__/types.test.ts

@@ -1,64 +0,0 @@
-import {
-  CapabilityKind,
-  AuthSource,
-  type Capability,
-  type CapabilityProvider,
-  type CredentialMap,
-} from '../types';
-
-describe('CapabilityProvider types', () => {
-  it('CapabilityKind enum covers tool/skill/mcp', () => {
-    expect(CapabilityKind.TOOL).toBe('tool');
-    expect(CapabilityKind.SKILL).toBe('skill');
-    expect(CapabilityKind.MCP).toBe('mcp');
-  });
-
-  it('AuthSource enum covers server/user/forwarded', () => {
-    expect(AuthSource.SERVER).toBe('server');
-    expect(AuthSource.USER).toBe('user');
-    expect(AuthSource.FORWARDED).toBe('forwarded');
-  });
-
-  it('Capability shape reserves upstream metadata fields', () => {
-    const cap: Capability = {
-      kind: CapabilityKind.TOOL,
-      name: 'sample',
-      description: 'test capability',
-      schema: { type: 'object' },
-      authConfig: [],
-      metadata: {
-        icon: '/icon.svg',
-        category: 'test',
-        tags: ['a', 'b'],
-        auth: 'oauth',
-        expires_at: 1735689600,
-        injectedMessages: false,
-        sessionAware: false,
-      },
-    };
-    expect(cap.name).toBe('sample');
-    expect(cap.metadata.expires_at).toBe(1735689600);
-  });
-
-  it('CredentialMap is a plain string record', () => {
-    const creds: CredentialMap = {
-      OPENAI_API_KEY: 'sk-xxx',
-      WOLFRAM_APP_ID: 'abc123',
-    };
-    expect(Object.keys(creds)).toHaveLength(2);
-  });
-
-  it('CapabilityProvider is an implementable contract', () => {
-    class FakeProvider implements CapabilityProvider {
-      readonly providerId = 'fake';
-      async fetchManifest() {
-        return [];
-      }
-      async createRunnables() {
-        return [];
-      }
-    }
-    const p: CapabilityProvider = new FakeProvider();
-    expect(p.providerId).toBe('fake');
-  });
-});

package/src/providers/a2a/A2ACapabilityProvider.ts

@@ -1,384 +0,0 @@
-/**
- * A2ACapabilityProvider — client-side adapter for consuming A2A-served
- * remote agents as capabilities.
- *
- * Same pattern as `MCPCapabilityProvider`: take a unified spec map,
- * speak the protocol (A2A JSON-RPC over HTTP), expose each skill as a
- * `Capability` / `StructuredTool`.
- *
- * Design:
- *   - One `A2AClient` per remote spec, cached after first use.
- *   - `fetchManifest()`:
- *       for each remote, GET /.well-known/agent.json → emit one
- *       Capability per advertised skill (or one per remote when
- *       `flattenAsSingleTool` is set).
- *   - `createRunnables()`:
- *       each Capability becomes a StructuredTool whose invoke sends a
- *       JSON-RPC `tasks/send` to the remote and returns the final
- *       artifact's text.
- *
- * What the host supplies:
- *   - `remotes`: unified spec map (normalized from whatever source).
- *   - `getAuthHeaders?`: per-remote header resolver. Called at connect
- *     time. OAuth / token refresh stays in the host.
- */
-
-import { tool, type StructuredToolInterface } from '@langchain/core/tools';
-
-import {
-  CapabilityKind,
-  type Capability,
-  type CapabilityFilter,
-  type CapabilityProvider,
-  type CredentialMap,
-} from '@/providers/types';
-import {
-  CAPABILITY_NAME_SEPARATOR,
-  formatCapabilityName,
-  parseCapabilityName as parseSharedName,
-} from '@/providers/capabilityNaming';
-import { A2AClient, extractTaskText, generateRpcId } from './client';
-import { consoleLogger, getA2AEnvDefaults } from './config';
-import type {
-  A2AAgentCard,
-  A2ALogger,
-  A2AProviderConfig,
-  A2ARemoteSpec,
-  A2ASkill,
-} from './types';
-
-/**
- * Per-remote cached state. The agent card is fetched lazily and reused.
- */
-interface RemoteConnection {
-  remoteName: string;
-  spec: A2ARemoteSpec;
-  client: A2AClient;
-  card: A2AAgentCard;
-}
-
-export class A2ACapabilityProvider implements CapabilityProvider {
-  readonly providerId: string;
-  private readonly config: Required<
-    Pick<A2AProviderConfig, 'clientInfo' | 'timeoutMs'>
-  > &
-    Pick<A2AProviderConfig, 'remotes' | 'getAuthHeaders'>;
-  private readonly logger: A2ALogger;
-  private readonly connections = new Map<string, RemoteConnection>();
-
-  constructor(config: A2AProviderConfig) {
-    if (!config.remotes || Object.keys(config.remotes).length === 0) {
-      throw new Error('A2ACapabilityProvider: at least one remote is required');
-    }
-    const env = getA2AEnvDefaults();
-    this.config = {
-      remotes: config.remotes,
-      getAuthHeaders: config.getAuthHeaders,
-      clientInfo: config.clientInfo ?? {
-        name: env.clientName,
-        version: env.clientVersion,
-      },
-      timeoutMs: config.timeoutMs ?? env.timeoutMs,
-    };
-    this.logger = config.logger ?? consoleLogger;
-    const names = Object.keys(config.remotes).sort().join(',');
-    this.providerId = `a2a:${names}`;
-  }
-
-  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {
-    if (filter?.kind && filter.kind !== CapabilityKind.A2A) return [];
-
-    const capabilities: Capability[] = [];
-    for (const remoteName of Object.keys(this.config.remotes)) {
-      try {
-        const conn = await this.ensureConnection(remoteName);
-        const caps = this.cardToCapabilities(remoteName, conn.card, conn.spec);
-        for (const cap of caps) {
-          if (this.capabilityMatchesFilter(cap, filter)) capabilities.push(cap);
-        }
-      } catch (err) {
-        // One remote failing must not block others — log and continue.
-        this.logger.warn(
-          `[a2a] failed to fetch manifest for remote "${remoteName}":`,
-          err instanceof Error ? err.message : err
-        );
-      }
-    }
-
-    this.logger.debug(
-      `[a2a] manifest assembled — ${capabilities.length} capabilities across ${this.connections.size}/${Object.keys(this.config.remotes).length} connected remotes`
-    );
-
-    return capabilities;
-  }
-
-  async createRunnables(
-    capabilities: Capability[],
-    _credentials: CredentialMap
-  ): Promise<StructuredToolInterface[]> {
-    const runnables: StructuredToolInterface[] = [];
-    for (const cap of capabilities) {
-      if (cap.kind !== CapabilityKind.A2A) continue;
-      const parsed = parseCapabilityName(cap.name);
-      if (!parsed) {
-        this.logger.warn(
-          `[a2a] skipping capability "${cap.name}" — unparseable`
-        );
-        continue;
-      }
-      runnables.push(
-        this.buildProxyTool(parsed.remoteName, parsed.skillId, cap)
-      );
-    }
-    return runnables;
-  }
-
-  /** Disconnect any cached clients. A2A is stateless over HTTP so this
-   *  is effectively a cache clear — no sockets to close. */
-  async close(): Promise<void> {
-    this.connections.clear();
-  }
-
-  // --- internals ---------------------------------------------------------
-
-  private async ensureConnection(
-    remoteName: string
-  ): Promise<RemoteConnection> {
-    const existing = this.connections.get(remoteName);
-    if (existing) return existing;
-
-    const spec = this.config.remotes[remoteName];
-    if (!spec) {
-      throw new Error(`[a2a] remote "${remoteName}" not in config`);
-    }
-
-    const authHeaders = await this.resolveAuthHeaders(remoteName);
-    const headers = {
-      ...(spec.headers ?? {}),
-      ...(authHeaders ?? {}),
-      'user-agent': `${this.config.clientInfo.name}/${this.config.clientInfo.version}`,
-    };
-
-    const client = new A2AClient({
-      baseUrl: spec.url,
-      headers,
-      timeoutMs: this.config.timeoutMs,
-      cardPath: spec.cardPath,
-      rpcPath: spec.rpcPath,
-    });
-
-    this.logger.debug(
-      `[a2a] fetching card from "${remoteName}" at ${spec.url}`
-    );
-    const card = await client.fetchAgentCard();
-    this.logger.debug(
-      `[a2a] connected to "${remoteName}" — ${card.skills.length ?? 0} skills discovered`
-    );
-
-    const conn: RemoteConnection = { remoteName, spec, client, card };
-    this.connections.set(remoteName, conn);
-    return conn;
-  }
-
-  private async resolveAuthHeaders(
-    remoteName: string
-  ): Promise<Record<string, string> | undefined> {
-    if (!this.config.getAuthHeaders) return undefined;
-    try {
-      return await this.config.getAuthHeaders(remoteName);
-    } catch (err) {
-      this.logger.warn(
-        `[a2a] getAuthHeaders("${remoteName}") threw:`,
-        err instanceof Error ? err.message : err
-      );
-      return undefined;
-    }
-  }
-
-  private cardToCapabilities(
-    remoteName: string,
-    card: A2AAgentCard,
-    spec: A2ARemoteSpec
-  ): Capability[] {
-    if (spec.flattenAsSingleTool) {
-      // One capability per remote, named after the remote. Useful when
-      // the card has no skills listed or you want coarse routing.
-      return [
-        {
-          kind: CapabilityKind.A2A,
-          name: formatCapabilityName(remoteName),
-          description: card.description ?? card.name,
-          schema: MESSAGE_INPUT_SCHEMA,
-          authConfig: [],
-          metadata: {
-            category: 'a2a',
-            tags: [remoteName, ...(card.skills.map((s) => s.id) ?? [])],
-          },
-        },
-      ];
-    }
-
-    if (!card.skills || card.skills.length === 0) {
-      // No skills advertised — expose a single message endpoint so the
-      // agent can still invoke the remote with free-form text.
-      return [
-        {
-          kind: CapabilityKind.A2A,
-          name: formatCapabilityName(remoteName),
-          description:
-            card.description ?? `Delegate to remote agent "${card.name}".`,
-          schema: MESSAGE_INPUT_SCHEMA,
-          authConfig: [],
-          metadata: { category: 'a2a', tags: [remoteName] },
-        },
-      ];
-    }
-
-    return card.skills.map(
-      (skill): Capability => skillToCapability(remoteName, skill)
-    );
-  }
-
-  private capabilityMatchesFilter(
-    cap: Capability,
-    filter?: CapabilityFilter
-  ): boolean {
-    if (!filter) return true;
-    if (filter.kind && cap.kind !== filter.kind) return false;
-    if (filter.names && !filter.names.includes(cap.name)) return false;
-    if (filter.tags?.length) {
-      const capTags = new Set(cap.metadata.tags ?? []);
-      if (!filter.tags.some((t) => capTags.has(t))) return false;
-    }
-    return true;
-  }
-
-  private buildProxyTool(
-    remoteName: string,
-    skillId: string | undefined,
-    cap: Capability
-  ): StructuredToolInterface {
-    const logger = this.logger;
-    const ensureConnection = this.ensureConnection.bind(this);
-
-    return tool(
-      async (input: unknown): Promise<string> => {
-        // DEBUG: log tool invocation (remove after POC stabilizes)
-        logger.debug(
-          `[a2a] invoking ${remoteName}${skillId ? `:${skillId}` : ''}`
-        );
-
-        const message = coerceInputToA2AMessage(input, skillId);
-        const conn = await ensureConnection(remoteName);
-        const task = await conn.client.sendTask({
-          id: generateRpcId(),
-          message,
-        });
-
-        try {
-          return extractTaskText(task);
-        } catch (err) {
-          throw new Error(
-            `A2A ${remoteName}${skillId ? `:${skillId}` : ''} failed: ${err instanceof Error ? err.message : String(err)}`
-          );
-        }
-      },
-      {
-        name: cap.name,
-        description: cap.description,
-        schema: (cap.schema as object) ?? MESSAGE_INPUT_SCHEMA,
-        responseFormat: 'content',
-      }
-    );
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Helpers exported for testing
-// ---------------------------------------------------------------------------
-
-// CAPABILITY_NAME_SEPARATOR + formatCapabilityName live in the shared
-// `@/providers/capabilityNaming` module so every provider uses the same
-// encoding. Re-exported here for backward-compatible imports from the
-// A2A barrel.
-export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName };
-
-/**
- * Parse a capability name produced by this provider, returning A2A-specific
- * field names (`remoteName` / `skillId`). Thin adapter over the shared
- * `parseCapabilityName` — kept local so callers see the A2A vocabulary.
- */
-export function parseCapabilityName(
-  name: string
-): { remoteName: string; skillId?: string } | null {
-  const parsed = parseSharedName(name);
-  if (!parsed) return null;
-  return {
-    remoteName: parsed.sourceName,
-    skillId: parsed.itemName,
-  };
-}
-
-/** Derive a Capability from a skill entry on the agent card. */
-export function skillToCapability(
-  remoteName: string,
-  skill: A2ASkill
-): Capability {
-  return {
-    kind: CapabilityKind.A2A,
-    name: formatCapabilityName(remoteName, skill.id),
-    description: skill.description || skill.name || skill.id,
-    schema: MESSAGE_INPUT_SCHEMA,
-    authConfig: [],
-    metadata: {
-      category: 'a2a',
-      tags: [remoteName, ...(skill.tags ?? [])],
-    },
-  };
-}
-
-/**
- * Default input schema for A2A capabilities. Every invocation is a text
- * message — we don't try to infer a per-skill input shape because the
- * A2A spec's skill entries don't include a parameter schema.
- */
-export const MESSAGE_INPUT_SCHEMA = {
-  type: 'object',
-  properties: {
-    message: {
-      type: 'string',
-      description:
-        'Instruction or question to send to the remote agent as a user message.',
-    },
-  },
-  required: ['message'],
-} as const;
-
-/**
- * Coerce arbitrary LLM-supplied input into a valid A2A message. If the
- * input is a string, wraps it directly. If it's `{ message: "..." }`,
- * uses `message`. Otherwise JSON-stringifies so the agent receives
- * something it can try to interpret.
- *
- * When a skill id is known, it's prepended to the message text so the
- * remote agent can route — some A2A implementations use this, others
- * ignore it, it's best-effort.
- */
-export function coerceInputToA2AMessage(
-  input: unknown,
-  skillId?: string
-): { role: 'user'; parts: Array<{ type: 'text'; text: string }> } {
-  let text: string;
-  if (typeof input === 'string') {
-    text = input;
-  } else if (input && typeof input === 'object' && 'message' in input) {
-    const val = (input as { message: unknown }).message;
-    text = typeof val === 'string' ? val : JSON.stringify(val);
-  } else {
-    text = JSON.stringify(input);
-  }
-  if (skillId) {
-    text = `[skill: ${skillId}]\n${text}`;
-  }
-  return { role: 'user', parts: [{ type: 'text', text }] };
-}