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

package/dist/types/tools/proxyTool.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { type StructuredToolInterface } from '@langchain/core/tools';
+import type { Capability, CredentialMap } from '@/providers/types';
+/** 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 declare function buildProxyTool(capability: Capability, credentials: CredentialMap, options: ProxyToolOptions): StructuredToolInterface;

package/dist/types/types/stream.d.ts

@@ -116,6 +116,16 @@ export type ToolCallsDetails = {
 export type ToolCallDelta = {
     type: StepTypes;
     tool_calls?: ToolCallChunk[];
+    /**
+     * 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 = {
     id: string;

package/dist/types/utils/credentials.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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.
+ */
+import type { AuthConfigEntry, Capability, CredentialMap } from '@/providers/types';
+/**
+ * Source of a credential value in the merged result. Useful for logging
+ * and debugging which layer won a given authField.
+ */
+export declare enum CredentialOrigin {
+    /** From the caller's process env (typically the CLI). */
+    ENV = "env",
+    /** From the agent definition's tool_credentials block. */
+    AGENT = "agent",
+    /** From the user's stored credentials in the host's credential store. */
+    USER = "user",
+    /** From an active OAuth session forwarded by the host. */
+    SESSION = "session",
+    /** Injected by the host at runtime for another reason. */
+    RUNTIME = "runtime"
+}
+/** One layer of credentials with its origin. */
+export interface CredentialLayer {
+    origin: CredentialOrigin;
+    values: CredentialMap;
+}
+/**
+ * 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).
+ */
+export declare function mergeCredentials(...layers: CredentialLayer[]): CredentialMap;
+/**
+ * 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.
+ */
+export declare function collectRequiredAuthFields(capabilities: Capability[]): string[];
+/**
+ * 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).
+ */
+export declare function filterForwardableCredentials(credentials: CredentialMap, capabilities: Capability[]): CredentialMap;
+/**
+ * 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.
+ */
+export declare function findMissingCredentials(capability: Capability, credentials: CredentialMap): string[];
+/**
+ * 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).
+ */
+export declare function credentialsFromEnv(authFields: readonly string[], env?: NodeJS.ProcessEnv): CredentialLayer;
+/**
+ * Type guard: check whether an auth config entry should be forwarded by
+ * the host (vs resolved by the provider itself).
+ */
+export declare function isForwardable(entry: AuthConfigEntry): boolean;

package/dist/types/utils/httpClient.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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.
+ */
+import { type AxiosInstance } from 'axios';
+/** Configuration for creating an HTTP client. */
+export interface HttpClientConfig {
+    /** Base URL prepended to all requests. */
+    baseURL: string;
+    /** Optional API key — if present, sent as `x-api-key` header. */
+    apiKey?: string;
+    /** Custom header map merged into every request. */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds. Defaults to 30_000. */
+    timeoutMs?: number;
+    /**
+     * Override for the PROXY env var. Useful for tests. If undefined,
+     * falls back to process.env.PROXY.
+     */
+    proxy?: string | null;
+}
+/**
+ * Build an axios instance configured per HttpClientConfig.
+ *
+ * The returned instance should be retained (not recreated per request) so
+ * keepalive connections can be reused.
+ */
+export declare function createHttpClient(config: HttpClientConfig): AxiosInstance;
+/**
+ * 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.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly url: string;
+    constructor(status: number, url: string, body: unknown);
+}
+/** Assert that an axios response is a 2xx; throw HttpError otherwise. */
+export declare function assertOk(status: number, url: string, body: unknown): void;

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

@@ -13,3 +13,6 @@ export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
 export * from './fileManifest';
 export * from './errors';
+export * from './httpClient';
+export * from './credentials';
+export * from './toolManifest';

