@jini-ai/agent-runtime 0.4.4 → 0.4.5

package/dist/detection.js

@@ -1,3 +1,7 @@
+import { createHash } from 'node:crypto';
+import { userToolchainBinDirs } from './executables.js';
+import { defaultRuntimeState } from './runtime-state.js';
+import { getRuntimeModelDiscoveryDeps } from './model-discovery-adapters.js';
 /**
  * @module detection
  *
@@ -14,7 +18,6 @@
 import { execAgentFile } from './invocation.js';
 import { offlineSnapshot, modelDiscoveryForDef } from './model-discovery.js';
 import { rememberLiveModels } from './models.js';
-import { agentCapabilities } from './capabilities.js';
 import { installMetaForAgent } from './metadata.js';
 import { AGENT_DEFS } from './registry.js';
 import { applyAgentLaunchEnv, resolveAgentLaunch } from './launch.js';
@@ -109,8 +112,8 @@ function unavailableAgent(def, diagnostics = []) {
 }
 // Probe the agent's `--help` once and record which advertised flags the
 // installed CLI supports, so buildArgs can consult the cache. Extracted
-// from the main probe so it can run concurrently with model + auth probing
-// instead of blocking them. Returns the capability map (or null when the
+// from the main probe so it can run before model discovery. It shares the existing
+// capability cache with real launches. Returns the capability map (or null when the
 // agent declares no help/capability metadata or the probe failed).
 async function probeCapabilities(def, launchPath, env) {
     if (!def.helpArgs || !def.capabilityFlags)
@@ -133,8 +136,6 @@ async function readCapabilities(helpArgs, capabilityFlags, launchPath, env) {
     }
     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.
  *
@@ -154,7 +155,9 @@ const capabilityProbes = new Map();
  * @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 }) {
+export function ensureAgentCapabilities({ def, launchPath, env }, { state = defaultRuntimeState, probe = ({ helpArgs, capabilityFlags, launchPath, env }) => readCapabilities(helpArgs, capabilityFlags, launchPath, env) } = {}) {
+    const agentCapabilities = state.capabilities;
+    const capabilityProbes = state.capabilityProbes;
     const { helpArgs, capabilityFlags } = def;
     if (!helpArgs || !capabilityFlags || agentCapabilities.has(def.id))
         return Promise.resolve();
@@ -162,12 +165,12 @@ export function ensureAgentCapabilities({ def, launchPath, env }) {
     const existing = capabilityProbes.get(key);
     if (existing)
         return existing;
-    const probe = readCapabilities(helpArgs, capabilityFlags, launchPath, env).then((caps) => {
+    const pending = probe({ helpArgs, capabilityFlags, launchPath, env }, {}).then((caps) => {
         if (!agentCapabilities.has(def.id))
             agentCapabilities.set(def.id, caps);
     }, () => undefined);
-    capabilityProbes.set(key, probe);
-    return probe;
+    capabilityProbes.set(key, pending);
+    return pending;
 }
 /**
  * The effort-level override a live model catalog earns, if any.
@@ -186,8 +189,8 @@ function derivedReasoningOverride(def, 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({ env: spawnEnvForAgent({ agentId: def.id, baseEnv: { ...process.env, ...(def.env || {}) } }, { configuredEnv: configuredEnv, hooks: {} }), launch: launch });
+function probeEnvForLaunch(def, configuredEnv, launch, options = {}) {
+    return applyAgentLaunchEnv({ env: spawnEnvForAgent({ agentId: def.id, baseEnv: { ...(options.env ?? process.env), ...(def.env || {}) } }, { configuredEnv: configuredEnv, hooks: {} }), launch: launch }, { appendPathDirs: userToolchainBinDirs({}, options) });
 }
 function unavailableModels(def) {
     const catalog = offlineSnapshot('', Date.now(), def.fallbackModels);
@@ -205,15 +208,15 @@ function unavailableModels(def) {
  * `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, context, deps, force = false } = {}) {
+export async function probeAgentModels({ def }, { configuredEnv = {}, amrProfileResolver = noopAmrProfileResolver, context, deps, force = false, state = defaultRuntimeState, env = process.env } = {}) {
     try {
-        const launch = resolveAgentLaunch({ def: def }, { configuredEnv: configuredEnv });
+        const launch = resolveAgentLaunch({ def: def }, { configuredEnv: configuredEnv, state, env });
         if (!launch.launchPath)
             return unavailableModels(def);
-        const probeEnv = probeEnvForLaunch(def, configuredEnv, launch);
-        const fetched = await fetchModels(def, launch.launchPath, probeEnv, { ...(context ? { context } : {}), ...(deps ? { deps } : {}), force });
+        const probeEnv = probeEnvForLaunch(def, configuredEnv, launch, { state, env });
+        const fetched = await fetchModels(def, launch.launchPath, probeEnv, { ...(context ? { context } : {}), deps: deps ?? getRuntimeModelDiscoveryDeps({ state }), force });
         const result = withRememberedAmrModels(def, probeEnv, fetched, amrProfileResolver);
-        rememberDetectedModelList(def, configuredEnv, result.models, amrProfileResolver);
+        rememberDetectedModelList(def, configuredEnv, result.models, amrProfileResolver, { state, env });
         return result;
     }
     catch {
@@ -229,28 +232,34 @@ async function probe(def, configuredEnv = {}, amrProfileResolver, options = {})
     // 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: def }, { configuredEnv: configuredEnv });
+    const launch = resolveAgentLaunch({ def: def }, { configuredEnv: configuredEnv, ...(options.state ? { state: options.state } : {}), ...(options.env ? { env: options.env } : {}) });
     if (!launch.selectedPath || !launch.launchPath) {
-        return unavailableAgent(def, [buildExecutableDiagnostic({ def: def }, { configuredEnv: configuredEnv })]);
+        return unavailableAgent(def, [buildExecutableDiagnostic({ def: def }, { configuredEnv: configuredEnv, ...(options.state ? { state: options.state } : {}), ...(options.env ? { env: options.env } : {}) })]);
     }
-    const probeEnv = probeEnvForLaunch(def, configuredEnv, launch);
+    const probeEnv = probeEnvForLaunch(def, configuredEnv, launch, options);
     const outcome = await probeVersionAtPath(def, launch.launchPath, probeEnv);
     if (outcome.kind === 'not-invocable') {
         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
-    // concurrently so a single agent's detection wall is
-    // max(help, models, auth) instead of the sum. `--help` capabilities are
-    // cached on `agentCapabilities` for buildArgs to consult.
-    const [caps, modelResult, auth] = await Promise.all([
-        probeCapabilities(def, launch.launchPath, probeEnv),
-        fetchModels(def, launch.launchPath, probeEnv, { version: outcome.version, ...options }),
-        probeAgentAuthStatus({ def: def, resolvedBin: launch.launchPath, env: probeEnv }),
-    ]);
+    // The version probe must finish first (it gates availability). Cheap help/auth checks
+    // precede model discovery; the shared process scheduler prevents concurrent CLI startups.
+    // Capability evidence belongs to the existing ensureAgentCapabilities cache, also used by runs.
+    const runtimeState = options.state ?? defaultRuntimeState;
+    const capabilityKey = `${def.id}\u0000${launch.launchPath}`;
+    if (options.force || !runtimeState.capabilityProbes.has(capabilityKey)) {
+        runtimeState.capabilities.delete(def.id);
+        if (options.force)
+            runtimeState.capabilityProbes.delete(capabilityKey);
+    }
+    await ensureAgentCapabilities({ def, launchPath: launch.launchPath, env: probeEnv }, { state: runtimeState,
+        probe: async () => (await probeCapabilities(def, launch.launchPath, probeEnv)) ?? {},
+    });
+    const caps = runtimeState.capabilities.get(def.id);
+    const auth = await probeAgentAuthStatus({ def, resolvedBin: launch.launchPath, env: probeEnv });
+    const modelResult = await fetchModels(def, launch.launchPath, probeEnv, { version: outcome.version, ...options, deps: options.deps ?? getRuntimeModelDiscoveryDeps({ state: runtimeState }) });
     const surfacedModelResult = withRememberedAmrModels(def, probeEnv, modelResult, amrProfileResolver);
     if (caps) {
-        agentCapabilities.set(def.id, caps);
+        (options.state ?? defaultRuntimeState).capabilities.set(def.id, caps);
     }
     const authDiagnostic = auth ? buildAuthDiagnostic({ def: def, auth: auth }) : null;
     return {
@@ -290,8 +299,38 @@ function stripFns(def) {
     const { discoverModels: _discoverModels, resolveDefaultModel: _resolveDefaultModel, buildArgs: _buildArgs, listModels: _listModels, fetchModels: _fetchModels, deriveReasoningOptions: _deriveReasoningOptions, fallbackModels: _fallbackModels, fallbackModelsAssertedAt: _fallbackModelsAssertedAt, helpArgs: _helpArgs, capabilityFlags: _capabilityFlags, fallbackBins: _fallbackBins, versionProbeTimeoutMs: _versionProbeTimeoutMs, maxPromptArgBytes: _maxPromptArgBytes, env: _env, inactivityTimeoutMs: _inactivityTimeoutMs, authProbe: _authProbe, needsAgentLogFile: _needsAgentLogFile, stdoutPolicy: _stdoutPolicy, runtimeLock: _runtimeLock, ...rest } = def;
     return rest;
 }
-async function safeProbe(def, configuredEnv = {}, amrProfileResolver, options = {}) {
+/** Cache complete detection per host and effective launch. No TTL re-spawns version/help/auth.
+ * Explicit force queues after the current scan, so a rescan cannot overlap its predecessor.
+ * Hash credentials rather than retaining them in keys. @complexity O(e) launch-env hashing. */
+function safeProbe(def, configuredEnv, amrProfileResolver, options = {}) {
+    const state = options.state ?? defaultRuntimeState;
+    let key;
+    try {
+        key = detectionCacheKey({ def, configuredEnv, options, state });
+    }
+    catch {
+        return Promise.resolve(unavailableAgent(def));
+    }
+    const previous = state.detections.get(key);
+    if (previous && !options.force)
+        return previous;
+    const pending = (previous ?? Promise.resolve()).then(() => executeSafeProbe(def, configuredEnv, amrProfileResolver, options));
+    state.detections.set(key, pending);
+    return pending;
+}
+/** Effective launch material is hashed, so cache keys never expose credentials.
+ * Legacy remembered-model profile resolution must not gate executable availability. */
+function detectionCacheKey({ def, configuredEnv, options, state }, _options = {}) {
+    const launch = resolveAgentLaunch({ def }, { configuredEnv, state, ...(options.env ? { env: options.env } : {}) });
+    const env = options.env ?? process.env;
+    return createHash('sha256').update(JSON.stringify({ id: def.id, path: launch.launchPath,
+        env: Object.entries(env).sort(([a], [b]) => a.localeCompare(b)), configuredEnv,
+        context: options.context })).digest('hex');
+}
+async function executeSafeProbe(def, configuredEnv = {}, amrProfileResolver, options = {}) {
     try {
+        if (options.probeAgent)
+            return await options.probeAgent({ def, configuredEnv, amrProfileResolver }, options);
         return await probe(def, configuredEnv, amrProfileResolver, options);
     }
     catch {
@@ -302,19 +341,19 @@ async function safeProbe(def, configuredEnv = {}, amrProfileResolver, options =
         return unavailableAgent(def);
     }
 }
-function rememberDetectedLiveModels(def, configuredEnv, agent, amrProfileResolver) {
-    rememberDetectedModelList(def, configuredEnv, agent.models, amrProfileResolver);
+function rememberDetectedLiveModels(def, configuredEnv, agent, amrProfileResolver, options = {}) {
+    rememberDetectedModelList(def, configuredEnv, agent.models, amrProfileResolver, options);
 }
-function rememberDetectedModelList(def, configuredEnv, models, amrProfileResolver) {
+function rememberDetectedModelList(def, configuredEnv, models, amrProfileResolver, options = {}) {
     if (def.id === 'amr' && models.length === 0)
         return;
     const scope = def.id === 'amr'
-        ? amrModelScopeFromEnv({ ...process.env, ...(def.env || {}), ...configuredEnv }, amrProfileResolver)
+        ? amrModelScopeFromEnv({ ...(options.env ?? process.env), ...(def.env || {}), ...configuredEnv }, amrProfileResolver)
         : null;
-    rememberLiveModels({ agentId: def.id, models: models.filter((row) => row.identityKind !== 'routing-mode') }, { scope: scope });
+    rememberLiveModels({ agentId: def.id, models: models.filter((row) => row.identityKind !== 'routing-mode') }, { scope: scope, ...(options.state ? { state: options.state } : {}) });
 }
-export async function detectAgents({}, { configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver, modelContextByAgent = {}, modelDiscoveryDeps, force = false } = {}) {
-    const results = await Promise.all(AGENT_DEFS.map((def) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver, { ...(modelContextByAgent[def.id] ? { context: modelContextByAgent[def.id] } : {}), ...(modelDiscoveryDeps ? { deps: modelDiscoveryDeps } : {}), force })));
+export async function detectAgents({}, { configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver, modelContextByAgent = {}, modelDiscoveryDeps, force = false, state = defaultRuntimeState, env = process.env, probeAgent } = {}) {
+    const results = await Promise.all(AGENT_DEFS.map((def) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver, { ...(modelContextByAgent[def.id] ? { context: modelContextByAgent[def.id] } : {}), deps: modelDiscoveryDeps ?? getRuntimeModelDiscoveryDeps({ state }), force, state, env, ...(probeAgent ? { probeAgent } : {}) })));
     // 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
     // picked, including ones that only showed up after a CLI re-auth.
@@ -323,7 +362,7 @@ export async function detectAgents({}, { configuredEnvByAgent = {}, amrProfileRe
         // is in-bounds for `AGENT_DEFS` too — the assertion just satisfies
         // `noUncheckedIndexedAccess`.
         const def = AGENT_DEFS[index];
-        rememberDetectedLiveModels(def, configuredEnvByAgent?.[def.id] ?? {}, agent, amrProfileResolver);
+        rememberDetectedLiveModels(def, configuredEnvByAgent?.[def.id] ?? {}, agent, amrProfileResolver, { state, env });
     }
     return results;
 }
@@ -333,9 +372,9 @@ export async function detectAgents({}, { configuredEnvByAgent = {}, amrProfileRe
 // 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, modelContextByAgent = {}, modelDiscoveryDeps, force = false } = {}) {
-    const tagged = AGENT_DEFS.map((def, index) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver, { ...(modelContextByAgent[def.id] ? { context: modelContextByAgent[def.id] } : {}), ...(modelDiscoveryDeps ? { deps: modelDiscoveryDeps } : {}), force }).then((agent) => {
-        rememberDetectedLiveModels(def, configuredEnvByAgent?.[def.id] ?? {}, agent, amrProfileResolver);
+export async function* detectAgentsStream({}, { configuredEnvByAgent = {}, amrProfileResolver = noopAmrProfileResolver, modelContextByAgent = {}, modelDiscoveryDeps, force = false, state = defaultRuntimeState, env = process.env, probeAgent } = {}) {
+    const tagged = AGENT_DEFS.map((def, index) => safeProbe(def, configuredEnvByAgent?.[def.id] ?? {}, amrProfileResolver, { ...(modelContextByAgent[def.id] ? { context: modelContextByAgent[def.id] } : {}), deps: modelDiscoveryDeps ?? getRuntimeModelDiscoveryDeps({ state }), force, state, env, ...(probeAgent ? { probeAgent } : {}) }).then((agent) => {
+        rememberDetectedLiveModels(def, configuredEnvByAgent?.[def.id] ?? {}, agent, amrProfileResolver, { state, env });
         return { index, agent };
     }));
     const pending = new Set(tagged.keys());

package/dist/diagnostics.d.ts

@@ -1,9 +1,14 @@
+/**
+ * @module diagnostics
+ * Explain three detection failures: unresolved executable, uninvocable executable or missing authentication.
+ */
+import { type ExecutableResolutionOptions } from './executables.js';
 import type { AgentLaunchResolution } from './launch.js';
 import type { AgentAuthProbeResult } from './auth.js';
 import type { AgentDiagnostic, RuntimeAgentDef } from './types.js';
 export declare function buildExecutableDiagnostic({ def }: {
     def: Pick<RuntimeAgentDef, 'id' | 'name' | 'bin'>;
-}, { configuredEnv }?: {
+}, { configuredEnv, ...options }?: ExecutableResolutionOptions & {
     configuredEnv?: Record<string, string>;
 }): AgentDiagnostic;
 export type NotInvocableCause = 'not-executable' | 'missing-target';

package/dist/diagnostics.js

@@ -16,7 +16,7 @@ function setEnvIntent(agentId) {
 // 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 = {} } = {}) {
+export function buildExecutableDiagnostic({ def }, { configuredEnv = {}, ...options } = {}) {
     const envKey = agentBinEnvKey({ agentId: def.id });
     const overrideRaw = envKey ? configuredEnv?.[envKey]?.trim() : '';
     if (envKey && overrideRaw) {
@@ -32,7 +32,7 @@ export function buildExecutableDiagnostic({ def }, { configuredEnv = {} } = {})
         reason: 'not-on-path',
         severity: 'error',
         message: `${def.name} (\`${def.bin}\`) was not found on your PATH.`,
-        searchedDirs: agentSearchDirs().slice(0, MAX_SEARCHED_DIRS),
+        searchedDirs: agentSearchDirs({}, options).slice(0, MAX_SEARCHED_DIRS),
         fixActions: [{ kind: 'openInstall' }, ...setEnvIntent(def.id), { kind: 'rescan' }],
     };
 }

package/dist/executables.d.ts

@@ -1,4 +1,10 @@
+import { type AgentRuntimeState } from './runtime-state.js';
 import type { RuntimeAgentDef } from './types.js';
+/** Host environment and runtime state used by executable resolution. */
+export interface ExecutableResolutionOptions {
+    env?: NodeJS.ProcessEnv;
+    state?: AgentRuntimeState;
+}
 /**
  * Override the env var names `resolveDetectionHome` / the packaged-binary
  * lookup read. The host application (e.g. the OD adapter) calls this once
@@ -10,27 +16,27 @@ export declare function configureExecutableResolutionEnv({ overrides }: {
         agentHomeEnvVar?: string;
         resourceRootEnvVar?: string;
     };
+}, { state }?: {
+    state?: AgentRuntimeState;
 }): void;
-export declare function userToolchainBinDirs(): string[];
-export declare function agentSearchDirs(): string[];
+export declare function userToolchainBinDirs(_required?: Record<string, never>, options?: ExecutableResolutionOptions): string[];
+export declare function agentSearchDirs(_required?: Record<string, never>, options?: ExecutableResolutionOptions): string[];
 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[];
+}, options?: ExecutableResolutionOptions): string | null;
+export declare function resolveAmrOpenCodeExecutable({}: {}, { env, state }?: ExecutableResolutionOptions): string | null;
+export declare function codexAppBundleCandidates(_required?: Record<string, never>, options?: ExecutableResolutionOptions): string[];
 export declare function resolveAgentExecutable({ def }: {
     def: RuntimeAgentDef;
-}, { configuredEnv }?: {
+}, options?: ExecutableResolutionOptions & {
     configuredEnv?: Record<string, string>;
 }): string | null;
 export declare function inspectAgentExecutableResolution({ def }: {
     def: RuntimeAgentDef;
-}, { configuredEnv }?: {
+}, options?: ExecutableResolutionOptions & {
     configuredEnv?: Record<string, string>;
 }): {
     configuredOverridePath: string | null;

package/dist/executables.js

@@ -1,3 +1,4 @@
+import { defaultRuntimeState } from './runtime-state.js';
 /**
  * @module executables
  *
@@ -53,59 +54,58 @@ const AGENT_BIN_ENV_KEYS = new Map([
     ['trae-cli', 'TRAE_CLI_BIN'],
     ['vibe', 'VIBE_BIN'],
 ]);
-/** Env var names consulted by detection-home/resource-root resolution. Overridable via `configureExecutableResolutionEnv`. */
-const executableResolutionEnv = {
-    agentHomeEnvVar: 'AGENT_RUNTIME_HOME',
-    resourceRootEnvVar: 'AGENT_RUNTIME_RESOURCE_ROOT',
-};
 /**
  * Override the env var names `resolveDetectionHome` / the packaged-binary
  * lookup read. The host application (e.g. the OD adapter) calls this once
  * at startup if it wants its own namespaced env vars instead of the
  * generic defaults.
  */
-export function configureExecutableResolutionEnv({ overrides }) {
+export function configureExecutableResolutionEnv({ overrides }, { state = defaultRuntimeState } = {}) {
+    const executableResolutionEnv = state.executable.envNames;
     if (overrides.agentHomeEnvVar)
         executableResolutionEnv.agentHomeEnvVar = overrides.agentHomeEnvVar;
     if (overrides.resourceRootEnvVar)
         executableResolutionEnv.resourceRootEnvVar = overrides.resourceRootEnvVar;
 }
 const TOOLCHAIN_DIR_CACHE_TTL_MS = 5000;
-let cachedToolchainHome = null;
-let cachedToolchainDirs = null;
-let cachedToolchainDirsAt = 0;
+// Toolchain cache and env names live with the injected host state.
 // Resolve the home directory detection should search, honoring the
 // configured agent-home override env var. `hasOverride` lets callers scope
 // strictly to the override home (skipping real-machine system locations) so
 // sandboxed detection runs and tests stay deterministic instead of
 // reaching the host.
-function resolveDetectionHome() {
-    const homeOverride = process.env[executableResolutionEnv.agentHomeEnvVar];
-    return { home: homeOverride || homedir(), hasOverride: Boolean(homeOverride) };
+function resolveDetectionHome(options = {}) {
+    const env = options.env ?? process.env;
+    const homeOverride = env[(options.state ?? defaultRuntimeState).executable.envNames.agentHomeEnvVar];
+    return { home: homeOverride || env.HOME || env.USERPROFILE || homedir(), hasOverride: Boolean(homeOverride) };
 }
-function userToolchainDirs() {
-    const { home, hasOverride } = resolveDetectionHome();
+function userToolchainDirs(options = {}) {
+    const env = options.env ?? process.env;
+    const cache = (options.state ?? defaultRuntimeState).executable;
+    const { home, hasOverride } = resolveDetectionHome(options);
+    // Every environment field the existing toolchain adapter consults participates in the cache key.
+    const key = JSON.stringify([home, hasOverride, ...['VP_HOME', 'NPM_CONFIG_PREFIX', 'npm_config_prefix', 'APPDATA', 'LOCALAPPDATA', 'MISE_DATA_DIR', 'FNM_DIR'].map(name => env[name])]);
     const homeOverride = hasOverride ? home : undefined;
     const now = Date.now();
-    if (cachedToolchainHome === home &&
-        cachedToolchainDirs &&
-        now - cachedToolchainDirsAt < TOOLCHAIN_DIR_CACHE_TTL_MS) {
-        return cachedToolchainDirs;
+    if (cache.toolchainKey === key &&
+        cache.toolchainDirs &&
+        now - cache.toolchainDirsAt < TOOLCHAIN_DIR_CACHE_TTL_MS) {
+        return cache.toolchainDirs;
     }
-    cachedToolchainHome = home;
-    cachedToolchainDirsAt = now;
+    cache.toolchainKey = key;
+    cache.toolchainDirsAt = now;
     // When the agent-home override is set, scope the search strictly to the
     // override home: skip Homebrew / /usr/local *and* pass an empty env so
     // that a developer or CI runner with NPM_CONFIG_PREFIX /
     // npm_config_prefix exported can't leak the real machine's <prefix>/bin
     // into a sandboxed detection run. Without this, tests that build a tmp
     // home would be machine-environment-dependent.
-    cachedToolchainDirs = wellKnownUserToolchainBins({
+    cache.toolchainDirs = wellKnownUserToolchainBins({
         home,
         includeSystemBins: process.platform !== 'win32' && !homeOverride,
-        env: homeOverride ? {} : process.env,
+        env: homeOverride ? {} : env,
     });
-    return cachedToolchainDirs;
+    return cache.toolchainDirs;
 }
 // The user-level toolchain bin directories (Homebrew, ~/.local/bin, ~/.bun/bin,
 // version-manager node dirs, npm prefixes, …) that binary *resolution* searches
@@ -113,18 +113,19 @@ function userToolchainDirs() {
 // a binary can resolve here yet fail to *execute* if its shebang interpreter
 // (e.g. `#!/usr/bin/env bun`) lives in one of these dirs and the spawn PATH
 // doesn't include it. Keeping resolution and spawn PATH symmetric fixes that.
-export function userToolchainBinDirs() {
-    return userToolchainDirs();
+export function userToolchainBinDirs(_required = {}, options = {}) {
+    return userToolchainDirs(options);
 }
-function resolvePathDirs() {
+function resolvePathDirs(options = {}) {
+    const env = options.env ?? process.env;
     const seen = new Set();
     const dirs = [
-        ...(process.env.PATH || '').split(delimiter),
+        ...(env.PATH || '').split(delimiter),
         // GUI launchers (macOS .app bundles, Linux .desktop files) often start
         // with a minimal PATH. Include common user-level CLI install locations
         // so agent detection matches the user's shell-installed tools,
         // especially Node version managers.
-        ...userToolchainDirs(),
+        ...userToolchainDirs(options),
     ];
     return dirs.filter((dir) => {
         if (!dir || seen.has(dir))
@@ -137,8 +138,8 @@ function resolvePathDirs() {
 // detection can attach it to a `not-on-path` diagnostic verbatim — the UI
 // shows the user where we actually looked before asking them to set an
 // explicit binary path, instead of recomputing PATH client-side.
-export function agentSearchDirs() {
-    return resolvePathDirs();
+export function agentSearchDirs(_required = {}, options = {}) {
+    return resolvePathDirs(options);
 }
 // 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
@@ -148,11 +149,12 @@ export function agentBinEnvKey({ agentId }) {
         return null;
     return AGENT_BIN_ENV_KEYS.get(agentId) ?? null;
 }
-export function resolveOnPath({ bin }) {
+export function resolveOnPath({ bin }, options = {}) {
+    const env = options.env ?? process.env;
     const exts = process.platform === 'win32'
-        ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+        ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
         : [''];
-    const dirs = resolvePathDirs();
+    const dirs = resolvePathDirs(options);
     for (const dir of dirs) {
         for (const ext of exts) {
             const full = path.join(dir, bin + ext);
@@ -162,17 +164,18 @@ export function resolveOnPath({ bin }) {
     }
     return null;
 }
-function looksExecutableOnWindows(filePath) {
+function looksExecutableOnWindows(filePath, options = {}) {
+    const env = options.env ?? process.env;
     const ext = path.extname(filePath).trim().toUpperCase();
     if (!ext)
         return false;
-    const executableExts = (process.env.PATHEXT || '.EXE;.CMD;.BAT')
+    const executableExts = (env.PATHEXT || '.EXE;.CMD;.BAT')
         .split(';')
         .map((value) => value.trim().toUpperCase())
         .filter(Boolean);
     return executableExts.includes(ext);
 }
-function executableFilePath(raw) {
+function executableFilePath(raw, options = {}) {
     if (typeof raw !== 'string' || raw.trim().length === 0)
         return null;
     const expanded = expandHomePath({ value: raw.trim() });
@@ -182,7 +185,7 @@ function executableFilePath(raw) {
         if (!statSync(expanded).isFile())
             return null;
         if (process.platform === 'win32') {
-            if (!looksExecutableOnWindows(expanded))
+            if (!looksExecutableOnWindows(expanded, options))
                 return null;
         }
         else {
@@ -198,30 +201,32 @@ function executableFilePath(raw) {
 // `def.bin` first, then walks `def.fallbackBins` in order. Used for agents
 // whose forks ship under a different binary name but speak the exact same
 // CLI. Returns null when no candidate is on PATH.
-function configuredExecutableOverride(def, configuredEnv = {}) {
+function configuredExecutableOverride(def, configuredEnv = {}, options = {}) {
     const envKey = AGENT_BIN_ENV_KEYS.get(def?.id);
     if (!envKey)
         return null;
-    return executableFilePath(configuredEnv?.[envKey]);
+    return executableFilePath(configuredEnv?.[envKey], options);
 }
-export function resolveAmrOpenCodeExecutable({}, { env = process.env } = {}) {
-    const configured = executableFilePath(env.VELA_OPENCODE_BIN);
+export function resolveAmrOpenCodeExecutable({}, { env = process.env, state = defaultRuntimeState } = {}) {
+    const options = { env, state };
+    const executableResolutionEnv = state.executable.envNames;
+    const configured = executableFilePath(env.VELA_OPENCODE_BIN, options);
     if (configured)
         return configured;
     // In packaged builds prefer the bundled companion under
     // `<resourceRoot>/bin/libexec/opencode/opencode` so a stale global
     // `opencode` on the user's PATH can't override the known-good build that
     // shipped with this app. PATH is only consulted as a last resort.
-    const resourceRoot = (env[executableResolutionEnv.resourceRootEnvVar] ?? process.env[executableResolutionEnv.resourceRootEnvVar])?.trim();
+    const resourceRoot = (env[executableResolutionEnv.resourceRootEnvVar])?.trim();
     if (resourceRoot) {
-        const bundledDir = packagedVelaOpenCodeCompanionTree(resourceRoot);
+        const bundledDir = packagedVelaOpenCodeCompanionTree(resourceRoot, options);
         if (bundledDir) {
-            const bundled = executableFilePath(path.join(bundledDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode'));
+            const bundled = executableFilePath(path.join(bundledDir, process.platform === 'win32' ? 'opencode.exe' : 'opencode'), options);
             if (bundled)
                 return bundled;
         }
     }
-    return resolveOnPath({ bin: 'opencode-cli' }) ?? resolveOnPath({ bin: 'opencode' });
+    return resolveOnPath({ bin: 'opencode-cli' }, options) ?? resolveOnPath({ bin: 'opencode' }, options);
 }
 // The AMR (vela) OpenCode companion ships as a
 // `<resourceRoot>/bin/libexec/opencode/opencode` *executable file*, not just
@@ -229,7 +234,7 @@ export function resolveAmrOpenCodeExecutable({}, { env = process.env } = {}) {
 // a false-positive availability path: `detectAgents()` would surface AMR as
 // available even though the first real run can't launch. Verify the inner
 // executable too.
-function packagedVelaOpenCodeCompanionTree(resourceRoot) {
+function packagedVelaOpenCodeCompanionTree(resourceRoot, options = {}) {
     const candidate = path.join(resourceRoot, 'bin', 'libexec', 'opencode');
     const exe = path.join(candidate, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
     try {
@@ -238,7 +243,7 @@ function packagedVelaOpenCodeCompanionTree(resourceRoot) {
         if (!statSync(exe).isFile())
             return null;
         if (process.platform === 'win32') {
-            if (!looksExecutableOnWindows(exe))
+            if (!looksExecutableOnWindows(exe, options))
                 return null;
         }
         else {
@@ -250,14 +255,16 @@ function packagedVelaOpenCodeCompanionTree(resourceRoot) {
         return null;
     }
 }
-function packagedBuiltInExecutable(def, configuredEnv = {}) {
+function packagedBuiltInExecutable(def, configuredEnv = {}, options = {}) {
     if (def.id !== 'amr')
         return null;
-    const resourceRoot = process.env[executableResolutionEnv.resourceRootEnvVar]?.trim();
+    const env = options.env ?? process.env;
+    const executableResolutionEnv = (options.state ?? defaultRuntimeState).executable.envNames;
+    const resourceRoot = env[executableResolutionEnv.resourceRootEnvVar]?.trim();
     if (!resourceRoot)
         return null;
-    if (!resolveAmrOpenCodeExecutable({}, { env: { ...process.env, ...configuredEnv } }) &&
-        !packagedVelaOpenCodeCompanionTree(resourceRoot)) {
+    if (!resolveAmrOpenCodeExecutable({}, { ...options, env: { ...env, ...configuredEnv } }) &&
+        !packagedVelaOpenCodeCompanionTree(resourceRoot, options)) {
         return null;
     }
     const candidate = path.join(resourceRoot, 'bin', process.platform === 'win32' ? 'vela.exe' : 'vela');
@@ -265,7 +272,7 @@ function packagedBuiltInExecutable(def, configuredEnv = {}) {
         if (!statSync(candidate).isFile())
             return null;
         if (process.platform === 'win32') {
-            if (!looksExecutableOnWindows(candidate))
+            if (!looksExecutableOnWindows(candidate, options))
                 return null;
         }
         else {
@@ -286,11 +293,11 @@ function packagedBuiltInExecutable(def, configuredEnv = {}) {
 // bundle. Probe the well-known bundle locations so app-only installs are
 // detected. This is a last-resort fallback that ranks below PATH, so an
 // explicit `npm i -g` / Homebrew / version-manager install always wins.
-function codexAppBundleExecutable(def) {
+function codexAppBundleExecutable(def, options = {}) {
     if (def?.id !== 'codex')
         return null;
-    for (const candidate of codexAppBundleCandidates()) {
-        const resolved = executableFilePath(candidate);
+    for (const candidate of codexAppBundleCandidates({}, options)) {
+        const resolved = executableFilePath(candidate, options);
         if (resolved)
             return resolved;
     }
@@ -301,12 +308,12 @@ function codexAppBundleExecutable(def) {
 // depend on the host actually having `/Applications/Codex.app`), so tests
 // assert the built candidate list directly to catch a path typo or
 // ordering regression in the common real-world install case.
-export function codexAppBundleCandidates() {
+export function codexAppBundleCandidates(_required = {}, options = {}) {
     // The Codex app bundle is a macOS-only concept; other platforms have no
     // analogous standalone install of the `codex` CLI to probe for here.
     if (process.platform !== 'darwin')
         return [];
-    const { home, hasOverride } = resolveDetectionHome();
+    const { home, hasOverride } = resolveDetectionHome(options);
     const bundleSuffix = ['Codex.app', 'Contents', 'Resources', 'codex'];
     // User-scoped install (~/Applications). Honors the override home so
     // sandboxed detection runs and tests stay deterministic.
@@ -319,10 +326,10 @@ export function codexAppBundleCandidates() {
     }
     return candidates;
 }
-export function resolveAgentExecutable({ def }, { configuredEnv = {} } = {}) {
-    return inspectAgentExecutableResolution({ def: def }, { configuredEnv: configuredEnv }).selectedPath;
+export function resolveAgentExecutable({ def }, options = {}) {
+    return inspectAgentExecutableResolution({ def: def }, options).selectedPath;
 }
-export function inspectAgentExecutableResolution({ def }, { configuredEnv = {} } = {}) {
+export function inspectAgentExecutableResolution({ def }, options = {}) {
     if (!def?.bin) {
         return {
             configuredOverridePath: null,
@@ -330,21 +337,22 @@ export function inspectAgentExecutableResolution({ def }, { configuredEnv = {} }
             selectedPath: null,
         };
     }
-    const configuredOverridePath = configuredExecutableOverride(def, configuredEnv);
+    const configuredEnv = options.configuredEnv ?? {};
+    const configuredOverridePath = configuredExecutableOverride(def, configuredEnv, options);
     const candidates = [
         def.bin,
         ...(Array.isArray(def.fallbackBins) ? def.fallbackBins : []),
     ];
     let pathResolvedPath = null;
     for (const bin of candidates) {
-        const resolved = resolveOnPath({ bin: bin });
+        const resolved = resolveOnPath({ bin: bin }, options);
         if (resolved) {
             pathResolvedPath = resolved;
             break;
         }
     }
-    const builtInPath = packagedBuiltInExecutable(def, configuredEnv);
-    const appBundlePath = codexAppBundleExecutable(def);
+    const builtInPath = packagedBuiltInExecutable(def, configuredEnv, options);
+    const appBundlePath = codexAppBundleExecutable(def, options);
     return {
         configuredOverridePath,
         pathResolvedPath,