@addai/node 0.30.13 → 0.30.15

package/dist/entitybox-capacity-host.js

@@ -0,0 +1,155 @@
+"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.entityboxCapacityEnvironment = entityboxCapacityEnvironment;
+exports.startEntityboxCapacityHost = startEntityboxCapacityHost;
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const paths_1 = require("./paths");
+const store_1 = require("./store");
+const supabase_client_1 = require("./supabase-client");
+const docker_1 = require("./desktop/docker");
+const manager_1 = require("./desktop/manager");
+const entitybox_capacity_worker_1 = require("./entitybox-capacity-worker");
+const entitybox_desktop_admission_1 = require("./entitybox-desktop-admission");
+const exec = (0, util_1.promisify)(child_process_1.execFile);
+function entityboxCapacityEnvironment(env = process.env) {
+    if (env.AINODE_ENTITYBOX_CAPACITY_ENABLED !== '1')
+        return undefined;
+    const budget = { cpus: Number(env.AINODE_ENTITYBOX_DESKTOP_CPUS), memoryMb: Number(env.AINODE_ENTITYBOX_DESKTOP_MEMORY_MB), diskGb: Number(env.AINODE_ENTITYBOX_DESKTOP_DISK_GB) };
+    const imageId = env.AINODE_ENTITYBOX_CAPACITY_IMAGE ?? '', dockerContext = env.AINODE_ENTITYBOX_DOCKER_CONTEXT ?? '', directory = env.AINODE_ENTITYBOX_CAPACITY_DIRECTORY ?? path.join(paths_1.RUNTIME_HOME, 'entitybox', 'capacities');
+    if (env.DOCKER_HOST || !/^sha256:[a-f0-9]{64}$/.test(imageId) || !/^[-a-zA-Z0-9_.]{1,80}$/.test(dockerContext) || !path.isAbsolute(directory) || directory.startsWith('\\\\') || !(0, entitybox_desktop_admission_1.validateEntityboxDesktopBudget)(budget))
+        throw new Error('Invalid EntityBox computer setup configuration');
+    return { enabled: true, recoverPublication: env.AINODE_ENTITYBOX_CAPACITY_RECOVERY_ENABLED === '1', imageId, dockerContext, directory, budget };
+}
+/** 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. */
+function startEntityboxCapacityHost(env = process.env) {
+    const idle = { stop() { }, async drain(_timeout) { return true; } };
+    let configuration;
+    try {
+        configuration = entityboxCapacityEnvironment(env);
+    }
+    catch {
+        console.warn('[entitybox] Computer setup worker is disabled: invalid host configuration.');
+        return idle;
+    }
+    if (!configuration)
+        return idle;
+    const config = configuration;
+    const pairing = (0, store_1.readPairing)();
+    if (!pairing) {
+        console.warn('[entitybox] Computer setup worker requires a paired runtime.');
+        return idle;
+    }
+    let stopping = false;
+    async function policy(rows, id) {
+        const current = (0, store_1.readPairing)();
+        if (stopping || !current || current.runtimeId !== pairing.runtimeId || (0, supabase_client_1.rpcShouldSkip)() || !(0, manager_1.entityboxDesktopLimitKnown)())
+            throw Error('Unavailable');
+        if (!Array.isArray(rows) || !rows.length || rows.length > 1000 || rows.some(r => r.runtime_id !== current.runtimeId))
+            throw Error('Unavailable');
+        // Ordinary native Docker operations use the active context. Never budget a
+        // different engine from the one on which those operations will take place.
+        const context = (await exec('docker', ['context', 'show'], { windowsHide: true, timeout: 5000, maxBuffer: 4096 })).stdout.trim();
+        if (context !== config.dockerContext)
+            throw Error('Unavailable');
+        const provider = await (0, docker_1.getProvider)();
+        if (!provider || provider.id !== 'docker')
+            throw Error('Unavailable');
+        const observations = [];
+        for (const row of rows) {
+            if (row.entitybox_managed) {
+                observations.push({ row, exists: row.status !== 'pending', running: row.status !== 'pending' });
+                continue;
+            }
+            const actual = await provider.inspect(row);
+            observations.push({ row, exists: !!actual, running: actual?.running ?? false });
+        }
+        return (0, entitybox_desktop_admission_1.entityboxDesktopBudget)(observations, id, (0, manager_1.maxConcurrentDesktops)(), config.budget);
+    }
+    const gate = (0, entitybox_desktop_admission_1.installEntityboxDesktopAdmission)(policy);
+    const reported = new Map();
+    const worker = (0, entitybox_capacity_worker_1.createEntityboxCapacityWorker)({ ...config, runtimeId: pairing.runtimeId }, { rpc: supabase_client_1.rpc, pairing: store_1.readPairing,
+        admit: (id, createdAt, action, publicationOnly = false) => (0, entitybox_desktop_admission_1.entityboxWithDesktopStart)(async () => {
+            if (stopping || (0, supabase_client_1.rpcShouldSkip)())
+                return false;
+            const rows = await (0, manager_1.listDesktops)(), row = rows.find(r => r.id === id);
+            if (!row?.entitybox_managed)
+                return false;
+            if (publicationOnly) {
+                // Recovery only reads the already-reserved physical receipt and publishes
+                // it. It must not deadlock behind an ordinary start waiting for that slot.
+                // The worker never routes a provisioner through this branch.
+                const current = (0, store_1.readPairing)();
+                if (!config.recoverPublication || row.status !== 'creating' || row.runtime_id !== pairing.runtimeId || !current || current.runtimeId !== pairing.runtimeId || stopping)
+                    return false;
+                await action();
+                return true;
+            }
+            // The ordinary reconciler owns older start requests. Pending dedicated
+            // rows consume no slot, so yielding cannot deadlock the ordinary queue.
+            if (rows.some(r => !r.entitybox_managed && r.status === 'queued' && (!r.queued_at || !Number.isFinite(Date.parse(r.queued_at)) || Date.parse(r.queued_at) <= Date.parse(createdAt))))
+                return false;
+            const room = await policy(rows, id);
+            if (!room.allowed)
+                return false;
+            if (stopping)
+                return false;
+            await action();
+            return true;
+        }),
+        report: (state, id) => { const key = id ?? 'worker', last = reported.get(key), at = Date.now(); if (last?.state === state && at - last.at < 60000)
+            return; if (reported.size > 1000)
+            reported.clear(); reported.set(key, { state, at }); console.log('[entitybox] Computer setup ' + state + (id ? ' (' + id + ')' : '')); }, });
+    if (!worker) {
+        void gate.close();
+        return idle;
+    }
+    worker.start();
+    let closing;
+    return { stop() { if (stopping)
+            return; stopping = true; worker.stop(); closing = gate.close(); }, async drain(timeout = 15000) {
+            let deadline;
+            try {
+                return await Promise.race([Promise.all([worker.drain(timeout), closing]).then(([complete]) => complete), new Promise(resolve => { deadline = setTimeout(() => resolve(false), Math.max(0, timeout)); })]);
+            }
+            finally {
+                clearTimeout(deadline);
+            }
+        } };
+}

