@addai/node 0.30.13 → 0.30.14

package/dist/entitybox-application-guard.js

@@ -0,0 +1,239 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxApplicationGuard = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const path = __importStar(require("path"));
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_application_boundary_1 = require("./entitybox-application-boundary");
+const entitybox_host_process_1 = require("./entitybox-host-process");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const exec = (0, util_1.promisify)(child_process_1.execFile);
+const error = () => new entitybox_execution_lease_1.EntityboxExecutionError('Independent application ownership could not be verified');
+/** Host-side handle. Production adapters must retain this owner until stop
+ * proof and child exit settle. A disappeared guard never grants reuse. */
+class EntityboxApplicationGuard {
+    lease;
+    binding;
+    proc;
+    context;
+    requireInventory;
+    recovery;
+    processId;
+    closed;
+    ready;
+    started;
+    stopped;
+    readyResolve;
+    readyReject;
+    startResolve;
+    startReject;
+    stopResolve;
+    stopReject;
+    proof;
+    guardIdentity;
+    used = false;
+    closing = false;
+    didClose = false;
+    stopping;
+    abort = () => { void this.pauseAndVerify().catch(() => { }); };
+    constructor(lease, binding, proc, context, requireInventory, recovery) {
+        this.lease = lease;
+        this.binding = binding;
+        this.proc = proc;
+        this.context = context;
+        this.requireInventory = requireInventory;
+        this.recovery = recovery;
+        this.processId = proc.pid ?? 0;
+        this.ready = new Promise((resolve, reject) => { this.readyResolve = resolve; this.readyReject = reject; });
+        this.ready.catch(() => { });
+        this.started = new Promise((resolve, reject) => { this.startResolve = resolve; this.startReject = reject; });
+        this.started.catch(() => { });
+        this.stopped = new Promise((resolve, reject) => { this.stopResolve = resolve; this.stopReject = reject; });
+        this.stopped.catch(() => { });
+        this.closed = new Promise(resolve => { proc.once('close', () => { this.didClose = true; lease.signal.removeEventListener('abort', this.abort); this.readyReject(error()); this.startReject(error()); if (!this.proof) {
+            this.stopReject(error());
+            lease.fence();
+            if (this.used && !this.recovery)
+                void this.emergencyPause();
+        } resolve(); }); });
+        proc.on('error', () => { this.readyReject(error()); this.startReject(error()); this.stopReject(error()); lease.fence(); if (this.used && !this.recovery)
+            void this.emergencyPause(); });
+        proc.on('message', packet => this.message(packet));
+        lease.signal.addEventListener('abort', this.abort, { once: true });
+        this.send({ type: 'configure', identity: lease.identity, binding: this.binding, context, ...(recovery ? { recovery: { directory: recovery.store.directory, hostId: recovery.store.hostId, controller: recovery.controller } } : {}) });
+        if (lease.signal.aborted)
+            this.abort();
+    }
+    static async attach(lease, binding, options = {}) {
+        lease.assertActive();
+        const context = options.dockerContext ?? 'desktop-linux';
+        if (!/^[-a-zA-Z0-9_.]{1,80}$/.test(context))
+            throw error();
+        if (options.recoveryStore && !options.requireInventory)
+            throw error();
+        const controller = options.recoveryStore ? await (0, entitybox_host_process_1.readEntityboxHostProcess)() : null;
+        if (options.recoveryStore && !controller)
+            throw error();
+        lease.assertActive();
+        if (options.requireInventory)
+            await lease.registerResource('application', { ...binding });
+        const env = {};
+        for (const key of ['PATH', 'Path', 'SystemRoot', 'WINDIR', 'ComSpec', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA', 'TEMP', 'TMP', 'HOME', 'DOCKER_CONFIG'])
+            if (process.env[key] !== undefined)
+                env[key] = process.env[key];
+        const proc = (0, child_process_1.spawn)(process.execPath, [path.join(__dirname, 'entitybox-application-guard-process.js')], { env, detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+        const owner = new EntityboxApplicationGuard(lease, Object.freeze({ ...binding }), proc, context, options.requireInventory === true, options.recoveryStore && controller ? { store: options.recoveryStore, controller } : undefined);
+        try {
+            options.onOwner?.(owner);
+            await owner.deadline(owner.ready, 10000);
+            lease.assertActive();
+            if (owner.recovery) {
+                if (!owner.guardIdentity)
+                    throw error();
+                await lease.registerRecoveryHost((0, entitybox_recovery_store_1.parseEntityboxRecoveryHost)({ hostId: owner.recovery.store.hostId, dockerContext: context, controller: owner.recovery.controller, guard: owner.guardIdentity }));
+            }
+            lease.assertActive();
+            return owner;
+        }
+        catch {
+            lease.fence();
+            void owner.pauseAndVerify().catch(() => { });
+            throw error();
+        }
+    }
+    async resume() { if (this.used || this.closing)
+        throw error(); if (this.requireInventory)
+        this.lease.assertInventorySealed(); this.used = true; this.lease.assertActive(); this.send({ type: 'resume' }); try {
+        await this.deadline(this.started, 12000);
+        this.lease.assertActive();
+    }
+    catch {
+        this.lease.fence();
+        void this.pauseAndVerify().catch(() => { });
+        throw error();
+    } }
+    pauseAndVerify() {
+        if (this.stopping)
+            return this.stopping;
+        this.closing = true;
+        this.stopping = Promise.resolve().then(async () => { this.send({ type: 'stop' }); const proof = await this.deadline(this.stopped, 15000); await this.deadline(this.closed, 5000); const state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.lease.identity.scope, args => this.docker(args)); if (state === 'running')
+            throw error(); return proof; });
+        this.lease.fence();
+        return this.stopping;
+    }
+    async docker(args) { return (await exec('docker', ['--context', this.context, ...args], { windowsHide: true, timeout: 5000, maxBuffer: 1024 * 1024 })).stdout.trim(); }
+    async emergencyPause() { try {
+        if (await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(this.binding, this.lease.identity.scope, args => this.docker(args)) === 'running')
+            await this.docker(['container', 'pause', this.binding.containerId]);
+    }
+    catch { } /* No proof: an earlier guard mutation may still be outstanding. */ }
+    send(packet) { if (!this.proc.connected)
+        return; try {
+        this.proc.send(packet, e => { if (e) {
+            this.lease.fence();
+            this.startReject(error());
+        } });
+    }
+    catch {
+        this.lease.fence();
+        this.startReject(error());
+    } }
+    message(value) {
+        try {
+            const p = value;
+            if (p?.type === 'ready') {
+                if (this.closing)
+                    throw error();
+                if (this.recovery) {
+                    this.guardIdentity = (0, entitybox_host_process_1.parseEntityboxHostProcess)(p.process);
+                    if (this.guardIdentity.pid !== this.processId)
+                        throw error();
+                }
+                this.readyResolve();
+                return;
+            }
+            if (p?.type === 'challenge' && typeof p.id === 'string' && /^[0-9a-f-]{36}$/.test(p.id) && this.used && !this.closing) {
+                void this.grant(p.id);
+                return;
+            }
+            if (p?.type === 'started') {
+                this.lease.assertActive();
+                if (this.closing)
+                    throw error();
+                this.startResolve();
+                return;
+            }
+            if (p?.type === 'stopped') {
+                const r = p.proof;
+                if (r?.capacityId !== this.binding.capacityId || r.containerId !== this.binding.containerId || r.attemptId !== this.lease.identity.attemptId || !['paused', 'stopped'].includes(r.state) || !Number.isFinite(Date.parse(r.observedAt)))
+                    throw error();
+                this.proof = Object.freeze({ ...r });
+                this.closing = true;
+                this.stopResolve(this.proof);
+                this.lease.fence();
+                return;
+            }
+            if (p?.type === 'unverified') {
+                this.stopReject(error());
+                throw error();
+            }
+            throw error();
+        }
+        catch {
+            this.readyReject(error());
+            this.startReject(error());
+            this.lease.fence();
+        }
+    }
+    async grant(id) { try {
+        await this.lease.authorizeQueuedChallenge();
+        this.lease.assertActive();
+        if (this.closing || this.didClose)
+            throw error();
+        this.send({ type: 'grant', id });
+    }
+    catch {
+        this.lease.fence();
+    } }
+    async deadline(work, ms) { let timer; try {
+        return await Promise.race([work, new Promise((_, reject) => { timer = setTimeout(() => reject(error()), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    } }
+}
+exports.EntityboxApplicationGuard = EntityboxApplicationGuard;

package/dist/entitybox-capacity-health-host.d.ts

@@ -0,0 +1,12 @@
+import { type EntityboxCapacityHealthIO } from './entitybox-capacity-health-worker';
+export declare function entityboxCapacityHealthEnvironment(env?: NodeJS.ProcessEnv): {
+    enabled: true;
+    dockerContext: string;
+    directory: string;
+} | undefined;
+/** Independently enabled so health can keep reporting while setup or task
+ * execution is disabled. It never starts or modifies a computer. */
+export declare function startEntityboxCapacityHealthHost(io: Omit<EntityboxCapacityHealthIO, 'report'>, env?: NodeJS.ProcessEnv): {
+    stop(): void;
+    drain(_timeout?: number): Promise<boolean>;
+};

package/dist/entitybox-capacity-health-host.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityboxCapacityHealthEnvironment = entityboxCapacityHealthEnvironment;
+exports.startEntityboxCapacityHealthHost = startEntityboxCapacityHealthHost;
+const path = __importStar(require("path"));
+const paths_1 = require("./paths");
+const entitybox_capacity_health_worker_1 = require("./entitybox-capacity-health-worker");
+function entityboxCapacityHealthEnvironment(env = process.env) {
+    if (env.AINODE_ENTITYBOX_CAPACITY_HEALTH_ENABLED !== '1')
+        return undefined;
+    const dockerContext = env.AINODE_ENTITYBOX_DOCKER_CONTEXT ?? '';
+    const directory = env.AINODE_ENTITYBOX_CAPACITY_DIRECTORY ?? path.join(paths_1.RUNTIME_HOME, 'entitybox', 'capacities');
+    if (env.DOCKER_HOST || !/^[-a-zA-Z0-9_.]{1,80}$/.test(dockerContext) || !path.isAbsolute(directory) || directory.startsWith('\\\\'))
+        throw new Error('Invalid computer health configuration');
+    return { enabled: true, dockerContext, directory };
+}
+/** Independently enabled so health can keep reporting while setup or task
+ * execution is disabled. It never starts or modifies a computer. */
+function startEntityboxCapacityHealthHost(io, env = process.env) {
+    const idle = { stop() { }, async drain(_timeout) { return true; } };
+    try {
+        const config = entityboxCapacityHealthEnvironment(env);
+        if (!config)
+            return idle;
+        const pairing = io.pairing();
+        if (!pairing)
+            throw new Error();
+        const reported = new Map();
+        const worker = (0, entitybox_capacity_health_worker_1.createEntityboxCapacityHealthWorker)({ ...config, runtimeId: pairing.runtimeId }, { ...io, report: (state, id) => {
+                const key = id ?? 'worker', at = Date.now(), last = reported.get(key);
+                if (last?.state === state && at - last.at < 60000)
+                    return;
+                if (reported.size > 1000)
+                    reported.clear();
+                reported.set(key, { state, at });
+                console.log('[entitybox] Computer health ' + state + (id ? ' (' + id + ')' : ''));
+            } });
+        if (!worker)
+            return idle;
+        worker.start();
+        return worker;
+    }
+    catch {
+        console.warn('[entitybox] Computer health is disabled: host configuration unavailable.');
+        return idle;
+    }
+}

package/dist/entitybox-capacity-health-worker.d.ts

@@ -0,0 +1,22 @@
+import { observeEntityboxCapacity } from './entitybox-capacity-provisioner';
+import type { EntityboxCapacityRegistrationIO } from './entitybox-capacity-registration';
+export interface EntityboxCapacityHealthConfiguration {
+    enabled?: boolean;
+    runtimeId: string;
+    dockerContext: string;
+    directory: string;
+}
+export interface EntityboxCapacityHealthIO extends Pick<EntityboxCapacityRegistrationIO, 'rpc' | 'pairing'> {
+    /** Fixture-only observer. Production always uses exact physical inspection. */
+    observe?: typeof observeEntityboxCapacity;
+    report?: (state: 'paused' | 'running' | 'unavailable', desktopId?: string) => void;
+}
+/** Health grants no lifecycle authority. Each report requires a fresh server
+ * challenge followed by physical inspection. Uncertain replies are not replayed
+ * as new observations; the next round starts a new challenge and inspects again. */
+export declare function createEntityboxCapacityHealthWorker(config: EntityboxCapacityHealthConfiguration, io: EntityboxCapacityHealthIO): {
+    tick: () => Promise<void>;
+    start(): void;
+    stop(): void;
+    drain(timeoutMs?: number): Promise<boolean>;
+} | undefined;

package/dist/entitybox-capacity-health-worker.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntityboxCapacityHealthWorker = createEntityboxCapacityHealthWorker;
+const path = __importStar(require("path"));
+const entitybox_capacity_provisioner_1 = require("./entitybox-capacity-provisioner");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const entitybox_operation_1 = require("./entitybox-operation");
+const uuid = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+/** Health grants no lifecycle authority. Each report requires a fresh server
+ * challenge followed by physical inspection. Uncertain replies are not replayed
+ * as new observations; the next round starts a new challenge and inspects again. */
+function createEntityboxCapacityHealthWorker(config, io) {
+    if (config.enabled !== true)
+        return undefined;
+    if (!uuid.test(config.runtimeId) || !/^[-a-zA-Z0-9_.]{1,80}$/.test(config.dockerContext)
+        || !path.isAbsolute(config.directory) || config.directory.startsWith('\\\\'))
+        throw new Error('Invalid computer health configuration');
+    const settings = Object.freeze({ ...config });
+    let stopped = false, started = false, timer, flight;
+    const token = () => {
+        const p = io.pairing();
+        if (stopped || !p || p.runtimeId !== settings.runtimeId || typeof p.daemonToken !== 'string' || !p.daemonToken)
+            throw new Error();
+        return p.daemonToken;
+    };
+    const report = (state, id) => { try {
+        io.report?.(state, id);
+    }
+    catch { } };
+    async function run() {
+        try {
+            const paired = token();
+            const current = () => { if (token() !== paired)
+                throw new Error(); };
+            const rpc = async (name, args) => {
+                current();
+                const result = await (0, entitybox_operation_1.entityboxOperation)([], 4500, () => io.rpc(name, { p_token: paired, ...args }));
+                current();
+                return result;
+            };
+            // Validate every page before observing any computer. Older schemas and
+            // disabled workspaces omit health metadata and cause no physical reads.
+            const rows = [], ids = new Set(), desktops = new Set();
+            let after = null, complete = false;
+            for (let page = 0; page < 10; page++) {
+                const values = await rpc('entitybox_native_capacity_inventory', { p_after: after, p_limit: 50 });
+                if (!Array.isArray(values) || values.length > 50)
+                    throw new Error();
+                for (const value of values) {
+                    if (!value || ![value.id, value.desktopId, value.runtimeId].every(v => typeof v === 'string' && uuid.test(v))
+                        || value.runtimeId !== settings.runtimeId || ids.has(value.id) || desktops.has(value.desktopId)
+                        || after !== null && value.id <= after || !['reserved', 'provisioning', 'ready'].includes(value.phase))
+                        throw new Error();
+                    ids.add(value.id);
+                    desktops.add(value.desktopId);
+                    after = value.id;
+                    if (value.health !== undefined && (!value.health || !['unknown', 'stale', 'paused', 'running', 'unavailable'].includes(value.health.state)))
+                        throw new Error();
+                    if (value.phase !== 'ready' || value.health === undefined)
+                        continue;
+                    const receipt = JSON.parse((0, entitybox_recovery_store_1.entityboxCanonical)(value.receipt));
+                    if (!receipt || receipt.version !== 1 || receipt.application?.desktopId !== value.desktopId || receipt.application?.runtimeId !== settings.runtimeId
+                        || receipt.display?.desktopId !== value.desktopId || receipt.display?.runtimeId !== settings.runtimeId)
+                        throw new Error();
+                    rows.push({ id: value.id, desktopId: value.desktopId, runtimeId: value.runtimeId, receipt });
+                }
+                if (values.length < 50) {
+                    complete = true;
+                    break;
+                }
+            }
+            if (!complete)
+                throw new Error();
+            let next = 0;
+            async function lane() {
+                while (next < rows.length && !stopped) {
+                    const row = rows[next++];
+                    try {
+                        current();
+                        const challenge = await rpc('entitybox_native_capacity_health_begin', { p_id: row.id, p_receipt: row.receipt });
+                        if (!challenge || challenge.id !== row.id || challenge.desktopId !== row.desktopId || challenge.runtimeId !== settings.runtimeId
+                            || typeof challenge.challengeId !== 'string' || !uuid.test(challenge.challengeId))
+                            throw new Error();
+                        let state = 'unavailable';
+                        try {
+                            const observation = await (io.observe ?? entitybox_capacity_provisioner_1.observeEntityboxCapacity)({ ...settings, desktopId: row.desktopId, receipt: row.receipt });
+                            if (observation && ['paused', 'running', 'unavailable'].includes(observation.state))
+                                state = observation.state;
+                        }
+                        catch { /* An inconclusive read is unavailable, never healthy. */ }
+                        current();
+                        const accepted = await rpc('entitybox_native_capacity_health_report', { p_id: row.id, p_challenge_id: challenge.challengeId, p_state: state });
+                        if (!accepted || accepted.state !== state || typeof accepted.checkedAt !== 'string' || !Number.isFinite(Date.parse(accepted.checkedAt))
+                            || typeof accepted.validUntil !== 'string' || Date.parse(accepted.validUntil) - Date.parse(accepted.checkedAt) !== 60000)
+                            throw new Error();
+                        report(state, row.desktopId);
+                    }
+                    catch {
+                        if (!stopped)
+                            report('unavailable', row.desktopId);
+                    }
+                }
+            }
+            // Bounded concurrency lets one slow engine read coexist with the other
+            // computers. Server timestamps expire health even when a lane stalls.
+            await Promise.all(Array.from({ length: Math.min(4, rows.length) }, () => lane()));
+        }
+        catch {
+            if (!stopped)
+                report('unavailable');
+        }
+    }
+    function tick() { if (stopped)
+        return Promise.resolve(); if (!flight)
+        flight = run().finally(() => { flight = undefined; }); return flight; }
+    function schedule() { if (stopped)
+        return; timer = setTimeout(() => { void tick().finally(schedule); }, 15000); timer.unref?.(); }
+    return {
+        tick,
+        start() { if (started || stopped)
+            return; started = true; void tick().finally(schedule); },
+        stop() { stopped = true; clearTimeout(timer); },
+        async drain(timeoutMs = 15000) {
+            if (!flight)
+                return true;
+            let deadline;
+            try {
+                return await Promise.race([flight.then(() => true), new Promise(resolve => { deadline = setTimeout(() => resolve(false), Math.max(0, timeoutMs)); })]);
+            }
+            finally {
+                clearTimeout(deadline);
+            }
+        },
+    };
+}

package/dist/entitybox-capacity-host.d.ts

@@ -0,0 +1,17 @@
+import { type EntityboxDesktopBudget } from './entitybox-desktop-admission';
+export interface EntityboxCapacityHostConfiguration {
+    enabled: true;
+    recoverPublication: boolean;
+    imageId: string;
+    dockerContext: string;
+    directory: string;
+    budget: EntityboxDesktopBudget;
+}
+export declare function entityboxCapacityEnvironment(env?: NodeJS.ProcessEnv): EntityboxCapacityHostConfiguration | undefined;
+/** Startup integration only. Default-off; no new native queue or host execution
+ * route. Budget numbers are explicit operator reservations for AddAI desktops,
+ * not claims about other applications or Docker/OS storage quotas. */
+export declare function startEntityboxCapacityHost(env?: NodeJS.ProcessEnv): {
+    stop(): void;
+    drain(_timeout?: number): Promise<boolean>;
+};