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

package/dist/cjs/utils/credentials.cjs

@@ -1,142 +0,0 @@
-'use strict';
-
-var types = require('../providers/types.cjs');
-
-/**
- * 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.
- */
-exports.CredentialOrigin = void 0;
-(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";
-})(exports.CredentialOrigin || (exports.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 === types.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 === types.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: exports.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 !== types.AuthSource.SERVER;
-}
-
-exports.collectRequiredAuthFields = collectRequiredAuthFields;
-exports.credentialsFromEnv = credentialsFromEnv;
-exports.filterForwardableCredentials = filterForwardableCredentials;
-exports.findMissingCredentials = findMissingCredentials;
-exports.isForwardable = isForwardable;
-exports.mergeCredentials = mergeCredentials;
-//# sourceMappingURL=credentials.cjs.map

package/dist/cjs/utils/credentials.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"credentials.cjs","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":["CredentialOrigin","AuthSource"],"mappings":"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"}

package/dist/cjs/utils/httpClient.cjs

@@ -1,74 +0,0 @@
-'use strict';
-
-var axios = require('axios');
-var httpsProxyAgent = require('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.HttpsProxyAgent(resolvedProxy);
-        axiosConfig.httpAgent = new httpsProxyAgent.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);
-    }
-}
-
-exports.HttpError = HttpError;
-exports.assertOk = assertOk;
-exports.createHttpClient = createHttpClient;
-//# sourceMappingURL=httpClient.cjs.map

package/dist/cjs/utils/httpClient.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"httpClient.cjs","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":["HttpsProxyAgent"],"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,IAAIA,+BAAe,CAAC,aAAa,CAAC;QAC3D,WAAW,CAAC,SAAS,GAAG,IAAIA,+BAAe,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/cjs/utils/toolManifest.cjs