package/dist/types/utils/toolManifest.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+import type { Capability, CapabilityFilter } from '@/providers/types';
+export interface ManifestCacheConfig {
+    /** Time-to-live in milliseconds. 0 disables caching. Defaults to 60_000 (1 min). */
+    ttlMs?: number;
+}
+/**
+ * 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).
+ */
+export declare class ManifestCache {
+    private readonly ttlMs;
+    private readonly store;
+    constructor(config?: ManifestCacheConfig);
+    /** Retrieve cached capabilities, or undefined on miss / expiry. */
+    get(key: string): Capability[] | undefined;
+    /** Insert or replace cached capabilities for the given key. */
+    set(key: string, capabilities: Capability[]): void;
+    /** Remove all cached entries. */
+    clear(): void;
+    /** For tests / diagnostics. */
+    get size(): number;
+}
+/**
+ * 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.
+ */
+export declare function filterToCacheKey(filter?: CapabilityFilter): string;
+/**
+ * Apply a CapabilityFilter to a pre-fetched manifest. Used by providers
+ * that fetch the full manifest once and filter in memory.
+ */
+export declare function applyFilter(capabilities: Capability[], filter?: CapabilityFilter): Capability[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.3.1",
+  "version": "1.4.0-alpha.0",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -9,6 +9,26 @@
       "import": "./dist/esm/main.mjs",
       "require": "./dist/cjs/main.cjs",
       "types": "./dist/types/index.d.ts"
+    },
+    "./providers/tools-server": {
+      "import": "./dist/esm/providers/tools-server/ToolsServerCapabilityProvider.mjs",
+      "require": "./dist/cjs/providers/tools-server/ToolsServerCapabilityProvider.cjs",
+      "types": "./dist/types/providers/tools-server/ToolsServerCapabilityProvider.d.ts"
+    },
+    "./providers/mcp": {
+      "import": "./dist/esm/providers/mcp/MCPCapabilityProvider.mjs",
+      "require": "./dist/cjs/providers/mcp/MCPCapabilityProvider.cjs",
+      "types": "./dist/types/providers/mcp/MCPCapabilityProvider.d.ts"
+    },
+    "./providers/a2a": {
+      "import": "./dist/esm/providers/a2a/A2ACapabilityProvider.mjs",
+      "require": "./dist/cjs/providers/a2a/A2ACapabilityProvider.cjs",
+      "types": "./dist/types/providers/a2a/A2ACapabilityProvider.d.ts"
+    },
+    "./providers/composite": {
+      "import": "./dist/esm/providers/composite/CompositeCapabilityProvider.mjs",
+      "require": "./dist/cjs/providers/composite/CompositeCapabilityProvider.cjs",
+      "types": "./dist/types/providers/composite/CompositeCapabilityProvider.d.ts"
     }
   },
   "type": "module",

package/src/graphs/Graph.ts

@@ -1498,14 +1498,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           clientOptions: effectiveClientOptions,
         });
 
-      // DEBUG: Log which model and tools each agent uses during handoff
-      mlog(
-        `[createCallModel] Agent "${agentId}" invoking LLM | provider=${agentContext.provider} | ` +
-          `model=${(effectiveClientOptions as Record<string, unknown>).model ?? 'default'} | ` +
-          `toolsForBinding=${toolsForBinding?.length ?? 0} | ` +
-          `toolNames=[${(toolsForBinding ?? []).map((t) => (t as { name?: string }).name ?? 'unknown').join(', ')}]`
-      );
-
       if (agentContext.systemRunnable) {
         model = agentContext.systemRunnable.pipe(model as Runnable);
       }
@@ -1680,27 +1672,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
         // Step 1: Resolve best available summary
         let summary: string | undefined;
-        let summarySource: string;
 
         if (this._cachedRunSummary != null) {
           summary = this._cachedRunSummary;
-          summarySource = 'cached';
         } else if (
           agentContext.persistedSummary != null &&
           agentContext.persistedSummary !== ''
         ) {
           summary = agentContext.persistedSummary;
           this._cachedRunSummary = summary;
-          summarySource = 'persisted';
         } else if (
           sumConfig?.initialSummary != null &&
           sumConfig.initialSummary !== ''
         ) {
           summary = sumConfig.initialSummary;
           this._cachedRunSummary = summary;
-          summarySource = 'initial-seed';
-        } else {
-          summarySource = 'none';
         }
 
         // Step 2: Calculate token budget
@@ -1847,15 +1833,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
         agentContext.indexTokenCountMap = viewTokenMap;
 
