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

package/dist/esm/utils/credentials.mjs

@@ -1,135 +0,0 @@
-import { AuthSource } from '../providers/types.mjs';
-
-/**
- * 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.
- */
-var CredentialOrigin;
-(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";
-})(CredentialOrigin || (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 === 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 === 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: 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 !== AuthSource.SERVER;
-}
-
-export { CredentialOrigin, collectRequiredAuthFields, credentialsFromEnv, filterForwardableCredentials, findMissingCredentials, isForwardable, mergeCredentials };
-//# sourceMappingURL=credentials.mjs.map

package/dist/esm/utils/credentials.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"credentials.mjs","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":[],"mappings":";;AAAA;;;;;;;;;;AAUG;AASH;;;AAGG;IACS;AAAZ,CAAA,UAAY,gBAAgB,EAAA;;AAE1B,IAAA,gBAAA,CAAA,KAAA,CAAA,GAAA,KAAW;;AAEX,IAAA,gBAAA,CAAA,OAAA,CAAA,GAAA,OAAe;;AAEf,IAAA,gBAAA,CAAA,MAAA,CAAA,GAAA,MAAa;;AAEb,IAAA,gBAAA,CAAA,SAAA,CAAA,GAAA,SAAmB;;AAEnB,IAAA,gBAAA,CAAA,SAAA,CAAA,GAAA,SAAmB;AACrB,CAAC,EAXW,gBAAgB,KAAhB,gBAAgB,GAAA,EAAA,CAAA,CAAA;AAmB5B;;;;;;;;;;;AAWG;AACG,SAAU,gBAAgB,CAAC,GAAG,MAAyB,EAAA;IAC3D,MAAM,MAAM,GAAkB,EAAE;;AAEhC,IAAA,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE;AAC3C,QAAA,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC;AACvB,QAAA,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE;AACvD,YAAA,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE;AACzD,gBAAA,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK;YACrB;QACF;IACF;AACA,IAAA,OAAO,MAAM;AACf;AAEA;;;;AAIG;AACG,SAAU,yBAAyB,CACvC,YAA0B,EAAA;AAE1B,IAAA,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU;AAChC,IAAA,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE;AAC9B,QAAA,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,UAAU,EAAE;AAClC,YAAA,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;QAC7B;IACF;AACA,IAAA,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;AAC3B;AAEA;;;;;;AAMG;AACG,SAAU,4BAA4B,CAC1C,WAA0B,EAC1B,YAA0B,EAAA;AAE1B,IAAA,MAAM,mBAAmB,GAAG,IAAI,GAAG,EAAU;AAC7C,IAAA,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE;AAC9B,QAAA,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,UAAU,EAAE;YAClC,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM,EAAE;AACtC,gBAAA,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC;YAC1C;QACF;IACF;IACA,MAAM,WAAW,GAAkB,EAAE;AACrC,IAAA,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE;QACtD,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;AACjC,YAAA,WAAW,CAAC,GAAG,CAAC,GAAG,KAAK;QAC1B;IACF;AACA,IAAA,OAAO,WAAW;AACpB;AAEA;;;;;AAKG;AACG,SAAU,sBAAsB,CACpC,UAAsB,EACtB,WAA0B,EAAA;IAE1B,MAAM,OAAO,GAAa,EAAE;AAC5B,IAAA,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,UAAU,EAAE;AACzC,QAAA,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM;YAAE;QACxC,IAAI,CAAC,KAAK,CAAC,QAAQ;YAAE;QACrB,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE;AACjC,YAAA,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;QAC/B;IACF;AACA,IAAA,OAAO,OAAO;AAChB;AAEA;;;AAGG;AACG,SAAU,kBAAkB,CAChC,UAA6B,EAC7B,GAAA,GAAyB,OAAO,CAAC,GAAG,EAAA;IAEpC,MAAM,MAAM,GAAkB,EAAE;AAChC,IAAA,KAAK,MAAM,KAAK,IAAI,UAAU,EAAE;AAC9B,QAAA,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;AACxB,QAAA,IAAI,KAAK;AAAE,YAAA,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK;IAClC;IACA,OAAO,EAAE,MAAM,EAAE,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE;AACjD;AAEA;;;AAGG;AACG,SAAU,aAAa,CAAC,KAAsB,EAAA;AAClD,IAAA,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,CAAC,MAAM;AAC3C;;;;"}

package/dist/esm/utils/httpClient.mjs

@@ -1,70 +0,0 @@
-import axios from 'axios';
-import { HttpsProxyAgent } from '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(resolvedProxy);
-        axiosConfig.httpAgent = new 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);
-    }
-}
-
-export { HttpError, assertOk, createHttpClient };
-//# sourceMappingURL=httpClient.mjs.map

package/dist/esm/utils/httpClient.mjs.map

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

