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

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

@@ -1,77 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-/**
- * 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/toolManifest.d.ts

@@ -1,49 +0,0 @@
-/**
- * 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/src/common/__tests__/spawnPath.test.ts

@@ -1,110 +0,0 @@
-import {
-  SPAWN_PATH_SEP,
-  MAX_NESTING_DEPTH,
-  buildSpawnPath,
-  spawnPathDepth,
-  parentSpawnPath,
-  spawnPathParts,
-  leafSpawnKey,
-  isAncestorSpawnPath,
-} from '../spawnPath';
-
-describe('spawnPath utilities', () => {
-  describe('constants', () => {
-    it('exports a slash separator', () => {
-      expect(SPAWN_PATH_SEP).toBe('/');
-    });
-    it('default max nesting depth is 5', () => {
-      expect(MAX_NESTING_DEPTH).toBe(5);
-    });
-  });
-
-  describe('buildSpawnPath', () => {
-    it('returns key as-is when parent is empty/null/undefined', () => {
-      expect(buildSpawnPath('', 'a')).toBe('a');
-      expect(buildSpawnPath(null, 'a')).toBe('a');
-      expect(buildSpawnPath(undefined, 'a')).toBe('a');
-    });
-    it('appends key to parent with separator', () => {
-      expect(buildSpawnPath('a', 'b')).toBe('a/b');
-      expect(buildSpawnPath('a/b', 'c')).toBe('a/b/c');
-    });
-    it('throws on empty key', () => {
-      expect(() => buildSpawnPath('a', '')).toThrow(/empty key/);
-    });
-  });
-
-  describe('spawnPathDepth', () => {
-    it('root is depth 0', () => {
-      expect(spawnPathDepth('')).toBe(0);
-      expect(spawnPathDepth(null)).toBe(0);
-      expect(spawnPathDepth(undefined)).toBe(0);
-    });
-    it('single segment is depth 1', () => {
-      expect(spawnPathDepth('a')).toBe(1);
-    });
-    it('multi segment counts segments', () => {
-      expect(spawnPathDepth('a/b')).toBe(2);
-      expect(spawnPathDepth('a/b/c/d')).toBe(4);
-    });
-    it('ignores empty segments from stray separators', () => {
-      expect(spawnPathDepth('a//b')).toBe(2);
-      expect(spawnPathDepth('/a/b')).toBe(2);
-    });
-  });
-
-  describe('parentSpawnPath', () => {
-    it('root returns null', () => {
-      expect(parentSpawnPath('')).toBeNull();
-      expect(parentSpawnPath(null)).toBeNull();
-    });
-    it('single segment returns empty (root)', () => {
-      expect(parentSpawnPath('a')).toBe('');
-    });
-    it('multi segment drops last', () => {
-      expect(parentSpawnPath('a/b')).toBe('a');
-      expect(parentSpawnPath('a/b/c')).toBe('a/b');
-    });
-  });
-
-  describe('spawnPathParts', () => {
-    it('empty path returns empty array', () => {
-      expect(spawnPathParts('')).toEqual([]);
-      expect(spawnPathParts(null)).toEqual([]);
-    });
-    it('splits segments', () => {
-      expect(spawnPathParts('a/b/c')).toEqual(['a', 'b', 'c']);
-    });
-  });
-
-  describe('leafSpawnKey', () => {
-    it('root returns null', () => {
-      expect(leafSpawnKey('')).toBeNull();
-    });
-    it('returns last segment', () => {
-      expect(leafSpawnKey('a')).toBe('a');
-      expect(leafSpawnKey('a/b/c')).toBe('c');
-    });
-  });
-
-  describe('isAncestorSpawnPath', () => {
-    it('root is ancestor of any non-root path', () => {
-      expect(isAncestorSpawnPath('', 'a')).toBe(true);
-      expect(isAncestorSpawnPath('', 'a/b')).toBe(true);
-    });
-    it('root is not ancestor of root', () => {
-      expect(isAncestorSpawnPath('', '')).toBe(false);
-    });
-    it('strict ancestor detection', () => {
-      expect(isAncestorSpawnPath('a', 'a/b')).toBe(true);
-      expect(isAncestorSpawnPath('a/b', 'a/b/c')).toBe(true);
-      expect(isAncestorSpawnPath('a', 'a')).toBe(false);
-    });
-    it('sibling is not ancestor', () => {
-      expect(isAncestorSpawnPath('a/b', 'a/c')).toBe(false);
-    });
-    it('partial-prefix is not ancestor (must respect segment boundary)', () => {
-      expect(isAncestorSpawnPath('ab', 'abc')).toBe(false);
-    });
-  });
-});

package/src/common/spawnPath.ts

@@ -1,101 +0,0 @@
-/**
- * spawnPath — hierarchical invocation identity for nested multi-agent orchestration.
- *
- * A spawnPath is a slash-separated chain of spawnKeys from the root of the current
- * agent invocation to the current spawn. The root agent has an empty spawnPath;
- * each handoff/transfer/sequence that spawns a new subgraph appends a new spawnKey.
- *
- * Examples:
- *   ""                               → primary agent (no spawn)
- *   "call_abc"                       → first-level handoff child
- *   "call_abc/call_def"              → grandchild (depth 2)
- *   "call_abc/call_def/call_ghi"     → depth 3
- *
- * These utilities are the single source of truth for path manipulation across:
- *   - @illuma-ai/agents (MultiAgentGraph, HandoffRegistry, callbacks)
- *   - host api (initialize.js, callbacks.js, ExecutionTrace writes)
- *   - host client (subagent store, sidebar rendering)
- *
- * See docs/multi-agent-nesting-architecture.md for the full design.
- */
-
-/** Separator between spawnKeys in a spawnPath. Chosen so that the path looks
- * like a filesystem/URL path, which makes it easy to read in logs and traces. */
-export const SPAWN_PATH_SEP = '/';
-
-/** Hard cap on nested multi-agent invocations. Prevents runaway recursion.
- * Can be overridden at the host api layer via MULTI_AGENT_MAX_NESTING_DEPTH. */
-export const MAX_NESTING_DEPTH = 5;
-
-/**
- * Append a spawnKey to a parent spawnPath.
- *
- * @param parent - Parent spawnPath (may be undefined/null/empty for root)
- * @param key    - spawnKey to append
- * @returns New spawnPath string
- */
-export function buildSpawnPath(
-  parent: string | undefined | null,
-  key: string
-): string {
-  if (!key) {
-    throw new Error('[spawnPath] buildSpawnPath called with empty key');
-  }
-  if (parent == null || parent === '') return key;
-  return `${parent}${SPAWN_PATH_SEP}${key}`;
-}
-
-/**
- * Compute the depth of a spawnPath.
- * Root (empty) → 0; single-segment → 1; etc.
- */
-export function spawnPathDepth(path: string | undefined | null): number {
-  if (path == null || path === '') return 0;
-  return path.split(SPAWN_PATH_SEP).filter(Boolean).length;
-}
-
-/**
- * Return the parent spawnPath, or null if the input is already root.
- *
- * - parentSpawnPath("a/b/c") === "a/b"
- * - parentSpawnPath("a") === ""
- * - parentSpawnPath("") === null
- */
-export function parentSpawnPath(
-  path: string | undefined | null
-): string | null {
-  if (path == null || path === '') return null;
-  const parts = path.split(SPAWN_PATH_SEP).filter(Boolean);
-  if (parts.length <= 1) return '';
-  return parts.slice(0, -1).join(SPAWN_PATH_SEP);
-}
-
-/** Split a spawnPath into its constituent spawnKey segments. */
-export function spawnPathParts(path: string | undefined | null): string[] {
-  if (path == null || path === '') return [];
-  return path.split(SPAWN_PATH_SEP).filter(Boolean);
-}
-
-/**
- * Return the last spawnKey in a spawnPath (the "current" spawn).
- * Returns null for root.
- */
-export function leafSpawnKey(path: string | undefined | null): string | null {
-  const parts = spawnPathParts(path);
-  return parts.length === 0 ? null : parts[parts.length - 1];
-}
-
-/**
- * True if `ancestor` is a strict ancestor of `descendant`. Root ("") is
- * ancestor of everything except itself.
- */
-export function isAncestorSpawnPath(
-  ancestor: string | undefined | null,
-  descendant: string | undefined | null
-): boolean {
-  const a = ancestor ?? '';
-  const d = descendant ?? '';
-  if (a === d) return false;
-  if (a === '') return d !== '';
-  return d.startsWith(a + SPAWN_PATH_SEP);
-}