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

package/dist/types/providers/a2a/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * 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;
+}
+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;
+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/dist/types/providers/capabilityNaming.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 declare const CAPABILITY_NAME_SEPARATOR = "__";
+/** Compose a capability name. If `itemName` is omitted, returns just `sourceName`. */
+export declare function formatCapabilityName(sourceName: string, itemName?: string): string;
+/**
+ * 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 declare function parseCapabilityName(name: string): {
+    sourceName: string;
+    itemName?: string;
+} | null;

package/dist/types/providers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Capability provider abstraction.
+ *
+ * See docs/architecture-capability-layer.md for the full design rationale.
+ */
+export * from './types';
+export * from './capabilityNaming';
+export * from './tools-server';
+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/dist/types/providers/mcp/MCPCapabilityProvider.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 { type StructuredToolInterface } from '@langchain/core/tools';
+import { type Capability, type CapabilityFilter, type CapabilityProvider, type CredentialMap } from '@/providers/types';
+import { CAPABILITY_NAME_SEPARATOR, formatCapabilityName } from '@/providers/capabilityNaming';
+import type { MCPProviderConfig, MCPToolCallResult } from './types';
+export declare class MCPCapabilityProvider implements CapabilityProvider {
+    readonly providerId: string;
+    private readonly config;
+    private readonly logger;
+    private readonly connections;
+    constructor(config: MCPProviderConfig);
+    fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;
+    createRunnables(capabilities: Capability[], _credentials: CredentialMap): Promise<StructuredToolInterface[]>;
+    /**
+     * Disconnect all open MCP client connections. Callers should invoke this
+     * on shutdown to release transports and child processes (for stdio).
+     */
+    close(): Promise<void>;
+    private ensureConnection;
+    private resolveAuthHeaders;
+    private toolToCapability;
+    private capabilityMatchesFilter;
+    private buildProxyTool;
+}
+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 declare function flattenToolCallResponse(response: unknown): MCPToolCallResult;

package/dist/types/providers/mcp/config.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Environment-driven configuration defaults for the MCP capability provider.
+ *
+ * Hosts can override any of these via the provider config object. Env vars
+ * exist so deployments can brand or tune the library without code changes.
+ */
+import type { MCPLogger } from './types';
+/**
+ * Read env values with fallbacks. Kept as a function (not a constant) so
+ * tests and hosts that mutate process.env after import get the current
+ * value on each call.
+ */
+export declare function getMCPEnvDefaults(): {
+    clientName: string;
+    clientVersion: string;
+    connectTimeoutMs: number;
+    requestTimeoutMs: number;
+};
+/** Console-routed default logger. */
+export declare const consoleLogger: MCPLogger;

package/dist/types/providers/mcp/index.d.ts

@@ -0,0 +1,5 @@
+export { MCPCapabilityProvider } from './MCPCapabilityProvider';
+export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName, flattenToolCallResponse, } from './MCPCapabilityProvider';
+export { createTransport } from './transport';
+export { consoleLogger as mcpConsoleLogger, getMCPEnvDefaults } from './config';
+export type { MCPLogger, MCPProviderConfig, MCPServerSpec, MCPTransportKind, StdioSpec, SSESpec, StreamableHTTPSpec, WebSocketSpec, MCPToolDescriptor, MCPToolCallResult, MCPStructuredTool, } from './types';

package/dist/types/providers/mcp/transport.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Transport factory — turns an `MCPServerSpec` into a configured
+ * MCP SDK transport. One switch statement per kind.
+ *
+ * Each transport is constructed with the merged header map (spec headers
+ * plus any `getAuthHeaders`-resolved additions) for HTTP-based kinds.
+ * Stdio uses `env` + `command` + `args` directly.
+ */
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { MCPServerSpec } from './types';
+/**
+ * Build a Transport from a spec + resolved auth headers.
+ *
+ * @param spec - the server spec (one of stdio / sse / streamable-http / websocket)
+ * @param authHeaders - headers merged over `spec.headers` at connect time
+ * @returns a configured Transport ready to be passed to `Client.connect()`
+ */
+export declare function createTransport(spec: MCPServerSpec, authHeaders?: Record<string, string>): Transport;

