@jini-ai/agent-runtime 0.3.9 → 0.4.0

package/dist/detection.d.ts

@@ -4,6 +4,30 @@ type FetchedRuntimeModels = {
     models: RuntimeModelOption[];
     source: RuntimeModelSource;
 };
+/**
+ * Makes sure `agentCapabilities` holds this def's `--help`-probed flags before its `buildArgs` runs.
+ *
+ * Why this exists: `agentCapabilities` used to be filled ONLY by {@link detectAgents}. A host whose
+ * run process never calls `detectAgents` (it lists agents with its own lighter probe, or not at
+ * all) left the map empty for every run, so every probe-gated flag stayed off for good — for
+ * `claude` that meant no `--include-partial-messages` (no streamed text) and no `--effort`, even on
+ * a CLI that supports both. The run path calls this with the exact launch path and env it is about
+ * to spawn, so the gate reflects the binary that actually runs.
+ *
+ * A no-op when the def declares no probe or the map already has an entry (a `detectAgents` result
+ * wins). Probes once per def id + launch path for the life of the process. A failed probe records
+ * nothing, which keeps the safe baseline (no optional flags), and is not retried on every run.
+ *
+ * @param def - The def about to be spawned.
+ * @param launchPath - The resolved executable the run will spawn.
+ * @param env - The env the run will spawn with.
+ * @complexity O(1) after the first call per def + path; the first call costs one `--help` spawn (5 s cap).
+ */
+export declare function ensureAgentCapabilities({ def, launchPath, env }: {
+    def: RuntimeAgentDef;
+    launchPath: string;
+    env: NodeJS.ProcessEnv;
+}): Promise<void>;
 /** Result of {@link probeAgentModels}: the models to surface and where they came from. */
 export type ProbedAgentModels = FetchedRuntimeModels;
 /**
@@ -18,8 +42,16 @@ export type ProbedAgentModels = FetchedRuntimeModels;
  * `source: 'fallback'` (including when the binary is not found). Never rejects.
  * @complexity At most one model-listing spawn, bounded by the def's own timeout.
  */
