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

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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,384 @@
+/**
+ * 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 }] };
+}