package/dist/types/providers/mcp/types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Types for the MCP capability provider.
+ *
+ * Design notes:
+ *   - `MCPServerSpec` is a unified, minimal shape describing an MCP server
+ *     the library can connect to. All config sources (programmatic,
+ *     YAML-derived, marketplace-derived) normalize to this before reaching
+ *     the provider.
+ *   - Auth headers are provided per-request via `getAuthHeaders` on the
+ *     provider config. The library never orchestrates OAuth — the host
+ *     resolves tokens however it sees fit and forwards the headers map.
+ */
+import type { StructuredToolInterface } from '@langchain/core/tools';
+/** Transport kinds supported by the MCP SDK. */
+export type MCPTransportKind = 'stdio' | 'sse' | 'streamable-http' | 'websocket';
+/** Stdio-transport spec — spawn a local subprocess. */
+export interface StdioSpec {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    /** Working directory for the spawned process. */
+    cwd?: string;
+}
+/** SSE-transport spec (legacy EventSource-based transport). */
+export interface SSESpec {
+    type: 'sse';
+    url: string;
+    /** Static headers (e.g., API key). Forwarded on each HTTP request. */
+    headers?: Record<string, string>;
+}
+/** Streamable HTTP spec (the modern MCP HTTP transport). */
+export interface StreamableHTTPSpec {
+    type: 'streamable-http';
+    url: string;
+    headers?: Record<string, string>;
+}
+/** WebSocket transport spec. */
+export interface WebSocketSpec {
+    type: 'websocket';
+    url: string;
+    headers?: Record<string, string>;
+}
+/** Discriminated union of all supported transports. */
+export type MCPServerSpec = StdioSpec | SSESpec | StreamableHTTPSpec | WebSocketSpec;
+/** Configuration for the MCP capability provider. */
+export interface MCPProviderConfig {
+    /**
+     * Map of serverName → spec. Server names are stable identifiers used
+     * downstream as the capability name prefix and as keys for
+     * `getAuthHeaders` lookups.
+     *
+     * The host is responsible for normalizing configs from multiple sources
+     * (local database, YAML, marketplace catalog) into this unified shape.
+     */
+    servers: Record<string, MCPServerSpec>;
+    /**
+     * Optional callback to resolve auth headers for a given server at
+     * connect-time. Returns a header map (e.g., `{ Authorization: "Bearer ..." }`)
+     * that is merged into the spec's base headers.
+     *
+     * The library never stores tokens or orchestrates OAuth — the host
+     * owns that layer and surfaces the resolved value here.
+     */
+    getAuthHeaders?: (serverName: string) => Promise<Record<string, string> | undefined> | Record<string, string> | undefined;
+    /**
+     * Client identity sent to MCP servers on handshake. Defaults to
+     * env vars (`MCP_CLIENT_NAME` / `MCP_CLIENT_VERSION`) or a library
+     * fallback if not set. Hosts typically override with their app identity.
+     */
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Connection timeout in ms. Defaults to 30_000. */
+    connectTimeoutMs?: number;
+    /** Tool-list / tool-call timeout in ms. Defaults to 30_000. */
+    requestTimeoutMs?: number;
+    /**
+     * Optional logger. When omitted, falls back to a console-based default.
+     * Implementations are expected to match the `MCPLogger` minimal shape.
+     */
+    logger?: MCPLogger;
+}
+/** Minimal logger interface — matches pino-style signatures. */
+export interface MCPLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Shape returned by the MCP SDK's `listTools()`. Keeping our own narrow
+ * alias so we don't leak the full SDK types through the provider's public
+ * surface.
+ */
+export interface MCPToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+}
+/** Result of a tool invocation, flattened from the SDK response. */
+export interface MCPToolCallResult {
+    /** Plain-text content joined from the MCP response's content array. */
+    text: string;
+    /** Raw content array from the SDK response, for advanced consumers. */
+    rawContent: unknown;
+    /** True when the MCP server flagged the result as an error. */
+    isError: boolean;
+}
+/** What the provider returns from createRunnables (re-exported for clarity). */
+export type MCPStructuredTool = StructuredToolInterface;