-export declare function probeAgentModels(def: RuntimeAgentDef, configuredEnv?: Record<string, string>, amrProfileResolver?: AmrProfileResolver): Promise<ProbedAgentModels>;
-export declare function detectAgents(configuredEnvByAgent?: Record<string, Record<string, string>>, amrProfileResolver?: AmrProfileResolver): Promise<(Omit<RuntimeAgentDef, "buildArgs" | "listModels" | "fetchModels" | "deriveReasoningOptions" | "fallbackModels" | "fallbackModelsAssertedAt" | "helpArgs" | "capabilityFlags" | "fallbackBins" | "versionProbeTimeoutMs" | "maxPromptArgBytes" | "env" | "inactivityTimeoutMs" | "authProbe" | "needsAgentLogFile" | "stdoutPolicy" | "runtimeLock"> & {
+export declare function probeAgentModels({ def }: {
+    def: RuntimeAgentDef;
+}, { configuredEnv, amrProfileResolver }?: {
+    configuredEnv?: Record<string, string>;
+    amrProfileResolver?: AmrProfileResolver;
+}): Promise<ProbedAgentModels>;
+export declare function detectAgents({}: {}, { configuredEnvByAgent, amrProfileResolver }?: {
+    configuredEnvByAgent?: Record<string, Record<string, string>>;
+    amrProfileResolver?: AmrProfileResolver;
+}): Promise<(Omit<RuntimeAgentDef, "buildArgs" | "listModels" | "fetchModels" | "deriveReasoningOptions" | "fallbackModels" | "fallbackModelsAssertedAt" | "helpArgs" | "capabilityFlags" | "fallbackBins" | "versionProbeTimeoutMs" | "maxPromptArgBytes" | "env" | "inactivityTimeoutMs" | "authProbe" | "needsAgentLogFile" | "stdoutPolicy" | "runtimeLock"> & {
     models: RuntimeModelOption[];
     modelsSource: RuntimeModelSource;
     available: boolean;
@@ -29,6 +61,9 @@ export declare function detectAgents(configuredEnvByAgent?: Record<string, Recor
     version?: string | null;
     diagnostics?: AgentDiagnostic[];
 })[]>;
-export declare function detectAgentsStream(configuredEnvByAgent?: Record<string, Record<string, string>>, amrProfileResolver?: AmrProfileResolver): AsyncGenerator<DetectedAgent>;
+export declare function detectAgentsStream({}: {}, { configuredEnvByAgent, amrProfileResolver }?: {
+    configuredEnvByAgent?: Record<string, Record<string, string>>;
+    amrProfileResolver?: AmrProfileResolver;
+}): AsyncGenerator<DetectedAgent>;
 export {};
 //# sourceMappingURL=detection.d.ts.map

package/dist/detection.js

@@ -9,7 +9,7 @@
  * `AmrProfileResolver` port (see `amr-profile-resolver.ts`), defaulting to
  * a no-op. `detectAgents`/`detectAgentsStream` take it as an optional last
  * parameter; every other agent's detection path is unaffected. See
- * `source-map.md`.
+ * `archived provenance ledger`.
  */
 import { execAgentFile } from './invocation.js';
 import { getRememberedLiveModels, rememberLiveModels } from './models.js';
@@ -22,12 +22,12 @@ import { probeAgentAuthStatus } from './auth.js';
 import { noopAmrProfileResolver } from './amr-profile-resolver.js';
 import { buildAuthDiagnostic, buildExecutableDiagnostic, buildNotInvocableDiagnostic } from './diagnostics.js';
 function amrModelScopeFromEnv(env, amrProfileResolver) {
-    return amrProfileResolver.resolveProfile(env);
+    return amrProfileResolver.resolveProfile({ env: env });
 }
 function withRememberedAmrModels(def, env, modelResult, amrProfileResolver) {
     if (def.id !== 'amr' || modelResult.models.length > 0)
         return modelResult;
-    const rememberedModels = getRememberedLiveModels(def.id, amrModelScopeFromEnv(env, amrProfileResolver));
+    const rememberedModels = getRememberedLiveModels({ agentId: def.id }, { scope: amrModelScopeFromEnv(env, amrProfileResolver) });
     if (rememberedModels.length === 0)
         return modelResult;
     return { models: rememberedModels, source: 'live' };
@@ -35,7 +35,7 @@ function withRememberedAmrModels(def, env, modelResult, amrProfileResolver) {
 async function fetchModels(def, resolvedBin, env) {
     if (typeof def.fetchModels === 'function') {
         try {
-            const parsed = await def.fetchModels(resolvedBin, env);
+            const parsed = await def.fetchModels({ resolvedBin: resolvedBin, env: env });
             if (!parsed || parsed.length === 0) {
                 return { models: def.fallbackModels, source: 'fallback' };
             }
@@ -49,15 +49,15 @@ async function fetchModels(def, resolvedBin, env) {
         return { models: def.fallbackModels, source: 'fallback' };
     }
     try {
-        const { stdout } = await execAgentFile(resolvedBin, def.listModels.args, {
-            env,
-            timeout: def.listModels.timeoutMs,
-            // Models lists from popular CLIs (e.g. opencode) easily exceed the
-            // default 1MB buffer once you include every openrouter model. Bump
-            // it so we don't truncate the listing.
-            maxBuffer: 8 * 1024 * 1024,
-        });
-        const parsed = def.listModels.parse(String(stdout));
+        const { stdout } = await execAgentFile({ command: resolvedBin, args: def.listModels.args }, { options: {
+                env,
+                timeout: def.listModels.timeoutMs,
+                // Models lists from popular CLIs (e.g. opencode) easily exceed the
+                // default 1MB buffer once you include every openrouter model. Bump
+                // it so we don't truncate the listing.
+                maxBuffer: 8 * 1024 * 1024,
+            } });
+        const parsed = def.listModels.parse({ stdout: String(stdout) });
         // Empty / null parse result means the CLI didn't actually return a
         // usable list (e.g. cursor-agent's "No models available"); fall back
         // to the static hint so the picker isn't stuck on Default-only.
@@ -95,10 +95,10 @@ async function fetchModels(def, resolvedBin, env) {
  */
 async function probeVersionAtPath(def, resolved, env) {
     try {
-        const { stdout } = await execAgentFile(resolved, def.versionArgs, {
-            env,
-            timeout: def.versionProbeTimeoutMs ?? 3000,
-        });
+        const { stdout } = await execAgentFile({ command: resolved, args: def.versionArgs }, { options: {
+                env,
+                timeout: def.versionProbeTimeoutMs ?? 3000,
+            } });
         // `String.split()` on a non-empty string always returns at least one
         // element, so `[0]` is never `undefined` here — the assertion just
         // satisfies `noUncheckedIndexedAccess`.
@@ -128,7 +128,7 @@ function unavailableAgent(def, diagnostics = []) {
         modelsSource: 'fallback',
         available: false,
         ...(diagnostics.length > 0 ? { diagnostics } : {}),
-        ...installMetaForAgent(def.id),
+        ...installMetaForAgent({ agentId: def.id }),
     };
 }
 // Probe the agent's `--help` once and record which advertised flags the
@@ -140,12 +140,7 @@ async function probeCapabilities(def, launchPath, env) {
     if (!def.helpArgs || !def.capabilityFlags)
         return null;
     try {
-        const { stdout } = await execAgentFile(launchPath, def.helpArgs, { env, timeout: 5000, maxBuffer: 4 * 1024 * 1024 });
-        const caps = {};
-        for (const [flag, key] of Object.entries(def.capabilityFlags)) {
-            caps[key] = String(stdout).includes(flag);
-        }
-        return caps;
+        return await readCapabilities(def.helpArgs, def.capabilityFlags, launchPath, env);
     }
     catch {
         // If --help fails, leave caps empty so buildArgs falls back to the
@@ -153,6 +148,51 @@ async function probeCapabilities(def, launchPath, env) {
         return {};
     }
 }
+/** Runs the def's `--help` probe and maps each advertised flag to its capability key; throws on a failed probe. */
+async function readCapabilities(helpArgs, capabilityFlags, launchPath, env) {
+    const { stdout } = await execAgentFile({ command: launchPath, args: [...helpArgs] }, { options: { env, timeout: 5000, maxBuffer: 4 * 1024 * 1024 } });
+    const caps = {};
+    for (const [flag, key] of Object.entries(capabilityFlags)) {
+        caps[key] = String(stdout).includes(flag);
+    }
+    return caps;
+}
+/** One in-flight or settled `--help` probe per def id + launch path, so a run never re-spawns it. */
+const capabilityProbes = new Map();
+/**
+ * Makes sure `agentCapabilities` holds this def's `--help`-probed flags before its `buildArgs` runs.
+ *
+ * Why this exists: `agentCapabilities` used to be filled ONLY by {@link detectAgents}. A host whose
+ * run process never calls `detectAgents` (it lists agents with its own lighter probe, or not at
+ * all) left the map empty for every run, so every probe-gated flag stayed off for good — for
+ * `claude` that meant no `--include-partial-messages` (no streamed text) and no `--effort`, even on
+ * a CLI that supports both. The run path calls this with the exact launch path and env it is about
+ * to spawn, so the gate reflects the binary that actually runs.
+ *
+ * A no-op when the def declares no probe or the map already has an entry (a `detectAgents` result
+ * wins). Probes once per def id + launch path for the life of the process. A failed probe records
+ * nothing, which keeps the safe baseline (no optional flags), and is not retried on every run.
+ *
+ * @param def - The def about to be spawned.
+ * @param launchPath - The resolved executable the run will spawn.
+ * @param env - The env the run will spawn with.
+ * @complexity O(1) after the first call per def + path; the first call costs one `--help` spawn (5 s cap).
+ */
+export function ensureAgentCapabilities({ def, launchPath, env }) {
+    const { helpArgs, capabilityFlags } = def;
+    if (!helpArgs || !capabilityFlags || agentCapabilities.has(def.id))
+        return Promise.resolve();
+    const key = `${def.id}\u0000${launchPath}`;
+    const existing = capabilityProbes.get(key);
+    if (existing)
+        return existing;
+    const probe = readCapabilities(helpArgs, capabilityFlags, launchPath, env).then((caps) => {
+        if (!agentCapabilities.has(def.id))
+            agentCapabilities.set(def.id, caps);
+    }, () => undefined);
+    capabilityProbes.set(key, probe);
+    return probe;
+}
 /**
  * The effort-level override a live model catalog earns, if any.
  *
@@ -166,12 +206,12 @@ async function probeCapabilities(def, launchPath, env) {
  * @complexity O(1) here; the hook's own cost is documented on `deriveReasoningOptions`.
  */
 function derivedReasoningOverride(def, models) {
-    const derived = def.deriveReasoningOptions?.(models);
+    const derived = def.deriveReasoningOptions?.({ models: models });
     return derived && derived.length > 0 ? { reasoningOptions: derived } : {};
 }
 /** The env every probe of one def spawns with — the same env a real run would see. */
 function probeEnvForLaunch(def, configuredEnv, launch) {
-    return applyAgentLaunchEnv(spawnEnvForAgent(def.id, { ...process.env, ...(def.env || {}) }, configuredEnv, undefined, {}), launch);
+    return applyAgentLaunchEnv({ env: spawnEnvForAgent({ agentId: def.id, baseEnv: { ...process.env, ...(def.env || {}) } }, { configuredEnv: configuredEnv, hooks: {} }), launch: launch });
 }
 /**
  * The model half of {@link detectAgents} for ONE def, without the `--version`/`--help`/auth probes:
@@ -185,9 +225,9 @@ function probeEnvForLaunch(def, configuredEnv, launch) {
  * `source: 'fallback'` (including when the binary is not found). Never rejects.
  * @complexity At most one model-listing spawn, bounded by the def's own timeout.
  */
-export async function probeAgentModels(def, configuredEnv = {}, amrProfileResolver = noopAmrProfileResolver) {
+export async function probeAgentModels({ def }, { configuredEnv = {}, amrProfileResolver = noopAmrProfileResolver } = {}) {
     try {
-        const launch = resolveAgentLaunch(def, configuredEnv);
+        const launch = resolveAgentLaunch({ def: def }, { configuredEnv: configuredEnv });
         if (!launch.launchPath)
             return { models: def.fallbackModels, source: 'fallback' };
         const probeEnv = probeEnvForLaunch(def, configuredEnv, launch);
@@ -209,14 +249,14 @@ async function probe(def, configuredEnv = {}, amrProfileResolver) {
     // detection probes the shim but chat/run spawns the native binary, the
     // UI incorrectly reports "not installed" until the user pins the bin
     // override by hand even though the real launch path is healthy.
-    const launch = resolveAgentLaunch(def, configuredEnv);
+    const launch = resolveAgentLaunch({ def: def }, { configuredEnv: configuredEnv });
     if (!launch.selectedPath || !launch.launchPath) {
-        return unavailableAgent(def, [buildExecutableDiagnostic(def, configuredEnv)]);
+        return unavailableAgent(def, [buildExecutableDiagnostic({ def: def }, { configuredEnv: configuredEnv })]);
     }
     const probeEnv = probeEnvForLaunch(def, configuredEnv, launch);
     const outcome = await probeVersionAtPath(def, launch.launchPath, probeEnv);
     if (outcome.kind === 'not-invocable') {
-        return unavailableAgent(def, [buildNotInvocableDiagnostic(def, launch, outcome.cause)]);
+        return unavailableAgent(def, [buildNotInvocableDiagnostic({ def: def, launch: launch, cause: outcome.cause })]);
     }
     // The version probe must finish first (it gates availability), but the
     // three post-version probes are independent reads — run them
@@ -226,13 +266,13 @@ async function probe(def, configuredEnv = {}, amrProfileResolver) {
     const [caps, modelResult, auth] = await Promise.all([
         probeCapabilities(def, launch.launchPath, probeEnv),
         fetchModels(def, launch.launchPath, probeEnv),
-        probeAgentAuthStatus(def, launch.launchPath, probeEnv),
+        probeAgentAuthStatus({ def: def, resolvedBin: launch.launchPath, env: probeEnv }),
     ]);
     const surfacedModelResult = withRememberedAmrModels(def, probeEnv, modelResult, amrProfileResolver);
     if (caps) {
         agentCapabilities.set(def.id, caps);
     }
-    const authDiagnostic = auth ? buildAuthDiagnostic(def, auth) : null;
+    const authDiagnostic = auth ? buildAuthDiagnostic({ def: def, auth: auth }) : null;
     return {
         ...stripFns(def),
         ...derivedReasoningOverride(def, surfacedModelResult.models),
@@ -243,7 +283,7 @@ async function probe(def, configuredEnv = {}, amrProfileResolver) {
         version: outcome.version,
         ...(auth ? { authStatus: auth.status, ...(auth.message ? { authMessage: auth.message } : {}) } : {}),
         ...(authDiagnostic ? { diagnostics: [authDiagnostic] } : {}),
-        ...installMetaForAgent(def.id),
+        ...installMetaForAgent({ agentId: def.id }),
     };
 }
 function stripFns(def) {
@@ -289,9 +329,9 @@ function rememberDetectedModelList(def, configuredEnv, models, amrProfileResolve
     const scope = def.id === 'amr'
         ? amrModelScopeFromEnv({ ...process.env, ...(def.env || {}), ...configuredEnv }, amrProfileResolver)
         : null;
-    rememberLiveModels(def.id, models, scope);
+    rememberLiveModels({ agentId: def.id, models: models }, { scope: scope });
 }
-export async function detectAgents(configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver) {
+export async function detectAgents({}, { configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver } = {}) {
     const results = await Promise.all(AGENT_DEFS.map((def) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver)));
     // Refresh the validation cache from whatever we just surfaced to the UI
     // so a chat endpoint can accept any model the user could have just
@@ -311,7 +351,7 @@ export async function detectAgents(configuredEnvByAgent = {}, amrProfileResolver
 // validation cache is refreshed per-agent (same effect as the batch path,
 // just incrementally). `detectAgents` keeps the array contract for callers
 // that don't care about incremental delivery.
-export async function* detectAgentsStream(configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver) {
+export async function* detectAgentsStream({}, { configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver } = {}) {
     const tagged = AGENT_DEFS.map((def, index) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver).then((agent) => {
         rememberDetectedLiveModels(def, configuredEnvByAgent?.[def.id] ?? {}, agent, amrProfileResolver);
         return { index, agent };

package/dist/diagnostics.d.ts

@@ -1,8 +1,19 @@
 import type { AgentLaunchResolution } from './launch.js';
 import type { AgentAuthProbeResult } from './auth.js';
 import type { AgentDiagnostic, RuntimeAgentDef } from './types.js';
-export declare function buildExecutableDiagnostic(def: Pick<RuntimeAgentDef, 'id' | 'name' | 'bin'>, configuredEnv?: Record<string, string>): AgentDiagnostic;
+export declare function buildExecutableDiagnostic({ def }: {
+    def: Pick<RuntimeAgentDef, 'id' | 'name' | 'bin'>;
+}, { configuredEnv }?: {
+    configuredEnv?: Record<string, string>;
+}): AgentDiagnostic;
 export type NotInvocableCause = 'not-executable' | 'missing-target';
-export declare function buildNotInvocableDiagnostic(def: Pick<RuntimeAgentDef, 'id' | 'name'>, launch: Pick<AgentLaunchResolution, 'selectedPath' | 'launchPath'>, cause: NotInvocableCause): AgentDiagnostic;
-export declare function buildAuthDiagnostic(def: Pick<RuntimeAgentDef, 'id' | 'name'>, auth: AgentAuthProbeResult): AgentDiagnostic | null;
+export declare function buildNotInvocableDiagnostic({ def, launch, cause }: {
+    def: Pick<RuntimeAgentDef, 'id' | 'name'>;
+    launch: Pick<AgentLaunchResolution, 'selectedPath' | 'launchPath'>;
+    cause: NotInvocableCause;
+}): AgentDiagnostic;
+export declare function buildAuthDiagnostic({ def, auth }: {
+    def: Pick<RuntimeAgentDef, 'id' | 'name'>;
+    auth: AgentAuthProbeResult;
+}): AgentDiagnostic | null;
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.js

@@ -17,15 +17,15 @@ import { agentBinEnvKey, agentSearchDirs } from './executables.js';
 // land without ballooning the response payload.
 const MAX_SEARCHED_DIRS = 24;
 function setEnvIntent(agentId) {
-    const envKey = agentBinEnvKey(agentId);
+    const envKey = agentBinEnvKey({ agentId: agentId });
     return envKey ? [{ kind: 'setEnv', envKey }] : [];
 }
 // The agent is not resolvable at all: either nothing matched on PATH, or a
 // user-supplied `*_BIN` override points at a missing/invalid file. The two
 // cases get different copy + fix affordances because the remedy differs
 // (install / point us at the binary vs. fix or clear the override).
-export function buildExecutableDiagnostic(def, configuredEnv = {}) {
-    const envKey = agentBinEnvKey(def.id);
+export function buildExecutableDiagnostic({ def }, { configuredEnv = {} } = {}) {
+    const envKey = agentBinEnvKey({ agentId: def.id });
     const overrideRaw = envKey ? configuredEnv?.[envKey]?.trim() : '';
     if (envKey && overrideRaw) {
         return {
@@ -48,7 +48,7 @@ export function buildExecutableDiagnostic(def, configuredEnv = {}) {
 // are real binaries that need their executable bit restored; missing-target
 // failures are usually leftover npm/nvm/mise shims whose underlying target
 // was uninstalled.
-export function buildNotInvocableDiagnostic(def, launch, cause) {
+export function buildNotInvocableDiagnostic({ def, launch, cause }) {
     if (cause === 'not-executable') {
         return {
             reason: 'not-executable',
@@ -71,7 +71,7 @@ export function buildNotInvocableDiagnostic(def, launch, cause) {
 // for adapters that declare a cheap, side-effect-free authProbe; until an
 // adapter also declares a spawn-safe OAuth producer, diagnostics point at
 // docs.
-export function buildAuthDiagnostic(def, auth) {
+export function buildAuthDiagnostic({ def, auth }) {
     if (auth.status === 'ok')
         return null;
     const signInIntent = { kind: 'openDocs' };

package/dist/env.d.ts

@@ -3,17 +3,29 @@ export interface SpawnEnvHooks {
     /**
      * Per-agent env customization (e.g. vela/AMR profile forwarding,
      * analytics identity, a routed model's endpoint override). Called after
-     * the proxy-aware merge, before the built-in OpenCode/MiMo housekeeping.
+     * the proxy-aware merge and built-in housekeeping, before `sandboxOverlay`.
      * Return a partial env to merge in, or nothing to leave `env` as-is
      * (mutating `env` directly is also fine — it's a live object).
      */
-    perAgentEnv?: (agentId: string, env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv | void;
+    perAgentEnv?: (requiredArgs: {
+        agentId: string;
+        env: NodeJS.ProcessEnv;
+    }) => NodeJS.ProcessEnv | void;
     /**
      * Applied last, after all other env composition. A host with a
      * sandboxed/jailed spawn mode plugs its own env constraints in here.
      */
-    sandboxOverlay?: (env: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
+    sandboxOverlay?: (requiredArgs: {
+        env: NodeJS.ProcessEnv;
+    }) => NodeJS.ProcessEnv;
 }
-export declare function spawnEnvForAgent(agentId: string, baseEnv: RuntimeEnvMap, configuredEnv?: unknown, systemProxyEnv?: RuntimeEnvMap, hooks?: SpawnEnvHooks): NodeJS.ProcessEnv;
+export declare function spawnEnvForAgent({ agentId, baseEnv }: {
+    agentId: string;
+    baseEnv: RuntimeEnvMap;
+}, { configuredEnv, systemProxyEnv, hooks }?: {
+    configuredEnv?: unknown;
+    systemProxyEnv?: RuntimeEnvMap;
+    hooks?: SpawnEnvHooks;
+}): NodeJS.ProcessEnv;
 export {};
 //# sourceMappingURL=env.d.ts.map

package/dist/env.js

@@ -12,7 +12,7 @@
  * classification anticipated — it read OD's own app-config subsystem, OD's
  * sandbox-mode subsystem, and vela/AMR-specific env forwarding including a
  * literal product-name identity value and two product-prefixed env var
- * names (see `source-map.md` for the exact originals). None of that is
+ * names (see `archived provenance ledger` for the exact originals). None of that is
  * ported:
  *
  * - `mergeProxyAwareEnv` / `resolveSystemProxyEnv` now come from
@@ -30,7 +30,7 @@
  *   was itself product-branded. A host that needs equivalent trace
  *   correlation can build it as a `perAgentEnv` hook.
  *
- * See `source-map.md` for the full accounting.
+ * See `archived provenance ledger` for the full accounting.
  */
 import os from 'node:os';
 import { mergeProxyAwareEnv, resolveSystemProxyEnv } from '@jini-ai/platform';
@@ -43,8 +43,8 @@ function stripKeysCaseInsensitive(env, keysToStrip) {
             delete env[key];
     }
 }
-export function spawnEnvForAgent(agentId, baseEnv, configuredEnv = {}, systemProxyEnv = resolveSystemProxyEnv(), hooks = {}) {
-    const expandedConfiguredEnv = expandConfiguredEnv(configuredEnv);
+export function spawnEnvForAgent({ agentId, baseEnv }, { configuredEnv = {}, systemProxyEnv = resolveSystemProxyEnv(), hooks = {} } = {}) {
+    const expandedConfiguredEnv = expandConfiguredEnv({ configuredEnv: configuredEnv });
     const env = mergeProxyAwareEnv(process.platform, systemProxyEnv, baseEnv, expandedConfiguredEnv);
     if (agentId === 'amr') {
         // `execAgentFile` REPLACES the child environment (execFile with `env`
@@ -59,7 +59,7 @@ export function spawnEnvForAgent(agentId, baseEnv, configuredEnv = {}, systemPro
                 env.HOME = home;
         }
         if (!env.VELA_OPENCODE_BIN?.trim()) {
-            const opencodeBin = resolveAmrOpenCodeExecutable(env);
+            const opencodeBin = resolveAmrOpenCodeExecutable({}, { env: env });
             if (opencodeBin)
                 env.VELA_OPENCODE_BIN = opencodeBin;
         }
@@ -87,9 +87,9 @@ export function spawnEnvForAgent(agentId, baseEnv, configuredEnv = {}, systemPro
             env.MIMOCODE_DISABLE_PROJECT_CONFIG = 'true';
         }
     }
-    const perAgentOverrides = hooks.perAgentEnv?.(agentId, env);
+    const perAgentOverrides = hooks.perAgentEnv?.({ agentId: agentId, env: env });
     if (perAgentOverrides)
         Object.assign(env, perAgentOverrides);
-    return hooks.sandboxOverlay ? hooks.sandboxOverlay(env) : env;
+    return hooks.sandboxOverlay ? hooks.sandboxOverlay({ env: env }) : env;
 }
 //# sourceMappingURL=env.js.map

package/dist/executables.d.ts

@@ -5,18 +5,34 @@ import type { RuntimeAgentDef } from './types.js';
  * at startup if it wants its own namespaced env vars instead of the
  * generic defaults.
  */
-export declare function configureExecutableResolutionEnv(overrides: {
-    agentHomeEnvVar?: string;
-    resourceRootEnvVar?: string;
+export declare function configureExecutableResolutionEnv({ overrides }: {
+    overrides: {
+        agentHomeEnvVar?: string;
+        resourceRootEnvVar?: string;
+    };
 }): void;
 export declare function userToolchainBinDirs(): string[];
 export declare function agentSearchDirs(): string[];
-export declare function agentBinEnvKey(agentId: string | undefined): string | null;
-export declare function resolveOnPath(bin: string): string | null;
-export declare function resolveAmrOpenCodeExecutable(env?: Record<string, string | undefined>): string | null;
+export declare function agentBinEnvKey({ agentId }: {
+    agentId: string | undefined;
+}): string | null;
+export declare function resolveOnPath({ bin }: {
+    bin: string;
+}): string | null;
+export declare function resolveAmrOpenCodeExecutable({}: {}, { env }?: {
+    env?: Record<string, string | undefined>;
+}): string | null;
 export declare function codexAppBundleCandidates(): string[];
-export declare function resolveAgentExecutable(def: RuntimeAgentDef, configuredEnv?: Record<string, string>): string | null;
-export declare function inspectAgentExecutableResolution(def: RuntimeAgentDef, configuredEnv?: Record<string, string>): {
+export declare function resolveAgentExecutable({ def }: {
+    def: RuntimeAgentDef;
+}, { configuredEnv }?: {
+    configuredEnv?: Record<string, string>;
+}): string | null;
+export declare function inspectAgentExecutableResolution({ def }: {
+    def: RuntimeAgentDef;
+}, { configuredEnv }?: {
+    configuredEnv?: Record<string, string>;
+}): {
     configuredOverridePath: string | null;
     pathResolvedPath: string | null;
     selectedPath: string | null;

package/dist/executables.js

@@ -10,14 +10,14 @@
  *
  * 1. `wellKnownUserToolchainBins` now comes from `@jini-ai/platform` instead of
  *    the OD workspace package it originally shipped from (same function,
- *    already verbatim-lifted — see `@jini-ai/platform`'s own `source-map.md`).
+ *    already verbatim-lifted — see `@jini-ai/platform`'s own `archived provenance ledger`).
  * 2. De-branded: the origin's product-prefixed agent-home / resource-root
  *    env var names and its sandbox-runtime-config integration (an
  *    OD-daemon-level subsystem out of this package's charter) are replaced
  *    by `configureExecutableResolutionEnv()` — an injectable pair of
  *    env-var names, defaulting to `AGENT_RUNTIME_HOME` /
  *    `AGENT_RUNTIME_RESOURCE_ROOT`, with no sandbox dependency. See
- *    `source-map.md` for the exact original names.
+ *    `archived provenance ledger` for the exact original names.
  */
 import { accessSync, constants, existsSync, statSync } from 'node:fs';
 import { delimiter } from 'node:path';
@@ -65,7 +65,7 @@ const executableResolutionEnv = {
  * at startup if it wants its own namespaced env vars instead of the
  * generic defaults.
  */
-export function configureExecutableResolutionEnv(overrides) {
+export function configureExecutableResolutionEnv({ overrides }) {
     if (overrides.agentHomeEnvVar)
         executableResolutionEnv.agentHomeEnvVar = overrides.agentHomeEnvVar;
     if (overrides.resourceRootEnvVar)
@@ -144,12 +144,12 @@ export function agentSearchDirs() {
 // The `*_BIN` environment variable that overrides PATH detection for a given
 // agent id (e.g. `cursor-agent` → `CURSOR_AGENT_BIN`), or null when the agent
 // has no override key. Drives the `setEnv` / `clearEnv` fix intents.
-export function agentBinEnvKey(agentId) {
+export function agentBinEnvKey({ agentId }) {
     if (!agentId)
         return null;
     return AGENT_BIN_ENV_KEYS.get(agentId) ?? null;
 }
-export function resolveOnPath(bin) {
+export function resolveOnPath({ bin }) {
     const exts = process.platform === 'win32'
         ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
         : [''];
@@ -176,7 +176,7 @@ function looksExecutableOnWindows(filePath) {
 function executableFilePath(raw) {
     if (typeof raw !== 'string' || raw.trim().length === 0)
         return null;
-    const expanded = expandHomePath(raw.trim());
+    const expanded = expandHomePath({ value: raw.trim() });
     if (!path.isAbsolute(expanded))
         return null;
     try {
@@ -205,7 +205,7 @@ function configuredExecutableOverride(def, configuredEnv = {}) {
         return null;
     return executableFilePath(configuredEnv?.[envKey]);
 }
-export function resolveAmrOpenCodeExecutable(env = process.env) {
+export function resolveAmrOpenCodeExecutable({}, { env = process.env } = {}) {
     const configured = executableFilePath(env.VELA_OPENCODE_BIN);
     if (configured)
         return configured;
@@ -222,7 +222,7 @@ export function resolveAmrOpenCodeExecutable(env = process.env) {
                 return bundled;
         }
     }
-    return resolveOnPath('opencode-cli') ?? resolveOnPath('opencode');
+    return resolveOnPath({ bin: 'opencode-cli' }) ?? resolveOnPath({ bin: 'opencode' });
 }
 // The AMR (vela) OpenCode companion ships as a
 // `<resourceRoot>/bin/libexec/opencode/opencode` *executable file*, not just
@@ -257,7 +257,7 @@ function packagedBuiltInExecutable(def, configuredEnv = {}) {
     const resourceRoot = process.env[executableResolutionEnv.resourceRootEnvVar]?.trim();
     if (!resourceRoot)
         return null;
-    if (!resolveAmrOpenCodeExecutable({ ...process.env, ...configuredEnv }) &&
+    if (!resolveAmrOpenCodeExecutable({}, { env: { ...process.env, ...configuredEnv } }) &&
         !packagedVelaOpenCodeCompanionTree(resourceRoot)) {
         return null;
     }
@@ -320,10 +320,10 @@ export function codexAppBundleCandidates() {
     }
     return candidates;
 }
-export function resolveAgentExecutable(def, configuredEnv = {}) {
-    return inspectAgentExecutableResolution(def, configuredEnv).selectedPath;
+export function resolveAgentExecutable({ def }, { configuredEnv = {} } = {}) {
+    return inspectAgentExecutableResolution({ def: def }, { configuredEnv: configuredEnv }).selectedPath;
 }
-export function inspectAgentExecutableResolution(def, configuredEnv = {}) {
+export function inspectAgentExecutableResolution({ def }, { configuredEnv = {} } = {}) {
     if (!def?.bin) {
         return {
             configuredOverridePath: null,
@@ -338,7 +338,7 @@ export function inspectAgentExecutableResolution(def, configuredEnv = {}) {
     ];
     let pathResolvedPath = null;
     for (const bin of candidates) {
-        const resolved = resolveOnPath(bin);
+        const resolved = resolveOnPath({ bin: bin });
         if (resolved) {
             pathResolvedPath = resolved;
             break;