@addai/node 0.30.12 → 0.30.14

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

@@ -0,0 +1,36 @@
+import { readEntityboxCapacity, type EntityboxCapacityConfiguration, type EntityboxCapacityPlan, type EntityboxCapacityReceipt } from './entitybox-capacity-provisioner';
+type Rpc = <T>(name: string, args: Record<string, unknown>) => Promise<T>;
+export interface EntityboxCapacityAllocation {
+    id: string;
+    runtimeId: string;
+    desktopId: string;
+}
+export interface EntityboxCapacityRegistrationConfiguration {
+    enabled?: boolean;
+    recoverPublication?: boolean;
+    allocation: EntityboxCapacityAllocation;
+    imageId: string;
+    directory: string;
+    dockerContext?: string;
+}
+export interface EntityboxCapacityRegistrationIO {
+    pairing: () => {
+        runtimeId: string;
+        daemonToken: string;
+    } | null;
+    rpc: Rpc;
+    /** Fixture-only injection. Host callers normally use the actual provisioner. */
+    create?: (configuration: EntityboxCapacityConfiguration) => {
+        plan: Readonly<EntityboxCapacityPlan>;
+        provision: () => Promise<Readonly<EntityboxCapacityReceipt>>;
+    } | undefined;
+    read?: typeof readEntityboxCapacity;
+}
+/** One provisioning owner, with native SQL claim BEFORE Docker work and
+ * verified physical readiness BEFORE native publication. No request-pump or
+ * timer registration occurs merely by importing this module. A fresh process
+ * cannot steal an uncertain claim; setup recovery is a separate contract. */
+export declare function createEntityboxCapacityRegistration(config: EntityboxCapacityRegistrationConfiguration, io: EntityboxCapacityRegistrationIO): {
+    provision: () => Promise<Readonly<EntityboxCapacityReceipt>>;
+} | undefined;
+export {};

package/dist/entitybox-capacity-registration.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntityboxCapacityRegistration = createEntityboxCapacityRegistration;
+const entitybox_capacity_owner_1 = require("./entitybox-capacity-owner");
+const entitybox_capacity_publication_1 = require("./entitybox-capacity-publication");
+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 uuid = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/, fail = () => new entitybox_execution_lease_1.EntityboxExecutionError('Dedicated computer registration could not be verified');
+/** One provisioning owner, with native SQL claim BEFORE Docker work and
+ * verified physical readiness BEFORE native publication. No request-pump or
+ * timer registration occurs merely by importing this module. A fresh process
+ * cannot steal an uncertain claim; setup recovery is a separate contract. */
+function createEntityboxCapacityRegistration(config, io) {
+    if (config.enabled !== true)
+        return undefined;
+    const allocation = Object.freeze({ id: config.allocation?.id, runtimeId: config.allocation?.runtimeId, desktopId: config.allocation?.desktopId });
+    if (!allocation || ![allocation.id, allocation.runtimeId, allocation.desktopId].every(v => uuid.test(v)))
+        throw fail();
+    const recovery = config.recoverPublication === true, nonce = (0, crypto_1.randomUUID)(), directory = config.directory, context = config.dockerContext ?? 'desktop-linux';
+    let password = (0, crypto_1.randomBytes)(6).toString('base64url');
+    const candidate = (io.create ?? (recovery ? entitybox_capacity_owner_1.createEntityboxCapacityOwner : entitybox_capacity_provisioner_1.EntityboxCapacityProvisioner.create))({ enabled: true, runtimeId: allocation.runtimeId, desktopId: allocation.desktopId, imageId: config.imageId, directory, dockerContext: context, vncPassword: password });
+    if (!candidate)
+        throw fail();
+    const owner = candidate;
+    const plan = JSON.parse((0, entitybox_recovery_store_1.entityboxCanonical)(owner.plan));
+    if (plan.runtimeId !== allocation.runtimeId || plan.desktopId !== allocation.desktopId || plan.dockerContext !== context || plan.imageId !== config.imageId)
+        throw fail();
+    let flight, physical, complete;
+    const token = () => { const p = io.pairing(); if (!p || p.runtimeId !== allocation.runtimeId || typeof p.daemonToken !== 'string' || !p.daemonToken)
+        throw fail(); return p.daemonToken; };
+    function validate(reply, phase) {
+        if (!reply || reply.id !== allocation.id || reply.runtimeId !== allocation.runtimeId || reply.desktopId !== allocation.desktopId || reply.phase !== phase
+            || (0, entitybox_recovery_store_1.entityboxCanonical)(reply.plan) !== (0, entitybox_recovery_store_1.entityboxCanonical)(plan))
+            throw fail();
+        if (phase === 'ready' && (!physical || (0, entitybox_recovery_store_1.entityboxCanonical)(reply.receipt) !== (0, entitybox_recovery_store_1.entityboxCanonical)(physical)))
+            throw fail();
+    }
+    async function run() {
+        // Persist the original authority before any SQL claim. Opt-in only; this
+        // encrypted record permits read-only publication recovery after a restart.
+        if (recovery)
+            new entitybox_capacity_publication_1.EntityboxCapacityPublicationStore(directory, true).write({ version: 1, allocation, plan, nonce, password }, token());
+        const claimed = await io.rpc('entitybox_native_capacity_claim', { p_token: token(), p_id: allocation.id, p_nonce: nonce, p_plan: plan });
+        if (claimed?.phase === 'ready') {
+            // A lost publication response may be retried by THIS owner only. Its exact
+            // already-created physical receipt must match; nothing is created again.
+            validate(claimed, 'ready');
+            complete = physical;
+            password = '';
+            return complete;
+        }
+        validate(claimed, 'provisioning');
+        token();
+        physical ??= await owner.provision();
+        // A reply lost after Docker startup does not grant permission to re-create.
+        // The provisioner's own one-use journal enforces this on retry as well.
+        const verified = await (io.read ?? entitybox_capacity_provisioner_1.readEntityboxCapacity)(directory, allocation.desktopId, allocation.runtimeId);
+        if ((0, entitybox_recovery_store_1.entityboxCanonical)(verified) !== (0, entitybox_recovery_store_1.entityboxCanonical)(physical))
+            throw fail();
+        const result = await io.rpc('entitybox_native_capacity_publish', { p_token: token(), p_id: allocation.id, p_nonce: nonce, p_receipt: physical, p_vnc_password: password });
+        validate(result, 'ready');
+        complete = physical;
+        password = '';
+        return complete;
+    }
+    return { provision: () => {
+            if (complete)
+                return Promise.resolve(complete);
+            if (!flight)
+                flight = run().catch(() => { throw fail(); }).finally(() => { flight = undefined; });
+            return flight;
+        } };
+}

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