package/dist/types/providers/tools-server/ToolsServerCapabilityProvider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ToolsServerCapabilityProvider — capabilities sourced from a tools-server
+ * HTTP endpoint.
+ *
+ * Fetches the manifest via GET /manifest, builds proxy StructuredTools via
+ * POST /execute/:tool. Manifest is cached (TTL-configurable) so repeated
+ * init cycles don't refetch.
+ *
+ * See docs/architecture-capability-layer.md for the design rationale.
+ */
+import type { AxiosInstance } from 'axios';
+import type { StructuredToolInterface } from '@langchain/core/tools';
+import { type Capability, type CapabilityFilter, type CapabilityProvider, type CredentialMap } from '@/providers/types';
+/** Configuration for ToolsServerCapabilityProvider. */
+export interface ToolsServerConfig {
+    /** Tools-server base URL (e.g., https://tools.illuma.ai or http://localhost:3500). */
+    baseUrl: string;
+    /** API key sent as x-api-key header on all requests. Required. */
+    apiKey: string;
+    /** Optional override for manifest path. Defaults to `/manifest`. */
+    manifestPath?: string;
+    /** Optional override for execute path template. Defaults to `/execute/:name`. */
+    executePath?: string;
+    /** Request timeout in ms. Defaults to 30_000. */
+    timeoutMs?: number;
+    /** Manifest cache TTL in ms. 0 disables. Defaults to 60_000 (1 min). */
+    manifestTtlMs?: number;
+    /** Optional pre-built axios instance (for testing). */
+    client?: AxiosInstance;
+    /** Optional proxy override (defaults to process.env.PROXY). */
+    proxy?: string | null;
+}
+export declare class ToolsServerCapabilityProvider implements CapabilityProvider {
+    private readonly config;
+    readonly providerId: string;
+    private readonly client;
+    private readonly manifestPath;
+    private readonly executePath;
+    private readonly cache;
+    constructor(config: ToolsServerConfig);
+    fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;
+    createRunnables(capabilities: Capability[], credentials: CredentialMap): Promise<StructuredToolInterface[]>;
+    /** Force a manifest refresh on next fetchManifest call. */
+    invalidateCache(): void;
+}

package/dist/types/providers/tools-server/index.d.ts

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

package/dist/types/providers/types.d.ts

