@jini-ai/agent-runtime 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.4.8 — 2026-10-13
+
+- The root import no longer needs the optional `@jini-ai/integrations` peer: the media-provider catalog loads lazily, only when a default provider URL is needed. A missing peer at that point throws an actionable error with the import failure as its `cause`; explicit `*_BASE_URL` env values never touch it.
+- New `createElevenLabsVoiceClient({ http, clock }, { maxCacheEntries })`: voices listed through an injected `HttpClientPort`, expired entries swept, oldest evicted past the bound, `clearCache()`. `listElevenLabsVoiceOptions` stays as the compatibility wrapper over native fetch.
+
 ## 0.4.7 — 2026-10-13
 
 - New `createNativeAgentRuntime({ env }, { state, acpModelProbe, codexDisablePlugins, piGracefulShutdownMs })`: one host-owned runtime state with detection, launch and definitions bound to it, environment policies resolved once, and `dispose({})` that drains in-flight discovery before clearing caches.

package/dist/model-discovery-adapters.js

@@ -1,5 +1,4 @@
 import { defaultRuntimeState } from './runtime-state.js';
-import { VENDOR_API_BASE_URLS } from '@jini-ai/integrations/media-providers/catalog';
 import { execFile } from 'node:child_process';
 import { readFile, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
@@ -303,6 +302,21 @@ function runProcess(input) {
             child.stdin?.end(input.stdin);
         }) }, { signal: input.signal });
 }
