@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/desktopControl/deviceAdmission.js

@@ -0,0 +1,229 @@
+import { randomBytes } from 'node:crypto';
+import { bounded } from './helperProcess.js';
+import { nativeReceiptMatches } from './ownershipProtocol.js';
+export class DeviceAdmissionConnection {
+    registrationId;
+    owner;
+    host;
+    report;
+    generation;
+    admissions = new Map();
+    commands = new Map();
+    highestAcquireSequence = 0;
+    open = true;
+    accepting = true;
+    unwatch;
+    constructor(registrationId, owner, host, report) {
+        this.registrationId = registrationId;
+        this.owner = owner;
+        this.host = host;
+        this.report = report;
+        this.unwatch = owner.observe(() => { if (this.generation && this.open)
+            this.event(this.generation, '0'.repeat(32), 'snapshot', 'snapshot'); });
+    }
+    ready(generation) {
+        if (this.generation === generation)
+            return;
+        this.closeAdmission();
+        this.generation = generation;
+        this.open = true;
+        this.commands.clear();
+        this.highestAcquireSequence = 0;
+        this.pruneAdmissions();
+        this.event(generation, '0'.repeat(32), 'snapshot', 'snapshot');
+    }
+    closed(generation) { if (this.generation === generation) {
+        this.closeAdmission();
+        this.generation = undefined;
+    } }
+    retire(admission) {
+        admission.revoked = true;
+        admission.committed = false;
+        clearTimeout(admission.expiry);
+        if (admission.grant) {
+            try {
+                admission.host.revoke(admission.grant);
+            }
+            catch { }
+        }
+    }
+    closeAdmission() { this.open = false; for (const admission of this.admissions.values())
+        this.retire(admission); }
+    resumeAdmission() { if (this.generation)
+        this.open = true; }
+    holdNewAdmission() { this.accepting = false; }
+    resumeNewAdmission() { this.accepting = true; }
+    async isolate(admission) {
+        this.retire(admission);
+        if (admission.pending && !admission.grant)
+            throw new Error('physical_isolation_unconfirmed');
+        if (admission.grant && !admission.isolated && !await bounded(this.owner.release(admission.grant), 15_000))
+            throw new Error('physical_isolation_unconfirmed');
+    }
+    async isolateOriginal() {
+        const outcomes = await Promise.allSettled([...this.admissions.values()].map(admission => this.isolate(admission)));
+        this.pruneAdmissions();
+        const failures = outcomes.flatMap(outcome => outcome.status === 'rejected' ? [outcome.reason] : []);
+        if (failures.length)
+            throw new AggregateError(failures, 'physical_isolation_unconfirmed');
+    }
+    dispose() { this.closeAdmission(); this.unwatch(); }
+    key(generation, controllerId) { return `${generation}:${controllerId}`; }
+    pruneAdmissions() {
+        for (const [key, admission] of this.admissions)
+            if (!admission.pending && (!admission.grant || admission.isolated)) {
+                clearTimeout(admission.expiry);
+                this.admissions.delete(key);
+            }
+    }
+    event(generation, commandId, controllerId, status, reservationCause) {
+        if (this.generation === generation)
+            this.report({ t: 'desktop_ownership_result', ownershipProtocol: 1, commandId, controllerId,
+                deviceGeneration: generation, status, snapshot: this.owner.project(this.registrationId), ...(reservationCause ? { reservationCause } : {}) });
+    }
+    dispatch(command) {
+        if (!this.generation || command.deviceGeneration !== this.generation)
+            return Promise.resolve();
+        if (command.action === 'release' || command.action === 'cancel')
+            return this.perform(command);
+        const text = JSON.stringify(command), previous = this.commands.get(command.commandId);
+        if (previous)
+            return previous.text === text ? previous.result : Promise.reject(new Error('conflict'));
+        for (const [key, replay] of this.commands)
+            if (this.commands.size >= 1024 && replay.settled)
+                this.commands.delete(key);
+        if (this.commands.size >= 1024)
+            return Promise.reject(new Error('resource_limit'));
+        const replay = { text, settled: false, result: Promise.resolve() };
+        this.commands.set(command.commandId, replay);
+        replay.result = this.perform(command).finally(() => { replay.settled = true; });
+        return replay.result;
+    }
+    async perform(command) {
+        const generation = command.deviceGeneration, host = this.host;
+        const current = () => this.open && this.generation === generation && host?.current() === true;
+        const event = (status) => this.event(generation, command.commandId, command.controllerId, status);
+        this.pruneAdmissions();
+        const key = this.key(generation, command.controllerId);
+        if (command.action === 'cancel') {
+            const requestSequence = command.requestSequence;
+            if (!Number.isSafeInteger(requestSequence) || requestSequence < 1 || !command.acquireCommandId) {
+                event('conflict');
+                return;
+            }
+            this.highestAcquireSequence = Math.max(this.highestAcquireSequence, requestSequence);
+            const admission = this.admissions.get(key);
+            if (!admission || admission.command.commandId !== command.acquireCommandId || admission.command.requestSequence !== requestSequence) {
+                event('cancelled');
+                return;
+            }
+            try {
+                await this.isolate(admission);
+                event('cancelled');
+            }
+            catch {
+                event('busy');
+            }
+            this.pruneAdmissions();
+            return;
+        }
+        if (command.action !== 'acquire') {
+            const admission = this.admissions.get(key), grant = admission?.grant;
+            if (!admission || !grant || grant.deviceEpoch !== command.deviceEpoch || grant.revision !== command.revision) {
+                event('conflict');
+                return;
+            }
+            if (command.action === 'release') {
+                try {
+                    await this.isolate(admission);
+                    event('released');
+                }
+                catch {
+                    event('busy');
+                }
+                this.pruneAdmissions();
+                return;
+            }
+            if (!current()) {
+                event('unsupported');
+                return;
+            }
+            if (admission.committed && this.owner.current(grant, host)) {
+                event('committed');
+                return;
+            }
+            if (!this.accepting) {
+                event('busy');
+                return;
+            }
+            admission.committing = command.commandId;
+            let committed = !admission.revoked && (await this.owner.commit(grant)).status === 'granted';
+            if (committed && current() && this.owner.current(grant, host)) {
+                admission.committed = true;
+                clearTimeout(admission.expiry);
+            }
+            else {
+                try {
+                    await this.isolate(admission);
+                }
+                catch { }
+                committed = false;
+            }
+            event(committed ? 'committed' : 'busy');
+            this.pruneAdmissions();
+            return;
+        }
+        const requestSequence = command.requestSequence;
+        if (!Number.isSafeInteger(requestSequence) || requestSequence <= this.highestAcquireSequence) {
+            event('conflict');
+            return;
+        }
+        this.highestAcquireSequence = requestSequence;
+        if (!host || !current() || !this.accepting) {
+            event('unsupported');
+            return;
+        }
+        if (!command.acquisition || this.admissions.has(key) || this.admissions.size >= 1024) {
+            event('conflict');
+            return;
+        }
+        const admission = { pending: true, committed: false, revoked: false, isolated: false, host, command };
+        this.admissions.set(key, admission);
+        admission.expiry = setTimeout(() => { this.retire(admission); if (admission.grant)
+            void this.isolate(admission).catch(() => { }); }, 15_000);
+        admission.expiry.unref();
+        try {
+            const result = await this.owner.reserve({ registrationId: this.registrationId, controllerId: command.controllerId, kind: command.kind,
+                reservationCause: Object.freeze({ acquireCommandId: command.commandId, contenderControllerId: command.controllerId, deviceGeneration: generation }),
+                hostLifetime: host, valid: () => current() && !admission.revoked,
+                revoke: () => this.retire(admission),
+                admit: async (grant) => { const commandId = admission.committing; return !!commandId && nativeReceiptMatches(host, commandId, grant, 'admit', await host.admit(commandId, grant)); },
+                isolate: async () => {
+                    if (!admission.grant)
+                        return false;
+                    const commandId = randomBytes(16).toString('hex');
+                    admission.isolated = nativeReceiptMatches(host, commandId, admission.grant, 'isolate', await host.isolate(commandId, admission.grant));
+                    return admission.isolated;
+                },
+                lost: (_snapshot, cause) => this.event(generation, command.commandId, command.controllerId, 'lost', cause?.deviceGeneration === generation ? cause : undefined),
+            }, command.acquisition);
+            if (result.status === 'granted')
+                admission.grant = result.grant;
+            event(result.status === 'granted' ? 'acquired' : result.status);
+        }
+        finally {
+            admission.pending = false;
+            this.pruneAdmissions();
+        }
+    }
+    grant(controllerId) {
+        const admission = this.generation ? this.admissions.get(this.key(this.generation, controllerId)) : undefined;
+        return admission?.grant && admission.committed && !admission.revoked && this.open && this.host?.current() &&
+            this.owner.current(admission.grant, this.host) ? admission.grant : undefined;
+    }
+    current(grant) { return this.grant(grant.controllerId) === grant; }
+    activity() {
+        return { known: [...this.admissions.values()].every(admission => !admission.pending && (!admission.grant || admission.isolated || this.owner.current(admission.grant))),
+            consumers: [...this.admissions.values()].filter(admission => admission.pending || admission.grant && !admission.isolated).length };
+    }
+}

