@jini-ai/agent-runtime 0.3.10 → 0.4.1

package/dist/json-event-stream.js

@@ -39,7 +39,7 @@ function stringifyContent(value) {
         // `JSON.parse`, the same "keep the defensive branch, document it, don't
         // force a test around impossible data" call `@jini-ai/cli`'s
         // `defaultReadFile`'s `finish()` guard made on 2026-07-22 — see
-        // `source-map.md`'s 2026-07-22 entry for the full re-derivation.
+        // `archived provenance ledger`'s 2026-07-22 entry for the full re-derivation.
         return String(value);
     }
 }
@@ -860,7 +860,7 @@ function handleCodexEvent(obj, onEvent, state) {
     }
     return false;
 }
-export function createJsonEventStreamHandler(kind, onEvent) {
+export function createJsonEventStreamHandler({ kind, onEvent }) {
     let buffer = '';
     const state = {
         cursorTextSoFar: '',
@@ -896,7 +896,7 @@ export function createJsonEventStreamHandler(kind, onEvent) {
             return;
         onEvent({ type: 'raw', line });
     }
-    function feed(chunk) {
+    function feed({ chunk }) {
         buffer += chunk;
         let nl;
         while ((nl = buffer.indexOf('\n')) !== -1) {

package/dist/launch.d.ts

@@ -7,6 +7,16 @@ export type AgentLaunchResolution = ReturnType<typeof inspectAgentExecutableReso
     childPathPrepend: string[];
     diagnostic: string | null;
 };
-export declare function resolveAgentLaunch(def: RuntimeAgentDef, configuredEnv?: Record<string, string>): AgentLaunchResolution;
-export declare function applyAgentLaunchEnv(env: NodeJS.ProcessEnv, launch: Pick<AgentLaunchResolution, 'childPathPrepend'>, nodeBinDir?: string, appendPathDirs?: string[]): NodeJS.ProcessEnv;
+export declare function resolveAgentLaunch({ def }: {
+    def: RuntimeAgentDef;
+}, { configuredEnv }?: {
+    configuredEnv?: Record<string, string>;
+}): AgentLaunchResolution;
+export declare function applyAgentLaunchEnv({ env, launch }: {
+    env: NodeJS.ProcessEnv;
+    launch: Pick<AgentLaunchResolution, 'childPathPrepend'>;
+}, { nodeBinDir, appendPathDirs }?: {
+    nodeBinDir?: string;
+    appendPathDirs?: string[];
+}): NodeJS.ProcessEnv;
 //# sourceMappingURL=launch.d.ts.map

package/dist/launch.js

@@ -9,8 +9,8 @@
 import { accessSync, closeSync, constants, openSync, readdirSync, readSync, realpathSync, statSync } from 'node:fs';
 import path, { delimiter } from 'node:path';
 import { inspectAgentExecutableResolution, userToolchainBinDirs } from './executables.js';
-export function resolveAgentLaunch(def, configuredEnv = {}) {
-    const resolution = inspectAgentExecutableResolution(def, configuredEnv);
+export function resolveAgentLaunch({ def }, { configuredEnv = {} } = {}) {
+    const resolution = inspectAgentExecutableResolution({ def: def }, { configuredEnv: configuredEnv });
     if (!resolution.selectedPath) {
         return { ...resolution, launchPath: null, launchKind: 'selected', childPathPrepend: [], diagnostic: null };
     }
@@ -29,7 +29,7 @@ export function resolveAgentLaunch(def, configuredEnv = {}) {
         diagnostic: native.diagnostic,
     };
 }
-export function applyAgentLaunchEnv(env, launch, nodeBinDir = path.dirname(process.execPath), appendPathDirs = userToolchainBinDirs()) {
+export function applyAgentLaunchEnv({ env, launch }, { nodeBinDir = path.dirname(process.execPath), appendPathDirs = userToolchainBinDirs() } = {}) {
     // Build the ordered list of directories to guarantee are at the front of
     // PATH: the running Node binary directory first (so npm .cmd shims on
     // Windows that invoke bare "node" find the correct binary even when the

package/dist/log-file.d.ts

@@ -19,5 +19,8 @@ export type PreparedAgentLogFile = {
  * @complexity One `mkdtemp` syscall; `null` return path does no I/O at all.
  * @overallScore 100/100
  */
-export declare function prepareAgentLogFile(def: RuntimeAgentDef | null | undefined, label: string): Promise<PreparedAgentLogFile | null>;
+export declare function prepareAgentLogFile({ def, label }: {
+    def: RuntimeAgentDef | null | undefined;
+    label: string;
+}): Promise<PreparedAgentLogFile | null>;
 //# sourceMappingURL=log-file.d.ts.map

package/dist/log-file.js

@@ -21,7 +21,7 @@
  * No OD provenance: OD's daemon derived antigravity's `--log-file` path
  * inline in `server.ts` rather than through a reusable helper. Extracted as
  * one here so the staging is testable on its own and so a second adapter with
- * a log-file flag needs no new code — see `source-map.md`.
+ * a log-file flag needs no new code — see `archived provenance ledger`.
  */
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
@@ -40,7 +40,7 @@ import path from 'node:path';
  * @complexity One `mkdtemp` syscall; `null` return path does no I/O at all.
  * @overallScore 100/100
  */
-export async function prepareAgentLogFile(def, label) {
+export async function prepareAgentLogFile({ def, label }) {
     if (!def?.needsAgentLogFile)
         return null;
     const safeLabel = label.replace(/[^a-zA-Z0-9_.-]/g, '-').slice(0, 80) || 'agent';

package/dist/mcp.d.ts

@@ -9,7 +9,7 @@
  * function was hardwired to inject exactly one product feature — a
  * specifically-named, specifically-branded MCP server spawned via that
  * product's own CLI binary, with a fixed args tail baked in (see
- * `source-map.md` for the exact literal). That's a specific product's MCP
+ * `archived provenance ledger` for the exact literal). That's a specific product's MCP
  * tool, not a generic runtime concern, so it is not ported. What genuinely
  * is generic — and is kept
  * here — is the *gating + env-shape* mechanism: only attach a server when
@@ -17,7 +17,7 @@
  * field as an array (`[{name, value}]`) or a map (`{KEY: value}`) per
  * `def.acpMcpEnvFormat`, since different ACP implementations expect
  * different shapes there. The host application supplies the actual server
- * name/command/args. See `source-map.md`.
+ * name/command/args. See `archived provenance ledger`.
  */
 import type { RuntimeAgentDef } from './types.js';
 export type AcpMcpServerSpec = {
@@ -40,5 +40,8 @@ export type AcpMcpServerEntry = {
         value: string;
     }>;
 };
-export declare function buildAcpMcpServersForAgent(def: Pick<RuntimeAgentDef, 'mcpDiscovery' | 'acpMcpEnvFormat'>, spec: AcpMcpServerSpec): AcpMcpServerEntry[];
+export declare function buildAcpMcpServersForAgent({ def, spec }: {
+    def: Pick<RuntimeAgentDef, 'mcpDiscovery' | 'acpMcpEnvFormat'>;
+    spec: AcpMcpServerSpec;
+}): AcpMcpServerEntry[];
 //# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -1,4 +1,4 @@
-export function buildAcpMcpServersForAgent(def, spec) {
+export function buildAcpMcpServersForAgent({ def, spec }) {
     const { name, command, args = [], extraEnv = {}, enabled = true } = spec;
     if (!enabled || def?.mcpDiscovery !== 'mature-acp')
         return [];

package/dist/metadata.d.ts

@@ -10,9 +10,9 @@
  * drops the three OD-self-referential entries the origin had for `amr`,
  * `pi`, and `hermes` (an install URL and two docs URLs that pointed at
  * OD's own site/fork rather than at the third-party CLI vendor — see
- * `source-map.md` for the exact original URLs), so they don't belong in a
+ * `archived provenance ledger` for the exact original URLs), so they don't belong in a
  * product-neutral default. Every other agent's real third-party vendor
- * link is unchanged. See `source-map.md`.
+ * link is unchanged. See `archived provenance ledger`.
  */
 export type AgentInstallMeta = {
     installUrl?: string;
@@ -20,5 +20,9 @@ export type AgentInstallMeta = {
 };
 /** HTTPS links for a Settings-shaped UI when an agent is unavailable. Keys match `RuntimeAgentDef.id`. */
 export declare const DEFAULT_AGENT_INSTALL_LINKS: Record<string, AgentInstallMeta>;
-export declare function installMetaForAgent(agentId: string, table?: Record<string, AgentInstallMeta>): AgentInstallMeta;
+export declare function installMetaForAgent({ agentId }: {
+    agentId: string;
+}, { table }?: {
+    table?: Record<string, AgentInstallMeta>;
+}): AgentInstallMeta;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.js

@@ -110,7 +110,7 @@ function sanitizeHttpsUrl(value) {
         return undefined;
     }
 }
-export function installMetaForAgent(agentId, table = DEFAULT_AGENT_INSTALL_LINKS) {
+export function installMetaForAgent({ agentId }, { table = DEFAULT_AGENT_INSTALL_LINKS } = {}) {
     const meta = table[agentId];
     if (!meta)
         return {};

package/dist/mmd-routes.d.ts

@@ -3,10 +3,26 @@ export type MmdRouteLaunchEnv = {
     ANTHROPIC_BASE_URL: string;
     ANTHROPIC_AUTH_TOKEN?: string;
 };
-export declare function resolveMmdRoutesFile(env: RuntimeEnv): string | null;
-export declare function parseMmdRouteModelIds(raw: unknown): string[];
-export declare function resolveMmdRouteLaunchEnv(raw: unknown, modelId: string | null | undefined): MmdRouteLaunchEnv | null;
-export declare function mergeMmdRouteModels(routeIds: readonly string[], fallbackModels: readonly RuntimeModelOption[]): RuntimeModelOption[];
-export declare function loadMmdRouteModels(env: RuntimeEnv, fallbackModels: readonly RuntimeModelOption[]): Promise<RuntimeModelOption[] | null>;
-export declare function loadMmdRouteLaunchEnv(env: RuntimeEnv, modelId: string | null | undefined): Promise<MmdRouteLaunchEnv | null>;
+export declare function resolveMmdRoutesFile({ env }: {
+    env: RuntimeEnv;
+}): string | null;
+export declare function parseMmdRouteModelIds({ raw }: {
+    raw: unknown;
+}): string[];
+export declare function resolveMmdRouteLaunchEnv({ raw, modelId }: {
+    raw: unknown;
+    modelId: string | null | undefined;
+}): MmdRouteLaunchEnv | null;
+export declare function mergeMmdRouteModels({ routeIds, fallbackModels }: {
+    routeIds: readonly string[];
+    fallbackModels: readonly RuntimeModelOption[];
+}): RuntimeModelOption[];
+export declare function loadMmdRouteModels({ env, fallbackModels }: {
+    env: RuntimeEnv;
+    fallbackModels: readonly RuntimeModelOption[];
+}): Promise<RuntimeModelOption[] | null>;
+export declare function loadMmdRouteLaunchEnv({ env, modelId }: {
+    env: RuntimeEnv;
+    modelId: string | null | undefined;
+}): Promise<MmdRouteLaunchEnv | null>;
 //# sourceMappingURL=mmd-routes.d.ts.map

package/dist/mmd-routes.js

@@ -32,7 +32,7 @@ function expandRoutesFileOverride(raw, env) {
     }
     return raw;
 }
-export function resolveMmdRoutesFile(env) {
+export function resolveMmdRoutesFile({ env }) {
     const override = stringEnv(env, MMD_MODEL_ROUTES_FILE_ENV);
     if (override)
         return expandRoutesFileOverride(override, env);
@@ -44,13 +44,13 @@ export function resolveMmdRoutesFile(env) {
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-export function parseMmdRouteModelIds(raw) {
+export function parseMmdRouteModelIds({ raw }) {
     if (!isRecord(raw) || !isRecord(raw.routes))
         return [];
     const seen = new Set();
     const ids = [];
     for (const rawId of Object.keys(raw.routes)) {
-        const id = sanitizeCustomModel(rawId);
+        const id = sanitizeCustomModel({ id: rawId });
         if (!id || seen.has(id))
             continue;
         seen.add(id);
@@ -58,8 +58,8 @@ export function parseMmdRouteModelIds(raw) {
     }
     return ids;
 }
-export function resolveMmdRouteLaunchEnv(raw, modelId) {
-    const id = sanitizeCustomModel(modelId);
+export function resolveMmdRouteLaunchEnv({ raw, modelId }) {
+    const id = sanitizeCustomModel({ id: modelId });
     if (!id || !isRecord(raw) || !isRecord(raw.routes))
         return null;
     const route = raw.routes[id];
@@ -79,7 +79,7 @@ export function resolveMmdRouteLaunchEnv(raw, modelId) {
     };
 }
 function addModel(out, seen, option) {
-    const id = sanitizeCustomModel(option.id);
+    const id = sanitizeCustomModel({ id: option.id });
     if (!id || seen.has(id))
         return;
     seen.add(id);
@@ -88,7 +88,7 @@ function addModel(out, seen, option) {
         : id;
     out.push({ id, label });
 }
-export function mergeMmdRouteModels(routeIds, fallbackModels) {
+export function mergeMmdRouteModels({ routeIds, fallbackModels }) {
     const out = [];
     const seen = new Set();
     addModel(out, seen, DEFAULT_MODEL_OPTION);
@@ -100,8 +100,8 @@ export function mergeMmdRouteModels(routeIds, fallbackModels) {
     }
     return out;
 }
-export async function loadMmdRouteModels(env, fallbackModels) {
-    const routesFile = resolveMmdRoutesFile(env);
+export async function loadMmdRouteModels({ env, fallbackModels }) {
+    const routesFile = resolveMmdRoutesFile({ env: env });
     if (!routesFile)
         return null;
     let text;
@@ -118,13 +118,13 @@ export async function loadMmdRouteModels(env, fallbackModels) {
     catch {
         return null;
     }
-    const routeIds = parseMmdRouteModelIds(parsed);
+    const routeIds = parseMmdRouteModelIds({ raw: parsed });
     if (routeIds.length === 0)
         return null;
-    return mergeMmdRouteModels(routeIds, fallbackModels);
+    return mergeMmdRouteModels({ routeIds: routeIds, fallbackModels: fallbackModels });
 }
-export async function loadMmdRouteLaunchEnv(env, modelId) {
-    const routesFile = resolveMmdRoutesFile(env);
+export async function loadMmdRouteLaunchEnv({ env, modelId }) {
+    const routesFile = resolveMmdRoutesFile({ env: env });
     if (!routesFile)
         return null;
     let text;
@@ -141,6 +141,6 @@ export async function loadMmdRouteLaunchEnv(env, modelId) {
     catch {
         return null;
     }
-    return resolveMmdRouteLaunchEnv(parsed, modelId);
+    return resolveMmdRouteLaunchEnv({ raw: parsed, modelId: modelId });
 }
 //# sourceMappingURL=mmd-routes.js.map

package/dist/model-catalog-cache.d.ts

@@ -0,0 +1,50 @@
+import type { Clock } from '@jini-ai/core/primitives';
+/** Components are encoded as a JSON tuple; delimiter characters cannot alias another tenant's key. Hosts include all credential/provider scopes affecting discovery. */
+export type ModelCatalogCacheKey = readonly string[];
+export type ModelDiscovery<Model> = (input: {
+    cacheKey: ModelCatalogCacheKey;
+}) => Promise<readonly Model[] | null>;
+export type ModelMerger<Model> = (input: {
+    fallback: readonly Model[];
+    live: readonly Model[];
+}) => readonly Model[];
+export interface ModelCatalogCacheDependencies<Model> {
+    readonly discover: ModelDiscovery<Model>;
+    readonly clock: Clock;
+    readonly merge: ModelMerger<Model>;
+}
+export interface ModelCatalogCacheOptions {
+    readonly ttlMs?: number;
+    /** Called once per failed discovery, after fallback state is recorded. */
+    readonly onDiscoveryError?: (input: {
+        error: unknown;
+        cacheKey: ModelCatalogCacheKey;
+    }) => void;
+}
+/** Per-call discovery can close over a credential the host has already resolved. */
+export interface ModelCatalogReadOptions<Model> {
+    readonly discover?: ModelDiscovery<Model>;
+}
+/** Blocking live-discovery enrichment backed by the same single-flight loader as the legacy model cache. Successes and failures share the TTL; the host resolves credentials before calling get. */
+export declare class ModelCatalogCache<Model> {
+    private readonly required;
+    private readonly optional;
+    private readonly states;
+    private readonly ttlMs;
+    constructor(required: ModelCatalogCacheDependencies<Model>, optional?: ModelCatalogCacheOptions);
+    /** Returns the current fallback merged with cached live data, awaiting at most one discovery per key.
+     * Local key work is proportional to the key's encoded length; discovery and merge cost belongs to the host ports. State retains one entry per distinct key until this instance is discarded.
+     */
+    get({ cacheKey, fallback }: {
+        cacheKey: ModelCatalogCacheKey;
+        fallback: readonly Model[];
+    }, options?: ModelCatalogReadOptions<Model>): Promise<readonly Model[]>;
+}
+/** Keeps every fallback entry and its metadata in order, then appends each unseen live ID once. Neither input list is mutated. Time and space are O(fallback.length + live.length). */
+export declare function unionModels<Model extends {
+    readonly id: string;
+}>({ fallback, live }: {
+    fallback: readonly Model[];
+    live: readonly Model[];
+}): Model[];
+//# sourceMappingURL=model-catalog-cache.d.ts.map

package/dist/model-catalog-cache.js

@@ -0,0 +1,61 @@
+import { coalesceModelLoad } from './model-loading-state.js';
+/** Blocking live-discovery enrichment backed by the same single-flight loader as the legacy model cache. Successes and failures share the TTL; the host resolves credentials before calling get. */
+export class ModelCatalogCache {
+    required;
+    optional;
+    states = new Map();
+    ttlMs;
+    constructor(required, optional = {}) {
+        this.required = required;
+        this.optional = optional;
+        this.ttlMs = optional.ttlMs ?? 5 * 60_000;
+        if (!Number.isFinite(this.ttlMs) || this.ttlMs < 0)
+            throw new RangeError('ttlMs must be finite and non-negative');
+    }
+    /** Returns the current fallback merged with cached live data, awaiting at most one discovery per key.
+     * Local key work is proportional to the key's encoded length; discovery and merge cost belongs to the host ports. State retains one entry per distinct key until this instance is discarded.
+     */
+    async get({ cacheKey, fallback }, options = {}) {
+        const key = JSON.stringify(cacheKey);
+        let state = this.states.get(key);
+        if (!state) {
+            state = { inFlight: null, expiresAt: -Infinity, live: null };
+            this.states.set(key, state);
+        }
+        if (state.inFlight) {
+            await state.inFlight;
+        }
+        else if (state.expiresAt <= this.required.clock.nowMs()) {
+            state.expiresAt = this.required.clock.nowMs() + this.ttlMs;
+            const current = state;
+            const discover = options.discover ?? this.required.discover;
+            // Snapshot the key before crossing the asynchronous discovery boundary.
+            const scopedKey = [...cacheKey];
+            await coalesceModelLoad({
+                state: current, load: async () => {
+                    try {
+                        current.live = await discover({ cacheKey: scopedKey });
+                    }
+                    catch (error) {
+                        current.live = null;
+                        this.optional.onDiscoveryError?.({ error, cacheKey: scopedKey });
+                    }
+                }
+            });
+        }
+        return this.required.merge({ fallback, live: state.live ?? [] });
+    }
+}
+/** Keeps every fallback entry and its metadata in order, then appends each unseen live ID once. Neither input list is mutated. Time and space are O(fallback.length + live.length). */
+export function unionModels({ fallback, live }) {
+    const seen = new Set(fallback.map(model => model.id));
+    const merged = [...fallback];
+    for (const model of live) {
+        if (seen.has(model.id))
+            continue;
+        seen.add(model.id);
+        merged.push(model);
+    }
+    return merged;
+}
+//# sourceMappingURL=model-catalog-cache.js.map

package/dist/model-loading-state.d.ts

@@ -0,0 +1,10 @@
+/** Mutable state owned by one cache instance and one key. */
+export interface ModelLoadingState {
+    inFlight: Promise<void> | null;
+}
+/** Shares one load until it settles. Install the promise before invoking the collaborator so a synchronous completion cannot leave a stuck in-flight entry. The load callback owns error policy; an uncaught load error rejects the shared promise. Local work and space are O(1). */
+export declare function coalesceModelLoad({ state, load }: {
+    state: ModelLoadingState;
+    load: () => Promise<void>;
+}): Promise<void>;
+//# sourceMappingURL=model-loading-state.d.ts.map

package/dist/model-loading-state.js

@@ -0,0 +1,23 @@
+/** Shares one load until it settles. Install the promise before invoking the collaborator so a synchronous completion cannot leave a stuck in-flight entry. The load callback owns error policy; an uncaught load error rejects the shared promise. Local work and space are O(1). */
+export function coalesceModelLoad({ state, load }) {
+    if (state.inFlight)
+        return state.inFlight;
+    let finish;
+    let fail;
+    const pending = new Promise((resolve, reject) => { finish = resolve; fail = reject; });
+    state.inFlight = pending;
+    void (async () => {
+        try {
+            await load();
+            finish();
+        }
+        catch (error) {
+            fail(error);
+        }
+        finally {
+            state.inFlight = null;
+        }
+    })();
+    return pending;
+}
+//# sourceMappingURL=model-loading-state.js.map

package/dist/model-registry.d.ts

@@ -14,7 +14,7 @@
  * `packages/contracts/src/api/app-config.ts` (`AgentModelPrefs`),
  * `apps/web/src/components/providerModelsCache.ts`, and
  * `apps/web/src/components/agentModelSelection.ts` — see
- * `packages/agent-runtime/source-map.md` for the full per-symbol mapping.
+ * `packages/agent-runtime/archived provenance ledger` for the full per-symbol mapping.
  * No OD product-identity strings or OD-specific gating (e.g. the original's
  * hardcoded `agent.id === 'amr'` carve-out) survived the port.
  *
@@ -47,32 +47,53 @@ export interface AgentModelChoice {
  * doesn't require credentials is always `available`; otherwise the status
  * depends on whether a credential has actually been stored.
  */
-export declare function resolveCredentialStatus(provider: Pick<ModelProvider, 'credentialsRequired'>, hasStoredCredential: boolean): CredentialStatus;
+export declare function resolveCredentialStatus({ provider, hasStoredCredential }: {
+    provider: Pick<ModelProvider, 'credentialsRequired'>;
+    hasStoredCredential: boolean;
+}): CredentialStatus;
 /**
  * Merges a live-fetched model list with a static suggestion list, keeping
  * fetched entries first and deduping by id (first write wins). Blank ids are
  * dropped; blank labels fall back to the id.
  */
-export declare function mergeModelOptions(fetchedModels: readonly ModelCatalogOption[], suggestedModels: readonly ModelCatalogOption[]): ModelCatalogOption[];
+export declare function mergeModelOptions({ fetchedModels, suggestedModels }: {
+    fetchedModels: readonly ModelCatalogOption[];
+    suggestedModels: readonly ModelCatalogOption[];
+}): ModelCatalogOption[];
 /** Deterministic, non-reversible fingerprint — never persist or transmit the raw credential. */
-export declare function fingerprintCredential(value: string): string;
+export declare function fingerprintCredential({ value }: {
+    value: string;
+}): string;
 /**
  * A stable key for caching a fetched model catalogue, scoped to the
  * provider, endpoint, and credential in use — so switching any one of them
  * misses the cache instead of silently reusing another provider's list.
  * `variant` covers protocols that key on more than credential + endpoint
  * (e.g. an API version).
+ * @throws {TypeError} When a supplied variant is not a string.
  */
-export declare function modelCatalogCacheKey(providerId: string, baseUrl: string, credential: string, variant?: string): string;
+export declare function modelCatalogCacheKey({ providerId, baseUrl, credential }: {
+    providerId: string;
+    baseUrl: string;
+    credential: string;
+}, { variant }?: {
+    variant?: unknown;
+}): string;
 /**
  * If `choice` names a model no longer in the agent's current catalogue,
  * falls back to the agent's first available model. Returns `null` when no
  * normalization is needed (nothing to change) or possible (no configured
  * model, or the agent has no models to fall back to).
  */
-export declare function normalizeAgentModelChoice(agent: Pick<AgentDefinition, 'models'> | null | undefined, choice: AgentModelChoice | undefined): AgentModelChoice | null;
+export declare function normalizeAgentModelChoice({ agent, choice }: {
+    agent: Pick<AgentDefinition, 'models'> | null | undefined;
+    choice: AgentModelChoice | undefined;
+}): AgentModelChoice | null;
 /** `normalizeAgentModelChoice`'s result if normalization applied, else the original choice. */
-export declare function effectiveAgentModelChoice(agent: Pick<AgentDefinition, 'models'> | null | undefined, choice: AgentModelChoice | undefined): AgentModelChoice | undefined;
+export declare function effectiveAgentModelChoice({ agent, choice }: {
+    agent: Pick<AgentDefinition, 'models'> | null | undefined;
+    choice: AgentModelChoice | undefined;
+}): AgentModelChoice | undefined;
 /**
  * Model/provider/agent catalogue vocabulary. Moved to `@jini-ai/protocol` on 2026-07-29 (see that
  * package's `agent-catalog.ts`) so a browser package can consume it without depending on this

package/dist/model-registry.js

@@ -3,7 +3,7 @@
  * doesn't require credentials is always `available`; otherwise the status
  * depends on whether a credential has actually been stored.
  */
-export function resolveCredentialStatus(provider, hasStoredCredential) {
+export function resolveCredentialStatus({ provider, hasStoredCredential }) {
     if (provider.credentialsRequired === false)
         return 'available';
     return hasStoredCredential ? 'configured' : 'unconfigured';
@@ -13,7 +13,7 @@ export function resolveCredentialStatus(provider, hasStoredCredential) {
  * fetched entries first and deduping by id (first write wins). Blank ids are
  * dropped; blank labels fall back to the id.
  */
-export function mergeModelOptions(fetchedModels, suggestedModels) {
+export function mergeModelOptions({ fetchedModels, suggestedModels }) {
     const seen = new Set();
     const merged = [];
     const add = (model) => {
@@ -30,7 +30,7 @@ export function mergeModelOptions(fetchedModels, suggestedModels) {
     return merged;
 }
 /** Deterministic, non-reversible fingerprint — never persist or transmit the raw credential. */
-export function fingerprintCredential(value) {
+export function fingerprintCredential({ value }) {
     let hash = 0x811c9dc5;
     for (let i = 0; i < value.length; i += 1) {
         hash ^= value.charCodeAt(i);
@@ -44,12 +44,15 @@ export function fingerprintCredential(value) {
  * misses the cache instead of silently reusing another provider's list.
  * `variant` covers protocols that key on more than credential + endpoint
  * (e.g. an API version).
+ * @throws {TypeError} When a supplied variant is not a string.
  */
-export function modelCatalogCacheKey(providerId, baseUrl, credential, variant = '') {
+export function modelCatalogCacheKey({ providerId, baseUrl, credential }, { variant = '' } = {}) {
+    if (typeof variant !== 'string')
+        throw new TypeError('Model catalog variant must be a string');
     return [
         providerId,
         baseUrl.trim().replace(/\/+$/, ''),
-        fingerprintCredential(credential.trim()),
+        fingerprintCredential({ value: credential.trim() }),
         variant.trim(),
     ].join('\n');
 }
@@ -59,7 +62,7 @@ export function modelCatalogCacheKey(providerId, baseUrl, credential, variant =
  * normalization is needed (nothing to change) or possible (no configured
  * model, or the agent has no models to fall back to).
  */
-export function normalizeAgentModelChoice(agent, choice) {
+export function normalizeAgentModelChoice({ agent, choice }) {
     const configuredModel = typeof choice?.model === 'string' && choice.model ? choice.model : null;
     if (!configuredModel)
         return null;
@@ -71,7 +74,7 @@ export function normalizeAgentModelChoice(agent, choice) {
     return { ...choice, model: modelIds[0] };
 }
 /** `normalizeAgentModelChoice`'s result if normalization applied, else the original choice. */
-export function effectiveAgentModelChoice(agent, choice) {
-    return normalizeAgentModelChoice(agent, choice) ?? choice;
+export function effectiveAgentModelChoice({ agent, choice }) {
+    return normalizeAgentModelChoice({ agent: agent, choice: choice }) ?? choice;
 }
 //# sourceMappingURL=model-registry.js.map

package/dist/models.d.ts

@@ -7,10 +7,35 @@
  */
 import type { RuntimeAgentDef, RuntimeModelOption } from './types.js';
 export declare const DEFAULT_MODEL_OPTION: RuntimeModelOption;
-export declare function rememberLiveModels(agentId: string, models: RuntimeModelOption[], scope?: string | null): void;
-export declare function getRememberedLiveModels(agentId: string, scope?: string | null): RuntimeModelOption[];
-export declare function preferFreshLiveModels(freshModels: RuntimeModelOption[], rememberedModels: RuntimeModelOption[]): RuntimeModelOption[];
-export declare function isKnownModel(def: RuntimeAgentDef, modelId: string | null | undefined, scope?: string | null): boolean;
-export declare function resolveModelForAgent(def: RuntimeAgentDef, resolved: string | null, env?: Record<string, string | undefined>, liveModelScope?: string | null): string | null;
-export declare function sanitizeCustomModel(id: string | null | undefined): string | null;
+export declare function rememberLiveModels({ agentId, models }: {
+    agentId: string;
+    models: RuntimeModelOption[];
+}, { scope }?: {
+    scope?: string | null;
+}): void;
+export declare function getRememberedLiveModels({ agentId }: {
+    agentId: string;
+}, { scope }?: {
+    scope?: string | null;
+}): RuntimeModelOption[];
+export declare function preferFreshLiveModels({ freshModels, rememberedModels }: {
+    freshModels: RuntimeModelOption[];
+    rememberedModels: RuntimeModelOption[];
+}): RuntimeModelOption[];
+export declare function isKnownModel({ def, modelId }: {
+    def: RuntimeAgentDef;
+    modelId: string | null | undefined;
+}, { scope }?: {
+    scope?: string | null;
+}): boolean;
+export declare function resolveModelForAgent({ def, resolved }: {
+    def: RuntimeAgentDef;
+    resolved: string | null;
+}, { env, liveModelScope }?: {
+    env?: Record<string, string | undefined>;
+    liveModelScope?: string | null;
+}): string | null;
+export declare function sanitizeCustomModel({ id }: {
+    id: string | null | undefined;
+}): string | null;
 //# sourceMappingURL=models.d.ts.map