@@ -1,96 +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.
- */
-/**
- * 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;
-    });
-}
-
-export { ManifestCache, applyFilter, filterToCacheKey };
-//# sourceMappingURL=toolManifest.mjs.map

package/dist/esm/utils/toolManifest.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"toolManifest.mjs","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":"AAAA;;;;;;;;;AASG;AAeH;;;;;;;AAOG;MACU,aAAa,CAAA;AACP,IAAA,KAAK;AACL,IAAA,KAAK,GAAG,IAAI,GAAG,EAAsB;AAEtD,IAAA,WAAA,CAAY,SAA8B,EAAE,EAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM;IACrC;;AAGA,IAAA,GAAG,CAAC,GAAW,EAAA;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;AACjC,QAAA,IAAI,CAAC,KAAK;AAAE,YAAA,OAAO,SAAS;QAC5B,IAAI,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE;AAChC,YAAA,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC;AACtB,YAAA,OAAO,SAAS;QAClB;QACA,OAAO,KAAK,CAAC,YAAY;IAC3B;;IAGA,GAAG,CAAC,GAAW,EAAE,YAA0B,EAAA;AACzC,QAAA,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC;YAAE;AACrB,QAAA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK;YAClC,YAAY;AACb,SAAA,CAAC;IACJ;;IAGA,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE;IACpB;;AAGA,IAAA,IAAI,IAAI,GAAA;AACN,QAAA,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI;IACxB;AACD;AAED;;;;;;AAMG;AACG,SAAU,gBAAgB,CAAC,MAAyB,EAAA;AACxD,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,SAAS;IAC7B,MAAM,KAAK,GAAa,EAAE;IAC1B,IAAI,MAAM,CAAC,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,CAAA,KAAA,EAAQ,MAAM,CAAC,IAAI,CAAA,CAAE,CAAC;AAClD,IAAA,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM;QACrB,KAAK,CAAC,IAAI,CAAC,CAAA,KAAA,EAAQ,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA,CAAE,CAAC;AACzD,IAAA,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM;QACtB,KAAK,CAAC,IAAI,CAAC,CAAA,MAAA,EAAS,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA,CAAE,CAAC;AAC3D,IAAA,OAAO,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS;AACnD;AAEA;;;AAGG;AACG,SAAU,WAAW,CACzB,YAA0B,EAC1B,MAAyB,EAAA;AAEzB,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,YAAY;AAChC,IAAA,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,GAAG,KAAI;QACjC,IAAI,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;AAAE,YAAA,OAAO,KAAK;AACzD,QAAA,IAAI,MAAM,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;AAAE,YAAA,OAAO,KAAK;AAClE,QAAA,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE;AACvB,YAAA,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;YAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACxD,YAAA,IAAI,CAAC,QAAQ;AAAE,gBAAA,OAAO,KAAK;QAC7B;AACA,QAAA,OAAO,IAAI;AACb,IAAA,CAAC,CAAC;AACJ;;;;"}

package/dist/types/common/spawnPath.d.ts

@@ -1,59 +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 declare 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 declare 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 declare function buildSpawnPath(parent: string | undefined | null, key: string): string;
-/**
- * Compute the depth of a spawnPath.
- * Root (empty) → 0; single-segment → 1; etc.
- */
-export declare function spawnPathDepth(path: string | undefined | null): number;
-/**
- * Return the parent spawnPath, or null if the input is already root.
- *
- * - parentSpawnPath("a/b/c") === "a/b"
- * - parentSpawnPath("a") === ""
- * - parentSpawnPath("") === null
- */
-export declare function parentSpawnPath(path: string | undefined | null): string | null;
-/** Split a spawnPath into its constituent spawnKey segments. */
-export declare function spawnPathParts(path: string | undefined | null): string[];
-/**
- * Return the last spawnKey in a spawnPath (the "current" spawn).
- * Returns null for root.
- */
-export declare function leafSpawnKey(path: string | undefined | null): string | null;
-/**
- * True if `ancestor` is a strict ancestor of `descendant`. Root ("") is
- * ancestor of everything except itself.
- */
-export declare function isAncestorSpawnPath(ancestor: string | undefined | null, descendant: string | undefined | null): boolean;

package/dist/types/content/ArtifactStore.d.ts