package/dist/workstation/desktopControl/deviceOwnership.js

@@ -0,0 +1,130 @@
+import { randomBytes } from 'node:crypto';
+import { deviceAcquisitionSchema, matchesDeviceGrant } from './ownershipProtocol.js';
+export class DeviceOwnership {
+    deviceEpoch = randomBytes(32).toString('base64url');
+    revision = 0;
+    state = 'free';
+    owner;
+    transition;
+    listeners = new Set();
+    snapshot() {
+        const candidate = this.owner?.candidate;
+        return { deviceEpoch: this.deviceEpoch, revision: this.revision, state: this.state,
+            controller: candidate ? { registrationId: candidate.registrationId, controllerId: candidate.controllerId, kind: candidate.kind } : null };
+    }
+    project(registrationId) {
+        const snapshot = this.snapshot();
+        if (snapshot.controller && snapshot.controller.registrationId !== registrationId)
+            snapshot.controller = { registrationId: 'another', controllerId: 'another', kind: 'unknown' };
+        return snapshot;
+    }
+    observe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+    publish() { for (const listener of this.listeners) {
+        try {
+            listener();
+        }
+        catch { }
+    } }
+    current(grant, hostLifetime) {
+        return this.state === 'active' && !!this.owner && matchesDeviceGrant(this.owner.grant, grant) &&
+            (hostLifetime === undefined || hostLifetime === this.owner.candidate.hostLifetime) && this.owner.candidate.valid();
+    }
+    isolate(owner) {
+        return owner.cleanup ??= Promise.resolve().then(() => owner.candidate.isolate()).catch(() => false).then(isolated => {
+            owner.isolated = isolated;
+            if (!isolated)
+                owner.cleanup = undefined;
+            return isolated;
+        });
+    }
+    async acquire(candidate, request) {
+        const reservation = await this.reserve(candidate, request);
+        if (reservation.status !== 'granted')
+            return reservation;
+        return this.commit(reservation.grant);
+    }
+    async reserve(candidate, request) {
+        deviceAcquisitionSchema.parse(request);
+        const refused = (status) => ({ status, snapshot: this.snapshot() });
+        if (!candidate.valid())
+            return refused('conflict');
+        if (request.kind === 'takeover' && (request.expectedDeviceEpoch !== this.deviceEpoch || request.expectedRevision !== this.revision))
+            return refused('conflict');
+        if (this.state === 'draining' || request.kind === 'if_free' && this.owner)
+            return refused('busy');
+        if (this.revision === Number.MAX_SAFE_INTEGER)
+            return refused('busy');
+        const old = this.owner;
+        this.transition = {};
+        this.state = 'draining';
+        this.revision++;
+        old?.candidate.revoke();
+        this.publish();
+        const cause = candidate.reservationCause;
+        try {
+            old?.candidate.lost(this.snapshot(), old.candidate.registrationId === candidate.registrationId &&
+                cause?.contenderControllerId === candidate.controllerId && old.candidate.reservationCause?.deviceGeneration === cause?.deviceGeneration ? cause : undefined);
+        }
+        catch { }
+        if (old && !await this.isolate(old))
+            return refused('busy');
+        if (!candidate.valid()) {
+            this.owner = undefined;
+            this.state = 'free';
+            this.publish();
+            return refused('conflict');
+        }
+        const grant = Object.freeze({ deviceEpoch: this.deviceEpoch, revision: this.revision,
+            registrationId: candidate.registrationId, controllerId: candidate.controllerId, authorization: randomBytes(32).toString('base64url') });
+        this.owner = { candidate, grant };
+        return { status: 'granted', grant };
+    }
+    async commit(grant) {
+        const next = this.owner;
+        if (!next || this.state !== 'draining' || next.cleanup || !matchesDeviceGrant(next.grant, grant))
+            return { status: 'conflict', snapshot: this.snapshot() };
+        const candidate = next.candidate, transition = this.transition;
+        let admitted = false;
+        try {
+            admitted = await candidate.admit(grant);
+        }
+        catch { }
+        if (!admitted || !candidate.valid() || this.transition !== transition) {
+            candidate.revoke();
+            if (await this.isolate(next) && this.owner === next) {
+                this.owner = undefined;
+                this.state = 'free';
+            }
+            this.publish();
+            return { status: 'busy', snapshot: this.snapshot() };
+        }
+        this.state = 'active';
+        this.publish();
+        return { status: 'granted', grant };
+    }
+    async release(grant) {
+        const owner = this.owner;
+        if (!owner || !matchesDeviceGrant(owner.grant, grant))
+            return false;
+        const transition = this.transition;
+        if (this.state === 'active' || !owner.cleanup) {
+            this.state = 'draining';
+            this.revision++;
+            owner.candidate.revoke();
+            this.publish();
+        }
+        const isolated = await this.isolate(owner);
+        if (this.owner === owner && this.transition === transition && isolated) {
+            this.owner = undefined;
+            this.state = 'free';
+            this.publish();
+        }
+        return isolated;
+    }
+    async retireRegistration(registrationId) {
+        const owner = this.owner;
+        if (!owner || owner.candidate.registrationId !== registrationId)
+            return true;
+        return this.release(owner.grant);
+    }
+}

