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

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

@@ -0,0 +1,220 @@
+/**
+ * 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;
+}
+
+/**
+ * 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;
+}
+
+export class ToolsServerCapabilityProvider implements CapabilityProvider {
+  readonly providerId: string;
+  private readonly client: AxiosInstance;
+  private readonly manifestPath: string;
+  private readonly executePath: string;
+  private readonly cache: ManifestCache;
+
+  constructor(private readonly config: ToolsServerConfig) {
+    const {
+      baseUrl,
+      apiKey,
+      manifestPath = '/manifest',
+      executePath = '/execute/:name',
+      timeoutMs = 30_000,
+      manifestTtlMs = 60_000,
+      client,
+      proxy,
+    } = 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 });
+
+    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,
+      })
+    );
+  }
+
+  /** 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,
+    },
+  };
+}

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

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

package/src/providers/types.ts

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

package/src/tools/proxyTool.ts

@@ -0,0 +1,146 @@
+/**
+ * proxyTool — wraps a Capability into a LangChain StructuredTool that
+ * dispatches execution to a remote backend (e.g., tools-server) over HTTP.
+ *
+ * The LLM sees this tool identically to a locally-implemented tool:
+ *   - same name
+ *   - same description
+ *   - same input schema (JSON Schema)
+ *   - same invoke(input) contract
+ *
+ * Under the hood, invoke() POSTs to the backend's execute endpoint with
+ * the input and a caller-supplied credential map. The backend returns
+ * { success, result, error, timing } which this wrapper unpacks.
+ */
+
+import type { AxiosInstance } from 'axios';
+import { tool, type StructuredToolInterface } from '@langchain/core/tools';
+import type { Capability, CredentialMap } from '@/providers/types';
+import { HttpError } from '@/utils/httpClient';
+
+/** Shape of the backend's execute response. Matches tools-server. */
+export interface ExecuteResponse {
+  success: boolean;
+  result?: unknown;
+  error?: string;
+  timing?: { durationMs: number };
+}
+
+/** Options passed to buildProxyTool. */
+export interface ProxyToolOptions {
+  /** HTTP client configured with backend base URL + auth. */
+  client: AxiosInstance;
+  /**
+   * Path template for execution. The literal `:name` is replaced with the
+   * capability's name. Defaults to `/execute/:name` (tools-server convention).
+   */
+  executePath?: string;
+  /**
+   * Optional callback invoked on every execution — used for metrics,
+   * telemetry, debug logging. Errors in the hook are swallowed.
+   */
+  onExecute?: (ctx: ExecuteCallbackContext) => void;
+}
+
+export interface ExecuteCallbackContext {
+  capabilityName: string;
+  input: unknown;
+  response?: ExecuteResponse;
+  error?: Error;
+  durationMs: number;
+}
+
+/**
+ * Build a StructuredTool that proxies to a remote backend.
+ *
+ * The credentialMap is baked into the closure — callers that need
+ * per-invocation credential rotation should rebuild the tool.
+ */
+export function buildProxyTool(
+  capability: Capability,
+  credentials: CredentialMap,
+  options: ProxyToolOptions
+): StructuredToolInterface {
+  const { client, executePath = '/execute/:name', onExecute } = options;
+  const url = executePath.replace(':name', encodeURIComponent(capability.name));
+
+  return tool(
+    async (input: unknown): Promise<string> => {
+      const startMs = Date.now();
+      const debugPrefix = `[proxyTool:${capability.name}]`;
+
+      try {
+        // DEBUG: log (remove after POC stabilizes)
+        // eslint-disable-next-line no-console
+        console.debug(
+          `${debugPrefix} invoking — inputKeys=${input && typeof input === 'object' ? Object.keys(input as object).length : 0}`
+        );
+
+        const res = await client.post<ExecuteResponse>(url, {
+          input,
+          credentials,
+        });
+
+        const durationMs = Date.now() - startMs;
+
+        if (res.status < 200 || res.status >= 300) {
+          throw new HttpError(res.status, url, res.data);
+        }
+
+        const body = res.data;
+        if (onExecute) {
+          try {
+            onExecute({
+              capabilityName: capability.name,
+              input,
+              response: body,
+              durationMs,
+            });
+          } catch {
+            // hook errors are non-fatal
+          }
+        }
+
+        if (!body.success) {
+          // DEBUG
+          // eslint-disable-next-line no-console
+          console.debug(
+            `${debugPrefix} backend reported failure — ${body.error}`
+          );
+          throw new Error(body.error ?? 'Tool execution failed');
+        }
+
+        // LangChain tools typically return strings; stringify non-string results
+        if (typeof body.result === 'string') {
+          return body.result;
+        }
+        return JSON.stringify(body.result);
+      } catch (err) {
+        const durationMs = Date.now() - startMs;
+        const error = err instanceof Error ? err : new Error(String(err));
+        if (onExecute) {
+          try {
+            onExecute({
+              capabilityName: capability.name,
+              input,
+              error,
+              durationMs,
+            });
+          } catch {
+            // hook errors are non-fatal
+          }
+        }
+        throw error;
+      }
+    },
+    {
+      name: capability.name,
+      description: capability.description,
+      schema: (capability.schema as object) ?? {
+        type: 'object',
+        properties: {},
+      },
+      responseFormat: 'content',
+    }
+  );
+}

package/src/types/stream.ts

