@addai/node 0.30.12 → 0.30.14

package/dist/entitybox-vault-provider.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxVaultProvider = void 0;
+exports.entityboxAnthropicKey = entityboxAnthropicKey;
+exports.entityboxNativeProvider = entityboxNativeProvider;
+const crypto_1 = require("crypto");
+const config_1 = require("./config");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_operation_1 = require("./entitybox-operation");
+const unavailable = () => new entitybox_execution_lease_1.EntityboxExecutionError('The selected provider credential is unavailable. Check its Vault grant and provider fields.');
+// Same field contract as EntityBox/services/worker/provider-key.mjs. Parse in
+// host memory only. Do not include Vault values or diagnostics in errors.
+function entityboxAnthropicKey(values) {
+    if (!values || typeof values !== 'object' || Array.isArray(values))
+        throw unavailable();
+    const fields = values;
+    const explicit = ['api_key', 'ANTHROPIC_API_KEY', 'anthropic_api_key', 'API_KEY'].map(k => fields[k]).filter((v) => typeof v === 'string' && !!v.trim());
+    const found = explicit.length ? explicit.map(v => v.trim()) : typeof fields.content === 'string' ? (fields.content.match(/sk-ant-[A-Za-z0-9_-]{20,}/g) ?? []) : [];
+    const unique = [...new Set(found)];
+    if (unique.length !== 1 || unique[0].length > 4096 || !/^sk-ant-[A-Za-z0-9_-]{20,}$/.test(unique[0]))
+        throw unavailable();
+    return unique[0];
+}
+/** Reuse the existing entity-authenticated Vault MCP get_login operation.
+ * Each lookup checks the current Vault grant; no secret cache, host login
+ * directory, environment fallback or credential file is used. */
+class EntityboxVaultProvider {
+    lease;
+    config;
+    constructor(lease, config) {
+        this.lease = lease;
+        if (!/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i.test(config.itemId)
+            || typeof config.entityKey !== 'string' || !config.entityKey.trim() || config.entityKey.length > 8192 || /[\r\n]/.test(config.entityKey))
+            throw unavailable();
+        this.config = Object.freeze({ itemId: config.itemId.toLowerCase(), entityKey: config.entityKey, fetch: config.fetch });
+    }
+    async apiKey(signal) {
+        try {
+            this.lease.assertActive();
+            return await (0, entitybox_operation_1.entityboxOperation)([signal, this.lease.signal], 10000, async (operationSignal) => {
+                const id = (0, crypto_1.randomUUID)();
+                const response = await (this.config.fetch ?? fetch)(config_1.SUPABASE_URL + '/functions/v1/vault-mcp', {
+                    method: 'POST', redirect: 'error', signal: operationSignal,
+                    headers: { 'Content-Type': 'application/json', 'ENTITY-API-KEY': this.config.entityKey },
+                    body: JSON.stringify({ jsonrpc: '2.0', id, method: 'tools/call', params: { name: 'get_login', arguments: { item_id: this.config.itemId, reason: 'EntityBox run ' + this.lease.identity.scope.runId + ': authenticate the selected AI provider' } } }),
+                });
+                if (!response.ok || !response.body) {
+                    void response.body?.cancel().catch(() => { });
+                    throw unavailable();
+                }
+                const length = response.headers.get('content-length');
+                if (length !== null && (!/^\d+$/.test(length) || Number(length) > 128 * 1024)) {
+                    void response.body.cancel().catch(() => { });
+                    throw unavailable();
+                }
+                const reader = response.body.getReader(), parts = [];
+                let size = 0;
+                const cancel = () => { void reader.cancel().catch(() => { }); };
+                operationSignal.addEventListener('abort', cancel, { once: true });
+                try {
+                    if (operationSignal.aborted)
+                        throw unavailable();
+                    while (true) {
+                        const chunk = await reader.read();
+                        if (operationSignal.aborted)
+                            throw unavailable();
+                        if (chunk.done)
+                            break;
+                        size += chunk.value.byteLength;
+                        if (size > 128 * 1024)
+                            throw unavailable();
+                        parts.push(chunk.value);
+                    }
+                    const envelope = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts)));
+                    if (envelope.jsonrpc !== '2.0' || envelope.id !== id || envelope.error || !envelope.result || envelope.result.isError)
+                        throw unavailable();
+                    let payload = envelope.result.structuredContent;
+                    if (payload === undefined) {
+                        const values = [];
+                        for (const part of envelope.result.content ?? [])
+                            if (part?.type === 'text' && typeof part.text === 'string') {
+                                try {
+                                    values.push(JSON.parse(part.text));
+                                }
+                                catch { }
+                            }
+                        if (values.length !== 1)
+                            throw unavailable();
+                        payload = values[0];
+                    }
+                    this.lease.assertActive();
+                    if (operationSignal.aborted)
+                        throw unavailable();
+                    if (typeof payload?.item_id !== 'string' || payload.item_id.toLowerCase() !== this.config.itemId)
+                        throw unavailable();
+                    return entityboxAnthropicKey(payload?.values);
+                }
+                finally {
+                    operationSignal.removeEventListener('abort', cancel);
+                    cancel();
+                    reader.releaseLock();
+                }
+            });
+        }
+        catch {
+            throw unavailable();
+        }
+    }
+}
+exports.EntityboxVaultProvider = EntityboxVaultProvider;
+/** Construct the contained broker's API provider from server-verified native
+ * selection. The entity key comes from the read-only native desktop resolver.
+ * Every inference lookup rechecks that selection before asking Vault, so a
+ * revoked or changed binding cannot quietly switch credentials mid-task. */
+async function entityboxNativeProvider(lease, entityKey, signal, transport) {
+    const selection = await (0, entitybox_operation_1.entityboxOperation)([signal, lease.signal], 4500, () => lease.providerSelection());
+    const vault = new EntityboxVaultProvider(lease, { itemId: selection.vaultItemId, entityKey, fetch: transport });
+    return {
+        models: Object.freeze([selection.model]),
+        apiKey: caller => (0, entitybox_operation_1.entityboxOperation)([caller, lease.signal], 10000, async (operationSignal) => {
+            await lease.providerSelection();
+            if (operationSignal.aborted)
+                throw unavailable();
+            return vault.apiKey(operationSignal);
+        }),
+    };
+}