package/dist/workstation/desktopControl/deviceSockets.js

@@ -27,7 +27,7 @@ export class DeviceSockets {
         const url = desktopSocketUrl(this.server, 'media', this.allowPrivateWs);
         url.protocol = url.protocol === 'wss:' ? 'https:' : 'http:';
         url.pathname = url.pathname.replace(/\/ws\/desktop\/media$/, '/desktop/background');
-        const headers = { 'X-Axom-Background-Grant': grant, 'Content-Type': 'image/jpeg' };
+        const headers = { 'X-Axom-Background-Grant': grant, 'Content-Type': 'image/webp' };
         if (wallpaper) {
             headers['X-Axom-Background-Asset'] = Buffer.from(JSON.stringify(wallpaper.asset)).toString('base64url');
             headers['X-Axom-Background-Unchanged'] = unchanged ? '1' : '0';
@@ -35,7 +35,7 @@ export class DeviceSockets {
         else
             headers['X-Axom-Background-Error'] = 'unavailable';
         const response = await fetch(url, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000), headers,
-            body: wallpaper && !unchanged ? new Uint8Array(wallpaper.jpeg) : undefined });
+            body: wallpaper && !unchanged ? new Uint8Array(wallpaper.bytes) : undefined });
         if (!response.ok)
             throw new NativeCommandError('transport_failed');
         await response.body?.cancel();

