@addai/node 0.30.12 → 0.30.14

package/dist/entitybox-controller-recovery.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxControllerRecovery = void 0;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const crypto_1 = require("crypto");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_mcp_contract_1 = require("./entitybox-mcp-contract");
+const entitybox_application_boundary_1 = require("./entitybox-application-boundary");
+const entitybox_display_binding_1 = require("./entitybox-display-binding");
+const entitybox_host_process_1 = require("./entitybox-host-process");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const uuid = /^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/, exec = (0, util_1.promisify)(child_process_1.execFile), fail = () => new entitybox_execution_lease_1.EntityboxExecutionError('Native controller recovery could not be verified');
+const terminal = ['completed', 'failed', 'canceled', 'dead_letter', 'deleted'];
+/** Retain this object across failed/lost replies: the recovery nonce is private,
+ * and retries use the same ID. No timeout hands recovery to another process.
+ * A completed attempt returns BEFORE any Docker operation, including replay
+ * after a replacement task has resumed the retained application. */
+class EntityboxControllerRecovery {
+    options;
+    id = (0, crypto_1.randomUUID)();
+    nonce = (0, crypto_1.randomUUID)();
+    identity;
+    context;
+    docker;
+    owner;
+    pending;
+    completed;
+    constructor(options) {
+        this.options = options;
+        const i = options.identity;
+        if (!i || !uuid.test(i.requestId) || !uuid.test(i.attemptId))
+            throw fail();
+        this.identity = Object.freeze({ requestId: i.requestId, attemptId: i.attemptId, scope: (0, entitybox_mcp_contract_1.parseEntityboxMcpScope)(i.scope) });
+        this.context = options.dockerContext ?? 'desktop-linux';
+        if (!/^[-a-zA-Z0-9_.]{1,80}$/.test(this.context))
+            throw fail();
+        this.docker = options.docker ?? (async (args) => (await exec('docker', ['--context', this.context, ...args], { windowsHide: true, ...(args[0] === 'container' && args[1] === 'rm' ? {} : { timeout: 5000 }), maxBuffer: 1024 * 1024 })).stdout.trim());
+    }
+    run() {
+        if (this.completed)
+            return Promise.resolve(this.completed);
+        if (this.pending)
+            return this.pending;
+        this.pending = this.recover().then(status => { this.completed = status; return status; }).catch(() => { throw fail(); }).finally(() => { this.pending = undefined; });
+        return this.pending;
+    }
+    async call(name, args = {}) {
+        let timer;
+        try {
+            const raw = await Promise.race([this.options.rpc('entitybox_native_execution_recovery_' + name, { p_token: this.options.token(), p_attempt_id: this.identity.attemptId, ...args }), new Promise((_, reject) => { timer = setTimeout(() => reject(fail()), 4500); })]);
+            return this.snapshot(raw);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    snapshot(raw) {
+        const s = raw;
+        if (!s || s.attemptId !== this.identity.attemptId || s.requestId !== this.identity.requestId || s.runId !== this.identity.scope.runId || !Number.isSafeInteger(s.epoch) || s.epoch < 1
+            || (0, entitybox_recovery_store_1.entityboxCanonical)((0, entitybox_mcp_contract_1.parseEntityboxMcpScope)(s.scope)) !== (0, entitybox_recovery_store_1.entityboxCanonical)(this.identity.scope) || !['running', 'stop_requested', 'stopped'].includes(s.phase) || ![...terminal, 'starting', 'running'].includes(s.requestStatus))
+            throw fail();
+        return s;
+    }
+    ended(s) { if (s.phase !== 'stopped')
+        return; if (!terminal.includes(s.requestStatus))
+        throw fail(); return s.requestStatus; }
+    recovery(s) {
+        const r = s.recovery;
+        if (r === null)
+            return null;
+        if (!r || !uuid.test(r.id) || !Number.isSafeInteger(r.generation) || r.generation < 1 || r.hostId !== this.options.store.hostId || r.phase !== 'checking')
+            throw fail();
+        (0, entitybox_host_process_1.parseEntityboxHostProcess)(r.owner);
+        return r;
+    }
+    async recover() {
+        let snapshot = await this.call('status');
+        const ended = this.ended(snapshot);
+        if (ended)
+            return ended;
+        const h = (0, entitybox_recovery_store_1.parseEntityboxRecoveryHost)(snapshot.host), inventory = snapshot.inventory;
+        if (h.hostId !== this.options.store.hostId || h.dockerContext !== this.context || inventory?.sealed !== true || typeof inventory.hasExecution !== 'boolean' || !Array.isArray(inventory.resources) || inventory.resources.length !== (inventory.hasExecution ? 3 : 2))
+            throw fail();
+        const resource = (kind, keys) => { const list = inventory.resources.filter(r => r.kind === kind); if (list.length !== 1)
+            throw fail(); const b = list[0].binding; if (!b || Object.keys(b).sort().join(',') !== keys.sort().join(',') || !Object.values(b).every(v => typeof v === 'string'))
+            throw fail(); return b; };
+        const app = resource('application', ['capacityId', 'desktopId', 'runtimeId', 'containerId', 'imageId', 'startedAt']);
+        const display = resource('display', ['capacityId', 'desktopId', 'runtimeId', 'containerId', 'imageId', 'startedAt']);
+        if (app.capacityId !== display.capacityId || app.containerId === display.containerId)
+            throw fail();
+        const executor = inventory.hasExecution ? resource('execution', ['containerId', 'imageId', 'watchdogSha256']) : null;
+        if (executor && (!/^[a-f0-9]{64}$/.test(executor.containerId) || !/^sha256:[a-f0-9]{64}$/.test(executor.imageId) || !/^[a-f0-9]{64}$/.test(executor.watchdogSha256) || [app.containerId, display.containerId].includes(executor.containerId)))
+            throw fail();
+        const evidence = this.options.store.readProof(this.identity.attemptId), proof = evidence.value;
+        if ((0, entitybox_recovery_store_1.entityboxCanonical)(proof.host) !== (0, entitybox_recovery_store_1.entityboxCanonical)(h) || (0, entitybox_recovery_store_1.entityboxCanonical)(proof.identity) !== (0, entitybox_recovery_store_1.entityboxCanonical)(this.identity) || (0, entitybox_recovery_store_1.entityboxCanonical)(proof.application) !== (0, entitybox_recovery_store_1.entityboxCanonical)(app)
+            || proof.proof?.attemptId !== this.identity.attemptId || proof.proof.capacityId !== app.capacityId || proof.proof.containerId !== app.containerId || !['paused', 'stopped'].includes(proof.proof.state) || !Number.isFinite(Date.parse(proof.proof.observedAt)))
+            throw fail();
+        const gone = this.options.assertGone ?? entitybox_host_process_1.assertEntityboxHostProcessGone;
+        await gone(h.controller);
+        await gone(h.guard);
+        if (!this.owner) {
+            const owner = await (this.options.readProcess ?? entitybox_host_process_1.readEntityboxHostProcess)();
+            if (!owner)
+                throw fail();
+            this.owner = (0, entitybox_host_process_1.parseEntityboxHostProcess)(owner);
+        }
+        if (this.owner.platform !== h.controller.platform)
+            throw fail();
+        const previous = this.recovery(snapshot);
+        if (previous && previous.id !== this.id)
+            await gone(previous.owner);
+        snapshot = await this.call('claim', { p_recovery_id: this.id, p_recovery_nonce: this.nonce, p_host_id: h.hostId, p_owner: this.owner, p_expected_id: previous?.id ?? null, p_expected_generation: previous?.generation ?? 0 });
+        const finished = this.ended(snapshot);
+        if (finished)
+            return finished;
+        const claimed = this.recovery(snapshot);
+        if (!claimed || claimed.id !== this.id || (0, entitybox_recovery_store_1.entityboxCanonical)(claimed.owner) !== (0, entitybox_recovery_store_1.entityboxCanonical)(this.owner) || snapshot.phase !== 'stop_requested')
+            throw fail();
+        // These are observations only. Recovery never unpauses, pauses, restarts or
+        // adopts an application/display. The old guard already joined its mutations.
+        await (0, entitybox_display_binding_1.verifyEntityboxDisplay)(display, this.identity.scope, this.docker);
+        let state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(app, this.identity.scope, this.docker);
+        if (state === 'running')
+            throw fail();
+        if (executor)
+            await this.retire(executor);
+        state = await (0, entitybox_application_boundary_1.inspectEntityboxApplication)(app, this.identity.scope, this.docker);
+        if (state === 'running')
+            throw fail();
+        const final = await this.call('complete', { p_recovery_id: this.id, p_recovery_nonce: this.nonce, p_generation: claimed.generation, p_proof: { guardSha256: evidence.sha256, applicationState: state, executorRemoved: !!executor } });
+        const status = this.ended(final);
+        if (!status)
+            throw fail();
+        return status;
+    }
+    async retire(resource) {
+        const list = async () => { const value = (await this.docker(['container', 'ls', '--all', '--no-trunc', '--filter', 'id=' + resource.containerId, '--format', '{{.ID}}'])).trim(); if (value !== '' && value !== resource.containerId)
+            throw fail(); return value; };
+        if (await list() === '')
+            return;
+        const rows = JSON.parse(await this.docker(['container', 'inspect', resource.containerId]));
+        if (!Array.isArray(rows) || rows.length !== 1)
+            throw fail();
+        const c = rows[0], labels = c?.Config?.Labels;
+        if (c?.Id !== resource.containerId || c.Image !== resource.imageId || labels?.['ai.add.entitybox.execution'] !== this.identity.attemptId || labels?.['ai.add.entitybox.execution.request'] !== this.identity.requestId || labels?.['ai.add.entitybox.execution.watchdog'] !== resource.watchdogSha256
+            || c.HostConfig?.RestartPolicy?.Name !== 'no' || c.State?.Running !== false || c.State.Pid !== 0 || c.State.Paused !== false || c.State.Restarting !== false || !['exited', 'dead', 'created'].includes(c.State.Status))
+            throw fail();
+        // Join the actual CLI lifecycle. No force and no mutation deadline. Even a
+        // late reply targets only this immutable, never-reused old executor ID.
+        await this.docker(['container', 'rm', resource.containerId]);
+        if (await list() !== '')
+            throw fail();
+    }
+}
+exports.EntityboxControllerRecovery = EntityboxControllerRecovery;

package/dist/entitybox-desktop-action-server.d.ts

@@ -0,0 +1,34 @@
+import type { EntityboxExecutionLease } from './entitybox-execution-lease';
+import type { EntityboxExecutionContainer } from './entitybox-execution-container';
+import type { EntityboxDesktopActionOwner } from './entitybox-mcp-broker';
+import type { EntityboxMcpScope } from './entitybox-mcp-contract';
+/** Host-only bridge for the actual native MCP. The isolated model has neither
+ * network access to this endpoint nor its bearer token. Native entity access
+ * checks remain in the MCP before every dispatch. */
+export declare class EntityboxDesktopActionServer implements EntityboxDesktopActionOwner {
+    private readonly lease;
+    private readonly container;
+    readonly scope: EntityboxMcpScope;
+    private readonly server;
+    private readonly token;
+    private configuration?;
+    private readonly seen;
+    private readonly pending;
+    private stopping?;
+    private closing;
+    private constructor();
+    static start(lease: EntityboxExecutionLease, container: EntityboxExecutionContainer): Promise<EntityboxDesktopActionServer>;
+    get transport(): {
+        configuration: string;
+        token: string;
+        capability: {
+            version: number;
+            requestId: string;
+            attemptId: string;
+            scope: EntityboxMcpScope;
+        };
+    };
+    assertActive(): Promise<void>;
+    private handle;
+    stopAndVerify(): Promise<void>;
+}

package/dist/entitybox-desktop-action-server.js

@@ -0,0 +1,176 @@
+"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.EntityboxDesktopActionServer = void 0;
+const http = __importStar(require("http"));
+const crypto_1 = require("crypto");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+/** Host-only bridge for the actual native MCP. The isolated model has neither
+ * network access to this endpoint nor its bearer token. Native entity access
+ * checks remain in the MCP before every dispatch. */
+class EntityboxDesktopActionServer {
+    lease;
+    container;
+    scope;
+    server;
+    token = (0, crypto_1.randomBytes)(32).toString('hex');
+    configuration;
+    seen = new Set();
+    pending = new Set();
+    stopping;
+    closing = false;
+    constructor(lease, container) {
+        this.lease = lease;
+        this.container = container;
+        this.scope = lease.identity.scope;
+        if (!container.hasDedicatedDisplay || container.executionIdentity.requestId !== lease.identity.requestId
+            || container.executionIdentity.attemptId !== lease.identity.attemptId)
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Contained desktop binding required');
+        this.server = http.createServer((req, res) => {
+            const done = this.handle(req, res).finally(() => this.pending.delete(done));
+            this.pending.add(done);
+        });
+        this.server.requestTimeout = 15000;
+        this.server.headersTimeout = 10000;
+        this.server.keepAliveTimeout = 1000;
+        this.server.maxRequestsPerSocket = 1;
+        this.server.on('error', () => lease.fence());
+        lease.signal.addEventListener('abort', () => { void this.stopAndVerify().catch(() => { }); }, { once: true });
+    }
+    static async start(lease, container) {
+        const bridge = new EntityboxDesktopActionServer(lease, container);
+        try {
+            await bridge.assertActive();
+            await new Promise((resolve, reject) => { bridge.server.once('error', reject); bridge.server.listen(0, '127.0.0.1', () => { bridge.server.removeListener('error', reject); resolve(); }); });
+            const address = bridge.server.address();
+            if (!address || typeof address === 'string')
+                throw new Error();
+            bridge.configuration = JSON.stringify({ version: 1, endpoint: 'http://127.0.0.1:' + address.port + '/entitybox/action', token: bridge.token, identity: lease.identity });
+            await bridge.assertActive();
+            return bridge;
+        }
+        catch {
+            lease.fence();
+            await bridge.stopAndVerify().catch(() => { });
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Contained desktop bridge could not start');
+        }
+    }
+    get transport() {
+        if (!this.configuration)
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Contained desktop bridge unavailable');
+        return { configuration: this.configuration, token: this.token, capability: { version: 1, requestId: this.lease.identity.requestId, attemptId: this.lease.identity.attemptId, scope: this.scope } };
+    }
+    async assertActive() {
+        try {
+            if (this.closing)
+                throw new Error();
+            await this.container.assertActive();
+            this.lease.assertActive();
+        }
+        catch {
+            this.lease.fence();
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Contained desktop authority ended');
+        }
+    }
+    async handle(req, res) {
+        const auth = Buffer.from(req.headers.authorization ?? ''), expected = Buffer.from('Bearer ' + this.token);
+        if (req.method !== 'POST' || req.url !== '/entitybox/action' || req.headers.origin !== undefined
+            || auth.length !== expected.length || !(0, crypto_1.timingSafeEqual)(auth, expected)) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        const abort = new AbortController();
+        const lost = () => { if (!res.writableFinished) {
+            abort.abort();
+            this.lease.fence();
+        } };
+        req.once('aborted', lost);
+        res.once('close', lost);
+        try {
+            await this.assertActive();
+            let input = '';
+            req.setEncoding('utf8');
+            for await (const part of req) {
+                input += part;
+                if (Buffer.byteLength(input) > 512 * 1024)
+                    throw new Error();
+            }
+            const p = JSON.parse(input), i = p?.identity;
+            if (p?.version !== 1 || typeof p.actionId !== 'string' || !/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(p.actionId)
+                || i?.requestId !== this.lease.identity.requestId || i?.attemptId !== this.lease.identity.attemptId || i?.scope?.version !== 1
+                || !['runId', 'desktopId', 'runtimeId'].every(k => i.scope[k] === this.scope[k])
+                || p.desktopId !== this.scope.desktopId || p.runtimeId !== this.scope.runtimeId || p.display !== ':1'
+                || typeof p.input !== 'string' || p.input.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(p.input)
+                || this.seen.has(p.actionId) || this.seen.size >= 1024)
+                throw new Error();
+            this.seen.add(p.actionId);
+            const result = await this.container.executeAction({ argv: p.argv, input: Buffer.from(p.input, 'base64'), timeoutMs: p.timeoutMs, display: ':1', signal: abort.signal });
+            await this.assertActive();
+            res.writeHead(200, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            res.end(JSON.stringify({ version: 1, actionId: p.actionId, stdout: result.stdout.toString('base64'), stderr: result.stderr.toString('base64'), code: result.code }));
+        }
+        catch {
+            this.lease.fence();
+            if (!res.headersSent)
+                res.writeHead(409);
+            res.end();
+        }
+        finally {
+            req.removeListener('aborted', lost);
+            res.removeListener('close', lost);
+        }
+    }
+    async stopAndVerify() {
+        if (this.stopping)
+            return this.stopping;
+        this.closing = true;
+        this.stopping = Promise.resolve().then(async () => {
+            const closed = new Promise(resolve => { this.server.close(() => resolve()); this.server.closeAllConnections(); });
+            await this.container.stopAndVerify();
+            await Promise.all([...this.pending]);
+            await closed;
+        });
+        this.lease.fence();
+        try {
+            await this.stopping;
+        }
+        catch (error) {
+            this.stopping = undefined;
+            throw error;
+        }
+    }
+}
+exports.EntityboxDesktopActionServer = EntityboxDesktopActionServer;

package/dist/entitybox-desktop-admission.d.ts

@@ -0,0 +1,32 @@
+import type { DesktopRow } from './desktop/spec';
+export type EntityboxAdmission = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+};
+export interface EntityboxDesktopBudget {
+    cpus: number;
+    memoryMb: number;
+    diskGb: number;
+}
+export interface EntityboxDesktopObservation {
+    row: DesktopRow;
+    exists: boolean;
+    running: boolean;
+}
+type Policy = (rows: DesktopRow[], id: string) => Promise<EntityboxAdmission>;
+/** Opt-in host gate. With no EntityBox worker, existing native callers keep
+ * their original behavior and do not gain an extra RPC or engine inspection. */
+export declare function entityboxAdmissionEnabled(): boolean;
+export declare function entityboxDesktopAdmission(rows: DesktopRow[], id: string): Promise<EntityboxAdmission | undefined>;
+export declare function entityboxWithDesktopStart<T>(action: () => Promise<T>): Promise<T>;
+export declare function installEntityboxDesktopAdmission(check: Policy): {
+    close: () => Promise<void>;
+};
+export declare function validateEntityboxDesktopBudget(b: EntityboxDesktopBudget): boolean;
+/** Reservation accounting for AddAI desktops, not an OS quota. A stopped
+ * computer retains disk; a claimed/uncertain dedicated computer retains every
+ * reservation until explicit lifecycle cleanup. Unclaimed new rows use none. */
+export declare function entityboxDesktopBudget(observations: EntityboxDesktopObservation[], target: string, maxSlots: number, budget: EntityboxDesktopBudget): EntityboxAdmission;
+export {};

package/dist/entitybox-desktop-admission.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityboxAdmissionEnabled = entityboxAdmissionEnabled;
+exports.entityboxDesktopAdmission = entityboxDesktopAdmission;
+exports.entityboxWithDesktopStart = entityboxWithDesktopStart;
+exports.installEntityboxDesktopAdmission = installEntityboxDesktopAdmission;
+exports.validateEntityboxDesktopBudget = validateEntityboxDesktopBudget;
+exports.entityboxDesktopBudget = entityboxDesktopBudget;
+const unavailable = () => ({ allowed: false, reason: 'Desktop capacity could not be verified. Check the runtime and try again.' });
+let installed;
+/** Opt-in host gate. With no EntityBox worker, existing native callers keep
+ * their original behavior and do not gain an extra RPC or engine inspection. */
+function entityboxAdmissionEnabled() { return installed !== undefined; }
+async function entityboxDesktopAdmission(rows, id) {
+    const owner = installed;
+    if (!owner)
+        return undefined;
+    if (owner.closing)
+        return unavailable();
+    try {
+        return await owner.check(rows, id);
+    }
+    catch {
+        return unavailable();
+    }
+}
+function entityboxWithDesktopStart(action) {
+    const owner = installed;
+    if (!owner)
+        return action();
+    if (owner.closing)
+        return Promise.reject(new Error('Desktop admission is stopping. Try again when the runtime is ready.'));
+    const result = owner.tail.then(action);
+    owner.tail = result.then(() => { }, () => { });
+    return result;
+}
+function installEntityboxDesktopAdmission(check) {
+    if (installed)
+        throw new Error('EntityBox desktop admission is already configured');
+    const owner = { check, tail: Promise.resolve(), closing: false };
+    installed = owner;
+    return { async close() { owner.closing = true; await owner.tail; if (installed === owner)
+            installed = undefined; } };
+}
+function validateEntityboxDesktopBudget(b) {
+    return !!b && Number.isFinite(b.cpus) && b.cpus >= 2 && b.cpus <= 128 && Number.isInteger(b.memoryMb) && b.memoryMb >= 2048 && b.memoryMb <= 262144 && Number.isInteger(b.diskGb) && b.diskGb >= 20 && b.diskGb <= 16384;
+}
+/** Reservation accounting for AddAI desktops, not an OS quota. A stopped
+ * computer retains disk; a claimed/uncertain dedicated computer retains every
+ * reservation until explicit lifecycle cleanup. Unclaimed new rows use none. */
+function entityboxDesktopBudget(observations, target, maxSlots, budget) {
+    if (!validateEntityboxDesktopBudget(budget) || !Number.isInteger(maxSlots) || maxSlots < 1 || maxSlots > 16)
+        return unavailable();
+    const found = observations.filter(o => o.row.id === target);
+    if (found.length !== 1 || new Set(observations.map(o => o.row.id)).size !== observations.length)
+        return unavailable();
+    let slots = 0, cpus = 0, memory = 0, disk = 0;
+    for (const { row, exists, running } of observations) {
+        const selected = row.id === target, managed = row.entitybox_managed === true;
+        if (!['pending', 'creating', 'starting', 'running', 'stopped', 'failed', 'deleting', 'queued'].includes(row.status) || typeof exists !== 'boolean' || typeof running !== 'boolean' || running && !exists)
+            return unavailable();
+        const reserved = selected || (managed ? row.status !== 'pending' : running || ['creating', 'starting', 'deleting'].includes(row.status));
+        const retainsDisk = selected || exists || row.status !== 'pending';
+        if (reserved && (!Number.isFinite(row.cpus) || row.cpus <= 0 || !Number.isFinite(row.memory_mb) || row.memory_mb <= 0) || retainsDisk && (!Number.isFinite(row.disk_gb) || row.disk_gb <= 0))
+            return unavailable();
+        if (reserved) {
+            slots++;
+            cpus += row.cpus;
+            memory += row.memory_mb;
+        }
+        if (retainsDisk)
+            disk += row.disk_gb;
+    }
+    if (slots > maxSlots)
+        return { allowed: false, reason: 'This runtime has no free desktop slot. Waiting for capacity.' };
+    if (cpus > budget.cpus || memory > budget.memoryMb || disk > budget.diskGb)
+        return { allowed: false, reason: 'This runtime’s desktop resource budget is fully reserved. Waiting for capacity.' };
+    return { allowed: true };
+}

package/dist/entitybox-display-binding.d.ts

@@ -0,0 +1,13 @@
+import type { EntityboxMcpScope } from './entitybox-mcp-contract';
+/** Trusted descriptor for NEW dedicated native capacity. Existing desktops do
+ * not have these labels and cannot be silently adopted or recreated. */
+export interface EntityboxDisplayBinding {
+    capacityId: string;
+    desktopId: string;
+    runtimeId: string;
+    containerId: string;
+    imageId: string;
+    startedAt: string;
+}
+export declare function entityboxDisplayVolume(binding: EntityboxDisplayBinding): string;
+export declare function verifyEntityboxDisplay(binding: EntityboxDisplayBinding, scope: EntityboxMcpScope, docker: (args: string[]) => Promise<string>): Promise<void>;

package/dist/entitybox-display-binding.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityboxDisplayVolume = entityboxDisplayVolume;
+exports.verifyEntityboxDisplay = verifyEntityboxDisplay;
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+function entityboxDisplayVolume(binding) {
+    if (!/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(binding?.capacityId))
+        throw new entitybox_execution_lease_1.EntityboxExecutionError('Invalid dedicated display');
+    return 'entitybox-display-' + binding.capacityId;
+}
+async function verifyEntityboxDisplay(binding, scope, docker) {
+    const volume = entityboxDisplayVolume(binding);
+    if (binding.desktopId !== scope.desktopId || binding.runtimeId !== scope.runtimeId
+        || !/^[0-9a-f]{64}$/.test(binding.containerId) || !/^sha256:[0-9a-f]{64}$/.test(binding.imageId)
+        || typeof binding.startedAt !== 'string' || binding.startedAt.length > 80 || !Number.isFinite(Date.parse(binding.startedAt)))
+        throw new entitybox_execution_lease_1.EntityboxExecutionError('Invalid dedicated display');
+    const [containerText, volumeText] = await Promise.all([docker(['container', 'inspect', binding.containerId]), docker(['volume', 'inspect', volume])]);
+    const c = JSON.parse(containerText)[0], v = JSON.parse(volumeText)[0];
+    const labels = (value) => value?.['ai.add.entitybox.display.version'] === '1'
+        && value['ai.add.entitybox.display.capacity'] === binding.capacityId
+        && value['ai.add.entitybox.display.desktop'] === binding.desktopId
+        && value['ai.add.entitybox.display.runtime'] === binding.runtimeId;
+    const socket = c?.Mounts?.filter((m) => m.Destination === '/tmp/.X11-unix');
+    if (c?.Id !== binding.containerId || c.Image !== binding.imageId || !labels(c.Config?.Labels)
+        || !c.State?.Running || c.State.Pid <= 0 || c.State.StartedAt !== binding.startedAt
+        || c.HostConfig?.Privileged || c.HostConfig?.Binds?.length || !['', 'private'].includes(c.HostConfig?.PidMode ?? '') || c.HostConfig?.NetworkMode === 'host'
+        || !Array.isArray(c.Mounts) || c.Mounts.some((m) => m.Type !== 'tmpfs' && m.Destination !== '/tmp/.X11-unix')
+        || socket?.length !== 1 || socket[0].Type !== 'volume' || socket[0].Name !== volume || socket[0].RW !== true
+        || v?.Name !== volume || v.Driver !== 'local' || Object.keys(v.Options ?? {}).length || !labels(v.Labels))
+        throw new entitybox_execution_lease_1.EntityboxExecutionError('Dedicated display ownership changed');
+}

package/dist/entitybox-execution-container.d.ts

@@ -0,0 +1,82 @@
+import { type EntityboxExecutionLease } from './entitybox-execution-lease';
+import { type EntityboxDisplayBinding } from './entitybox-display-binding';
+import type { EntityboxBrokerEmit } from './entitybox-provider-broker';
+export interface EntityboxActionOptions {
+    argv: readonly string[];
+    input?: Buffer;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    display?: ':1';
+}
+export interface EntityboxActionResult {
+    stdout: Buffer;
+    stderr: Buffer;
+    code: number;
+}
+export interface EntityboxExecutionResource {
+    containerId: string;
+    imageId: string;
+    watchdogSha256: string;
+}
+interface Options {
+    /** Durable public identity must settle before Docker start is issued. */
+    onCreated?: (resource: Readonly<EntityboxExecutionResource>) => Promise<void>;
+    imageId: string;
+    dockerContext?: string;
+    /** Trusted capacity setting. Small synthetic fixtures explicitly use 256. */
+    memoryMiB?: number;
+    /** Optional read-only socket of separately owned, dedicated native capacity. */
+    display?: EntityboxDisplayBinding;
+    /** Trusted adapter configuration, NEVER command text from a task or model. */
+    command: string[];
+    /** Public task data only. Credentialed tools/providers belong to a broker. */
+    task: unknown;
+    onOutput: (data: Buffer) => void;
+    onBroker?: (request: unknown, signal: AbortSignal, emit: EntityboxBrokerEmit) => Promise<void>;
+}
+/** Owns a new container by its immutable ID. It never enters, mounts, changes
+ * or stops a native desktop. External tool actions must acquire their own
+ * verified stop boundary before this can serve as a complete task executor. */
+export declare class EntityboxExecutionContainer {
+    private readonly lease;
+    private readonly options;
+    private readonly proc;
+    private readonly docker;
+    private readonly watchdogDigest;
+    private readonly actionSource;
+    readonly done: Promise<number>;
+    readonly id: string;
+    failureCode: 'entitybox_broker_connection_failed' | undefined;
+    private stopped?;
+    private output;
+    private modelExit?;
+    private closed;
+    private stopping;
+    private ready;
+    private readonly started;
+    private startedResolve;
+    private startedReject;
+    private readonly actions;
+    private readonly requests;
+    private constructor();
+    static start(lease: EntityboxExecutionLease, options: Options): Promise<EntityboxExecutionContainer>;
+    private consume;
+    private broker;
+    private grant;
+    get scope(): import("./entitybox-mcp-contract").EntityboxMcpScope;
+    whenStarted(): Promise<void>;
+    get executionIdentity(): Readonly<import("./entitybox-execution-lease").EntityboxExecutionIdentity>;
+    get hasDedicatedDisplay(): boolean;
+    assertActive(): Promise<void>;
+    private inspectOwned;
+    /** Commands run only in this task's PID namespace. No native desktop, host
+     * execution or remote-queue fallback is permitted here. A lost exec transport
+     * fences the entire task: closing a Docker client is not proof of inner stop. */
+    executeAction(options: EntityboxActionOptions): Promise<EntityboxActionResult>;
+    stopAndVerify(): Promise<void>;
+    private stopOwned;
+    /** Keep the stopped resource until the caller has recorded its stop receipt.
+     * Missing/unverifiable resources cannot themselves prove process shutdown. */
+    removeStopped(): Promise<void>;
+}
+export {};