@@ -164,6 +164,16 @@ export type ToolCallsDetails = {
 export type ToolCallDelta = {
   type: StepTypes;
   tool_calls?: ToolCallChunk[]; // #new
+  /**
+   * Auth URL for tool calls that require interactive authentication
+   * (typically OAuth-gated MCP tools). Hosts populate this on a delta
+   * dispatch when a tool invocation surfaces an auth challenge so the
+   * client can render an approval prompt without waiting for the call
+   * to complete.
+   */
+  auth?: string;
+  /** Auth challenge expiration (UNIX seconds). Pairs with `auth`. */
+  expires_at?: number;
 };
 
 export type AgentToolCall =

package/src/utils/__tests__/credentials.test.ts

@@ -0,0 +1,130 @@
+import {
+  mergeCredentials,
+  collectRequiredAuthFields,
+  filterForwardableCredentials,
+  findMissingCredentials,
+  credentialsFromEnv,
+  isForwardable,
+  CredentialOrigin,
+} from '../credentials';
+import { AuthSource, CapabilityKind, type Capability } from '@/providers/types';
+
+const makeCap = (
+  name: string,
+  authFields: Array<[string, AuthSource?, boolean?]>
+): Capability => ({
+  kind: CapabilityKind.TOOL,
+  name,
+  description: `${name} capability`,
+  authConfig: authFields.map(([authField, source, required]) => ({
+    authField,
+    source,
+    required,
+  })),
+  metadata: {},
+});
+
+describe('mergeCredentials', () => {
+  it('first layer wins on collision', () => {
+    const result = mergeCredentials(
+      { origin: CredentialOrigin.RUNTIME, values: { KEY: 'runtime' } },
+      {
+        origin: CredentialOrigin.AGENT,
+        values: { KEY: 'agent', OTHER: 'agent' },
+      },
+      { origin: CredentialOrigin.ENV, values: { KEY: 'env', THIRD: 'env' } }
+    );
+    expect(result.KEY).toBe('runtime');
+    expect(result.OTHER).toBe('agent');
+    expect(result.THIRD).toBe('env');
+  });
+
+  it('skips empty/undefined/null values', () => {
+    const result = mergeCredentials(
+      { origin: CredentialOrigin.RUNTIME, values: { KEY: '' } },
+      { origin: CredentialOrigin.ENV, values: { KEY: 'fallback' } }
+    );
+    expect(result.KEY).toBe('fallback');
+  });
+
+  it('returns empty map when all layers empty', () => {
+    const result = mergeCredentials();
+    expect(result).toEqual({});
+  });
+});
+
+describe('collectRequiredAuthFields', () => {
+  it('unions auth fields across capabilities', () => {
+    const caps = [
+      makeCap('a', [['KEY_1'], ['KEY_2']]),
+      makeCap('b', [['KEY_2'], ['KEY_3']]),
+    ];
+    const fields = collectRequiredAuthFields(caps);
+    expect(fields.sort()).toEqual(['KEY_1', 'KEY_2', 'KEY_3']);
+  });
+});
+
+describe('filterForwardableCredentials', () => {
+  it('strips credentials whose source is SERVER', () => {
+    const caps = [
+      makeCap('x', [
+        ['SERVER_KEY', AuthSource.SERVER],
+        ['USER_KEY', AuthSource.USER],
+      ]),
+    ];
+    const filtered = filterForwardableCredentials(
+      { SERVER_KEY: 'secret', USER_KEY: 'u1', UNRELATED: 'ok' },
+      caps
+    );
+    expect(filtered).toEqual({ USER_KEY: 'u1', UNRELATED: 'ok' });
+  });
+});
+
+describe('findMissingCredentials', () => {
+  it('flags missing required fields that are not server-resolved', () => {
+    const cap = makeCap('tool', [
+      ['REQUIRED_USER', AuthSource.USER, true],
+      ['OPTIONAL_USER', AuthSource.USER, false],
+      ['SERVER_MANAGED', AuthSource.SERVER, true],
+    ]);
+    const missing = findMissingCredentials(cap, {});
+    expect(missing).toEqual(['REQUIRED_USER']);
+  });
+
+  it('returns empty when all required are present', () => {
+    const cap = makeCap('tool', [['KEY', AuthSource.USER, true]]);
+    expect(findMissingCredentials(cap, { KEY: 'val' })).toEqual([]);
+  });
+});
+
+describe('credentialsFromEnv', () => {
+  it('reads only fields present in env', () => {
+    const layer = credentialsFromEnv(['A', 'B', 'C'], {
+      A: '1',
+      C: '3',
+    } as NodeJS.ProcessEnv);
+    expect(layer.values).toEqual({ A: '1', C: '3' });
+    expect(layer.origin).toBe(CredentialOrigin.ENV);
+  });
+});
+
+describe('isForwardable', () => {
+  it('SERVER is not forwardable', () => {
+    expect(isForwardable({ authField: 'K', source: AuthSource.SERVER })).toBe(
+      false
+    );
+  });
+  it('USER is forwardable', () => {
+    expect(isForwardable({ authField: 'K', source: AuthSource.USER })).toBe(
+      true
+    );
+  });
+  it('FORWARDED is forwardable', () => {
+    expect(
+      isForwardable({ authField: 'K', source: AuthSource.FORWARDED })
+    ).toBe(true);
+  });
+  it('defaults to forwardable when source is undefined', () => {
+    expect(isForwardable({ authField: 'K' })).toBe(true);
+  });
+});