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

package/src/providers/tools-server/ToolsServerCapabilityProvider.ts

@@ -1,248 +0,0 @@
-/**
- * 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 {
-  CapabilityKind,
-  type Capability,
-  type CapabilityFilter,
-  type CapabilityProvider,
-  type CredentialMap,
-} from '@/providers/types';
-import {
-  createHttpClient,
-  type HttpClientConfig,
-  assertOk,
-} from '@/utils/httpClient';
-import {
-  ManifestCache,
-  filterToCacheKey,
-  applyFilter,
-} from '@/utils/toolManifest';
-import { buildProxyTool } from '@/tools/proxyTool';
-
-/** 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;
-  /**
-   * Optional per-request auth header builder — invoked on every tool
-   * invocation (NOT on the manifest fetch, which is service-to-service).
-   * When provided, the returned headers are merged into the `/execute`
-   * request so the host can pass user-scoped identity (e.g.,
-   * `Authorization: Bearer <jwt>`) that tools-server verifies for
-   * admin-gated tools.
-   *
-   * Typical host wiring: mint a short-lived JWT per call carrying the
-   * authenticated user's `{ userId, role }` claims; tools-server's
-   * `TOOLS_SERVER_JWT_SECRET` validates.
-   */
-  getExecuteAuthHeaders?: () =>
-    | Record<string, string>
-    | Promise<Record<string, string>>;
-}
-
-/**
- * Shape of a single entry from tools-server's /manifest response.
- *
- * Matches the tools-server ManifestToolEntry type. We define our own here
- * to avoid cross-package coupling — the shape is a stable HTTP contract.
- */
-interface ToolsServerManifestEntry {
-  pluginKey: string;
-  name: string;
-  description: string;
-  icon?: string;
-  authConfig?: Array<{
-    authField: string;
-    label?: string;
-    description?: string;
-    source?: string;
-    required?: boolean;
-    prod?: boolean;
-    admin?: boolean;
-    hide?: boolean;
-  }>;
-  /** Input schema as JSON Schema (tools-server emits `schema`). */
-  schema?: unknown;
-  /** Legacy alias accepted for backwards compatibility. */
-  jsonSchema?: unknown;
-  category?: string;
-  tags?: string[];
-  toolkit?: string;
-  endpoint?: string;
-  /** Governance flags forwarded by tools-server getManifest(). */
-  hidden?: boolean;
-  admin?: boolean;
-  env?: Array<'development' | 'production' | 'test' | 'staging'>;
-}
-
-export class ToolsServerCapabilityProvider implements CapabilityProvider {
-  readonly providerId: string;
-  private readonly client: AxiosInstance;
-  private readonly manifestPath: string;
-  private readonly executePath: string;
-  private readonly cache: ManifestCache;
-  private readonly getExecuteAuthHeaders?:
-    | (() => Record<string, string> | Promise<Record<string, string>>);
-
-  constructor(private readonly config: ToolsServerConfig) {
-    const {
-      baseUrl,
-      apiKey,
-      manifestPath = '/manifest',
-      executePath = '/execute/:name',
-      timeoutMs = 30_000,
-      manifestTtlMs = 60_000,
-      client,
-      proxy,
-      getExecuteAuthHeaders,
-    } = config;
-
-    if (!baseUrl) {
-      throw new Error('ToolsServerCapabilityProvider: baseUrl is required');
-    }
-    if (!apiKey) {
-      throw new Error('ToolsServerCapabilityProvider: apiKey is required');
-    }
-
-    this.providerId = `tools-server:${baseUrl}`;
-    this.manifestPath = manifestPath;
-    this.executePath = executePath;
-    this.cache = new ManifestCache({ ttlMs: manifestTtlMs });
-    this.getExecuteAuthHeaders = getExecuteAuthHeaders;
-
-    if (client) {
-      this.client = client;
-    } else {
-      const httpConfig: HttpClientConfig = {
-        baseURL: baseUrl,
-        apiKey,
-        timeoutMs,
-        proxy,
-      };
-      this.client = createHttpClient(httpConfig);
-    }
-  }
-
-  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {
-    const cacheKey = filterToCacheKey(filter);
-    const cached = this.cache.get(cacheKey);
-    if (cached) {
-      // DEBUG: cache hit (remove after stabilization)
-      // eslint-disable-next-line no-console
-      console.debug(
-        `[${this.providerId}] manifest cache hit — ${cached.length} caps`
-      );
-      return cached;
-    }
-
-    // DEBUG
-    // eslint-disable-next-line no-console
-    console.debug(
-      `[${this.providerId}] fetching manifest from ${this.manifestPath}`
-    );
-
-    const res = await this.client.get<ToolsServerManifestEntry[]>(
-      this.manifestPath
-    );
-    assertOk(res.status, this.manifestPath, res.data);
-
-    const entries = Array.isArray(res.data) ? res.data : [];
-    const capabilities: Capability[] = entries.map((entry) =>
-      normalizeEntry(entry)
-    );
-
-    // Apply filter before caching the full list separately so unfiltered
-    // refetches don't re-hit the network.
-    const fullCacheKey = filterToCacheKey();
-    this.cache.set(fullCacheKey, capabilities);
-
-    const filtered = applyFilter(capabilities, filter);
-    if (cacheKey !== fullCacheKey) {
-      this.cache.set(cacheKey, filtered);
-    }
-
-    // DEBUG
-    // eslint-disable-next-line no-console
-    console.debug(
-      `[${this.providerId}] manifest loaded — ${capabilities.length} caps, ${filtered.length} after filter`
-    );
-
-    return filtered;
-  }
-
-  async createRunnables(
-    capabilities: Capability[],
-    credentials: CredentialMap
-  ): Promise<StructuredToolInterface[]> {
-    return capabilities.map((cap) =>
-      buildProxyTool(cap, credentials, {
-        client: this.client,
-        executePath: this.executePath,
-        getAuthHeaders: this.getExecuteAuthHeaders,
-      })
-    );
-  }
-
-  /** Force a manifest refresh on next fetchManifest call. */
-  invalidateCache(): void {
-    this.cache.clear();
-  }
-}
-
-/**
- * Translate a raw tools-server manifest entry into a typed Capability.
- * Defensive — tools-server may add fields; we pull only what we need.
- */
-function normalizeEntry(entry: ToolsServerManifestEntry): Capability {
-  return {
-    kind: CapabilityKind.TOOL,
-    name: entry.pluginKey,
-    description: entry.description ?? '',
-    schema: entry.schema ?? entry.jsonSchema,
-    authConfig: (entry.authConfig ?? []).map((ac) => ({
-      authField: ac.authField,
-      label: ac.label,
-      description: ac.description,
-      required: ac.required,
-      prod: ac.prod,
-      admin: ac.admin,
-      hide: ac.hide,
-      // Source is a string in wire format; downstream consumers coerce to AuthSource.
-      source: ac.source as Capability['authConfig'][number]['source'],
-    })),
-    metadata: {
-      icon: entry.icon,
-      category: entry.category,
-      tags: entry.tags,
-      // Governance — hosts use these to gate UI/role/environment.
-      hidden: entry.hidden,
-      admin: entry.admin,
-      env: entry.env,
-    },
-  };
-}

package/src/providers/tools-server/index.ts

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

package/src/providers/types.ts

@@ -1,204 +0,0 @@
-/**
- * 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 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 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[];
-
-  // --- Governance flags ------------------------------------------------
-
-  /**
-   * When true, hosts omit this capability from user-facing pickers
-   * (Agent Builder, tool dropdown). Still invokable when a saved agent
-   * references it by name.
-   */
-  hidden?: boolean;
-  /** When true, only admin-role users can enable or invoke this capability. */
-  admin?: boolean;
-  /**
-   * Deployment-stage restriction. When set, hosts whose deployment stage
-   * isn't in the array should hide the capability (e.g., a prod host
-   * shouldn't surface a tool with `env: ['development']`).
-   */
-  env?: Array<'development' | 'production' | 'test' | 'staging'>;
-
-  // --- Reserved for upstream patterns (not populated today) ---
-
-  /** 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[]>;
-}