package/dist/entitybox-capacity-owner-process.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entitybox-capacity-owner-process.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const entitybox_capacity_provisioner_1 = require("./entitybox-capacity-provisioner");
+/** Fixed hidden helper. No real pairing, provider, environment-file or native
+ * request-pump imports. Configuration arrives once over private parent IPC.
+ * After setup starts, parent disconnect deliberately does not cancel it. */
+if (require.main === module) {
+    let configured = false;
+    const deadline = setTimeout(() => process.exit(70), 10000);
+    process.once('disconnect', () => { if (!configured)
+        process.exit(70); });
+    process.once('message', async (raw) => {
+        configured = true;
+        clearTimeout(deadline);
+        try {
+            const packet = raw;
+            if (!packet || Object.keys(packet).sort().join(',') !== 'config,plan,type' || packet.type !== 'provision' || packet.config?.enabled !== true)
+                throw Error();
+            const owner = entitybox_capacity_provisioner_1.EntityboxCapacityProvisioner.createReserved(packet.config, packet.plan);
+            if (!owner)
+                throw Error();
+            await owner.provision();
+        }
+        catch {
+            process.exitCode = 70;
+        }
+        finally {
+            if (process.connected)
+                process.disconnect();
+        }
+    });
+}

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

@@ -0,0 +1,16 @@
+import { type ChildProcess, type SpawnOptions } from 'child_process';
+import { readEntityboxCapacity, type EntityboxCapacityConfiguration, type EntityboxCapacityReceipt } from './entitybox-capacity-provisioner';
+interface OwnerIO {
+    /** Trusted fixture seams only. No task/model/renderer configuration. */
+    launch?: (file: string, args: string[], options: SpawnOptions) => ChildProcess;
+    read?: typeof readEntityboxCapacity;
+}
+/** One physical setup process, independent of the runtime controller. The
+ * caller must claim the plan before calling provision(). A parent crash does
+ * not terminate this process or transfer its immutable desktop reservation.
+ * The helper never publishes SQL; recovery verifies its completed receipt. */
+export declare function createEntityboxCapacityOwner(config: EntityboxCapacityConfiguration, io?: OwnerIO): {
+    plan: Readonly<import("./entitybox-capacity-provisioner").EntityboxCapacityPlan>;
+    provision(): Promise<Readonly<EntityboxCapacityReceipt>>;
+} | undefined;
+export {};