package/dist/harness-registry.js

@@ -48,7 +48,9 @@ exports.HARNESSES = {
         label: 'Codex',
         npmPackage: '@openai/codex',
         findBinary: codex_binary_1.findCodexBinary,
-        efforts: ['minimal', 'low', 'medium', 'high'],
+        // Until codex lists its models (codex-models.ts), whose efforts then win.
+        // xhigh and max reach older codex as high; see codexEffort().
+        efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
         login: {
             strategy: 'api-key',
             instructions: 'Paste an OpenAI API key (applied via `codex login --with-api-key`).',

package/dist/index.js

@@ -1,6 +1,4 @@
 "use strict";
-// ainode — the +Ai Node background daemon that pairs with +Ai (Supabase)
-// and runs Claude / Codex sessions on behalf of authenticated requests.
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -37,6 +35,12 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 exports.start = start;
+const entitybox_capacity_health_host_1 = require("./entitybox-capacity-health-host");
+const entitybox_recovery_host_1 = require("./entitybox-recovery-host");
+const entitybox_execution_host_1 = require("./entitybox-execution-host");
+const entitybox_capacity_host_1 = require("./entitybox-capacity-host");
+// ainode — the +Ai Node background daemon that pairs with +Ai (Supabase)
+// and runs Claude / Codex sessions on behalf of authenticated requests.
 const path = __importStar(require("path"));
 const control_server_1 = require("./control-server");
 const paths_1 = require("./paths");
@@ -63,6 +67,8 @@ const relay_client_1 = require("./desktop/relay-client");
 const session_runner_1 = require("./session-runner");
 const diskguard_1 = require("./diskguard");
 const pty_helper_1 = require("./pty-helper");
+const supervisor_1 = require("./direct/supervisor");
+const config_1 = require("./direct/config");
 // Read version from package.json at module-load. Previously hardcoded to
 // '0.1.0' and never updated when package.json bumped — the CLI banner lied
 // about which version was actually running, making upgrade verification
@@ -144,6 +150,13 @@ async function start(argv = []) {
             throw err;
         }
     }
+    // Explicit host opt-in only. Install shared admission before any desktop
+    // starts; ordinary runtime behavior stays unchanged when the flag is absent.
+    const entityboxCapacity = (0, entitybox_capacity_host_1.startEntityboxCapacityHost)();
+    const entityboxExecution = (0, entitybox_execution_host_1.startEntityboxExecutionHost)({ rpc: supabase_client_1.rpc, pairing: store_1.readPairing });
+    (0, request_pump_1.configureEntityboxQueueServices)(entityboxExecution.services);
+    const entityboxHealth = (0, entitybox_capacity_health_host_1.startEntityboxCapacityHealthHost)({ rpc: supabase_client_1.rpc, pairing: store_1.readPairing });
+    const entityboxRecovery = (0, entitybox_recovery_host_1.startEntityboxRecoveryHost)({ rpc: supabase_client_1.rpc, pairing: store_1.readPairing, activeRequests: request_pump_1.activeRequestIdList });
     // Begin the heartbeat — this also pushes the first capabilities probe
     // up to Supabase so the runtime appears "online" immediately. When the
     // server reports queued install/login commands, the command runner
@@ -230,6 +243,9 @@ async function start(argv = []) {
     (0, relay_client_1.onWake)('command', command_runner_1.wake);
     (0, relay_client_1.onWake)('request', request_pump_1.pumpNow);
     (0, relay_client_1.startRelayClient)();
+    // Optional direct coding sessions use their own child process and relay.
+    // Disabled by default; the entity/flow/desktop execution paths are unchanged.
+    const directService = (0, supervisor_1.startDirectService)((0, config_1.directEnvironment)());
     let stopped = false;
     // Outcome of the last drain, so a remote roll can report whether it left
     // work unfinished instead of claiming a clean restart either way.
@@ -238,12 +254,17 @@ async function start(argv = []) {
         if (stopped)
             return;
         stopped = true;
+        await directService.stop();
         // Stop accepting new work first — otherwise the pump would queue
         // another request between drain start and process exit.
         (0, projects_1.stop)();
         (0, manager_1.stopDesktopManager)();
+        entityboxCapacity.stop();
         (0, relay_client_1.stopRelayClient)();
         (0, request_pump_1.stop)();
+        entityboxExecution.stop();
+        entityboxRecovery.stop();
+        entityboxHealth.stop();
         (0, pump_1.stop)();
         (0, heartbeat_1.stop)();
         (0, auto_update_1.stop)();
@@ -260,8 +281,12 @@ async function start(argv = []) {
             // timeout to shut down, and the timeout is there because something
             // upstream is waiting for this process to be gone.
             const [requests, flows] = await Promise.all([
+                // Result is intentionally not used to release native resources.
                 (0, request_pump_1.drain)(drainTimeoutMs),
                 (0, pump_1.drain)(drainTimeoutMs),
+                entityboxCapacity.drain(drainTimeoutMs),
+                entityboxRecovery.drain(drainTimeoutMs),
+                entityboxHealth.drain(drainTimeoutMs),
             ]);
             lastDrain = { drained: requests.drained, timedOut: requests.timedOut };
             if (requests.drained || requests.timedOut) {
@@ -301,44 +326,51 @@ async function start(argv = []) {
     // and npm is never called — nothing to fetch, and nothing that can fail
     // offline.
     const performRestart = async ({ commandId, version, restartOnly }) => {
-        const mode = (0, self_update_1.detectLaunchMode)(process.argv[1] ?? '');
-        const plan = (0, self_update_1.planRespawn)(mode, process.argv[1] ?? '', version, process.execPath, process.argv.slice(2));
-        const supervised = (0, autostart_1.isSupervised)();
-        if (plan.installFirst && !restartOnly) {
-            const err = await (0, self_update_1.installGlobal)(version);
-            if (err)
-                throw new Error(err);
-        }
-        // Drain generously — a restart is elective, so it should never guillotine
-        // a live entity turn the way a 15s SIGTERM drain would.
-        await stop(RESTART_DRAIN_MS);
-        // Point of no return. Past this line a replacement daemon either exists or
-        // is guaranteed by the supervisor, so we MUST exit — two live daemons on
-        // one node is worse than a command left unreported. Hence the handoff
-        // write (which only affects reporting) can never abort the exit.
-        if (!supervised) {
-            (0, self_update_1.spawnReplacement)(plan, path.join(paths_1.RUNTIME_HOME, 'daemon.log'), process.cwd());
-        }
+        if (!await directService.quiesce())
+            throw new Error('Close active direct coding sessions before updating or restarting this node.');
         try {
-            (0, self_update_1.writeHandoff)(paths_1.RUNTIME_HOME, {
-                command_id: commandId,
-                from_version: VERSION,
-                target_version: version,
-                mode,
-                at: new Date().toISOString(),
-                drained: lastDrain.drained,
-                timed_out: lastDrain.timedOut,
-                restart_only: restartOnly === true,
-            });
+            const mode = (0, self_update_1.detectLaunchMode)(process.argv[1] ?? '');
+            const plan = (0, self_update_1.planRespawn)(mode, process.argv[1] ?? '', version, process.execPath, process.argv.slice(2));
+            const supervised = (0, autostart_1.isSupervised)();
+            if (plan.installFirst && !restartOnly) {
+                const err = await (0, self_update_1.installGlobal)(version);
+                if (err)
+                    throw new Error(err);
+            }
+            // Drain generously — a restart is elective, so it should never guillotine
+            // a live entity turn the way a 15s SIGTERM drain would.
+            await stop(RESTART_DRAIN_MS);
+            // Point of no return. Past this line a replacement daemon either exists or
+            // is guaranteed by the supervisor, so we MUST exit — two live daemons on
+            // one node is worse than a command left unreported. Hence the handoff
+            // write (which only affects reporting) can never abort the exit.
+            if (!supervised) {
+                (0, self_update_1.spawnReplacement)(plan, path.join(paths_1.RUNTIME_HOME, 'daemon.log'), process.cwd());
+            }
+            try {
+                (0, self_update_1.writeHandoff)(paths_1.RUNTIME_HOME, {
+                    command_id: commandId,
+                    from_version: VERSION,
+                    target_version: version,
+                    mode,
+                    at: new Date().toISOString(),
+                    drained: lastDrain.drained,
+                    timed_out: lastDrain.timedOut,
+                    restart_only: restartOnly === true,
+                });
+            }
+            catch (err) {
+                console.error('[restart] handoff write failed — the roll still happened, it just cannot self-report:', err.message);
+            }
+            const what = restartOnly ? `${mode} → restart on ${version}` : `${mode} → ${version}`;
+            console.log(supervised
+                ? `[restart] standing down for launchd to restart us (${what}); exiting`
+                : `[restart] handed over to ${plan.file} (${what}); exiting`);
+            setTimeout(() => process.exit(0), 250).unref?.();
         }
-        catch (err) {
-            console.error('[restart] handoff write failed — the roll still happened, it just cannot self-report:', err.message);
+        finally {
+            directService.release();
         }
-        const what = restartOnly ? `${mode} → restart on ${version}` : `${mode} → ${version}`;
-        console.log(supervised
-            ? `[restart] standing down for launchd to restart us (${what}); exiting`
-            : `[restart] handed over to ${plan.file} (${what}); exiting`);
-        setTimeout(() => process.exit(0), 250).unref?.();
     };
     (0, command_runner_1.setRestartHook)(performRestart);
     // Hourly auto-update — the node keeps itself and its harnesses current
@@ -347,7 +379,9 @@ async function start(argv = []) {
     // roll cannot drift apart.
     (0, auto_update_1.start)({
         token: () => (0, store_1.readPairing)()?.daemonToken ?? null,
-        isBusy: () => (0, request_pump_1.activeRequestIdList)().length > 0,
+        isBusy: () => (0, request_pump_1.activeRequestIdList)().length > 0 || directService.busy(),
+        quiesceDirect: () => directService.quiesce(),
+        releaseDirect: () => directService.release(),
         breakerOpen: () => (0, supabase_client_1.rpcShouldSkip)(),
         enabled: heartbeat_1.autoUpdateEnabled,
         probe: () => (0, capabilities_1.probeCapabilities)(),

package/dist/install.d.ts

@@ -42,7 +42,16 @@ export interface InstallResult {
     /** Cleanup callback — removes everything this install wrote. */
     dispose: () => Promise<void>;
 }
-export declare function writeMcpConfig(cwd: string, mcps: ResolvedMcp[]): string | null;
+/** Resolve the existing request's desktop identity for the contained broker.
+ * This path is read-only: it never writes MCP/skill files, uses the installer
+ * cache, falls back to a different request, or accepts a caller's entity key.
+ * The caller must already hold a verified native execution lease. */
+export declare function resolveEntityboxDesktopConnection(set: InstallSet, overrides: Record<string, Record<string, string>> | undefined, requestId: string, signal: AbortSignal): Promise<{
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+}>;
+export declare function writeMcpConfig(cwd: string, mcps: ResolvedMcp[], entityboxRequestId?: string): string | null;
 /**
  * Run install side-effects against `cwd` and return paths to clean up
  * later. Safe to call with an empty set — returns a no-op result.
@@ -60,5 +69,8 @@ skillVarValues?: Record<string, Record<string, string>>,
 /** The entity_runtime_requests row being installed. Passed to the server
  *  so credential resolution is scoped to THIS request instead of the
  *  latest in-flight request on the runtime. */
-requestId?: string): Promise<InstallResult>;
+requestId?: string, 
+/** Report a required EntityBox setup failure before the caller can spawn a
+ * harness. Ordinary native installs never enter this failure callback. */
+onRequiredSetupFailure?: (message: string) => Promise<void>): Promise<InstallResult>;
 export {};

package/dist/install.js

@@ -47,9 +47,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LEGACY_MCP_CONFIG_FILENAME = exports.MCP_CONFIG_FILENAME = void 0;
+exports.resolveEntityboxDesktopConnection = resolveEntityboxDesktopConnection;
 exports.writeMcpConfig = writeMcpConfig;
 exports.install = install;
 const fs = __importStar(require("fs"));
+const crypto_1 = require("crypto");
+const entitybox_install_1 = require("./entitybox-install");
+const entitybox_operation_1 = require("./entitybox-operation");
 const path = __importStar(require("path"));
 const supabase_client_1 = require("./supabase-client");
 const store_1 = require("./store");
@@ -68,10 +72,13 @@ const NOOP_RESULT = {
 function token() {
     return (0, store_1.readPairing)()?.daemonToken ?? null;
 }
-async function fetchResolved(set, requestId) {
+async function fetchResolved(set, requestId, requireRequest = false) {
     const t = token();
-    if (!t)
+    if (!t) {
+        if (requireRequest)
+            throw new entitybox_install_1.EntityboxInstallError('Pair the runtime before starting a computer task.');
         return { mcps: [], skills: [] };
+    }
     if (set.mcpIds.length === 0 && set.skillIds.length === 0 && set.packageIds.length === 0) {
         return { mcps: [], skills: [] };
     }
@@ -93,7 +100,7 @@ async function fetchResolved(set, requestId) {
         // A DB that predates the p_request_id migration rejects the unknown
         // parameter (PostgREST 404 "function not found"). Degrade to the legacy
         // runtime-wide heuristic rather than failing the whole install.
-        if (requestId && err instanceof supabase_client_1.RpcError && err.status === 404) {
+        if (!requireRequest && requestId && err instanceof supabase_client_1.RpcError && err.status === 404) {
             out = await (0, supabase_client_1.rpc)('runtime_resolve_install_set', baseArgs);
         }
         else {
@@ -105,7 +112,37 @@ async function fetchResolved(set, requestId) {
         skills: Array.isArray(out?.skills) ? out.skills : [],
     };
 }
-function writeMcpConfig(cwd, mcps) {
+/** Resolve the existing request's desktop identity for the contained broker.
+ * This path is read-only: it never writes MCP/skill files, uses the installer
+ * cache, falls back to a different request, or accepts a caller's entity key.
+ * The caller must already hold a verified native execution lease. */
+async function resolveEntityboxDesktopConnection(set, overrides, requestId, signal) {
+    try {
+        const scope = (0, entitybox_install_1.entityboxInstallScope)(overrides, requestId);
+        if (!scope || Object.keys(overrides?.['entity-desktop-mcp'] ?? {}).some(key => key !== 'ENTITYBOX_DESKTOP_SCOPE'))
+            throw new Error();
+        // Snapshot before awaiting: the selected set and scope cannot be changed
+        // underneath an outstanding credential lookup by a mutable request row.
+        const selection = structuredClone(set);
+        return await (0, entitybox_operation_1.entityboxOperation)([signal], 4500, async (operationSignal) => {
+            const resolved = await fetchResolved(selection, requestId, true);
+            if (operationSignal.aborted)
+                throw new Error();
+            const rows = resolved.mcps.filter(m => m.slug === 'entity-desktop-mcp')
+                .map(m => ({ ...m, env: { ...(m.env ?? {}), ENTITYBOX_DESKTOP_SCOPE: scope } }));
+            (0, entitybox_install_1.assertEntityboxDesktopMcp)(rows, scope);
+            const m = rows[0], guard = path.join(__dirname, 'entitybox-mcp-guard.js');
+            if (!fs.existsSync(guard))
+                throw new Error();
+            const wrapped = (0, win_1.wrapMcpCommandForPlatform)(m.command, Array.isArray(m.args) ? m.args : []);
+            return { command: process.execPath, args: [guard, '--', wrapped.command, ...wrapped.args], env: m.env };
+        });
+    }
+    catch {
+        throw new entitybox_install_1.EntityboxInstallError('The selected computer identity could not be verified. Check the runtime connection and task access.');
+    }
+}
+function writeMcpConfig(cwd, mcps, entityboxRequestId) {
     if (mcps.length === 0)
         return null;
     const servers = {};
@@ -150,14 +187,23 @@ function writeMcpConfig(cwd, mcps) {
     // The daemon scopes these files per request id; the caller passes a
     // unique cwd directory or we'd race ourselves on concurrent sessions
     // in the same project.
-    const target = path.join(cwd, exports.MCP_CONFIG_FILENAME);
+    if (entityboxRequestId !== undefined && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(entityboxRequestId)) {
+        throw new entitybox_install_1.EntityboxInstallError('Invalid computer task request identifier.');
+    }
+    // Each scoped attempt owns a unique file; a late dispose cannot remove a
+    // replacement attempt's credentials, even when a working directory is reused.
+    const target = path.join(cwd, entityboxRequestId
+        ? '.entitybox-' + entityboxRequestId + '-' + (0, crypto_1.randomUUID)() + '.mcp.json'
+        : exports.MCP_CONFIG_FILENAME);
     // A session dir reused from before the rename can still hold the old file;
     // leaving it would let an agent read a stale server list.
-    try {
-        fs.rmSync(path.join(cwd, exports.LEGACY_MCP_CONFIG_FILENAME), { force: true });
+    if (!entityboxRequestId) {
+        try {
+            fs.rmSync(path.join(cwd, exports.LEGACY_MCP_CONFIG_FILENAME), { force: true });
+        }
+        catch { /* best effort */ }
     }
-    catch { /* best effort */ }
-    fs.writeFileSync(target, JSON.stringify({ mcpServers: servers }, null, 2));
+    fs.writeFileSync(target, JSON.stringify({ mcpServers: servers }, null, 2), entityboxRequestId ? { flag: 'wx', mode: 0o600 } : undefined);
     return target;
 }
 function writeSkills(cwd, skills, skillVarValues) {
@@ -299,7 +345,66 @@ skillVarValues,
 /** The entity_runtime_requests row being installed. Passed to the server
  *  so credential resolution is scoped to THIS request instead of the
  *  latest in-flight request on the runtime. */
-requestId) {
+requestId, 
+/** Report a required EntityBox setup failure before the caller can spawn a
+ * harness. Ordinary native installs never enter this failure callback. */
+onRequiredSetupFailure) {
+    try {
+        const scope = (0, entitybox_install_1.entityboxInstallScope)(envOverrides, requestId);
+        if (scope !== null) {
+            let scoped;
+            try {
+                scoped = await fetchResolved(set, requestId, true);
+            }
+            catch {
+                throw new entitybox_install_1.EntityboxInstallError('The computer connection could not be verified. Check the runtime connection and try again.');
+            }
+            for (const m of scoped.mcps) {
+                const override = envOverrides?.[m.slug];
+                if (override)
+                    m.env = { ...(m.env || {}), ...override };
+            }
+            (0, entitybox_install_1.assertEntityboxDesktopMcp)(scoped.mcps, scope);
+            const guard = path.join(__dirname, 'entitybox-mcp-guard.js');
+            if (!fs.existsSync(guard))
+                throw new entitybox_install_1.EntityboxInstallError('Update the runtime before starting a computer task.');
+            scoped.mcps = scoped.mcps.map(m => {
+                if (m.slug !== 'entity-desktop-mcp')
+                    return m;
+                const wrapped = (0, win_1.wrapMcpCommandForPlatform)(m.command, Array.isArray(m.args) ? m.args : []);
+                // All harnesses consume the guarded descriptor, whether they read the
+                // generated config or build their own config from installed.mcps.
+                return { ...m, command: process.execPath, args: [guard, '--', wrapped.command, ...wrapped.args] };
+            });
+            // Required computer installs never use the ordinary best-effort cache.
+            const config = writeMcpConfig(cwd, scoped.mcps, requestId);
+            if (!config)
+                throw new entitybox_install_1.EntityboxInstallError('The required computer configuration could not be written.');
+            try {
+                const skills = writeSkills(cwd, scoped.skills, skillVarValues);
+                return { mcpConfigPath: config, skillSlugs: skills.slugs, mcps: scoped.mcps,
+                    dispose: async () => { try {
+                        fs.unlinkSync(config);
+                    }
+                    catch { /* already removed */ } } };
+            }
+            catch (error) {
+                try {
+                    fs.unlinkSync(config);
+                }
+                catch { }
+                throw error;
+            }
+        }
+    }
+    catch (error) {
+        // A present restriction must never degrade to the ordinary install path.
+        const failure = error instanceof entitybox_install_1.EntityboxInstallError ? error
+            : new entitybox_install_1.EntityboxInstallError('The computer connection could not be installed.');
+        if (onRequiredSetupFailure)
+            await onRequiredSetupFailure(failure.message);
+        throw failure;
+    }
     if (set.mcpIds.length === 0 && set.skillIds.length === 0 && set.packageIds.length === 0) {
         return NOOP_RESULT;
     }

package/dist/model-cache.d.ts

@@ -0,0 +1,38 @@
+export type ModelProbeResult<R> = {
+    ok: true;
+    report: R;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ModelCacheOptions<R extends {
+    models: string[];
+}> {
+    probe: (bin: string) => Promise<ModelProbeResult<R>>;
+    now: () => number;
+    log: (line: string) => void;
+    /** Which CLI, for the log. */
+    agent: string;
+    /** Detail for the log line when a new list arrives. */
+    describe?: (report: R) => string;
+    /** True when the answer already held for this binary is worth more than a
+     *  new one — codex's account list over the bundled one a probe that had to
+     *  leave the login alone gets. The held answer then counts as refreshed. */
+    keep?: (held: R, next: R) => boolean;
+}
+export declare function createModelCache<R extends {
+    models: string[];
+}>(opts: ModelCacheOptions<R>): {
+    /**
+     * The models for this binary state, or null to mean "use the built-in
+     * list". Never waits: a missing or stale answer is fetched in the
+     * background and arrives on a later call.
+     */
+    get(bin: string, key: string): R | null;
+    /** The last real answer, whichever binary gave it. */
+    last(): R | null;
+};
+/** A throwaway folder for one probe, under RUNTIME_HOME/model-probe. Folders
+ *  older than a day are swept — a probe's own cleanup can lose a race with
+ *  Windows releasing its files. */
+export declare function makeProbeDir(prefix?: string): string | null;