package/dist/workstation/desktopControl/helperProcess.js

@@ -5,6 +5,11 @@ import { z } from 'zod';
 import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
 import { decodeMedia, mediaRequire } from './media.js';
 import { decodeAudio } from './audio.js';
+import { randomBytes as automationRandomBytes } from 'node:crypto';
+import { parseAutomationJson } from './automationJson.js';
+import { AutomationTransport } from './automationTransport.js';
+import { AutomationSession } from './automationSession.js';
+import { decodeAutomationFailureDetail } from './automationProtocol.js';
 const execute = promisify(execFile);
 const commands = ['focus', 'cache_dependency', 'transport_cost', 'prepare_motion_cut', 'commit_motion_cut', 'prepare', 'start', 'decoder_ready', 'first_presented', 'acknowledge', 'credit', 'renew', 'input', 'clipboard', 'overview', 'reserve_overview', 'resize',
     'held_state', 'text_result', 'recover_display', 'set_rate', 'refresh', 'stop', 'verify_cleanup', 'probe', 'status'];
@@ -85,10 +90,12 @@ const replySchema = z.union([
 export class NativeCommandError extends Error {
     code;
     counters;
-    constructor(code, counters) {
+    detail;
+    constructor(code, counters, detail = null) {
         super(code);
         this.code = code;
         this.counters = counters;
+        this.detail = detail;
     }
 }
 /** Local queue retirement, created only before allocating an ID or writing bytes. */
@@ -323,6 +330,248 @@ export class HelperProcess {
 function write(stream, bytes) {
     return new Promise((resolve, reject) => stream.write(bytes, error => error ? reject(error) : resolve()));
 }
+export async function launchAutomationHelper(executable, env, binding) {
+    if (!binding.native || !binding.preparation)
+        throw new NativeCommandError('trusted_preparation_unavailable');
+    const token = automationRandomBytes(32).toString('hex');
+    const child = spawn(executable, ['--automation-fd', '3'], { stdio: ['pipe', 'pipe', 'ignore', 'pipe'],
+        env: { ...env, AXOM_AUTOMATION_TOKEN: token, AXOM_AUTOMATION_FEATURES: 'capture_wait_v1' } });
+    child.stdin.on('error', () => { });
+    const control = new NativeByteReader(child.stdout, 49152), binary = new NativeByteReader(child.stdio[3], 8388608 + 49156);
+    let ended = false, controlId = 0, writeCount = 0, writeTail = Promise.resolve();
+    const renewals = new Map();
+    const preparations = new Map();
+    const statuses = new Map();
+    const readControls = new Map();
+    const send = (text) => {
+        if (ended || writeCount >= 64)
+            return Promise.reject(new NativeCommandError('resource_limit'));
+        const body = Buffer.from(text);
+        if (!body.length || body.length > 49152)
+            return Promise.reject(new NativeCommandError('invalid_argument'));
+        const prefix = Buffer.alloc(4);
+        prefix.writeUInt32BE(body.length);
+        writeCount++;
+        const pending = writeTail.then(() => { if (ended)
+            throw new NativeCommandError('closed'); return bounded(write(child.stdin, Buffer.concat([prefix, body])), 1000); });
+        writeTail = pending.catch(() => { }).finally(() => { writeCount--; });
+        return pending;
+    };
+    const transport = new AutomationTransport(send, requestId => { void send(JSON.stringify({ command: 'cancel', requestId })).catch(() => { }); });
+    const retire = () => {
+        if (ended)
+            return;
+        ended = true;
+        transport.close('transport_failed');
+        for (const renewal of renewals.values()) {
+            clearTimeout(renewal.timer);
+            renewal.reject(new NativeCommandError('closed'));
+        }
+        renewals.clear();
+        for (const pending of preparations.values()) {
+            clearTimeout(pending.timer);
+            pending.detach();
+            pending.reject(new NativeCommandError('closed'));
+        }
+        preparations.clear();
+        for (const pending of statuses.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new NativeCommandError('closed'));
+        }
+        statuses.clear();
+        for (const pending of readControls.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(new NativeCommandError('closed'));
+        }
+        readControls.clear();
+    };
+    const closed = new Promise(resolve => { child.once('exit', () => { retire(); resolve(); }); child.once('error', () => { retire(); resolve(); }); });
+    const readControl = async () => {
+        const size = (await control.exact(4)).readUInt32BE();
+        return parseAutomationJson(await control.exact(size), 49152).value;
+    };
+    const stop = async () => {
+        try {
+            if (!ended)
+                await send(JSON.stringify({ command: 'shutdown' }));
+        }
+        catch { }
+        retire();
+        child.kill('SIGTERM');
+        try {
+            await bounded(closed, 1000);
+        }
+        catch {
+            child.kill('SIGKILL');
+            await bounded(closed, 2000);
+        }
+        child.stdin?.destroy();
+        child.stdout?.destroy();
+        child.stdio[3].destroy();
+    };
+    try {
+        const handshake = await bounded(readControl(), 3000, 'unsupported_automation_protocol');
+        if (handshake.automationProtocol !== 1 || !Array.isArray(handshake.operations) || !handshake.operations.includes('capture'))
+            throw new NativeCommandError('unsupported_automation_protocol');
+        await send(JSON.stringify({ command: 'bind', token, context: { ...binding.native, route: binding.route, executionId: binding.executionId,
+                preparation: { ...binding.preparation, selector: null, mode: null } } }));
+        const attached = await bounded(readControl(), 3000, 'unsupported_automation_protocol');
+        if (attached.control !== 'bound' || !Array.isArray(attached.operations))
+            throw new NativeCommandError('unsupported_automation_protocol');
+        void (async () => {
+            while (!ended) {
+                const message = await readControl();
+                const readPending = readControls.get(message.id);
+                if (readPending && ['status_only', 'isolate', 'prepare_failed'].includes(message.control)) {
+                    readControls.delete(message.id);
+                    clearTimeout(readPending.timer);
+                    if (message.control === 'prepare_failed')
+                        readPending.reject(new NativeCommandError(message.code));
+                    else if (message.control !== readPending.command || message.result?.physical !== 'completed' || message.result?.revoked !== true)
+                        readPending.reject(new NativeCommandError('isolation_unconfirmed'));
+                    else
+                        readPending.resolve(message.result);
+                }
+                else if (message.control === 'lease_admitted') {
+                    const renewal = renewals.get(message.id);
+                    if (!renewal)
+                        continue;
+                    renewals.delete(message.id);
+                    clearTimeout(renewal.timer);
+                    renewal.resolve({ admitted: true, physical: message.physical });
+                }
+                else if (message.control === 'prepared' || message.control === 'prepare_failed') {
+                    const pending = preparations.get(message.id);
+                    if (!pending)
+                        continue;
+                    preparations.delete(message.id);
+                    clearTimeout(pending.timer);
+                    pending.detach();
+                    if (message.control === 'prepared')
+                        pending.resolve(message.attachment);
+                    else
+                        pending.reject(new NativeCommandError(message.code, undefined, decodeAutomationFailureDetail(message.detail)));
+                }
+                else if (message.control === 'control_status') {
+                    const pending = statuses.get(message.id);
+                    if (!pending)
+                        continue;
+                    statuses.delete(message.id);
+                    clearTimeout(pending.timer);
+                    pending.resolve({ physical: message.physical, revoked: message.revoked });
+                }
+                else if (message.control !== 'close_admitted') {
+                    const accepted = transport.acceptResponse(JSON.stringify(message));
+                    if (!accepted.ok && accepted.code !== 'unknown_request')
+                        throw new NativeCommandError('invalid_response');
+                }
+            }
+        })().catch(() => { retire(); child.kill('SIGTERM'); });
+        void (async () => {
+            while (!ended) {
+                const prefix = await binary.exact(4), length = prefix.readUInt32BE();
+                if (length < 1 || length > 49152)
+                    throw new NativeCommandError('invalid_binary');
+                const header = await binary.exact(length), value = parseAutomationJson(header, 49152).value;
+                if (!Number.isInteger(value.bytesLength) || value.bytesLength < 1 || value.bytesLength > 8388608)
+                    throw new NativeCommandError('invalid_binary');
+                transport.acceptBinary(Buffer.concat([prefix, header, await binary.exact(value.bytesLength)]));
+            }
+        })().catch(() => { retire(); child.kill('SIGTERM'); });
+        return new AutomationSession(transport, binding, { operations: attached.operations.filter((operation) => handshake.operations.includes(operation)), close: stop,
+            readControl: async (command, fields) => {
+                if (readControls.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const requestId = `read-control-${++controlId}`;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { readControls.delete(requestId); reject(new NativeCommandError('timed_out')); }, 5000);
+                    readControls.set(requestId, { command, resolve, reject, timer });
+                });
+                void send(JSON.stringify({ command, requestId, ...fields })).catch(error => {
+                    const entry = readControls.get(requestId);
+                    if (entry) {
+                        readControls.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.reject(error);
+                    }
+                });
+                return pending;
+            },
+            prepare: async (preparation, options = {}) => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                if (options.signal?.aborted)
+                    throw new NativeCommandError('cancelled');
+                const requestId = `attachment-${++controlId}`;
+                const pending = new Promise((resolve, reject) => {
+                    const abort = () => {
+                        const entry = preparations.get(requestId);
+                        if (!entry)
+                            return;
+                        preparations.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.detach();
+                        reject(new NativeCommandError('cancelled'));
+                        void send(JSON.stringify({ command: 'cancel', requestId })).catch(() => { });
+                    };
+                    const timer = setTimeout(() => { abort(); }, options.timeoutMs ?? 65000);
+                    preparations.set(requestId, { resolve, reject, timer, detach: () => options.signal?.removeEventListener('abort', abort) });
+                    options.signal?.addEventListener('abort', abort, { once: true });
+                });
+                void send(JSON.stringify({ command: 'prepare', requestId, preparation })).catch(error => {
+                    const entry = preparations.get(requestId);
+                    if (entry) {
+                        preparations.delete(requestId);
+                        clearTimeout(entry.timer);
+                        entry.detach();
+                        entry.reject(error);
+                    }
+                });
+                return pending;
+            },
+            status: async () => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const id = ++controlId;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { statuses.delete(id); reject(new NativeCommandError('timed_out')); }, 1000);
+                    statuses.set(id, { resolve, reject, timer });
+                });
+                void send(JSON.stringify({ command: 'control_status', id })).catch(error => { const entry = statuses.get(id); if (entry) {
+                    clearTimeout(entry.timer);
+                    statuses.delete(id);
+                    entry.reject(error);
+                } });
+                return pending;
+            },
+            renew: async (leaseMs) => {
+                if (preparations.size + renewals.size + statuses.size >= 8 || ended)
+                    throw new NativeCommandError('resource_limit');
+                const id = ++controlId;
+                const pending = new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => { renewals.delete(id); reject(new NativeCommandError('timed_out')); }, 1000);
+                    renewals.set(id, { resolve, reject, timer });
+                });
+                try {
+                    await send(JSON.stringify({ command: 'renew', id, leaseMs }));
+                    return await pending;
+                }
+                catch (error) {
+                    const renewal = renewals.get(id);
+                    if (renewal) {
+                        clearTimeout(renewal.timer);
+                        renewals.delete(id);
+                        renewal.resolve({ admitted: true, physical: 'failed' });
+                    }
+                    throw error;
+                }
+            } });
+    }
+    catch (error) {
+        await stop();
+        throw error instanceof NativeCommandError ? error : new NativeCommandError('unsupported_automation_protocol');
+    }
+}
 /** A single bounded session/event consumer; overflow retires the session. */
 export class DesktopQueue {
     limit;