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

package/src/providers/a2a/types.ts

@@ -0,0 +1,191 @@
+/**
+ * Types for the A2A capability provider.
+ *
+ * A2A (Agent-to-Agent) is a public HTTP + JSON-RPC 2.0 protocol for
+ * invoking one agent from another. When an agent has been served over
+ * A2A (e.g., via `ranger agents serve` or any compliant runtime), a
+ * caller agent can use `A2ACapabilityProvider` to:
+ *   - discover the remote agent's skills via `GET /.well-known/agent.json`
+ *   - invoke it by POSTing JSON-RPC `tasks/send` to its base URL
+ *
+ * The types here mirror the public A2A protocol shape at the subset
+ * needed for client-side integration.
+ */
+
+/** Capabilities advertised on the remote agent's agent card. */
+export interface A2ACardCapabilities {
+  /** True when the agent supports SSE streaming via `tasks/sendSubscribe`. */
+  streaming: boolean;
+  pushNotifications?: boolean;
+  stateTransitionHistory?: boolean;
+}
+
+/** A single skill exposed by a remote agent on its agent card. */
+export interface A2ASkill {
+  /** Stable skill identifier. */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Description of what the skill does. */
+  description: string;
+  /** Optional tags (e.g., "search", "analysis"). */
+  tags?: string[];
+  /** Optional example inputs. */
+  examples?: string[];
+}
+
+/** Shape served at `GET /.well-known/agent.json`. */
+export interface A2AAgentCard {
+  name: string;
+  description?: string;
+  /** Base URL clients should POST task requests to. */
+  url: string;
+  /** Card version — independent of the underlying model/agent version. */
+  version: string;
+  capabilities: A2ACardCapabilities;
+  defaultInputModes?: string[];
+  defaultOutputModes?: string[];
+  skills: A2ASkill[];
+  provider?: {
+    organization: string;
+    url?: string;
+  };
+}
+
+/** Spec describing one remote A2A-served agent the provider should connect to. */
+export interface A2ARemoteSpec {
+  /**
+   * Base URL of the remote A2A endpoint. The provider will fetch the
+   * card from `<url>/.well-known/agent.json` and POST task requests to
+   * `<url>/` (JSON-RPC root).
+   */
+  url: string;
+  /**
+   * Optional static headers to include on every request. Auth headers
+   * should be provided via the `getAuthHeaders` callback instead, so
+   * token refresh doesn't require rebuilding the provider.
+   */
+  headers?: Record<string, string>;
+  /**
+   * When true, expose the remote agent as a single coarse-grained
+   * Capability (one per remote, named after the agent). When false
+   * (default), expose one Capability per skill advertised on the card.
+   */
+  flattenAsSingleTool?: boolean;
+  /**
+   * Optional override of the agent card URL. Defaults to
+   * `<url>/.well-known/agent.json`.
+   */
+  cardPath?: string;
+  /**
+   * Optional override of the JSON-RPC endpoint path. Defaults to `/`.
+   */
+  rpcPath?: string;
+}
+
+/** Configuration for the A2A capability provider. */
+export interface A2AProviderConfig {
+  /**
+   * Map of remoteName → spec. Remote names are stable identifiers used
+   * as the capability name prefix and as keys for `getAuthHeaders`.
+   */
+  remotes: Record<string, A2ARemoteSpec>;
+  /**
+   * Optional callback to resolve auth headers for a given remote at
+   * connect-time. Returns a header map merged over `spec.headers`.
+   *
+   * The library never stores tokens — the host owns auth lifecycle and
+   * provides resolved values here.
+   */
+  getAuthHeaders?: (
+    remoteName: string
+  ) =>
+    | Promise<Record<string, string> | undefined>
+    | Record<string, string>
+    | undefined;
+  /**
+   * Identity announced to remotes on every request via `user-agent` /
+   * provider headers. Defaults to env vars (`A2A_CLIENT_NAME` /
+   * `A2A_CLIENT_VERSION`) or a library fallback.
+   */
+  clientInfo?: { name: string; version: string };
+  /** HTTP request timeout in ms. Defaults to 30_000. */
+  timeoutMs?: number;
+  /** Optional logger. Defaults to a console-based one. */
+  logger?: A2ALogger;
+}
+
+/** Minimal logger interface — matches pino-style signatures. */
+export interface A2ALogger {
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+// ---------------------------------------------------------------------------
+// JSON-RPC 2.0 shapes (subset used by the provider)
+// ---------------------------------------------------------------------------
+
+export interface JsonRpcRequest<P = unknown> {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  method: string;
+  params?: P;
+}
+
+export interface JsonRpcSuccess<R = unknown> {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result: R;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  error: { code: number; message: string; data?: unknown };
+}
+
+export type JsonRpcResponse<R = unknown> =
+  | JsonRpcSuccess<R>
+  | JsonRpcErrorResponse;
+
+// ---------------------------------------------------------------------------
+// A2A task message shapes
+// ---------------------------------------------------------------------------
+
+export interface A2AMessage {
+  role: 'user' | 'agent';
+  parts: Array<{ type: 'text'; text: string }>;
+}
+
+export interface A2ATaskParams {
+  /** Caller-assigned task id — echoed back by the server. */
+  id: string;
+  /** Optional session id for multi-turn continuity. */
+  sessionId?: string;
+  /** The message to deliver to the remote agent. */
+  message: A2AMessage;
+}
+
+export type A2ATaskState =
+  | 'submitted'
+  | 'working'
+  | 'input-required'
+  | 'completed'
+  | 'failed'
+  | 'canceled';
+
+export interface A2ATaskStatus {
+  state: A2ATaskState;
+  timestamp: string;
+}
+
+export interface A2ATask {
+  id: string;
+  sessionId?: string;
+  status: A2ATaskStatus;
+  /** Final agent response — populated when status is `completed`. */
+  artifacts?: Array<{ parts: Array<{ type: 'text'; text: string }> }>;
+  error?: { code: number; message: string };
+}

package/src/providers/capabilityNaming.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared capability-name encoding used by source-specific providers
+ * (MCP, A2A, and future providers that expose multi-level namespaces).
+ *
+ * A capability name encodes `<sourceName>__<itemName>` where:
+ *   - `sourceName` is the provider-level identifier (MCP server name,
+ *     A2A remote name, etc.)
+ *   - `itemName` is the per-source sub-unit (MCP tool name, A2A skill id)
+ *
+ * Centralizing the separator + parsing here keeps both providers in lockstep
+ * and prevents collisions when re-exported from the provider barrel.
+ */
+
+/** Separator between source and item in an encoded capability name. */
+export const CAPABILITY_NAME_SEPARATOR = '__';
+
+/** Compose a capability name. If `itemName` is omitted, returns just `sourceName`. */
+export function formatCapabilityName(
+  sourceName: string,
+  itemName?: string
+): string {
+  return itemName
+    ? `${sourceName}${CAPABILITY_NAME_SEPARATOR}${itemName}`
+    : sourceName;
+}
+
+/**
+ * Parse a capability name into its components. Returns `null` when `name`
+ * is empty. When the name has no separator, `itemName` is undefined
+ * (the caller can treat that as a whole-source invocation).
+ */
+export function parseCapabilityName(
+  name: string
+): { sourceName: string; itemName?: string } | null {
+  if (!name) return null;
+  const sepIdx = name.indexOf(CAPABILITY_NAME_SEPARATOR);
+  if (sepIdx < 0) return { sourceName: name };
+  return {
+    sourceName: name.slice(0, sepIdx),
+    itemName: name.slice(sepIdx + CAPABILITY_NAME_SEPARATOR.length),
+  };
+}

package/src/providers/index.ts

@@ -0,0 +1,68 @@
+/**
+ * Capability provider abstraction.
+ *
+ * See docs/architecture-capability-layer.md for the full design rationale.
+ */
+
+export * from './types';
+// Shared capability-name helpers — single source of truth so both MCP and
+// A2A consumers get the same encoding without re-export duplication.
+export * from './capabilityNaming';
+export * from './tools-server';
+// Hosts compose multiple providers by iterating a plain array and
+// concatenating tools — see docs/capability-providers.md. No wrapper
+// class is provided because the loop is trivial and keeps host code
+// transparent.
+// MCP + A2A barrels intentionally namespaced to avoid re-exporting
+// `CAPABILITY_NAME_SEPARATOR` / `formatCapabilityName` twice (each
+// provider module re-exports them internally; the canonical export
+// comes from `./capabilityNaming` above).
+export {
+  MCPCapabilityProvider,
+  flattenToolCallResponse,
+  createTransport,
+  mcpConsoleLogger,
+  getMCPEnvDefaults,
+} from './mcp';
+export type {
+  MCPLogger,
+  MCPProviderConfig,
+  MCPServerSpec,
+  MCPTransportKind,
+  StdioSpec,
+  SSESpec,
+  StreamableHTTPSpec,
+  WebSocketSpec,
+  MCPToolDescriptor,
+  MCPToolCallResult,
+  MCPStructuredTool,
+} from './mcp';
+export {
+  A2ACapabilityProvider,
+  A2AClient,
+  extractTaskText,
+  generateRpcId,
+  skillToCapability,
+  coerceInputToA2AMessage,
+  MESSAGE_INPUT_SCHEMA,
+  a2aConsoleLogger,
+  getA2AEnvDefaults,
+} from './a2a';
+export type {
+  A2AAgentCard,
+  A2ACardCapabilities,
+  A2AClientOptions,
+  A2ALogger,
+  A2AMessage,
+  A2AProviderConfig,
+  A2ARemoteSpec,
+  A2ASkill,
+  A2ATask,
+  A2ATaskParams,
+  A2ATaskState,
+  A2ATaskStatus,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  JsonRpcSuccess,
+  JsonRpcErrorResponse,
+} from './a2a';

package/src/providers/mcp/MCPCapabilityProvider.ts

@@ -0,0 +1,345 @@
+/**
+ * MCPCapabilityProvider — connects to MCP servers via the official MCP SDK
+ * and exposes their tools as `Capability` / `StructuredToolInterface`.
+ *
+ * Mirrors the pattern of `ToolsServerCapabilityProvider`: thin adapter,
+ * protocol-specific transport, stateless as far as tokens/OAuth are
+ * concerned (all auth is host-resolved and forwarded via `getAuthHeaders`).
+ *
+ * What the host supplies:
+ *   - `servers`: unified spec map (normalized from whatever source:
+ *     programmatic, YAML, DB, marketplace catalog).
+ *   - `getAuthHeaders?`: per-server header resolver. Called at connect
+ *     time. OAuth orchestration / token refresh happens in the host.
+ *
+ * What the library does:
+ *   - Picks the right SDK transport per spec.
+ *   - Connects, calls `listTools()`, wraps each tool as a `Capability`.
+ *   - `createRunnables()` returns `StructuredTool`s that invoke the
+ *     server's tools on demand, streaming the string result back to the
+ *     agent.
+ *   - Caches open connections per-instance so repeated `fetchManifest` /
+ *     `createRunnables` calls reuse them.
+ */
+
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+import {
+  CapabilityKind,
+  type Capability,
+  type CapabilityFilter,
+  type CapabilityProvider,
+  type CredentialMap,
+} from '@/providers/types';
+import {
+  CAPABILITY_NAME_SEPARATOR,
+  formatCapabilityName,
+  parseCapabilityName,
+} from '@/providers/capabilityNaming';
+import { createTransport } from './transport';
+import { consoleLogger, getMCPEnvDefaults } from './config';
+import type {
+  MCPLogger,
+  MCPProviderConfig,
+  MCPServerSpec,
+  MCPToolCallResult,
+  MCPToolDescriptor,
+} from './types';
+
+/**
+ * Per-server connection state kept inside the provider. Reused across
+ * manifest fetches and tool invocations.
+ */
+interface ServerConnection {
+  serverName: string;
+  spec: MCPServerSpec;
+  client: Client;
+  transport: Transport;
+  tools: MCPToolDescriptor[];
+}
+
+export class MCPCapabilityProvider implements CapabilityProvider {
+  readonly providerId: string;
+  private readonly config: Required<
+    Pick<
+      MCPProviderConfig,
+      'connectTimeoutMs' | 'requestTimeoutMs' | 'clientInfo'
+    >
+  > &
+    Pick<MCPProviderConfig, 'servers' | 'getAuthHeaders'>;
+  private readonly logger: MCPLogger;
+  private readonly connections = new Map<string, ServerConnection>();
+
+  constructor(config: MCPProviderConfig) {
+    if (!config.servers || Object.keys(config.servers).length === 0) {
+      throw new Error('MCPCapabilityProvider: at least one server is required');
+    }
+    const env = getMCPEnvDefaults();
+    this.config = {
+      servers: config.servers,
+      getAuthHeaders: config.getAuthHeaders,
+      clientInfo: config.clientInfo ?? {
+        name: env.clientName,
+        version: env.clientVersion,
+      },
+      connectTimeoutMs: config.connectTimeoutMs ?? env.connectTimeoutMs,
+      requestTimeoutMs: config.requestTimeoutMs ?? env.requestTimeoutMs,
+    };
+    this.logger = config.logger ?? consoleLogger;
+    const names = Object.keys(config.servers).sort().join(',');
+    this.providerId = `mcp:${names}`;
+  }
+
+  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {
+    // MCP only emits kind='mcp' — short-circuit if filter excludes us.
+    if (filter?.kind && filter.kind !== CapabilityKind.MCP) return [];
+
+    const capabilities: Capability[] = [];
+
+    for (const serverName of Object.keys(this.config.servers)) {
+      try {
+        const conn = await this.ensureConnection(serverName);
+        for (const toolDesc of conn.tools) {
+          const cap = this.toolToCapability(serverName, toolDesc);
+          if (this.capabilityMatchesFilter(cap, filter)) {
+            capabilities.push(cap);
+          }
+        }
+      } catch (err) {
+        // One server failing should not block the others — log and continue.
+        this.logger.warn(
+          `[mcp] failed to fetch manifest for server "${serverName}":`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+
+    this.logger.debug(
+      `[mcp] manifest assembled — ${capabilities.length} capabilities across ${this.connections.size}/${Object.keys(this.config.servers).length} connected servers`
+    );
+
+    return capabilities;
+  }
+
+  async createRunnables(
+    capabilities: Capability[],
+    _credentials: CredentialMap
+  ): Promise<StructuredToolInterface[]> {
+    const runnables: StructuredToolInterface[] = [];
+
+    for (const cap of capabilities) {
+      if (cap.kind !== CapabilityKind.MCP) continue;
+
+      const parsed = parseCapabilityName(cap.name);
+      const serverName = parsed?.sourceName;
+      const toolName = parsed?.itemName;
+      if (!serverName || !toolName) {
+        this.logger.warn(
+          `[mcp] skipping capability "${cap.name}" — unparseable`
+        );
+        continue;
+      }
+
+      const runnable = this.buildProxyTool(serverName, toolName, cap);
+      runnables.push(runnable);
+    }
+
+    return runnables;
+  }
+
+  /**
+   * Disconnect all open MCP client connections. Callers should invoke this
+   * on shutdown to release transports and child processes (for stdio).
+   */
+  async close(): Promise<void> {
+    for (const [serverName, conn] of this.connections.entries()) {
+      try {
+        await conn.client.close();
+      } catch (err) {
+        this.logger.warn(
+          `[mcp] error closing connection to "${serverName}":`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    }
+    this.connections.clear();
+  }
+
+  // --- internals ---------------------------------------------------------
+
+  private async ensureConnection(
+    serverName: string
+  ): Promise<ServerConnection> {
+    const existing = this.connections.get(serverName);
+    if (existing) return existing;
+
+    const spec = this.config.servers[serverName];
+    if (!spec) {
+      throw new Error(`[mcp] server "${serverName}" not in config`);
+    }
+
+    const authHeaders = await this.resolveAuthHeaders(serverName);
+    const transport = createTransport(spec, authHeaders);
+    const client = new Client(this.config.clientInfo, {
+      capabilities: {},
+    });
+
+    this.logger.debug(`[mcp] connecting to "${serverName}" (${spec.type})`);
+    await client.connect(transport);
+
+    const { tools } = await client.listTools();
+    this.logger.debug(
+      `[mcp] connected to "${serverName}" — ${tools.length} tools discovered`
+    );
+
+    const conn: ServerConnection = {
+      serverName,
+      spec,
+      client,
+      transport,
+      tools: tools as MCPToolDescriptor[],
+    };
+    this.connections.set(serverName, conn);
+    return conn;
+  }
+
+  private async resolveAuthHeaders(
+    serverName: string
+  ): Promise<Record<string, string> | undefined> {
+    if (!this.config.getAuthHeaders) return undefined;
+    try {
+      return await this.config.getAuthHeaders(serverName);
+    } catch (err) {
+      this.logger.warn(
+        `[mcp] getAuthHeaders("${serverName}") threw:`,
+        err instanceof Error ? err.message : err
+      );
+      return undefined;
+    }
+  }
+
+  private toolToCapability(
+    serverName: string,
+    toolDesc: MCPToolDescriptor
+  ): Capability {
+    return {
+      kind: CapabilityKind.MCP,
+      name: formatCapabilityName(serverName, toolDesc.name),
+      description:
+        toolDesc.description ?? `${toolDesc.name} (via ${serverName})`,
+      schema: toolDesc.inputSchema ?? {
+        type: 'object',
+        properties: {},
+      },
+      authConfig: [],
+      metadata: {
+        category: 'mcp',
+        tags: [serverName],
+      },
+    };
+  }
+
+  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(
+    serverName: string,
+    toolName: string,
+    cap: Capability
+  ): StructuredToolInterface {
+    // Arrow-function closures would capture `this` correctly but LangChain's
+    // `tool()` helper expects a plain async function; bind the methods we
+    // need up-front so the closure body stays clean and strict-lint-friendly.
+    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(
+          `[mcp] invoking ${serverName}:${toolName}`,
+          input && typeof input === 'object'
+            ? `inputKeys=${Object.keys(input as object).length}`
+            : ''
+        );
+
+        const conn = await ensureConnection(serverName);
+        const response = await conn.client.callTool({
+          name: toolName,
+          arguments: (input as Record<string, unknown>) ?? {},
+        });
+
+        const result = flattenToolCallResponse(response);
+        if (result.isError) {
+          throw new Error(
+            `MCP tool "${serverName}:${toolName}" failed: ${result.text}`
+          );
+        }
+        return result.text;
+      },
+      {
+        name: cap.name,
+        description: cap.description,
+        schema: (cap.schema as object) ?? { type: 'object', properties: {} },
+        responseFormat: 'content',
+      }
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers exported for testing
+// ---------------------------------------------------------------------------
+
+// CAPABILITY_NAME_SEPARATOR + formatCapabilityName live in the shared
+// `@/providers/capabilityNaming` module so MCP and A2A providers stay in
+// lockstep on name encoding. Re-exported here for callers that already
+// import from the MCP barrel.
+export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName };
+
+/**
+ * Flatten the MCP SDK's callTool response into a plain text + error flag.
+ * Concatenates any `text`-type content parts; non-text parts are
+ * JSON-stringified so the LLM sees something rather than silently
+ * dropping output.
+ */
+export function flattenToolCallResponse(response: unknown): MCPToolCallResult {
+  const resp = response as {
+    content?: Array<{ type?: string; text?: string; [k: string]: unknown }>;
+    isError?: boolean;
+  } | null;
+
+  const rawContent = resp?.content ?? [];
+  const isError = resp?.isError === true;
+
+  if (!Array.isArray(rawContent) || rawContent.length === 0) {
+    return {
+      text: isError ? '(error with no content)' : '(empty response)',
+      rawContent,
+      isError,
+    };
+  }
+
+  const parts = rawContent.map((item) => {
+    if (item.type === 'text' && typeof item.text === 'string') return item.text;
+    try {
+      return JSON.stringify(item);
+    } catch {
+      return '[unserializable content part]';
+    }
+  });
+
+  return { text: parts.join('\n\n'), rawContent, isError };
+}