package/dist/entitybox-capacity-owner.js

@@ -0,0 +1,90 @@
+"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.createEntityboxCapacityOwner = createEntityboxCapacityOwner;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const entitybox_capacity_provisioner_1 = require("./entitybox-capacity-provisioner");
+const entitybox_recovery_store_1 = require("./entitybox-recovery-store");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const fail = () => new entitybox_execution_lease_1.EntityboxExecutionError('Independent computer setup could not be verified');
+/** One physical setup process, independent of the runtime controller. The
+ * caller must claim the plan before calling provision(). A parent crash does
+ * not terminate this process or transfer its immutable desktop reservation.
+ * The helper never publishes SQL; recovery verifies its completed receipt. */
+function createEntityboxCapacityOwner(config, io = {}) {
+    if (config.enabled !== true)
+        return undefined;
+    const candidate = entitybox_capacity_provisioner_1.EntityboxCapacityProvisioner.create(config);
+    if (!candidate)
+        throw fail();
+    const plan = candidate.plan;
+    const settings = { enabled: true, runtimeId: plan.runtimeId, desktopId: plan.desktopId, imageId: plan.imageId, dockerContext: plan.dockerContext, directory: candidate.directory };
+    let password = config.vncPassword, flight;
+    const planSha256 = (0, crypto_1.createHash)('sha256').update((0, entitybox_recovery_store_1.entityboxCanonical)(plan)).digest('hex');
+    async function run() {
+        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];
+        await new Promise((resolve, reject) => {
+            let child;
+            try {
+                child = (io.launch ?? child_process_1.spawn)(process.execPath, [path.join(__dirname, 'entitybox-capacity-owner-process.js')], { env, detached: true, windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+            }
+            catch {
+                reject(fail());
+                return;
+            }
+            // Join the process even after an IPC/launch error. Neither a lost response
+            // nor a deadline permits another helper or a competing Docker operation.
+            child.on('error', () => { });
+            child.once('close', () => resolve());
+            try {
+                child.send({ type: 'provision', config: { ...settings, vncPassword: password }, plan }, () => { });
+            }
+            catch { /* Completion is determined after process exit. */ }
+            password = '';
+        });
+        // IPC acknowledgement/exit code is not physical proof. The durable original
+        // receipt permits recovery even when the final reply was lost.
+        const receipt = await (io.read ?? entitybox_capacity_provisioner_1.readEntityboxCapacity)(settings.directory, plan.desktopId, plan.runtimeId);
+        if (receipt.planSha256 !== planSha256 || receipt.dockerContext !== plan.dockerContext)
+            throw fail();
+        return receipt;
+    }
+    return { plan, provision() { flight ??= run().catch(() => { throw fail(); }).finally(() => { password = ''; }); return flight; } };
+}

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

@@ -0,0 +1,7 @@
+/** Fixed offline bootstrap programs. No request, prompt, URL or shell input is
+ * interpolated into them. They run in newly created dedicated containers. */
+export declare const entityboxCapacityInit: string;
+export declare const entityboxCapacityDisplay: string;
+export declare const entityboxCapacityPassword: string;
+export declare const entityboxCapacityApplication: string;
+export declare const entityboxCapacityReady: string;

package/dist/entitybox-capacity-programs.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.entityboxCapacityReady = exports.entityboxCapacityApplication = exports.entityboxCapacityPassword = exports.entityboxCapacityDisplay = exports.entityboxCapacityInit = void 0;
+/** Fixed offline bootstrap programs. No request, prompt, URL or shell input is
+ * interpolated into them. They run in newly created dedicated containers. */
+exports.entityboxCapacityInit = String.raw `
+const fs=require('node:fs');
+for(const p of ['/socket','/profile','/work']) {
+ if(fs.readdirSync(p).length)throw Error('Expected empty dedicated volume');
+ fs.chownSync(p,10001,10001);fs.chmodSync(p,p==='/socket'?0o1777:0o700);
+}
+`;
+exports.entityboxCapacityDisplay = String.raw `
+const fs=require('node:fs'),{spawn}=require('node:child_process');
+const options={env:{PATH:'/usr/local/bin:/usr/bin:/bin',HOME:'/tmp',DISPLAY:':1',LANG:'C.UTF-8'},stdio:'ignore'};
+const launch=(command,args)=>{const p=spawn(command,args,options);p.once('error',()=>process.exit(70));p.once('exit',()=>process.exit(71));return p;};
+launch('Xvfb',[':1','-screen','0','1280x800x24','-nolisten','tcp','-ac','-extension','MIT-SHM']);
+const deadline=setTimeout(()=>process.exit(72),45000);
+const poll=setInterval(()=>{
+ if(!fs.existsSync('/tmp/.X11-unix/X1')||!fs.existsSync('/run/entitybox-vnc-password'))return;
+ clearInterval(poll);clearTimeout(deadline);
+ launch('x11vnc',['-display',':1','-rfbport','5900','-listen','0.0.0.0','-passwdfile','rm:/run/entitybox-vnc-password','-forever','-shared','-noshm','-nolookup','-noipv6']);
+},100);
+`;
+// A secret goes through stdin to tmpfs. It is absent from argv, Docker config,
+// persistent volumes, public receipts and logs. x11vnc removes it after reading.
+exports.entityboxCapacityPassword = String.raw `
+const fs=require('node:fs');let value='';
+process.stdin.setEncoding('utf8');process.stdin.on('data',chunk=>{value+=chunk;if(value.length>8)process.exit(70)});
+process.stdin.on('end',()=>{if(!/^[A-Za-z0-9_-]{8}$/.test(value))process.exit(71);fs.writeFileSync('/run/entitybox-vnc-password',value+'\n',{flag:'wx',mode:0o600})});
+`;
+exports.entityboxCapacityApplication = String.raw `
+const fs=require('node:fs'),{spawn}=require('node:child_process');
+const html='<!doctype html><html><meta charset="utf-8"><title>EntityBox computer</title><style>body{margin:0;background:#101115;color:#f4f4f7;font:17px system-ui;display:grid;place-items:center;height:100vh}main{max-width:540px;padding:40px}span{color:#a99cff;font-size:15px}h1{font-size:36px;letter-spacing:-1px}p{color:#a9abb7;line-height:1.7}</style><main><span>ENTITYBOX</span><h1>Your computer is ready.</h1><p>This dedicated browser keeps its state between tasks. Its applications stay paused until a task takes ownership.</p></main></html>';
+fs.writeFileSync('/tmp/entitybox-welcome.html',html);
+const browser=spawn('browser',['--no-sandbox','--disable-dev-shm-usage','--disable-gpu','--disable-background-networking','--disable-component-update','--disable-default-apps','--disable-sync','--metrics-recording-only','--no-first-run','--no-default-browser-check','--user-data-dir=/home/entitybox/browser-profile','--window-size=1280,800','--window-position=0,0','file:///tmp/entitybox-welcome.html'],{env:{PATH:'/usr/local/bin:/usr/bin:/bin',HOME:'/home/entitybox',DISPLAY:':1',LANG:'C.UTF-8'},stdio:'ignore'});
+browser.once('error',()=>process.exit(70));browser.once('exit',()=>process.exit(71));
+`;
+exports.entityboxCapacityReady = String.raw `
+const net=require('node:net'),{spawnSync}=require('node:child_process');
+const x=spawnSync('xdotool',['search','--onlyvisible','--name','EntityBox computer'],{env:{PATH:'/usr/local/bin:/usr/bin:/bin',DISPLAY:':1'},timeout:2000});
+if(x.status!==0)process.exit(70);
+const socket=net.connect(5900,'127.0.0.1');let data=Buffer.alloc(0),phase=0;
+socket.setTimeout(2000,()=>process.exit(71));socket.on('error',()=>process.exit(72));
+socket.on('data',chunk=>{data=Buffer.concat([data,chunk]);
+ if(phase===0&&data.length>=12){if(!/^RFB 003\./.test(data.subarray(0,12).toString()))process.exit(73);data=data.subarray(12);phase=1;socket.write('RFB 003.008\n');}
+ if(phase===1&&data.length&&data.length>=data[0]+1){const types=[...data.subarray(1,1+data[0])];if(types.length!==1||types[0]!==2)process.exit(74);socket.destroy();console.log('ready');}
+});
+`;

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

@@ -0,0 +1,82 @@
+import type { EntityboxDedicatedCapacity } from './entitybox-native-services';
+export interface EntityboxCapacityConfiguration {
+    enabled?: boolean;
+    runtimeId: string;
+    desktopId: string;
+    imageId: string;
+    directory: string;
+    dockerContext?: string;
+    /** Issued and retained by the trusted native desktop allocator. Never a
+     * renderer/task input, and never written to this module's public journal. */
+    vncPassword: string;
+}
+export interface EntityboxCapacityReceipt extends EntityboxDedicatedCapacity {
+    version: 1;
+    dockerContext: string;
+    planSha256: string;
+    vncPort: number;
+    channels: readonly ['screen'];
+    applicationNetwork: 'none';
+}
+export type EntityboxCapacityDocker = (args: string[], stdin?: string) => Promise<string>;
+export interface EntityboxCapacityPlan {
+    version: 1;
+    capacityId: string;
+    runtimeId: string;
+    desktopId: string;
+    imageId: string;
+    dockerContext: string;
+    programsSha256: string;
+}
+export declare const entityboxCapacityLabels: (plan: EntityboxCapacityPlan, role: string) => {
+    'ai.add.entitybox.provision.version': string;
+    'ai.add.entitybox.provision.capacity': string;
+    'ai.add.entitybox.provision.desktop': string;
+    'ai.add.entitybox.provision.runtime': string;
+    'ai.add.entitybox.provision.plan': string;
+    'ai.add.entitybox.provision.role': string;
+};
+/** NEW offline dedicated capacity only. This is deliberately unregistered in
+ * the shared desktop command runner/reconciler. The server must reserve a new
+ * native desktop identity before invoking it, then publish the verified VNC
+ * descriptor through its existing authorization path. */
+export declare class EntityboxCapacityProvisioner {
+    private readonly docker;
+    readonly plan: Readonly<EntityboxCapacityPlan>;
+    readonly directory: string;
+    private result?;
+    private constructor();
+    private password;
+    static create(config: EntityboxCapacityConfiguration, docker?: EntityboxCapacityDocker): EntityboxCapacityProvisioner | undefined;
+    /** Continue a server-claimed plan in its one physical helper. This is not
+     * resumption: run() still atomically reserves the desktop before ANY Docker
+     * operation and rejects an existing reservation, even for the same plan. */
+    static createReserved(config: EntityboxCapacityConfiguration, plan: EntityboxCapacityPlan, docker?: EntityboxCapacityDocker): EntityboxCapacityProvisioner | undefined;
+    /** Calls on this one owner join. A new object/process cannot repeat the
+     * operation: the desktop reservation remains, even after an ambiguous error. */
+    provision(): Promise<Readonly<EntityboxCapacityReceipt>>;
+    private inspect;
+    private until;
+    private run;
+}
+/** Read-only reopening after a clean setup; never resumes, creates, repairs or
+ * deletes anything. Missing/ambiguous setup remains reserved for explicit
+ * recovery. A restarted container or changed published port is not adopted. */
+export declare function readEntityboxCapacity(directory: string, desktopId: string, runtimeId: string, docker?: EntityboxCapacityDocker): Promise<Readonly<EntityboxCapacityReceipt>>;
+export interface EntityboxCapacityObservationConfiguration {
+    enabled?: boolean;
+    directory: string;
+    desktopId: string;
+    runtimeId: string;
+    dockerContext: string;
+    /** Exact published native registry receipt, never a renderer-selected binding. */
+    receipt: Readonly<EntityboxCapacityReceipt>;
+}
+export type EntityboxCapacityObservation = Readonly<{
+    state: 'paused' | 'running' | 'unavailable';
+}>;
+/** A health observation is never execution, ownership, stop proof or permission
+ * to replace a computer. Every physical read is limited to this published
+ * receipt; unavailable includes missing evidence and inconclusive inspection.
+ * The existing task reader continues to require a paused application. */
+export declare function observeEntityboxCapacity(config: EntityboxCapacityObservationConfiguration, docker?: EntityboxCapacityDocker): Promise<EntityboxCapacityObservation | undefined>;