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

package/dist/esm/utils/credentials.mjs

@@ -0,0 +1,135 @@
+import { AuthSource } from '../providers/types.mjs';
+
+/**
+ * Credential merging utility for capability providers.
+ *
+ * The host is the source of truth for credential values. It resolves them
+ * from env vars, user settings, or active OAuth sessions, then passes a
+ * flat CredentialMap to the provider.
+ *
+ * This utility helps hosts build that map from multiple sources with clear
+ * precedence rules. Providers themselves do NOT use this — they just receive
+ * the finished map.
+ */
+/**
+ * Source of a credential value in the merged result. Useful for logging
+ * and debugging which layer won a given authField.
+ */
+var CredentialOrigin;
+(function (CredentialOrigin) {
+    /** From the caller's process env (typically the CLI). */
+    CredentialOrigin["ENV"] = "env";
+    /** From the agent definition's tool_credentials block. */
+    CredentialOrigin["AGENT"] = "agent";
+    /** From the user's stored credentials in the host's credential store. */
+    CredentialOrigin["USER"] = "user";
+    /** From an active OAuth session forwarded by the host. */
+    CredentialOrigin["SESSION"] = "session";
+    /** Injected by the host at runtime for another reason. */
+    CredentialOrigin["RUNTIME"] = "runtime";
+})(CredentialOrigin || (CredentialOrigin = {}));
+/**
+ * Merge credential layers with earlier layers overriding later ones.
+ *
+ * Typical host flow (in order of precedence):
+ *   1. runtime overrides (e.g., test injection)       → RUNTIME
+ *   2. active OAuth session tokens                    → SESSION
+ *   3. agent-defined tool_credentials                 → AGENT
+ *   4. user's stored credentials                      → USER
+ *   5. process env                                    → ENV
+ *
+ * Caller passes layers in precedence order (highest first).
+ */
+function mergeCredentials(...layers) {
+    const merged = {};
+    // Iterate reverse so first-declared layer wins on collision.
+    for (let i = layers.length - 1; i >= 0; i--) {
+        const layer = layers[i];
+        for (const [key, value] of Object.entries(layer.values)) {
+            if (value !== undefined && value !== null && value !== '') {
+                merged[key] = value;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Given a set of capabilities, return the union of authField names they
+ * require. Useful for hosts that want to pre-resolve credentials before
+ * calling createRunnables.
+ */
+function collectRequiredAuthFields(capabilities) {
+    const fields = new Set();
+    for (const cap of capabilities) {
+        for (const entry of cap.authConfig) {
+            fields.add(entry.authField);
+        }
+    }
+    return Array.from(fields);
+}
+/**
+ * Filter out credentials that the provider is expected to resolve itself
+ * (source === SERVER). Hosts call this before forwarding — these values
+ * live in the provider's own environment and shouldn't be sent.
+ *
+ * Precedence: entries without `source` default to USER (must be forwarded).
+ */
+function filterForwardableCredentials(credentials, capabilities) {
+    const serverManagedFields = new Set();
+    for (const cap of capabilities) {
+        for (const entry of cap.authConfig) {
+            if (entry.source === AuthSource.SERVER) {
+                serverManagedFields.add(entry.authField);
+            }
+        }
+    }
+    const forwardable = {};
+    for (const [key, value] of Object.entries(credentials)) {
+        if (!serverManagedFields.has(key)) {
+            forwardable[key] = value;
+        }
+    }
+    return forwardable;
+}
+/**
+ * Validate that all required credentials for a capability are present in
+ * the provided map. Returns the list of missing authFields (empty array
+ * if all satisfied). Credentials with `source === SERVER` are excluded
+ * from the check since the provider resolves them.
+ */
+function findMissingCredentials(capability, credentials) {
+    const missing = [];
+    for (const entry of capability.authConfig) {
+        if (entry.source === AuthSource.SERVER)
+            continue;
+        if (!entry.required)
+            continue;
+        if (!credentials[entry.authField]) {
+            missing.push(entry.authField);
+        }
+    }
+    return missing;
+}
+/**
+ * Build a CredentialLayer from process env given a list of authField names.
+ * Values that aren't set in env are omitted (not set to empty string).
+ */
+function credentialsFromEnv(authFields, env = process.env) {
+    const values = {};
+    for (const field of authFields) {
+        const value = env[field];
+        if (value)
+            values[field] = value;
+    }
+    return { origin: CredentialOrigin.ENV, values };
+}
+/**
+ * Type guard: check whether an auth config entry should be forwarded by
+ * the host (vs resolved by the provider itself).
+ */
+function isForwardable(entry) {
+    return entry.source !== AuthSource.SERVER;
+}
+
+export { CredentialOrigin, collectRequiredAuthFields, credentialsFromEnv, filterForwardableCredentials, findMissingCredentials, isForwardable, mergeCredentials };
+//# sourceMappingURL=credentials.mjs.map

package/dist/esm/utils/credentials.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.mjs","sources":["../../../src/utils/credentials.ts"],"sourcesContent":["/**\n * Credential merging utility for capability providers.\n *\n * The host is the source of truth for credential values. It resolves them\n * from env vars, user settings, or active OAuth sessions, then passes a\n * flat CredentialMap to the provider.\n *\n * This utility helps hosts build that map from multiple sources with clear\n * precedence rules. Providers themselves do NOT use this — they just receive\n * the finished map.\n */\n\nimport type {\n  AuthConfigEntry,\n  Capability,\n  CredentialMap,\n} from '@/providers/types';\nimport { AuthSource } from '@/providers/types';\n\n/**\n * Source of a credential value in the merged result. Useful for logging\n * and debugging which layer won a given authField.\n */\nexport enum CredentialOrigin {\n  /** From the caller's process env (typically the CLI). */\n  ENV = 'env',\n  /** From the agent definition's tool_credentials block. */\n  AGENT = 'agent',\n  /** From the user's stored credentials in the host's credential store. */\n  USER = 'user',\n  /** From an active OAuth session forwarded by the host. */\n  SESSION = 'session',\n  /** Injected by the host at runtime for another reason. */\n  RUNTIME = 'runtime',\n}\n\n/** One layer of credentials with its origin. */\nexport interface CredentialLayer {\n  origin: CredentialOrigin;\n  values: CredentialMap;\n}\n\n/**\n * Merge credential layers with earlier layers overriding later ones.\n *\n * Typical host flow (in order of precedence):\n *   1. runtime overrides (e.g., test injection)       → RUNTIME\n *   2. active OAuth session tokens                    → SESSION\n *   3. agent-defined tool_credentials                 → AGENT\n *   4. user's stored credentials                      → USER\n *   5. process env                                    → ENV\n *\n * Caller passes layers in precedence order (highest first).\n */\nexport function mergeCredentials(...layers: CredentialLayer[]): CredentialMap {\n  const merged: CredentialMap = {};\n  // Iterate reverse so first-declared layer wins on collision.\n  for (let i = layers.length - 1; i >= 0; i--) {\n    const layer = layers[i];\n    for (const [key, value] of Object.entries(layer.values)) {\n      if (value !== undefined && value !== null && value !== '') {\n        merged[key] = value;\n      }\n    }\n  }\n  return merged;\n}\n\n/**\n * Given a set of capabilities, return the union of authField names they\n * require. Useful for hosts that want to pre-resolve credentials before\n * calling createRunnables.\n */\nexport function collectRequiredAuthFields(\n  capabilities: Capability[]\n): string[] {\n  const fields = new Set<string>();\n  for (const cap of capabilities) {\n    for (const entry of cap.authConfig) {\n      fields.add(entry.authField);\n    }\n  }\n  return Array.from(fields);\n}\n\n/**\n * Filter out credentials that the provider is expected to resolve itself\n * (source === SERVER). Hosts call this before forwarding — these values\n * live in the provider's own environment and shouldn't be sent.\n *\n * Precedence: entries without `source` default to USER (must be forwarded).\n */\nexport function filterForwardableCredentials(\n  credentials: CredentialMap,\n  capabilities: Capability[]\n): CredentialMap {\n  const serverManagedFields = new Set<string>();\n  for (const cap of capabilities) {\n    for (const entry of cap.authConfig) {\n      if (entry.source === AuthSource.SERVER) {\n        serverManagedFields.add(entry.authField);\n      }\n    }\n  }\n  const forwardable: CredentialMap = {};\n  for (const [key, value] of Object.entries(credentials)) {\n    if (!serverManagedFields.has(key)) {\n      forwardable[key] = value;\n    }\n  }\n  return forwardable;\n}\n\n/**\n * Validate that all required credentials for a capability are present in\n * the provided map. Returns the list of missing authFields (empty array\n * if all satisfied). Credentials with `source === SERVER` are excluded\n * from the check since the provider resolves them.\n */\nexport function findMissingCredentials(\n  capability: Capability,\n  credentials: CredentialMap\n): string[] {\n  const missing: string[] = [];\n  for (const entry of capability.authConfig) {\n    if (entry.source === AuthSource.SERVER) continue;\n    if (!entry.required) continue;\n    if (!credentials[entry.authField]) {\n      missing.push(entry.authField);\n    }\n  }\n  return missing;\n}\n\n/**\n * Build a CredentialLayer from process env given a list of authField names.\n * Values that aren't set in env are omitted (not set to empty string).\n */\nexport function credentialsFromEnv(\n  authFields: readonly string[],\n  env: NodeJS.ProcessEnv = process.env\n): CredentialLayer {\n  const values: CredentialMap = {};\n  for (const field of authFields) {\n    const value = env[field];\n    if (value) values[field] = value;\n  }\n  return { origin: CredentialOrigin.ENV, values };\n}\n\n/**\n * Type guard: check whether an auth config entry should be forwarded by\n * the host (vs resolved by the provider itself).\n */\nexport function isForwardable(entry: AuthConfigEntry): boolean {\n  return entry.source !== AuthSource.SERVER;\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/utils/httpClient.mjs

@@ -0,0 +1,70 @@
+import axios from 'axios';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+/**
+ * HTTP client utility for capability providers.
+ *
+ * Wraps axios with proxy support, default headers, and consistent retry
+ * behavior so every provider doesn't reinvent the wheel. Used by
+ * ToolsServerCapabilityProvider and (future) any HTTP-backed provider.
+ *
+ * Proxy resolution follows the existing pattern in this codebase:
+ * the PROXY env var is read and an HttpsProxyAgent is attached if present.
+ */
+/**
+ * Build an axios instance configured per HttpClientConfig.
+ *
+ * The returned instance should be retained (not recreated per request) so
+ * keepalive connections can be reused.
+ */
+function createHttpClient(config) {
+    const { baseURL, apiKey, headers = {}, timeoutMs = 30_000, proxy } = config;
+    const resolvedProxy = proxy === undefined ? process.env.PROXY : proxy;
+    const defaultHeaders = {
+        'content-type': 'application/json',
+        ...headers,
+    };
+    if (apiKey) {
+        defaultHeaders['x-api-key'] = apiKey;
+    }
+    const axiosConfig = {
+        baseURL,
+        timeout: timeoutMs,
+        headers: defaultHeaders,
+        // Don't throw on non-2xx — callers handle status codes explicitly.
+        validateStatus: () => true,
+    };
+    if (resolvedProxy) {
+        // axios respects `httpsAgent` for outbound proxying
+        axiosConfig.httpsAgent = new HttpsProxyAgent(resolvedProxy);
+        axiosConfig.httpAgent = new HttpsProxyAgent(resolvedProxy);
+        // Disable axios's built-in proxy logic in favor of the agent.
+        axiosConfig.proxy = false;
+    }
+    return axios.create(axiosConfig);
+}
+/**
+ * Thin wrapper around an axios response that throws with a structured error
+ * on non-2xx status codes. Providers use this to get uniform error surface.
+ */
+class HttpError extends Error {
+    status;
+    body;
+    url;
+    constructor(status, url, body) {
+        super(`HTTP ${status} on ${url}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.url = url;
+        this.body = body;
+    }
+}
+/** Assert that an axios response is a 2xx; throw HttpError otherwise. */
+function assertOk(status, url, body) {
+    if (status < 200 || status >= 300) {
+        throw new HttpError(status, url, body);
+    }
+}
+
+export { HttpError, assertOk, createHttpClient };
+//# sourceMappingURL=httpClient.mjs.map

package/dist/esm/utils/httpClient.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpClient.mjs","sources":["../../../src/utils/httpClient.ts"],"sourcesContent":["/**\n * HTTP client utility for capability providers.\n *\n * Wraps axios with proxy support, default headers, and consistent retry\n * behavior so every provider doesn't reinvent the wheel. Used by\n * ToolsServerCapabilityProvider and (future) any HTTP-backed provider.\n *\n * Proxy resolution follows the existing pattern in this codebase:\n * the PROXY env var is read and an HttpsProxyAgent is attached if present.\n */\n\nimport axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\n\n/** Configuration for creating an HTTP client. */\nexport interface HttpClientConfig {\n  /** Base URL prepended to all requests. */\n  baseURL: string;\n  /** Optional API key — if present, sent as `x-api-key` header. */\n  apiKey?: string;\n  /** Custom header map merged into every request. */\n  headers?: Record<string, string>;\n  /** Request timeout in milliseconds. Defaults to 30_000. */\n  timeoutMs?: number;\n  /**\n   * Override for the PROXY env var. Useful for tests. If undefined,\n   * falls back to process.env.PROXY.\n   */\n  proxy?: string | null;\n}\n\n/**\n * Build an axios instance configured per HttpClientConfig.\n *\n * The returned instance should be retained (not recreated per request) so\n * keepalive connections can be reused.\n */\nexport function createHttpClient(config: HttpClientConfig): AxiosInstance {\n  const { baseURL, apiKey, headers = {}, timeoutMs = 30_000, proxy } = config;\n\n  const resolvedProxy = proxy === undefined ? process.env.PROXY : proxy;\n\n  const defaultHeaders: Record<string, string> = {\n    'content-type': 'application/json',\n    ...headers,\n  };\n  if (apiKey) {\n    defaultHeaders['x-api-key'] = apiKey;\n  }\n\n  const axiosConfig: AxiosRequestConfig = {\n    baseURL,\n    timeout: timeoutMs,\n    headers: defaultHeaders,\n    // Don't throw on non-2xx — callers handle status codes explicitly.\n    validateStatus: () => true,\n  };\n\n  if (resolvedProxy) {\n    // axios respects `httpsAgent` for outbound proxying\n    axiosConfig.httpsAgent = new HttpsProxyAgent(resolvedProxy);\n    axiosConfig.httpAgent = new HttpsProxyAgent(resolvedProxy);\n    // Disable axios's built-in proxy logic in favor of the agent.\n    axiosConfig.proxy = false;\n  }\n\n  return axios.create(axiosConfig);\n}\n\n/**\n * Thin wrapper around an axios response that throws with a structured error\n * on non-2xx status codes. Providers use this to get uniform error surface.\n */\nexport class HttpError extends Error {\n  readonly status: number;\n  readonly body: unknown;\n  readonly url: string;\n  constructor(status: number, url: string, body: unknown) {\n    super(`HTTP ${status} on ${url}`);\n    this.name = 'HttpError';\n    this.status = status;\n    this.url = url;\n    this.body = body;\n  }\n}\n\n/** Assert that an axios response is a 2xx; throw HttpError otherwise. */\nexport function assertOk(status: number, url: string, body: unknown): void {\n  if (status < 200 || status >= 300) {\n    throw new HttpError(status, url, body);\n  }\n}\n"],"names":[],"mappings":";;;AAAA;;;;;;;;;AASG;AAsBH;;;;;AAKG;AACG,SAAU,gBAAgB,CAAC,MAAwB,EAAA;AACvD,IAAA,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,SAAS,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM;AAE3E,IAAA,MAAM,aAAa,GAAG,KAAK,KAAK,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,KAAK;AAErE,IAAA,MAAM,cAAc,GAA2B;AAC7C,QAAA,cAAc,EAAE,kBAAkB;AAClC,QAAA,GAAG,OAAO;KACX;IACD,IAAI,MAAM,EAAE;AACV,QAAA,cAAc,CAAC,WAAW,CAAC,GAAG,MAAM;IACtC;AAEA,IAAA,MAAM,WAAW,GAAuB;QACtC,OAAO;AACP,QAAA,OAAO,EAAE,SAAS;AAClB,QAAA,OAAO,EAAE,cAAc;;AAEvB,QAAA,cAAc,EAAE,MAAM,IAAI;KAC3B;IAED,IAAI,aAAa,EAAE;;QAEjB,WAAW,CAAC,UAAU,GAAG,IAAI,eAAe,CAAC,aAAa,CAAC;QAC3D,WAAW,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,aAAa,CAAC;;AAE1D,QAAA,WAAW,CAAC,KAAK,GAAG,KAAK;IAC3B;AAEA,IAAA,OAAO,KAAK,CAAC,MAAM,CAAC,WAAW,CAAC;AAClC;AAEA;;;AAGG;AACG,MAAO,SAAU,SAAQ,KAAK,CAAA;AACzB,IAAA,MAAM;AACN,IAAA,IAAI;AACJ,IAAA,GAAG;AACZ,IAAA,WAAA,CAAY,MAAc,EAAE,GAAW,EAAE,IAAa,EAAA;AACpD,QAAA,KAAK,CAAC,CAAA,KAAA,EAAQ,MAAM,OAAO,GAAG,CAAA,CAAE,CAAC;AACjC,QAAA,IAAI,CAAC,IAAI,GAAG,WAAW;AACvB,QAAA,IAAI,CAAC,MAAM,GAAG,MAAM;AACpB,QAAA,IAAI,CAAC,GAAG,GAAG,GAAG;AACd,QAAA,IAAI,CAAC,IAAI,GAAG,IAAI;IAClB;AACD;AAED;SACgB,QAAQ,CAAC,MAAc,EAAE,GAAW,EAAE,IAAa,EAAA;IACjE,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,IAAI,GAAG,EAAE;QACjC,MAAM,IAAI,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;IACxC;AACF;;;;"}

package/dist/esm/utils/toolManifest.mjs

@@ -0,0 +1,96 @@
+/**
+ * Tool manifest cache.
+ *
+ * Providers fetch a manifest at init and potentially on refresh. This
+ * utility provides a minimal TTL cache so repeated fetchManifest() calls
+ * don't hammer the backing server.
+ *
+ * Caching is opt-in — providers that want fresh data every time (e.g.,
+ * MCP with dynamic tool lists) can skip this entirely.
+ */
+/**
+ * Simple in-memory TTL cache for manifests, keyed by a caller-supplied
+ * cache key (e.g., the filter hash or a fixed constant for unfiltered).
+ *
+ * Thread-safety: the cache uses a plain Map. Node's single-threaded event
+ * loop makes this safe for typical use. Not safe across workers — each
+ * worker keeps its own cache (fine, since manifests are small).
+ */
+class ManifestCache {
+    ttlMs;
+    store = new Map();
+    constructor(config = {}) {
+        this.ttlMs = config.ttlMs ?? 60_000;
+    }
+    /** Retrieve cached capabilities, or undefined on miss / expiry. */
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt < Date.now()) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.capabilities;
+    }
+    /** Insert or replace cached capabilities for the given key. */
+    set(key, capabilities) {
+        if (this.ttlMs <= 0)
+            return;
+        this.store.set(key, {
+            expiresAt: Date.now() + this.ttlMs,
+            capabilities,
+        });
+    }
+    /** Remove all cached entries. */
+    clear() {
+        this.store.clear();
+    }
+    /** For tests / diagnostics. */
+    get size() {
+        return this.store.size;
+    }
+}
+/**
+ * Build a deterministic cache key from a CapabilityFilter.
+ *
+ * Two identical filters always produce the same key. Providers use this
+ * so `fetchManifest(filter)` and `fetchManifest(sameFilter)` hit the
+ * same cache entry.
+ */
+function filterToCacheKey(filter) {
+    if (!filter)
+        return '__all__';
+    const parts = [];
+    if (filter.kind)
+        parts.push(`kind=${filter.kind}`);
+    if (filter.tags?.length)
+        parts.push(`tags=${[...filter.tags].sort().join(',')}`);
+    if (filter.names?.length)
+        parts.push(`names=${[...filter.names].sort().join(',')}`);
+    return parts.length ? parts.join('|') : '__all__';
+}
+/**
+ * Apply a CapabilityFilter to a pre-fetched manifest. Used by providers
+ * that fetch the full manifest once and filter in memory.
+ */
+function applyFilter(capabilities, filter) {
+    if (!filter)
+        return capabilities;
+    return capabilities.filter((cap) => {
+        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 ?? []);
+            const anyMatch = filter.tags.some((t) => capTags.has(t));
+            if (!anyMatch)
+                return false;
+        }
+        return true;
+    });
+}
+
+export { ManifestCache, applyFilter, filterToCacheKey };
+//# sourceMappingURL=toolManifest.mjs.map

package/dist/esm/utils/toolManifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolManifest.mjs","sources":["../../../src/utils/toolManifest.ts"],"sourcesContent":["/**\n * Tool manifest cache.\n *\n * Providers fetch a manifest at init and potentially on refresh. This\n * utility provides a minimal TTL cache so repeated fetchManifest() calls\n * don't hammer the backing server.\n *\n * Caching is opt-in — providers that want fresh data every time (e.g.,\n * MCP with dynamic tool lists) can skip this entirely.\n */\n\nimport type { Capability, CapabilityFilter } from '@/providers/types';\n\n/** Entry in the manifest cache. */\ninterface CacheEntry {\n  expiresAt: number;\n  capabilities: Capability[];\n}\n\nexport interface ManifestCacheConfig {\n  /** Time-to-live in milliseconds. 0 disables caching. Defaults to 60_000 (1 min). */\n  ttlMs?: number;\n}\n\n/**\n * Simple in-memory TTL cache for manifests, keyed by a caller-supplied\n * cache key (e.g., the filter hash or a fixed constant for unfiltered).\n *\n * Thread-safety: the cache uses a plain Map. Node's single-threaded event\n * loop makes this safe for typical use. Not safe across workers — each\n * worker keeps its own cache (fine, since manifests are small).\n */\nexport class ManifestCache {\n  private readonly ttlMs: number;\n  private readonly store = new Map<string, CacheEntry>();\n\n  constructor(config: ManifestCacheConfig = {}) {\n    this.ttlMs = config.ttlMs ?? 60_000;\n  }\n\n  /** Retrieve cached capabilities, or undefined on miss / expiry. */\n  get(key: string): Capability[] | undefined {\n    const entry = this.store.get(key);\n    if (!entry) return undefined;\n    if (entry.expiresAt < Date.now()) {\n      this.store.delete(key);\n      return undefined;\n    }\n    return entry.capabilities;\n  }\n\n  /** Insert or replace cached capabilities for the given key. */\n  set(key: string, capabilities: Capability[]): void {\n    if (this.ttlMs <= 0) return;\n    this.store.set(key, {\n      expiresAt: Date.now() + this.ttlMs,\n      capabilities,\n    });\n  }\n\n  /** Remove all cached entries. */\n  clear(): void {\n    this.store.clear();\n  }\n\n  /** For tests / diagnostics. */\n  get size(): number {\n    return this.store.size;\n  }\n}\n\n/**\n * Build a deterministic cache key from a CapabilityFilter.\n *\n * Two identical filters always produce the same key. Providers use this\n * so `fetchManifest(filter)` and `fetchManifest(sameFilter)` hit the\n * same cache entry.\n */\nexport function filterToCacheKey(filter?: CapabilityFilter): string {\n  if (!filter) return '__all__';\n  const parts: string[] = [];\n  if (filter.kind) parts.push(`kind=${filter.kind}`);\n  if (filter.tags?.length)\n    parts.push(`tags=${[...filter.tags].sort().join(',')}`);\n  if (filter.names?.length)\n    parts.push(`names=${[...filter.names].sort().join(',')}`);\n  return parts.length ? parts.join('|') : '__all__';\n}\n\n/**\n * Apply a CapabilityFilter to a pre-fetched manifest. Used by providers\n * that fetch the full manifest once and filter in memory.\n */\nexport function applyFilter(\n  capabilities: Capability[],\n  filter?: CapabilityFilter\n): Capability[] {\n  if (!filter) return capabilities;\n  return capabilities.filter((cap) => {\n    if (filter.kind && cap.kind !== filter.kind) return false;\n    if (filter.names && !filter.names.includes(cap.name)) return false;\n    if (filter.tags?.length) {\n      const capTags = new Set(cap.metadata.tags ?? []);\n      const anyMatch = filter.tags.some((t) => capTags.has(t));\n      if (!anyMatch) return false;\n    }\n    return true;\n  });\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;AASG;AAeH;;;;;;;AAOG;MACU,aAAa,CAAA;AACP,IAAA,KAAK;AACL,IAAA,KAAK,GAAG,IAAI,GAAG,EAAsB;AAEtD,IAAA,WAAA,CAAY,SAA8B,EAAE,EAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM;IACrC;;AAGA,IAAA,GAAG,CAAC,GAAW,EAAA;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;AACjC,QAAA,IAAI,CAAC,KAAK;AAAE,YAAA,OAAO,SAAS;QAC5B,IAAI,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE;AAChC,YAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;AACtB,YAAA,OAAO,SAAS;QAClB;QACA,OAAO,KAAK,CAAC,YAAY;IAC3B;;IAGA,GAAG,CAAC,GAAW,EAAE,YAA0B,EAAA;AACzC,QAAA,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC;YAAE;AACrB,QAAA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;YAClC,YAAY;AACb,SAAA,CAAC;IACJ;;IAGA,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE;IACpB;;AAGA,IAAA,IAAI,IAAI,GAAA;AACN,QAAA,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI;IACxB;AACD;AAED;;;;;;AAMG;AACG,SAAU,gBAAgB,CAAC,MAAyB,EAAA;AACxD,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,SAAS;IAC7B,MAAM,KAAK,GAAa,EAAE;IAC1B,IAAI,MAAM,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,CAAA,KAAA,EAAQ,MAAM,CAAC,IAAI,CAAA,CAAE,CAAC;AAClD,IAAA,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM;QACrB,KAAK,CAAC,IAAI,CAAC,CAAA,KAAA,EAAQ,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA,CAAE,CAAC;AACzD,IAAA,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM;QACtB,KAAK,CAAC,IAAI,CAAC,CAAA,MAAA,EAAS,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA,CAAE,CAAC;AAC3D,IAAA,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS;AACnD;AAEA;;;AAGG;AACG,SAAU,WAAW,CACzB,YAA0B,EAC1B,MAAyB,EAAA;AAEzB,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,YAAY;AAChC,IAAA,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,KAAI;QACjC,IAAI,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;AAAE,YAAA,OAAO,KAAK;AACzD,QAAA,IAAI,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;AAAE,YAAA,OAAO,KAAK;AAClE,QAAA,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE;AACvB,YAAA,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxD,YAAA,IAAI,CAAC,QAAQ;AAAE,gBAAA,OAAO,KAAK;QAC7B;AACA,QAAA,OAAO,IAAI;AACb,IAAA,CAAC,CAAC;AACJ;;;;"}

package/dist/types/index.d.ts

@@ -16,6 +16,8 @@ export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './tools/memory';
+export * from './tools/proxyTool';
+export * from './providers';
 export * from './memory';
 export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
 export { shouldFlushMemory, runMemoryFlush, } from './graphs/phases/memoryFlushPhase';

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

@@ -0,0 +1,89 @@
+/**
+ * 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 { 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 { A2AProviderConfig, A2ASkill } from './types';
+export declare class A2ACapabilityProvider implements CapabilityProvider {
+    readonly providerId: string;
+    private readonly config;
+    private readonly logger;
+    private readonly connections;
+    constructor(config: A2AProviderConfig);
+    fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;
+    createRunnables(capabilities: Capability[], _credentials: CredentialMap): Promise<StructuredToolInterface[]>;
+    /** Disconnect any cached clients. A2A is stateless over HTTP so this
+     *  is effectively a cache clear — no sockets to close. */
+    close(): Promise<void>;
+    private ensureConnection;
+    private resolveAuthHeaders;
+    private cardToCapabilities;
+    private capabilityMatchesFilter;
+    private buildProxyTool;
+}
+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 declare function parseCapabilityName(name: string): {
+    remoteName: string;
+    skillId?: string;
+} | null;
+/** Derive a Capability from a skill entry on the agent card. */
+export declare function skillToCapability(remoteName: string, skill: A2ASkill): Capability;
+/**
+ * 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 declare const MESSAGE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly message: {
+            readonly type: "string";
+            readonly description: "Instruction or question to send to the remote agent as a user message.";
+        };
+    };
+    readonly required: readonly ["message"];
+};
+/**
+ * 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 declare function coerceInputToA2AMessage(input: unknown, skillId?: string): {
+    role: 'user';
+    parts: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};

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

@@ -0,0 +1,47 @@
+/**
+ * A2A HTTP client — thin wrappers for the two operations the provider
+ * needs: fetching the agent card and sending JSON-RPC task requests.
+ *
+ * Uses axios (already in deps) via the shared httpClient utility so
+ * proxy config + headers work consistently with the tools-server provider.
+ */
+import type { A2AAgentCard, A2ATask, A2ATaskParams } from './types';
+/** Options for constructing a single-remote A2A client. */
+export interface A2AClientOptions {
+    baseUrl: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    cardPath?: string;
+    rpcPath?: string;
+}
+/**
+ * Lightweight single-remote A2A client. One instance per remote; the
+ * provider builds one per spec entry and caches them.
+ */
+export declare class A2AClient {
+    private readonly http;
+    private readonly cardPath;
+    private readonly rpcPath;
+    constructor(opts: A2AClientOptions);
+    /** GET /.well-known/agent.json (or the configured override). */
+    fetchAgentCard(): Promise<A2AAgentCard>;
+    /**
+     * POST a JSON-RPC `tasks/send` request and return the resulting Task.
+     * The caller supplies the params (id, sessionId, message); this helper
+     * wraps it in the JSON-RPC envelope, dispatches, and unwraps.
+     */
+    sendTask(params: A2ATaskParams): Promise<A2ATask>;
+    /** Low-level JSON-RPC dispatcher — exposed for tests / advanced callers. */
+    rpc<P, R>(method: string, params: P): Promise<R>;
+}
+/**
+ * Generate a short opaque id for JSON-RPC requests. Not cryptographic —
+ * just unique enough to pair request/response in logs.
+ */
+export declare function generateRpcId(): string;
+/**
+ * Extract the plain-text output from a completed Task's artifacts. If
+ * the task isn't `completed`, throws. If there are no text parts, returns
+ * an empty string rather than null so callers always get a string.
+ */
+export declare function extractTaskText(task: A2ATask): string;

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

@@ -0,0 +1,18 @@
+/**
+ * Environment-driven defaults + default logger for the A2A provider.
+ *
+ * Mirrors the MCP provider's config.ts so the two providers have the same
+ * override story for hosts.
+ */
+import type { A2ALogger } from './types';
+/**
+ * Read env values with fallbacks. Evaluated lazily so tests that mutate
+ * process.env get the current value.
+ */
+export declare function getA2AEnvDefaults(): {
+    clientName: string;
+    clientVersion: string;
+    timeoutMs: number;
+};
+/** Console-routed default logger. */
+export declare const consoleLogger: A2ALogger;

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

@@ -0,0 +1,6 @@
+export { A2ACapabilityProvider } from './A2ACapabilityProvider';
+export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName, parseCapabilityName, skillToCapability, coerceInputToA2AMessage, MESSAGE_INPUT_SCHEMA, } from './A2ACapabilityProvider';
+export { A2AClient, extractTaskText, generateRpcId } from './client';
+export type { A2AClientOptions } from './client';
+export { consoleLogger as a2aConsoleLogger, getA2AEnvDefaults } from './config';
+export type { A2AAgentCard, A2ACardCapabilities, A2ALogger, A2AMessage, A2AProviderConfig, A2ARemoteSpec, A2ASkill, A2ATask, A2ATaskParams, A2ATaskState, A2ATaskStatus, JsonRpcRequest, JsonRpcResponse, JsonRpcSuccess, JsonRpcErrorResponse, } from './types';