@@ -1,100 +0,0 @@
-'use strict';
-
-/**
- * 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;
-    });
-}
-
-exports.ManifestCache = ManifestCache;
-exports.applyFilter = applyFilter;
-exports.filterToCacheKey = filterToCacheKey;
-//# sourceMappingURL=toolManifest.cjs.map

package/dist/cjs/utils/toolManifest.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"toolManifest.cjs","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":"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"}

package/dist/esm/common/spawnPath.mjs

@@ -1,95 +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. */
-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. */
-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
- */
-function buildSpawnPath(parent, key) {
-    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.
- */
-function spawnPathDepth(path) {
-    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
- */
-function parentSpawnPath(path) {
-    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. */
-function spawnPathParts(path) {
-    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.
- */
-function leafSpawnKey(path) {
-    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.
- */
-function isAncestorSpawnPath(ancestor, descendant) {
-    const a = ancestor ?? '';
-    const d = descendant ?? '';
-    if (a === d)
-        return false;
-    if (a === '')
-        return d !== '';
-    return d.startsWith(a + SPAWN_PATH_SEP);
-}
-
-export { MAX_NESTING_DEPTH, SPAWN_PATH_SEP, buildSpawnPath, isAncestorSpawnPath, leafSpawnKey, parentSpawnPath, spawnPathDepth, spawnPathParts };
-//# sourceMappingURL=spawnPath.mjs.map

package/dist/esm/common/spawnPath.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawnPath.mjs","sources":["../../../src/common/spawnPath.ts"],"sourcesContent":["/**\n * spawnPath — hierarchical invocation identity for nested multi-agent orchestration.\n *\n * A spawnPath is a slash-separated chain of spawnKeys from the root of the current\n * agent invocation to the current spawn. The root agent has an empty spawnPath;\n * each handoff/transfer/sequence that spawns a new subgraph appends a new spawnKey.\n *\n * Examples:\n *   \"\"                               → primary agent (no spawn)\n *   \"call_abc\"                       → first-level handoff child\n *   \"call_abc/call_def\"              → grandchild (depth 2)\n *   \"call_abc/call_def/call_ghi\"     → depth 3\n *\n * These utilities are the single source of truth for path manipulation across:\n *   - @illuma-ai/agents (MultiAgentGraph, HandoffRegistry, callbacks)\n *   - host api (initialize.js, callbacks.js, ExecutionTrace writes)\n *   - host client (subagent store, sidebar rendering)\n *\n * See docs/multi-agent-nesting-architecture.md for the full design.\n */\n\n/** Separator between spawnKeys in a spawnPath. Chosen so that the path looks\n * like a filesystem/URL path, which makes it easy to read in logs and traces. */\nexport const SPAWN_PATH_SEP = '/';\n\n/** Hard cap on nested multi-agent invocations. Prevents runaway recursion.\n * Can be overridden at the host api layer via MULTI_AGENT_MAX_NESTING_DEPTH. */\nexport const MAX_NESTING_DEPTH = 5;\n\n/**\n * Append a spawnKey to a parent spawnPath.\n *\n * @param parent - Parent spawnPath (may be undefined/null/empty for root)\n * @param key    - spawnKey to append\n * @returns New spawnPath string\n */\nexport function buildSpawnPath(\n  parent: string | undefined | null,\n  key: string\n): string {\n  if (!key) {\n    throw new Error('[spawnPath] buildSpawnPath called with empty key');\n  }\n  if (parent == null || parent === '') return key;\n  return `${parent}${SPAWN_PATH_SEP}${key}`;\n}\n\n/**\n * Compute the depth of a spawnPath.\n * Root (empty) → 0; single-segment → 1; etc.\n */\nexport function spawnPathDepth(path: string | undefined | null): number {\n  if (path == null || path === '') return 0;\n  return path.split(SPAWN_PATH_SEP).filter(Boolean).length;\n}\n\n/**\n * Return the parent spawnPath, or null if the input is already root.\n *\n * - parentSpawnPath(\"a/b/c\") === \"a/b\"\n * - parentSpawnPath(\"a\") === \"\"\n * - parentSpawnPath(\"\") === null\n */\nexport function parentSpawnPath(\n  path: string | undefined | null\n): string | null {\n  if (path == null || path === '') return null;\n  const parts = path.split(SPAWN_PATH_SEP).filter(Boolean);\n  if (parts.length <= 1) return '';\n  return parts.slice(0, -1).join(SPAWN_PATH_SEP);\n}\n\n/** Split a spawnPath into its constituent spawnKey segments. */\nexport function spawnPathParts(path: string | undefined | null): string[] {\n  if (path == null || path === '') return [];\n  return path.split(SPAWN_PATH_SEP).filter(Boolean);\n}\n\n/**\n * Return the last spawnKey in a spawnPath (the \"current\" spawn).\n * Returns null for root.\n */\nexport function leafSpawnKey(path: string | undefined | null): string | null {\n  const parts = spawnPathParts(path);\n  return parts.length === 0 ? null : parts[parts.length - 1];\n}\n\n/**\n * True if `ancestor` is a strict ancestor of `descendant`. Root (\"\") is\n * ancestor of everything except itself.\n */\nexport function isAncestorSpawnPath(\n  ancestor: string | undefined | null,\n  descendant: string | undefined | null\n): boolean {\n  const a = ancestor ?? '';\n  const d = descendant ?? '';\n  if (a === d) return false;\n  if (a === '') return d !== '';\n  return d.startsWith(a + SPAWN_PATH_SEP);\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;AAmBG;AAEH;AACiF;AAC1E,MAAM,cAAc,GAAG;AAE9B;AACgF;AACzE,MAAM,iBAAiB,GAAG;AAEjC;;;;;;AAMG;AACG,SAAU,cAAc,CAC5B,MAAiC,EACjC,GAAW,EAAA;IAEX,IAAI,CAAC,GAAG,EAAE;AACR,QAAA,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC;IACrE;AACA,IAAA,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE;AAAE,QAAA,OAAO,GAAG;AAC/C,IAAA,OAAO,GAAG,MAAM,CAAA,EAAG,cAAc,CAAA,EAAG,GAAG,EAAE;AAC3C;AAEA;;;AAGG;AACG,SAAU,cAAc,CAAC,IAA+B,EAAA;AAC5D,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,CAAC;AACzC,IAAA,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM;AAC1D;AAEA;;;;;;AAMG;AACG,SAAU,eAAe,CAC7B,IAA+B,EAAA;AAE/B,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,IAAI;AAC5C,IAAA,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;AACxD,IAAA,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC;AAAE,QAAA,OAAO,EAAE;AAChC,IAAA,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC;AAChD;AAEA;AACM,SAAU,cAAc,CAAC,IAA+B,EAAA;AAC5D,IAAA,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,KAAK,EAAE;AAAE,QAAA,OAAO,EAAE;IAC1C,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;AACnD;AAEA;;;AAGG;AACG,SAAU,YAAY,CAAC,IAA+B,EAAA;AAC1D,IAAA,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC;IAClC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;AAC5D;AAEA;;;AAGG;AACG,SAAU,mBAAmB,CACjC,QAAmC,EACnC,UAAqC,EAAA;AAErC,IAAA,MAAM,CAAC,GAAG,QAAQ,IAAI,EAAE;AACxB,IAAA,MAAM,CAAC,GAAG,UAAU,IAAI,EAAE;IAC1B,IAAI,CAAC,KAAK,CAAC;AAAE,QAAA,OAAO,KAAK;IACzB,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,KAAK,EAAE;IAC7B,OAAO,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,cAAc,CAAC;AACzC;;;;"}

package/dist/esm/graphs/HandoffRegistry.mjs

@@ -1,141 +0,0 @@
-/**
- * Registry for async handoff execution.
- *
- * Enables the autonomous orchestration pattern:
- * 1. Orchestrator spawns children (non-blocking)
- * 2. Orchestrator stays alive to reason, spawn more, or check status
- * 3. Orchestrator collects results when ready
- *
- * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.
- */
-class HandoffRegistry {
-    records = new Map();
-    /** Monotonically increasing counter for unique spawn IDs */
-    spawnCounter = 0;
-    /**
-     * Register a spawned handoff child.
-     * The promise runs in the background — not awaited here.
-     * Uses a unique key per spawn so the same agent can be spawned multiple times
-     * across rounds without overwriting prior records.
-     */
-    spawn(params) {
-        // Unique internal key: agentId + counter to support multiple spawns of same agent.
-        // record.id stays as the agent identity so callers/observability can attribute
-        // results to the agent regardless of which spawn round they came from.
-        const spawnKey = `${params.id}__${this.spawnCounter++}`;
-        const record = {
-            id: params.id,
-            spawnKey,
-            name: params.name,
-            task: params.task,
-            spawnedAt: Date.now(),
-            status: 'running',
-            promise: params.promise,
-        };
-        // Wire up the promise to update the record on completion
-        params.promise
-            .then((result) => {
-            const resultText = params.extractResult(result.messages, params.id);
-            const truncated = params.truncateResult(resultText, params.maxResultChars);
-            record.status = 'completed';
-            record.resultText = truncated;
-            record.durationMs = Date.now() - record.spawnedAt;
-            record.resultMessageCount = result.messages.length;
-            params.onComplete?.(record);
-        })
-            .catch((err) => {
-            record.status = 'failed';
-            record.error = err instanceof Error ? err.message : String(err);
-            record.durationMs = Date.now() - record.spawnedAt;
-            params.onComplete?.(record);
-        });
-        this.records.set(spawnKey, record);
-    }
-    /** List all pending (running) handoffs */
-    listPending() {
-        return Array.from(this.records.values()).filter((r) => r.status === 'running');
-    }
-    /** List all completed handoffs (not yet collected) */
-    listCompleted() {
-        return Array.from(this.records.values()).filter((r) => r.status === 'completed' || r.status === 'failed');
-    }
-    /** List all handoffs regardless of status */
-    listAll() {
-        return Array.from(this.records.values());
-    }
-    /**
-     * Get a handoff record by either its unique spawnKey or by agentId.
-     * - Exact spawnKey match wins (O(1)).
-     * - Falls back to the most recently spawned record for that agentId — matching
-     *   lookups by callers that only know the agent identity, not the spawn round.
-     */
-    get(idOrSpawnKey) {
-        const direct = this.records.get(idOrSpawnKey);
-        if (direct)
-            return direct;
-        let latest;
-        for (const record of this.records.values()) {
-            if (record.id !== idOrSpawnKey)
-                continue;
-            if (!latest || record.spawnedAt >= latest.spawnedAt)
-                latest = record;
-        }
-        return latest;
-    }
-    /** Check if any handoffs are still running */
-    hasPending() {
-        return this.listPending().length > 0;
-    }
-    /**
-     * Wait for ALL pending handoffs to complete and return all records.
-     * Records are NOT auto-cleared — caller removes collected records via remove().
-     */
-    async waitForAll() {
-        const pending = this.listPending();
-        if (pending.length > 0) {
-            await Promise.allSettled(pending.map((r) => r.promise));
-        }
-        const results = this.listAll();
-        return results;
-    }
-    /**
-     * Wait for ANY pending handoff to complete.
-     * Returns the newly completed record(s).
-     */
-    async waitForAny() {
-        const pending = this.listPending();
-        if (pending.length === 0) {
-            return this.listCompleted();
-        }
-        // Race all pending promises — at least one will resolve
-        await Promise.race(pending.map((r) => r.promise.then(() => r).catch(() => r)));
-        // Small yield to let promise handlers update records
-        await new Promise((resolve) => setTimeout(resolve, 0));
-        return this.listCompleted();
-    }
-    /**
-     * Remove record(s) by spawnKey or agentId.
-     * - Exact spawnKey match removes only that record.
-     * - agentId match removes ALL records for that agent (covers callers that
-     *   want to forget everything tied to a given agent).
-     */
-    remove(idOrSpawnKey) {
-        if (this.records.delete(idOrSpawnKey))
-            return;
-        for (const [key, record] of this.records) {
-            if (record.id === idOrSpawnKey)
-                this.records.delete(key);
-        }
-    }
-    /** Clear all records (for cleanup between graph invocations) */
-    clear() {
-        this.records.clear();
-    }
-    /** Number of total tracked handoffs */
-    get size() {
-        return this.records.size;
-    }
-}
-
-export { HandoffRegistry };
-//# sourceMappingURL=HandoffRegistry.mjs.map

package/dist/esm/graphs/HandoffRegistry.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"HandoffRegistry.mjs","sources":["../../../src/graphs/HandoffRegistry.ts"],"sourcesContent":["import type { BaseMessage } from '@langchain/core/messages';\nimport type * as t from '@/types';\n\n/**\n * Tracks the lifecycle of a spawned handoff child agent.\n */\nexport type HandoffRecord = {\n  /** Agent identity (destination agentId) — stable across multiple spawns of the same agent */\n  id: string;\n  /** Unique internal key for this specific spawn (agentId + monotonic counter) */\n  spawnKey: string;\n  /** Display name of the child agent */\n  name: string;\n  /** Task description / instructions passed to child */\n  task: string;\n  /** When the handoff was spawned */\n  spawnedAt: number;\n  /** Current status */\n  status: 'pending' | 'running' | 'completed' | 'failed';\n  /** The background promise executing the child subgraph */\n  promise: Promise<t.BaseGraphState>;\n  /** Resolved result text (populated on completion) */\n  resultText?: string;\n  /** Error message (populated on failure) */\n  error?: string;\n  /** Duration in ms (populated on completion/failure) */\n  durationMs?: number;\n  /** Number of messages in child's output */\n  resultMessageCount?: number;\n};\n\n/**\n * Registry for async handoff execution.\n *\n * Enables the autonomous orchestration pattern:\n * 1. Orchestrator spawns children (non-blocking)\n * 2. Orchestrator stays alive to reason, spawn more, or check status\n * 3. Orchestrator collects results when ready\n *\n * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.\n */\nexport class HandoffRegistry {\n  private records: Map<string, HandoffRecord> = new Map();\n  /** Monotonically increasing counter for unique spawn IDs */\n  private spawnCounter = 0;\n\n  /**\n   * Register a spawned handoff child.\n   * The promise runs in the background — not awaited here.\n   * Uses a unique key per spawn so the same agent can be spawned multiple times\n   * across rounds without overwriting prior records.\n   */\n  spawn(params: {\n    id: string;\n    name: string;\n    task: string;\n    promise: Promise<t.BaseGraphState>;\n    extractResult: (messages: BaseMessage[], agentId: string) => string;\n    truncateResult: (text: string, maxChars: number) => string;\n    maxResultChars: number;\n    /** Callback when child completes (for SSE events) */\n    onComplete?: (record: HandoffRecord) => void;\n  }): void {\n    // Unique internal key: agentId + counter to support multiple spawns of same agent.\n    // record.id stays as the agent identity so callers/observability can attribute\n    // results to the agent regardless of which spawn round they came from.\n    const spawnKey = `${params.id}__${this.spawnCounter++}`;\n    const record: HandoffRecord = {\n      id: params.id,\n      spawnKey,\n      name: params.name,\n      task: params.task,\n      spawnedAt: Date.now(),\n      status: 'running',\n      promise: params.promise,\n    };\n\n    // Wire up the promise to update the record on completion\n    params.promise\n      .then((result) => {\n        const resultText = params.extractResult(result.messages, params.id);\n        const truncated = params.truncateResult(\n          resultText,\n          params.maxResultChars\n        );\n        record.status = 'completed';\n        record.resultText = truncated;\n        record.durationMs = Date.now() - record.spawnedAt;\n        record.resultMessageCount = result.messages.length;\n        params.onComplete?.(record);\n      })\n      .catch((err) => {\n        record.status = 'failed';\n        record.error = err instanceof Error ? err.message : String(err);\n        record.durationMs = Date.now() - record.spawnedAt;\n        params.onComplete?.(record);\n      });\n\n    this.records.set(spawnKey, record);\n  }\n\n  /** List all pending (running) handoffs */\n  listPending(): HandoffRecord[] {\n    return Array.from(this.records.values()).filter(\n      (r) => r.status === 'running'\n    );\n  }\n\n  /** List all completed handoffs (not yet collected) */\n  listCompleted(): HandoffRecord[] {\n    return Array.from(this.records.values()).filter(\n      (r) => r.status === 'completed' || r.status === 'failed'\n    );\n  }\n\n  /** List all handoffs regardless of status */\n  listAll(): HandoffRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  /**\n   * Get a handoff record by either its unique spawnKey or by agentId.\n   * - Exact spawnKey match wins (O(1)).\n   * - Falls back to the most recently spawned record for that agentId — matching\n   *   lookups by callers that only know the agent identity, not the spawn round.\n   */\n  get(idOrSpawnKey: string): HandoffRecord | undefined {\n    const direct = this.records.get(idOrSpawnKey);\n    if (direct) return direct;\n    let latest: HandoffRecord | undefined;\n    for (const record of this.records.values()) {\n      if (record.id !== idOrSpawnKey) continue;\n      if (!latest || record.spawnedAt >= latest.spawnedAt) latest = record;\n    }\n    return latest;\n  }\n\n  /** Check if any handoffs are still running */\n  hasPending(): boolean {\n    return this.listPending().length > 0;\n  }\n\n  /**\n   * Wait for ALL pending handoffs to complete and return all records.\n   * Records are NOT auto-cleared — caller removes collected records via remove().\n   */\n  async waitForAll(): Promise<HandoffRecord[]> {\n    const pending = this.listPending();\n    if (pending.length > 0) {\n      await Promise.allSettled(pending.map((r) => r.promise));\n    }\n    const results = this.listAll();\n    return results;\n  }\n\n  /**\n   * Wait for ANY pending handoff to complete.\n   * Returns the newly completed record(s).\n   */\n  async waitForAny(): Promise<HandoffRecord[]> {\n    const pending = this.listPending();\n    if (pending.length === 0) {\n      return this.listCompleted();\n    }\n\n    // Race all pending promises — at least one will resolve\n    await Promise.race(\n      pending.map((r) => r.promise.then(() => r).catch(() => r))\n    );\n\n    // Small yield to let promise handlers update records\n    await new Promise((resolve) => setTimeout(resolve, 0));\n\n    return this.listCompleted();\n  }\n\n  /**\n   * Remove record(s) by spawnKey or agentId.\n   * - Exact spawnKey match removes only that record.\n   * - agentId match removes ALL records for that agent (covers callers that\n   *   want to forget everything tied to a given agent).\n   */\n  remove(idOrSpawnKey: string): void {\n    if (this.records.delete(idOrSpawnKey)) return;\n    for (const [key, record] of this.records) {\n      if (record.id === idOrSpawnKey) this.records.delete(key);\n    }\n  }\n\n  /** Clear all records (for cleanup between graph invocations) */\n  clear(): void {\n    this.records.clear();\n  }\n\n  /** Number of total tracked handoffs */\n  get size(): number {\n    return this.records.size;\n  }\n}\n"],"names":[],"mappings":"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"}