-        mlog(
-          `[Graph:Compaction] ${messages.length}→${viewParts.length} msgs | ` +
-            `compacted=${compactedMessages.length} window=${recentMessages.length} | ` +
-            `summary=${summarySource} | budget=${usedTokens}/${recentBudget}` +
-            (fileManifestTokens > 0
-              ? ` | manifest=${fileManifest?.length ?? 0} files (${fileManifestTokens}tok)`
-              : '')
-        );
-
         // Step 5: Fire background summary update (non-blocking)
         // Summarize messages outside the window so next iteration has a fresh summary.
         // Only trigger if there are compacted messages worth summarizing.

package/src/index.ts

@@ -26,6 +26,10 @@ export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './tools/memory';
+export * from './tools/proxyTool';
+
+/* Capability Providers */
+export * from './providers';
 
 /* Memory (storage + factory) */
 export * from './memory';

package/src/providers/__tests__/CompositeCapabilityProvider.test.ts

@@ -0,0 +1,93 @@
+import { CompositeCapabilityProvider } from '../composite/CompositeCapabilityProvider';
+import {
+  CapabilityKind,
+  type Capability,
+  type CapabilityProvider,
+  type CredentialMap,
+} from '../types';
+
+const makeCap = (
+  name: string,
+  kind: CapabilityKind = CapabilityKind.TOOL
+): Capability => ({
+  kind,
+  name,
+  description: `${name} cap`,
+  authConfig: [],
+  metadata: {},
+});
+
+class FakeProvider implements CapabilityProvider {
+  readonly providerId: string;
+  manifestCallCount = 0;
+  createCallCount = 0;
+
+  constructor(
+    id: string,
+    private readonly manifest: Capability[],
+    private readonly failOnFetch = false
+  ) {
+    this.providerId = id;
+  }
+  async fetchManifest(): Promise<Capability[]> {
+    this.manifestCallCount++;
+    if (this.failOnFetch) throw new Error('simulated failure');
+    return this.manifest;
+  }
+  async createRunnables(capabilities: Capability[], _creds: CredentialMap) {
+    this.createCallCount++;
+    // Return one fake tool per capability name — we can't import StructuredToolInterface here cleanly,
+    // so cast. The test only checks length + name.
+    return capabilities.map((c) => ({ name: c.name }) as unknown as never);
+  }
+}
+
+describe('CompositeCapabilityProvider', () => {
+  it('throws on empty provider list', () => {
+    expect(() => new CompositeCapabilityProvider([])).toThrow(/at least one/);
+  });
+
+  it('providerId reflects composed providers', () => {
+    const composite = new CompositeCapabilityProvider([
+      new FakeProvider('p1', []),
+      new FakeProvider('p2', []),
+    ]);
+    expect(composite.providerId).toBe('composite:p1,p2');
+  });
+
+  it('merges manifests from all providers', async () => {
+    const p1 = new FakeProvider('p1', [makeCap('a'), makeCap('b')]);
+    const p2 = new FakeProvider('p2', [makeCap('c')]);
+    const composite = new CompositeCapabilityProvider([p1, p2]);
+    const caps = await composite.fetchManifest();
+    expect(caps.map((c) => c.name).sort()).toEqual(['a', 'b', 'c']);
+  });
+
+  it('deduplicates on name collision, first provider wins', async () => {
+    const p1 = new FakeProvider('p1', [makeCap('dup'), makeCap('a')]);
+    const p2 = new FakeProvider('p2', [makeCap('dup'), makeCap('b')]);
+    const composite = new CompositeCapabilityProvider([p1, p2]);
+    const caps = await composite.fetchManifest();
+    expect(caps.map((c) => c.name).sort()).toEqual(['a', 'b', 'dup']);
+  });
+
+  it('continues when one provider fails', async () => {
+    const p1 = new FakeProvider('p1', [], true);
+    const p2 = new FakeProvider('p2', [makeCap('x')]);
+    const composite = new CompositeCapabilityProvider([p1, p2]);
+    const caps = await composite.fetchManifest();
+    expect(caps).toHaveLength(1);
+    expect(caps[0].name).toBe('x');
+  });
+
+  it('createRunnables routes each capability to its owning provider', async () => {
+    const p1 = new FakeProvider('p1', [makeCap('a'), makeCap('b')]);
+    const p2 = new FakeProvider('p2', [makeCap('c')]);
+    const composite = new CompositeCapabilityProvider([p1, p2]);
+    const manifest = await composite.fetchManifest();
+    const runnables = await composite.createRunnables(manifest, {});
+    expect(runnables).toHaveLength(3);
+    expect(p1.createCallCount).toBe(1);
+    expect(p2.createCallCount).toBe(1);
+  });
+});