@@ -0,0 +1,170 @@
+/**
+ * CapabilityProvider types — the abstraction that lets agents consume tools,
+ * skills, and MCP-backed capabilities through a single interface regardless
+ * of where they come from.
+ *
+ * Design principles:
+ *   1. Source-agnostic — providers are distinguished by WHERE they come from
+ *      (tools-server, skill store, MCP server), not by the backend service
+ *      any individual tool calls.
+ *   2. Credential-agnostic — providers receive a flat credentialMap from the
+ *      host; they don't know about user settings, databases, OAuth flows.
+ *   3. Extension-ready — the shape reserves slots for upcoming patterns
+ *      (skills injectedMessages, ToolCall.auth/expires_at, skill sessions)
+ *      so when those land we don't refactor the core.
+ */
+import type { StructuredToolInterface } from '@langchain/core/tools';
+/**
+ * Kind of capability. Today only TOOL is implemented; SKILL and MCP are
+ * reserved — SkillCapabilityProvider + MCPCapabilityProvider will populate
+ * them in later phases. Keeping the enum from day one prevents a breaking
+ * change when those ship.
+ */
+export declare enum CapabilityKind {
+    TOOL = "tool",
+    SKILL = "skill",
+    MCP = "mcp",
+    /**
+     * Remote agent reachable over the A2A (Agent-to-Agent) protocol.
+     * The library's `A2ACapabilityProvider` is a client for this kind —
+     * invoking an A2A capability sends a JSON-RPC `tasks/send` to the
+     * remote agent's endpoint.
+     */
+    A2A = "a2a"
+}
+/**
+ * Where an auth credential comes from. Used by hosts to decide whether to
+ * forward the credential per-request or let the capability provider resolve
+ * it from its own environment.
+ */
+export declare enum AuthSource {
+    /** Resolved by the capability provider itself from its environment. Host never sends. */
+    SERVER = "server",
+    /** User-configured value stored in the host's credential store. Host forwards per-request. */
+    USER = "user",
+    /** Active OAuth/session token. Host forwards per-request from active session. */
+    FORWARDED = "forwarded"
+}
+/**
+ * One entry in a capability's auth config. Describes a single credential
+ * the capability needs. The `source` field tells the host how to resolve
+ * the value; the `prod`/`admin`/`hide` flags control UI visibility.
+ */
+export interface AuthConfigEntry {
+    /** Environment-variable-style name (e.g., "OPENAI_API_KEY"). Stable identifier. */
+    authField: string;
+    /** Human-readable label for UI. */
+    label?: string;
+    /** Optional description of how to obtain the credential. */
+    description?: string;
+    /** Where the value comes from. Defaults to USER if unspecified. */
+    source?: AuthSource;
+    /** True if the credential is required for the capability to function. */
+    required?: boolean;
+    /** Platform-managed in production — never prompt user. */
+    prod?: boolean;
+    /** Only admins can configure. */
+    admin?: boolean;
+    /** Never show in any UI (used when source === SERVER). */
+    hide?: boolean;
+}
+/**
+ * Arbitrary metadata attached to a capability. Extension point.
+ *
+ * Fields prefixed with "Reserved for" are not populated today but exist in
+ * the type so upstream patterns (skills, auth expiration, sessions) can
+ * drop in without a schema migration.
+ */
+export interface CapabilityMetadata {
+    /** Icon URL or path relative to the provider's static asset root. */
+    icon?: string;
+    /** Category for UI grouping (e.g., "search", "image", "finance"). */
+    category?: string;
+    /** Free-form tags for filtering / search. */
+    tags?: string[];
+    /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */
+    auth?: string;
+    /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */
+    expires_at?: number;
+    /** Reserved for upstream skills — capability returns injected messages on execute. */
+    injectedMessages?: boolean;
+    /** Reserved for upstream skills — capability consumes ToolSessionMap state. */
+    sessionAware?: boolean;
+}
+/**
+ * A single capability — a tool, skill, or MCP-backed operation that an agent
+ * can invoke. The shape mirrors common plugin-manifest conventions so the
+ * same entry can round-trip between an upstream catalog and a host registry.
+ */
+export interface Capability {
+    /** What kind of capability this is. Controls how it's invoked downstream. */
+    kind: CapabilityKind;
+    /**
+     * Stable unique identifier. For tools this is the pluginKey
+     * (e.g., "dalle", "wikipedia"). For skills this is the skill's `name`.
+     * Used everywhere the capability is referenced.
+     */
+    name: string;
+    /** Human-readable description for the LLM and UI. */
+    description: string;
+    /**
+     * Input schema as JSON Schema. For tools this comes from the Zod schema
+     * passed through `zodToJsonSchema`. Optional for capabilities with no
+     * input (e.g., parameter-less skills).
+     */
+    schema?: unknown;
+    /** Credential requirements. */
+    authConfig: AuthConfigEntry[];
+    /** Extension metadata. See CapabilityMetadata. */
+    metadata: CapabilityMetadata;
+}
+/** Filter for fetchManifest. All fields optional; missing = no filter. */
+export interface CapabilityFilter {
+    kind?: CapabilityKind;
+    tags?: string[];
+    /** Restrict to capabilities whose `name` is in this list. */
+    names?: string[];
+}
+/**
+ * A flat credential map: authField → value.
+ *
+ * The host is responsible for resolving values (from env vars, user
+ * settings, OAuth sessions, etc.) before passing to the provider. The
+ * provider does not inspect the origin — it just forwards to the tool.
+ */
+export type CredentialMap = Record<string, string>;
+/**
+ * The core interface. All concrete providers implement this.
+ *
+ * Providers are identified by `providerId` for logging/debug. They fetch
+ * their own manifest and build LangChain-compatible runnables from it.
+ *
+ * Lifetime: a provider may be instantiated once at startup (e.g., tools-
+ * server pointing at a stable URL) or per-user (e.g., MCP with per-user
+ * OAuth). The interface is agnostic.
+ */
+export interface CapabilityProvider {
+    /** Stable identifier for this provider instance (e.g., "tools-server:https://..."). */
+    readonly providerId: string;
+    /**
+     * Return the list of capabilities this provider exposes.
+     *
+     * Implementations may cache the manifest — the contract is that the
+     * returned list reflects the provider's current view of available
+     * capabilities.
+     *
+     * @param filter optional filter to scope the result
+     */
+    fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;
+    /**
+     * Build LangChain StructuredTools from a set of capabilities using the
+     * caller-supplied credentials.
+     *
+     * Called at agent init. The returned tools are bound to the LLM and
+     * invoked during the graph's tool-calling loop.
+     *
+     * @param capabilities the subset of capabilities the agent wants to use
+     * @param credentials credential values keyed by authField
+     */
+    createRunnables(capabilities: Capability[], credentials: CredentialMap): Promise<StructuredToolInterface[]>;
+}