@@ -0,0 +1,29 @@
+import { createEntityboxCapacityPublicationRecovery } from './entitybox-capacity-publication';
+import { type EntityboxCapacityRegistrationConfiguration, type EntityboxCapacityRegistrationIO } from './entitybox-capacity-registration';
+import type { EntityboxCapacityReceipt } from './entitybox-capacity-provisioner';
+export interface EntityboxCapacityWorkerConfiguration {
+    enabled?: boolean;
+    recoverPublication?: boolean;
+    runtimeId: string;
+    imageId: string;
+    directory: string;
+    dockerContext: string;
+}
+export interface EntityboxCapacityWorkerIO extends EntityboxCapacityRegistrationIO {
+    /** Hold the shared native start gate through claim, Docker startup and publish. */
+    admit: (id: string, createdAt: string, action: () => Promise<void>, publicationOnly?: boolean) => Promise<boolean>;
+    registration?: (config: EntityboxCapacityRegistrationConfiguration, io: EntityboxCapacityRegistrationIO) => {
+        provision: () => Promise<Readonly<EntityboxCapacityReceipt>>;
+    } | undefined;
+    publicationRecovery?: typeof createEntityboxCapacityPublicationRecovery;
+    clock?: () => number;
+    report?: (state: 'ready' | 'waiting' | 'attention' | 'unavailable', desktopId?: string) => void;
+}
+/** One live owner per allocation. Opt-in restart recovery may republish an
+ * exact finished receipt, never recreate an uncertain plan or its resources. */
+export declare function createEntityboxCapacityWorker(config: EntityboxCapacityWorkerConfiguration, io: EntityboxCapacityWorkerIO): {
+    tick: () => Promise<void>;
+    start(): void;
+    stop(): void;
+    drain(timeoutMs?: number): Promise<boolean>;
+} | undefined;