@@ -1,223 +0,0 @@
-import type Keyv from 'keyv';
-import { ContentStore } from './ContentStore';
-import type { StoreEntry, StoredEntry, ContentMetadata, EditResult, ReadResult, ReadAllResult, SearchMatch } from './types';
-/**
- * Minimal logger surface. Callers inject any winston/pino/console-like
- * logger that honors the four level methods; defaults to a no-op so the
- * library runs without a configured logger.
- */
-export interface Logger {
-    debug(...args: unknown[]): void;
-    info(...args: unknown[]): void;
-    warn(...args: unknown[]): void;
-    error(...args: unknown[]): void;
-}
-/**
- * Callback interface for S3 operations.
- * Injected at construction so ArtifactStore stays host-agnostic — the
- * consumer wires this to its own S3 strategy / presigner.
- */
-export interface S3Strategy {
-    /** Upload a buffer to S3, return the stored filepath (signed URL or key). */
-    saveBuffer(params: {
-        userId: string;
-        buffer: Buffer;
-        fileName: string;
-        basePath: string;
-    }): Promise<string>;
-    /** Download file content from S3 as a readable stream. */
-    getFileStream(filePath: string): Promise<NodeJS.ReadableStream>;
-    /** Delete a file from S3. Requires userId for ownership validation. */
-    deleteFile(userId: string, filePath: string): Promise<void>;
-}
-/**
- * Callback interface for MongoDB File model operations.
- * Injected to keep ArtifactStore decoupled from Mongoose models.
- */
-export interface FileModel {
-    /** Create or upsert a File document. */
-    createFile(data: Record<string, unknown>, disableTTL: boolean): Promise<Record<string, unknown>>;
-    /** Find a single File by filter. */
-    findFile(filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-    /** Find multiple Files by filter. */
-    findFiles(filter: Record<string, unknown>): Promise<Record<string, unknown>[]>;
-    /** Update a File document (must include file_id). */
-    updateFile(data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
-    /** Delete a File by file_id. */
-    deleteFile(fileId: string): Promise<Record<string, unknown> | null>;
-    /**
-     * Get the file_ids linked to a conversation via the Conversation.files array.
-     * Returns an empty array if the conversation is not found or has no files.
-     * This is the primary source of truth for "which files belong to this conversation".
-     */
-    getConversationFileIds(conversationId: string): Promise<string[]>;
-    /**
-     * Link file_ids to a conversation via $addToSet on Conversation.files.
-     * Idempotent — calling with already-linked file_ids is a no-op.
-     * Used after creating a File record to ensure it appears in "Files in Context".
-     */
-    addFilesToConversation(conversationId: string, fileIds: string[]): Promise<void>;
-}
-/**
- * Sanitize a filename for safe S3 key usage.
- * Replaces non-alphanumeric characters (except . _ - /) with underscores.
- */
-export declare function sanitizeName(name: string): string;
-/**
- * File-backed artifact store extending ContentStore with S3 persistence.
- *
- * Every write immediately persists to Redis (fast cache) AND S3 (permanent store).
- * S3 writes are fire-and-forget async — the agent gets an instant response from Redis.
- * On Redis cache miss, content is transparently restored from S3 via MongoDB lookup.
- *
- * Key structure (consistent across all layers):
- * - Redis:   `CONTENT_STORE::{conversationId}::{contentId}`
- * - S3:      `artifacts/{conversationId}/{userId}/{contentId}__{name}`
- * - MongoDB: `file_id: "artifact-{contentId}"`, `metadata.contentId: "{contentId}"`
- *
- * @example
- * ```ts
- * import Keyv from 'keyv';
- * import { ArtifactStore, CONTENT_TTL_MS } from '@illuma-ai/agents/content';
- *
- * const cache = new Keyv({ namespace: `content-store::${conversationId}`, ttl: CONTENT_TTL_MS });
- * const store = new ArtifactStore(cache, conversationId, userId, s3Strategy, fileModel, logger);
- * const id = await store.store({ name: 'App.tsx', type: 'text/x-typescript', content: code, source: 'agent' });
- * // Content is in the cache immediately; S3 + the injected FileModel persist in background.
- * const result = await store.readLines(id, 1, 50);
- * ```
- */
-export declare class ArtifactStore extends ContentStore {
-    protected conversationId: string;
-    protected userId: string;
-    protected s3: S3Strategy;
-    protected fileModel: FileModel;
-    protected logger: Logger;
-    constructor(cache: Keyv, conversationId: string, userId: string, s3: S3Strategy, fileModel: FileModel, logger?: Logger);
-    /** File ID prefix for MongoDB file_id. Override in subclasses. */
-    protected getFileIdPrefix(): string;
-    /** Context label stored on MongoDB File records. Override in subclasses. */
-    protected getContextLabel(): string;
-    /** S3 base path prefix. Override in subclasses. */
-    protected getS3BasePath(): string;
-    /** Build S3 file name. Override in subclasses. */
-    protected getS3FileName(contentId: string, name: string): string;
-    /** Build the canonical file_id for a content entry. */
-    protected buildFileId(contentId: string): string;
-    /**
-     * Store new content in Redis and persist to S3 + MongoDB in background.
-     * Returns immediately after Redis write — agent doesn't wait for S3.
-     *
-     * @param entry - The content to store.
-     * @returns The generated content ID.
-     */
-    store(entry: StoreEntry): Promise<string>;
-    /**
-     * Overwrite content for an existing entry. Updates Redis + syncs to S3.
-     *
-     * @param contentId - The content entry ID.
-     * @param content - New content to write.
-     * @throws If content ID is not found in Redis or S3.
-     */
-    write(contentId: string, content: string): Promise<void>;
-    /**
-     * Surgical string replacement. Updates Redis + syncs to S3.
-     *
-     * @param contentId - The content entry ID.
-     * @param oldStr - Exact string to find.
-     * @param newStr - Replacement string.
-     * @returns Edit result with diff and affected line info.
-     */
-    strReplace(contentId: string, oldStr: string, newStr: string): Promise<EditResult>;
-    /**
-     * Read lines with S3 fallback. If Redis has expired, loads from S3 first.
-     *
-     * @param contentId - The content entry ID.
-     * @param startLine - First line to read (1-based).
-     * @param endLine - Last line to read (inclusive).
-     * @returns Read result or null if not found in any layer.
-     */
-    readLines(contentId: string, startLine?: number, endLine?: number): Promise<ReadResult | null>;
-    /**
-     * Read full content with S3 fallback. If Redis has expired, loads from S3 first.
-     * No line cap — returns raw content for frontend display (e.g., CodeViz).
-     *
-     * @param contentId - The content entry ID.
-     * @returns Raw content with total line/char counts, or null if not found in any layer.
-     */
-    readAll(contentId: string): Promise<ReadAllResult | null>;
-    /**
-     * Search with S3 fallback. If Redis has expired, loads from S3 first.
-     *
-     * @param contentId - The content entry ID.
-     * @param pattern - Text or regex pattern to match.
-     * @param maxResults - Maximum matches to return.
-     * @returns Array of matches or null if not found.
-     */
-    search(contentId: string, pattern: string, maxResults?: number): Promise<SearchMatch[] | null>;
-    /**
-     * Get metadata with S3 fallback.
-     *
-     * @param contentId - The content entry ID.
-     * @returns Metadata or null if not found in any layer.
-     */
-    info(contentId: string): Promise<ContentMetadata | null>;
-    /**
-     * Delete an artifact from all layers: Redis + S3 + MongoDB.
-     *
-     * @param contentId - The content entry ID.
-     */
-    deleteFile(contentId: string): Promise<void>;
-    /**
-     * List all files in this conversation. Merges Redis index with MongoDB File
-     * records found via `Conversation.files` (the single source of truth).
-     *
-     * Query flow:
-     * 1. Redis index — fast cache of recently-accessed content entries (in-memory, no DB hit)
-     * 2. Conversation.files — canonical file_id list via `getConversationFileIds()`
-     *    SCALE: Single indexed `findOne` on `{ conversationId }` — O(1)
-     * 3. Backward compat fallback — `File.find({ conversationId, user })` for pre-migration
-     *    data not yet in `Conversation.files`. Uses index `{ user, conversationId, updatedAt }`.
-     *    Can be removed once all File records are migrated.
-     * 4. Batch fetch — `File.find({ file_id: { $in: mergedIds }, user })` to hydrate full
-     *    File documents. Uses index `{ file_id, user }`.
-     *
-     * Deduplication: Redis entries win — if a contentId is already in Redis, the MongoDB
-     * record is skipped. Non-artifact files are keyed by `file:{file_id}` to avoid dupes.
-     *
-     * @returns Array of metadata for all files in this conversation.
-     */
-    listFiles(): Promise<ContentMetadata[]>;
-    /**
-     * Persist a new content entry to S3 and create a MongoDB File record.
-     * Called in background after Redis store — agent doesn't wait for this.
-     *
-     * @param contentId - The content entry ID.
-     * @param entry - The original store entry with content and metadata.
-     */
-    protected persistToS3(contentId: string, entry: StoreEntry): Promise<void>;
-    /**
-     * Sync updated Redis content to S3 (overwrite same key).
-     * Called in background after write/edit operations.
-     *
-     * @param contentId - The content entry ID to sync.
-     */
-    protected syncToS3(contentId: string): Promise<void>;
-    /**
-     * Restore content from S3 into Redis on cache miss.
-     * Looks up the MongoDB File record to find the S3 path, downloads content,
-     * and re-populates the Redis cache with the same key structure.
-     *
-     * @param contentId - The content entry ID to restore.
-     * @returns The restored StoredEntry, or null if not found in S3/MongoDB.
-     */
-    protected restoreFromS3(contentId: string): Promise<StoredEntry | null>;
-    /**
-     * Ensure content is loaded into Redis. If not in Redis, attempt S3 restore.
-     * Used before write/edit operations that need content to be present.
-     *
-     * @param contentId - The content entry ID.
-     * @throws If content is not found in Redis or S3.
-     */
-    protected ensureLoaded(contentId: string): Promise<void>;
-}