+/** Load the catalog owner only for a default URL, so importing the runtime never needs this peer.
+ * @param required - The vendor whose default endpoint is needed.
+ * @returns The catalog-owned base URL; explicit host URLs bypass this lookup.
+ * @throws An actionable load error retaining the original import failure as its cause.
+ * @complexity O(1) lookup after Node's cached module load.
+ */
+async function defaultProviderBaseUrl({ provider }, _optional = {}) {
+    try {
+        const { VENDOR_API_BASE_URLS } = await import('@jini-ai/integrations/media-providers/catalog');
+        return VENDOR_API_BASE_URLS[provider];
+    }
+    catch (cause) {
+        throw new Error('Could not load @jini-ai/integrations/media-providers/catalog. Install the optional peer @jini-ai/integrations or inject ModelDiscoveryDeps.credential to discover models with default provider URLs.', { cause });
+    }
+}
 export const defaultModelDiscoveryDeps = {
     process: { run: runProcess },
     fs: {
@@ -326,18 +340,18 @@ export const defaultModelDiscoveryDeps = {
             // handles. BYOK env is usable only when it identifies this CLI's effective provider.
             const env = context.env;
             if (agentId === 'claude' && env.ANTHROPIC_API_KEY)
-                return { protocol: 'anthropic', baseUrl: env.ANTHROPIC_BASE_URL || VENDOR_API_BASE_URLS.anthropic, apiKey: env.ANTHROPIC_API_KEY };
+                return { protocol: 'anthropic', baseUrl: env.ANTHROPIC_BASE_URL || await defaultProviderBaseUrl({ provider: 'anthropic' }), apiKey: env.ANTHROPIC_API_KEY };
             const selected = context.model || (agentId === 'aider' ? env.AIDER_MODEL : agentId === 'qwen' ? env.QWEN_MODEL || env.OPENAI_MODEL : undefined);
             if (!selected)
                 return null;
             if (/^(anthropic\/|claude-)/.test(selected) && env.ANTHROPIC_API_KEY)
-                return { protocol: 'anthropic', baseUrl: env.ANTHROPIC_BASE_URL || VENDOR_API_BASE_URLS.anthropic, apiKey: env.ANTHROPIC_API_KEY };
+                return { protocol: 'anthropic', baseUrl: env.ANTHROPIC_BASE_URL || await defaultProviderBaseUrl({ provider: 'anthropic' }), apiKey: env.ANTHROPIC_API_KEY };
             if (/^(gemini\/|google\/|gemini-)/.test(selected) && env.GEMINI_API_KEY)
-                return { protocol: 'google', baseUrl: VENDOR_API_BASE_URLS.google, apiKey: env.GEMINI_API_KEY };
+                return { protocol: 'google', baseUrl: await defaultProviderBaseUrl({ provider: 'google' }), apiKey: env.GEMINI_API_KEY };
             if (/^openrouter\//.test(selected) && env.OPENROUTER_API_KEY)
-                return { protocol: 'openai', baseUrl: env.OPENROUTER_API_BASE || VENDOR_API_BASE_URLS.openrouter, apiKey: env.OPENROUTER_API_KEY };
+                return { protocol: 'openai', baseUrl: env.OPENROUTER_API_BASE || await defaultProviderBaseUrl({ provider: 'openrouter' }), apiKey: env.OPENROUTER_API_KEY };
             if ((/^(openai\/|gpt-|o\d)/.test(selected) || agentId === 'qwen' && (env.OPENAI_MODEL || env.OPENAI_BASE_URL)) && env.OPENAI_API_KEY)
-                return { protocol: 'openai', baseUrl: env.OPENAI_BASE_URL || env.OPENAI_API_BASE || VENDOR_API_BASE_URLS.openai, apiKey: env.OPENAI_API_KEY };
+                return { protocol: 'openai', baseUrl: env.OPENAI_BASE_URL || env.OPENAI_API_BASE || await defaultProviderBaseUrl({ provider: 'openai' }), apiKey: env.OPENAI_API_KEY };
             return null;
         } },
     acp: createAcpDiscoveryAdapter({ probe: nativeAcpModelProbe }),

package/dist/providers/elevenlabs.d.ts

@@ -1,3 +1,4 @@
+import { type Clock, type HttpClientPort } from '@jini-ai/core/primitives';
 export interface ElevenLabsVoiceOption {
     voiceId: string;
     name: string;
@@ -17,16 +18,32 @@ export type ElevenLabsCredentialResolver = (requiredArgs: {
 export declare class ElevenLabsCredentialMissingError extends Error {
     constructor();
 }
-/**
- * Lists the ElevenLabs voice catalog for a workspace, resolving credentials
- * via the injected {@link ElevenLabsCredentialResolver} and caching the
- * result for {@link ELEVENLABS_VOICE_CACHE_TTL_MS}. Throws
- * {@link ElevenLabsCredentialMissingError} when no API key is configured.
- */
-export declare function listElevenLabsVoiceOptions({ workspaceKey, resolveCredentials }: {
+export interface ElevenLabsVoiceClientOptions {
+    /** Maximum cached workspace/credential/page variants; oldest inserted entries are evicted. */
+    maxCacheEntries?: number;
+}
+export interface ElevenLabsVoiceListRequired {
     workspaceKey: string;
     resolveCredentials: ElevenLabsCredentialResolver;
-}, options?: {
+}
+export interface ElevenLabsVoiceListOptions {
+    limit?: number;
+}
+/** Owns transport, time and a bounded voice cache for one host lifecycle.
+ * Supply the existing policy-enforcing HTTP client; this factory never constructs a raw transport.
+ * @throws RangeError for an invalid cache bound; credential/transport/JSON errors propagate from listing.
+ * @complexity O(c + v) per lookup, c <= maxCacheEntries and v <= the requested page size.
+ */
+export declare function createElevenLabsVoiceClient({ http, clock }: {
+    readonly http: HttpClientPort;
+    readonly clock: Clock;
+}, { maxCacheEntries }?: ElevenLabsVoiceClientOptions): {
+    listVoiceOptions: ({ workspaceKey, resolveCredentials }: ElevenLabsVoiceListRequired, options?: ElevenLabsVoiceListOptions) => Promise<ElevenLabsVoiceOption[]>;
+    clearCache: () => void;
+};
+export type ElevenLabsVoiceClient = ReturnType<typeof createElevenLabsVoiceClient>;
+/** Compatibility wrapper for existing callers. New hosts retain an injected client and clear it on shutdown. */
+export declare function listElevenLabsVoiceOptions(required: ElevenLabsVoiceListRequired, options?: {
     limit?: number;
     requestInit?: Pick<RequestInit, 'dispatcher'>;
 }): Promise<ElevenLabsVoiceOption[]>;

package/dist/providers/elevenlabs.js

@@ -2,7 +2,7 @@
  * @module providers/elevenlabs
  *
  * ElevenLabs voice-catalog listing (`GET /v2/voices`), with a short in-memory
- * TTL cache keyed by workspace + base URL + page size + a credential
+ * bounded, client-owned TTL cache keyed by workspace + base URL + page size + a credential
  * fingerprint (never the raw key). Ported from OD's
  * `integrations/elevenlabs-voices.ts`.
  *
@@ -16,6 +16,7 @@
  * ElevenLabs wire API once it has a key.
  */
 import { createHash } from 'node:crypto';
+import { createSystemClock } from '@jini-ai/core/primitives';
 import { FETCH_TIMEOUT_MS, fetchWithTimeout } from '@jini-ai/platform/fetch-with-timeout';
 const ELEVENLABS_DEFAULT_BASE_URL = 'https://api.elevenlabs.io';
 const ELEVENLABS_DEFAULT_VOICE_LIMIT = 100;
@@ -28,7 +29,6 @@ export class ElevenLabsCredentialMissingError extends Error {
         this.name = 'ElevenLabsCredentialMissingError';
     }
 }
-const voiceOptionsCache = new Map();
 function isRecord(value) {
     return value !== null && typeof value === 'object';
 }
@@ -87,53 +87,90 @@ function cloneVoiceOptions(voices) {
         ...(voice.labels ? { labels: { ...voice.labels } } : {}),
     }));
 }
-/**
- * Lists the ElevenLabs voice catalog for a workspace, resolving credentials
- * via the injected {@link ElevenLabsCredentialResolver} and caching the
- * result for {@link ELEVENLABS_VOICE_CACHE_TTL_MS}. Throws
- * {@link ElevenLabsCredentialMissingError} when no API key is configured.
+/** Owns transport, time and a bounded voice cache for one host lifecycle.
+ * Supply the existing policy-enforcing HTTP client; this factory never constructs a raw transport.
+ * @throws RangeError for an invalid cache bound; credential/transport/JSON errors propagate from listing.
+ * @complexity O(c + v) per lookup, c <= maxCacheEntries and v <= the requested page size.
  */
-export async function listElevenLabsVoiceOptions({ workspaceKey, resolveCredentials }, options = {}) {
-    const credentials = await resolveCredentials({ workspaceKey });
-    if (!credentials.apiKey) {
-        throw new ElevenLabsCredentialMissingError();
+export function createElevenLabsVoiceClient({ http, clock }, { maxCacheEntries = 64 } = {}) {
+    if (!Number.isSafeInteger(maxCacheEntries) || maxCacheEntries < 1) {
+        throw new RangeError('maxCacheEntries must be a positive safe integer');
+    }
+    const cache = new Map();
+    function sweepExpired(now) {
+        for (const [key, entry] of cache)
+            if (entry.expiresAt <= now)
+                cache.delete(key);
     }
-    const baseUrl = (credentials.baseUrl || ELEVENLABS_DEFAULT_BASE_URL).replace(/\/$/, '');
-    const pageSize = clampLimit(options.limit);
-    const cacheKey = voiceCacheKey({
-        workspaceKey,
-        baseUrl,
-        apiKey: credentials.apiKey,
-        pageSize,
-    });
-    const cached = voiceOptionsCache.get(cacheKey);
-    const now = Date.now();
-    if (cached && cached.expiresAt > now) {
-        return cloneVoiceOptions(cached.voices);
+    /** Drops retained voices so a host can release them when its lifecycle ends. */
+    function clearCache() { cache.clear(); }
+    /** Lists and clones credential-scoped catalog values; unsuccessful responses are never cached. */
+    async function listVoiceOptions({ workspaceKey, resolveCredentials }, options = {}) {
+        const credentials = await resolveCredentials({ workspaceKey });
+        if (!credentials.apiKey)
+            throw new ElevenLabsCredentialMissingError();
+        const baseUrl = (credentials.baseUrl || ELEVENLABS_DEFAULT_BASE_URL).replace(/\/$/, '');
+        const pageSize = clampLimit(options.limit);
+        const cacheKey = voiceCacheKey({ workspaceKey, baseUrl, apiKey: credentials.apiKey, pageSize });
+        sweepExpired(clock.nowMs());
+        const cached = cache.get(cacheKey);
+        if (cached)
+            return cloneVoiceOptions(cached.voices);
+        const resp = await http.send({ request: {
+                url: `${baseUrl}/v2/voices?page_size=${pageSize}`,
+                method: 'GET',
+                headers: { 'xi-api-key': credentials.apiKey, accept: 'application/json' },
+                idleTimeoutMs: FETCH_TIMEOUT_MS.QUICK,
+                totalDeadlineMs: FETCH_TIMEOUT_MS.QUICK,
+                maxResponseBytes: 1024 * 1024,
+            } });
+        if (resp.status < 200 || resp.status >= 300) {
+            throw new Error(`elevenlabs voices ${resp.status}: ${resp.bodyText.slice(0, 240)}`);
+        }
+        if (resp.bodyTruncated)
+            throw new Error('elevenlabs voices response was truncated');
+        const payload = JSON.parse(resp.bodyText);
+        const rawVoices = isRecord(payload) && Array.isArray(payload.voices) ? payload.voices : [];
+        const voices = rawVoices.map((voice) => normalizeVoice(voice))
+            .filter((voice) => voice !== null);
+        const now = clock.nowMs();
+        sweepExpired(now);
+        // Replacing a key refreshes insertion order; concurrent misses cannot grow past the bound.
+        cache.delete(cacheKey);
+        if (cache.size >= maxCacheEntries)
+            cache.delete(cache.keys().next().value);
+        cache.set(cacheKey, { expiresAt: now + ELEVENLABS_VOICE_CACHE_TTL_MS, voices: cloneVoiceOptions(voices) });
+        return voices;
     }
-    const resp = await fetchWithTimeout(`${baseUrl}/v2/voices?page_size=${pageSize}`, {
-        ...options.requestInit,
-        method: 'GET',
-        headers: {
-            'xi-api-key': credentials.apiKey,
-            accept: 'application/json',
-        },
-    }, { timeoutMs: FETCH_TIMEOUT_MS.QUICK });
-    if (!resp.ok) {
-        const errText = await resp.text();
-        throw new Error(`elevenlabs voices ${resp.status}: ${errText.slice(0, 240)}`);
+    return { listVoiceOptions, clearCache };
+}
+/** Native defaults stay in this compatibility assembly; injected clients use HttpClientPort directly. */
+function createCompatibilityClient(requestInit = {}) {
+    return createElevenLabsVoiceClient({ clock: createSystemClock(), http: {
+            async send({ request }) {
+                const response = await fetchWithTimeout(request.url, {
+                    ...requestInit, method: request.method, headers: request.headers,
+                }, { timeoutMs: FETCH_TIMEOUT_MS.QUICK });
+                // Same reads as before the port: json() on success, text() for the error message.
+                return { status: response.status, headers: {},
+                    bodyText: response.ok ? JSON.stringify(await response.json()) : await response.text() };
+            },
+        } });
+}
+const compatibilityClient = createCompatibilityClient();
+const dispatcherClients = new WeakMap();
+/** Compatibility wrapper for existing callers. New hosts retain an injected client and clear it on shutdown. */
+export async function listElevenLabsVoiceOptions(required, options = {}) {
+    let client = compatibilityClient;
+    const dispatcher = options.requestInit?.dispatcher;
+    if (dispatcher && typeof dispatcher === 'object') {
+        let owned = dispatcherClients.get(dispatcher);
+        if (!owned) {
+            owned = createCompatibilityClient(options.requestInit);
+            dispatcherClients.set(dispatcher, owned);
+        }
+        client = owned;
     }
-    const payload = await resp.json();
-    const rawVoices = isRecord(payload) && Array.isArray(payload.voices)
-        ? payload.voices
-        : [];
-    const voices = rawVoices
-        .map((voice) => normalizeVoice(voice))
-        .filter((voice) => voice !== null);
-    voiceOptionsCache.set(cacheKey, {
-        expiresAt: now + ELEVENLABS_VOICE_CACHE_TTL_MS,
-        voices: cloneVoiceOptions(voices),
-    });
-    return voices;
+    return client.listVoiceOptions(required, options);
 }
 //# sourceMappingURL=elevenlabs.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/agent-runtime",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "Coding-agent runtime adapters: runtime registry, detection, launch, stream parsers, and the ACP/pi-rpc subprocess transport.",
   "license": "Apache-2.0",
   "repository": {
@@ -99,10 +99,10 @@
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.9",
     "@jini-ai/core": "^0.4.0",
-    "@jini-ai/oauth": "^0.2.2",
-    "@jini-ai/protocol": "^0.4.4",
+    "@jini-ai/integrations": "^0.4.2",
     "@jini-ai/platform": "^0.5.5",
-    "@jini-ai/integrations": "^0.4.2"
+    "@jini-ai/oauth": "^0.2.2",
+    "@jini-ai/protocol": "^0.4.4"
   },
   "dependencies": {
     "@jini-ai/core": "^0.4.4"