package/src/providers/__tests__/ToolsServerCapabilityProvider.integration.spec.ts

@@ -0,0 +1,79 @@
+/**
+ * Integration test — exercises ToolsServerCapabilityProvider against a live
+ * tools-server instance.
+ *
+ * RUN REQUIREMENTS:
+ *   1. tools-server must be running locally at TOOLS_SERVER_URL
+ *   2. TOOLS_SERVER_API_KEY must match the server's configured key
+ *
+ * The suite is skipped when TOOLS_SERVER_URL is not set so unit CI passes.
+ * To run: TOOLS_SERVER_URL=http://localhost:3500 TOOLS_SERVER_API_KEY=test \
+ *         npx jest --testPathPatterns=integration
+ */
+
+import { ToolsServerCapabilityProvider } from '../tools-server/ToolsServerCapabilityProvider';
+import { CapabilityKind } from '../types';
+
+const baseUrl = process.env.TOOLS_SERVER_URL;
+const apiKey = process.env.TOOLS_SERVER_API_KEY;
+
+const describeIfLive = baseUrl && apiKey ? describe : describe.skip;
+
+describeIfLive('ToolsServerCapabilityProvider (live integration)', () => {
+  let provider: ToolsServerCapabilityProvider;
+
+  beforeAll(() => {
+    provider = new ToolsServerCapabilityProvider({
+      baseUrl: baseUrl as string,
+      apiKey: apiKey as string,
+      manifestTtlMs: 0, // always fresh for tests
+    });
+  });
+
+  it('fetches manifest from live server', async () => {
+    const caps = await provider.fetchManifest();
+    expect(caps.length).toBeGreaterThan(0);
+    for (const cap of caps) {
+      expect(cap.kind).toBe(CapabilityKind.TOOL);
+      expect(typeof cap.name).toBe('string');
+      expect(typeof cap.description).toBe('string');
+      expect(Array.isArray(cap.authConfig)).toBe(true);
+    }
+  });
+
+  it('live manifest contains wikipedia', async () => {
+    const caps = await provider.fetchManifest();
+    const wikipedia = caps.find((c) => c.name === 'wikipedia');
+    expect(wikipedia).toBeDefined();
+    expect(wikipedia?.schema).toBeDefined();
+  });
+
+  it('builds runnables that invoke wikipedia end-to-end', async () => {
+    const caps = await provider.fetchManifest({ names: ['wikipedia'] });
+    expect(caps).toHaveLength(1);
+
+    const [tool] = await provider.createRunnables(caps, {});
+    const result = await tool.invoke({ action: 'search', query: 'TypeScript' });
+
+    // Wikipedia returns JSON-serialized results; just check it's non-empty
+    expect(typeof result).toBe('string');
+    expect((result as string).length).toBeGreaterThan(0);
+  });
+
+  it('surfaces backend failure as thrown error', async () => {
+    // Invoke wikipedia with missing required field → backend returns success:false
+    const caps = await provider.fetchManifest({ names: ['wikipedia'] });
+    const [tool] = await provider.createRunnables(caps, {});
+    await expect(tool.invoke({})).rejects.toThrow();
+  });
+
+  it('filters manifest by names correctly', async () => {
+    const caps = await provider.fetchManifest({
+      names: ['wikipedia', 'arxiv_search'],
+    });
+    expect(caps.length).toBeLessThanOrEqual(2);
+    for (const cap of caps) {
+      expect(['wikipedia', 'arxiv_search']).toContain(cap.name);
+    }
+  });
+});