package/dist/entitybox-capacity-worker.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEntityboxCapacityWorker = createEntityboxCapacityWorker;
+const entitybox_capacity_publication_1 = require("./entitybox-capacity-publication");
+const entitybox_capacity_registration_1 = require("./entitybox-capacity-registration");
+const uuid = /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+/** One live owner per allocation. Opt-in restart recovery may republish an
+ * exact finished receipt, never recreate an uncertain plan or its resources. */
+function createEntityboxCapacityWorker(config, io) {
+    if (config.enabled !== true)
+        return undefined;
+    if (!uuid.test(config.runtimeId) || !/^sha256:[a-f0-9]{64}$/.test(config.imageId) || !/^[-a-zA-Z0-9_.]{1,80}$/.test(config.dockerContext) || typeof config.directory !== 'string' || !config.directory)
+        throw new Error('Invalid EntityBox capacity worker configuration');
+    const configuration = Object.freeze({ ...config }), now = io.clock ?? Date.now;
+    const owners = new Map();
+    let stopped = false, flight, timer, started = false;
+    const token = () => { const p = io.pairing(); if (stopped || !p || p.runtimeId !== configuration.runtimeId || !p.daemonToken)
+        throw new Error('Unavailable'); return p.daemonToken; };
+    const report = (state, id) => { try {
+        io.report?.(state, id);
+    }
+    catch { } };
+    async function inventory() {
+        const all = [], seen = new Set();
+        let after = null;
+        for (let page = 0; page < 10; page++) {
+            const rows = await io.rpc('entitybox_native_capacity_inventory', { p_token: token(), p_after: after, p_limit: 50 });
+            token();
+            if (!Array.isArray(rows) || rows.length > 50)
+                throw new Error('Unavailable');
+            for (const r of rows) {
+                if (!r || ![r.id, r.runtimeId, r.desktopId].every(v => typeof v === 'string' && uuid.test(v)) || r.runtimeId !== configuration.runtimeId || !['reserved', 'provisioning', 'ready'].includes(r.phase) || typeof r.createdAt !== 'string' || !Number.isFinite(Date.parse(r.createdAt)) || seen.has(r.id) || after !== null && r.id <= after)
+                    throw new Error('Unavailable');
+                seen.add(r.id);
+                after = r.id;
+                all.push({ id: r.id, runtimeId: r.runtimeId, desktopId: r.desktopId, phase: r.phase, createdAt: r.createdAt });
+            }
+            if (rows.length < 50)
+                return all.sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt) || a.id.localeCompare(b.id));
+        }
+        throw new Error('Unavailable');
+    }
+    async function run() {
+        try {
+            const rows = await inventory();
+            for (const allocation of rows) {
+                if (stopped)
+                    return;
+                let retained = owners.get(allocation.id);
+                if (retained && (retained.allocation.desktopId !== allocation.desktopId || retained.allocation.runtimeId !== allocation.runtimeId))
+                    throw new Error('Unavailable');
+                if (allocation.phase === 'ready') {
+                    owners.delete(allocation.id);
+                    continue;
+                }
+                if (allocation.phase === 'provisioning' && !retained && configuration.recoverPublication !== true) {
+                    report('attention', allocation.desktopId);
+                    continue;
+                }
+                if (retained && now() < retained.retryAt)
+                    continue;
+                try {
+                    const publicationOnly = retained?.publicationOnly ?? allocation.phase === 'provisioning';
+                    const admitted = await io.admit(allocation.desktopId, allocation.createdAt, async () => {
+                        token();
+                        if (!retained) {
+                            if (owners.size >= 500)
+                                throw new Error('Unavailable');
+                            const factory = allocation.phase === 'provisioning' ? (io.publicationRecovery ?? entitybox_capacity_publication_1.createEntityboxCapacityPublicationRecovery) : (io.registration ?? entitybox_capacity_registration_1.createEntityboxCapacityRegistration);
+                            const owner = factory({ ...configuration, allocation }, { ...io, pairing: () => { token(); return io.pairing(); } });
+                            if (!owner)
+                                throw new Error('Unavailable');
+                            retained = { allocation, owner, failures: 0, retryAt: 0, publicationOnly };
+                            owners.set(allocation.id, retained);
+                        }
+                        await retained.owner.provision();
+                        token();
+                        owners.delete(allocation.id);
+                        report('ready', allocation.desktopId);
+                    }, publicationOnly);
+                    if (!admitted)
+                        report('waiting', allocation.desktopId);
+                }
+                catch {
+                    if (retained) {
+                        retained.failures++;
+                        retained.retryAt = now() + Math.min(300000, 5000 * 2 ** Math.min(retained.failures - 1, 6));
+                    }
+                    report('attention', allocation.desktopId);
+                }
+            }
+        }
+        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-computer-task.d.ts

@@ -0,0 +1,69 @@
+import { EntityboxExecutionContainer, type EntityboxExecutionResource } from './entitybox-execution-container';
+import { type EntityboxExecutionLease } from './entitybox-execution-lease';
+import { EntityboxMcpBroker } from './entitybox-mcp-broker';
+import { EntityboxProviderBroker } from './entitybox-provider-broker';
+import type { EntityboxDisplayBinding } from './entitybox-display-binding';
+import type { RuntimeEvent, RuntimePermissionMode, RuntimeEffortLevel } from './types';
+export interface EntityboxComputerTaskOptions {
+    /** Trusted request owner observes startup before any resource creation. */
+    onTask?: (task: EntityboxComputerTask) => void;
+    imageId: string;
+    dockerContext?: string;
+    display: EntityboxDisplayBinding;
+    /** Trusted model/provider selection from the native request adapter. */
+    provider: ConstructorParameters<typeof EntityboxProviderBroker>[1];
+    connection: Parameters<typeof EntityboxMcpBroker.connect>[1]['connection'];
+    desktopTools: readonly string[];
+    task: {
+        prompt: string;
+        model: string;
+        systemPrompt?: string;
+        permissionMode?: RuntimePermissionMode;
+        effort?: RuntimeEffortLevel;
+    };
+    /** Await durable native event writes. A failed sink fences the task. */
+    onEvent: (event: RuntimeEvent) => Promise<void>;
+    /** Record created executor identity before any task process can start. */
+    onContainerCreated?: (resource: Readonly<EntityboxExecutionResource>) => Promise<void>;
+    /** Register this exact owned container before exposing desktop tools. */
+    onContainer: (container: EntityboxExecutionContainer) => Promise<void>;
+}
+export interface EntityboxComputerTaskResult {
+    code: number;
+    taskProcessesStopped: true;
+}
+/** One native CLI/provider/MCP lifecycle. This does not pick requests, resolve
+ * credentials, provision capacity or acknowledge the SQL lease. A caller must
+ * aggregate any persistent-application/takeover proof before releasing it. */
+export declare class EntityboxComputerTask {
+    private readonly lease;
+    private readonly options;
+    readonly done: Promise<EntityboxComputerTaskResult>;
+    readonly artifactSha256: string;
+    private container?;
+    private bridge?;
+    private broker?;
+    private readonly connectionReady;
+    private readonly startupSettled;
+    private startupResolve;
+    private connectionResolve;
+    private connectionReject;
+    private doneResolve;
+    private doneReject;
+    private eventChain;
+    private queuedBytes;
+    private output;
+    private readonly decoder;
+    private completion?;
+    private failed;
+    private sinkFailed;
+    private stopping?;
+    private constructor();
+    static start(lease: EntityboxExecutionLease, options: EntityboxComputerTaskOptions): Promise<EntityboxComputerTask>;
+    get containerId(): string | undefined;
+    get mcpProcessId(): number | undefined;
+    requestStop(): void;
+    private consume;
+    private finish;
+    stopAndVerify(): Promise<void>;
+}

package/dist/entitybox-computer-task.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntityboxComputerTask = void 0;
+const entitybox_execution_container_1 = require("./entitybox-execution-container");
+const entitybox_execution_lease_1 = require("./entitybox-execution-lease");
+const entitybox_desktop_action_server_1 = require("./entitybox-desktop-action-server");
+const entitybox_mcp_broker_1 = require("./entitybox-mcp-broker");
+const entitybox_provider_broker_1 = require("./entitybox-provider-broker");
+const entitybox_model_artifact_1 = require("./entitybox-model-artifact");
+const string_decoder_1 = require("string_decoder");
+async function bounded(operation, ms) {
+    let timer;
+    try {
+        return await Promise.race([operation, new Promise((_, reject) => { timer = setTimeout(() => reject(new entitybox_execution_lease_1.EntityboxExecutionError('Native task operation timed out')), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** One native CLI/provider/MCP lifecycle. This does not pick requests, resolve
+ * credentials, provision capacity or acknowledge the SQL lease. A caller must
+ * aggregate any persistent-application/takeover proof before releasing it. */
+class EntityboxComputerTask {
+    lease;
+    options;
+    done;
+    artifactSha256;
+    container;
+    bridge;
+    broker;
+    connectionReady;
+    startupSettled;
+    startupResolve;
+    connectionResolve;
+    connectionReject;
+    doneResolve;
+    doneReject;
+    eventChain = Promise.resolve();
+    queuedBytes = 0;
+    output = '';
+    decoder = new string_decoder_1.StringDecoder('utf8');
+    completion;
+    failed = false;
+    sinkFailed = false;
+    stopping;
+    constructor(lease, options, artifactSha256) {
+        this.lease = lease;
+        this.options = options;
+        this.artifactSha256 = artifactSha256;
+        this.startupSettled = new Promise(resolve => { this.startupResolve = resolve; });
+        this.connectionReady = new Promise((resolve, reject) => { this.connectionResolve = resolve; this.connectionReject = reject; });
+        this.connectionReady.catch(() => { });
+        this.done = new Promise((resolve, reject) => { this.doneResolve = resolve; this.doneReject = reject; });
+        this.done.catch(() => { });
+        lease.signal.addEventListener('abort', () => { this.connectionReject(new entitybox_execution_lease_1.EntityboxExecutionError('Computer task ended')); void this.stopAndVerify().catch(() => { }); }, { once: true });
+    }
+    static async start(lease, options) {
+        lease.assertActive();
+        const artifact = (0, entitybox_model_artifact_1.readEntityboxModelArtifact)();
+        if (!options.display || typeof options.onEvent !== 'function' || typeof options.onContainer !== 'function'
+            || !options.provider.models.includes(options.task.model) || !options.desktopTools.length)
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Invalid native computer task');
+        const provider = new entitybox_provider_broker_1.EntityboxProviderBroker(lease, options.provider), task = new EntityboxComputerTask(lease, options, artifact.sha256);
+        try {
+            options.onTask?.(task);
+            task.container = await entitybox_execution_container_1.EntityboxExecutionContainer.start(lease, { imageId: options.imageId, dockerContext: options.dockerContext, memoryMiB: 1536, display: options.display,
+                onCreated: options.onContainerCreated, command: ['node', '-e', entitybox_model_artifact_1.ENTITYBOX_MODEL_LOADER], task: { files: artifact.files, task: { ...options.task, desktopMcp: true, allowedTools: options.desktopTools.map(name => 'mcp__entity-desktop-mcp__' + name) } },
+                onOutput: data => task.consume(data), onBroker: async (raw, signal, emit) => {
+                    await task.connectionReady;
+                    lease.assertActive();
+                    if (raw?.kind === 'desktop_mcp') {
+                        if (!task.broker)
+                            throw new Error();
+                        await task.broker.handle(raw, signal, emit);
+                    }
+                    else
+                        await provider.handle(raw, signal, emit);
+                } });
+            await bounded(options.onContainer(task.container), 10000);
+            await task.container.whenStarted();
+            task.bridge = await entitybox_desktop_action_server_1.EntityboxDesktopActionServer.start(lease, task.container);
+            task.broker = await entitybox_mcp_broker_1.EntityboxMcpBroker.connect(lease, { connection: options.connection, allowedTools: options.desktopTools, actions: task.bridge });
+            lease.assertActive();
+            task.connectionResolve();
+            task.startupResolve();
+            void task.finish();
+            return task;
+        }
+        catch {
+            task.failed = true;
+            task.connectionReject(new entitybox_execution_lease_1.EntityboxExecutionError('Computer task startup failed'));
+            lease.fence();
+            task.startupResolve();
+            try {
+                await task.stopAndVerify();
+            }
+            catch {
+                throw new entitybox_execution_lease_1.EntityboxExecutionError('Computer task startup failed; resource stop remains unverified');
+            }
+            throw new entitybox_execution_lease_1.EntityboxExecutionError('Computer task could not start');
+        }
+    }
+    get containerId() { return this.container?.id; }
+    get mcpProcessId() { return this.broker?.processId; }
+    requestStop() { this.lease.fence(); }
+    consume(data) {
+        try {
+            this.output += this.decoder.write(data);
+            if (Buffer.byteLength(this.output) > 32 * 1024 * 1024)
+                throw new Error();
+            let end;
+            while ((end = this.output.indexOf('\n')) >= 0) {
+                const line = this.output.slice(0, end);
+                this.output = this.output.slice(end + 1);
+                const event = JSON.parse(line);
+                if (!event || typeof event.type !== 'string')
+                    throw new Error();
+                if (event.type === 'error')
+                    this.failed = true;
+                // A model completion event is advisory until owned processes stop and
+                // the preceding native event writes have settled successfully.
+                if (event.type === 'turn_complete') {
+                    this.completion = event;
+                    continue;
+                }
+                const size = Buffer.byteLength(line);
+                this.queuedBytes += size;
+                if (this.queuedBytes > 32 * 1024 * 1024)
+                    throw new Error();
+                this.eventChain = this.eventChain.then(async () => { if (!this.sinkFailed)
+                    await bounded(this.options.onEvent(event), 15000); }).catch(() => { this.sinkFailed = true; this.failed = true; this.lease.fence(); }).finally(() => { this.queuedBytes -= size; });
+            }
+        }
+        catch {
+            this.failed = true;
+            this.lease.fence();
+        }
+    }
+    async finish() {
+        try {
+            const code = await this.container.done;
+            this.output += this.decoder.end();
+            const completed = code === 0 && !this.failed && !this.lease.signal.aborted && !this.output && this.completion?.type === 'turn_complete' && this.completion.stopReason === 'success';
+            await this.stopAndVerify();
+            await this.eventChain;
+            const success = completed && !this.failed;
+            if (success && this.completion)
+                await bounded(this.options.onEvent(this.completion), 15000);
+            this.doneResolve({ code: success ? 0 : 70, taskProcessesStopped: true });
+        }
+        catch {
+            this.lease.fence();
+            this.doneReject(new entitybox_execution_lease_1.EntityboxExecutionError('Computer task stop could not be confirmed'));
+        }
+    }
+    async stopAndVerify() {
+        if (this.stopping)
+            return this.stopping;
+        this.stopping = Promise.resolve().then(async () => {
+            await this.startupSettled;
+            this.connectionReject(new entitybox_execution_lease_1.EntityboxExecutionError('Computer task ended'));
+            const results = await Promise.allSettled([this.container?.stopAndVerify(), this.broker?.stopAndVerify(), this.bridge?.stopAndVerify()]);
+            if (results.some(r => r.status === 'rejected'))
+                throw new entitybox_execution_lease_1.EntityboxExecutionError('Computer task resources have not stopped');
+        });
+        this.lease.fence();
+        try {
+            await this.stopping;
+        }
+        catch (error) {
+            this.stopping = undefined;
+            throw error;
+        }
+    }
+}
+exports.EntityboxComputerTask = EntityboxComputerTask;

package/dist/entitybox-controller-recovery.d.ts

@@ -0,0 +1,40 @@
+import { type EntityboxExecutionIdentity } from './entitybox-execution-lease';
+import { type EntityboxApplicationDocker } from './entitybox-application-boundary';
+import { type EntityboxHostProcess } from './entitybox-host-process';
+import { type EntityboxRecoveryStore } from './entitybox-recovery-store';
+type Rpc = <T>(name: string, args: Record<string, unknown>) => Promise<T>;
+export interface EntityboxControllerRecoveryOptions {
+    identity: EntityboxExecutionIdentity;
+    store: EntityboxRecoveryStore;
+    dockerContext?: string;
+    token: () => string;
+    rpc: Rpc;
+    /** Trusted native test/transport seams, never values from the model. */
+    docker?: EntityboxApplicationDocker;
+    readProcess?: () => Promise<Readonly<EntityboxHostProcess> | null>;
+    assertGone?: (p: EntityboxHostProcess) => Promise<void>;
+}
+/** 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. */
+export declare class EntityboxControllerRecovery {
+    private readonly options;
+    private readonly id;
+    private readonly nonce;
+    private readonly identity;
+    private readonly context;
+    private readonly docker;
+    private owner?;
+    private pending?;
+    private completed?;
+    constructor(options: EntityboxControllerRecoveryOptions);
+    run(): Promise<string>;
+    private call;
+    private snapshot;
+    private ended;
+    private recovery;
+    private recover;
+    private retire;
+}
+export {};