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

package/src/providers/a2a/types.ts

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

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

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

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