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

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/composite/CompositeCapabilityProvider.ts

@@ -0,0 +1,112 @@
+/**
+ * CompositeCapabilityProvider — fans out to multiple CapabilityProviders
+ * and merges their manifests + runnables into one.
+ *
+ * Use case: an agent that consumes tools from tools-server AND MCP servers
+ * AND (future) skills. The composite exposes a single CapabilityProvider
+ * interface to the agent runtime so it doesn't know or care how many
+ * backing sources exist.
+ *
+ * Precedence: later providers do NOT override earlier ones on name
+ * collision — collisions are logged and the first-registered capability
+ * wins. Callers should ensure providers expose disjoint name spaces.
+ */
+
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import type {
+  Capability,
+  CapabilityFilter,
+  CapabilityProvider,
+  CredentialMap,
+} from '@/providers/types';
+
+export class CompositeCapabilityProvider implements CapabilityProvider {
+  readonly providerId: string;
+  private readonly providers: CapabilityProvider[];
+
+  constructor(providers: CapabilityProvider[]) {
+    if (!providers.length) {
+      throw new Error(
+        'CompositeCapabilityProvider: at least one provider is required'
+      );
+    }
+    this.providers = providers;
+    this.providerId = `composite:${providers.map((p) => p.providerId).join(',')}`;
+  }
+
+  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {
+    // Fetch all providers in parallel. One provider failing should not
+    // prevent others from contributing — log and continue.
+    const results = await Promise.allSettled(
+      this.providers.map((p) => p.fetchManifest(filter))
+    );
+
+    const merged: Capability[] = [];
+    const seen = new Set<string>();
+
+    for (let i = 0; i < results.length; i++) {
+      const result = results[i];
+      const provider = this.providers[i];
+
+      if (result.status === 'rejected') {
+        // DEBUG
+        // eslint-disable-next-line no-console
+        console.debug(
+          `[composite] provider ${provider.providerId} fetchManifest failed — ${String(result.reason)}`
+        );
+        continue;
+      }
+
+      for (const cap of result.value) {
+        if (seen.has(cap.name)) {
+          // DEBUG
+          // eslint-disable-next-line no-console
+          console.debug(
+            `[composite] name collision on "${cap.name}" from ${provider.providerId} — keeping first`
+          );
+          continue;
+        }
+        seen.add(cap.name);
+        merged.push(cap);
+      }
+    }
+
+    // DEBUG
+    // eslint-disable-next-line no-console
+    console.debug(
+      `[composite] merged manifest: ${merged.length} caps from ${this.providers.length} providers`
+    );
+
+    return merged;
+  }
+
+  async createRunnables(
+    capabilities: Capability[],
+    credentials: CredentialMap
+  ): Promise<StructuredToolInterface[]> {
+    // Determine which capabilities belong to which provider by refetching
+    // each provider's manifest and intersecting with the requested set.
+    // This keeps providers stateless — we don't require Capability to
+    // carry a back-reference to its provider.
+    const capabilityNames = new Set(capabilities.map((c) => c.name));
+    const perProviderCaps = await Promise.all(
+      this.providers.map(async (p) => {
+        const manifest = await p.fetchManifest();
+        return manifest.filter((c) => capabilityNames.has(c.name));
+      })
+    );
+
+    const allRunnables: StructuredToolInterface[] = [];
+    for (let i = 0; i < this.providers.length; i++) {
+      const providerCaps = perProviderCaps[i];
+      if (!providerCaps.length) continue;
+      const runnables = await this.providers[i].createRunnables(
+        providerCaps,
+        credentials
+      );
+      allRunnables.push(...runnables);
+    }
+
+    return allRunnables;
+  }
+}

package/src/providers/composite/index.ts

@@ -0,0 +1 @@
+export * from './CompositeCapabilityProvider';

package/src/providers/index.ts

@@ -0,0 +1,65 @@
+/**
+ * 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';
+export * from './composite';
+// 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';