@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/desktopControl/capabilities.js

@@ -0,0 +1,93 @@
+import { canonicalDesktopJson, decodeCapabilityReport, decodeDesktopManagementFrame } from './protocol.js';
+export const DESKTOP_PROBE_CAP_MS = 4000;
+/** Failure telemetry only: no backend, geometry or input is eligible for admission. */
+const unavailable = () => ({
+    protocols: { min: 2, max: 2 }, providerId: 'discovery', providerVersion: 'unknown', configured: true,
+    permission: 'not_applicable', health: 'unavailable', reason: 'probe_failed', formats: ['h264-420-v1'], encoderBackends: [],
+    input: { pointer: false, physicalKeyboard: false, unicodeText: false },
+    displays: [{ id: '0'.repeat(32), label: 'Unavailable', width: 2, height: 2, revision: 1, resize: 'none', modes: [] }],
+});
+export async function capabilitiesForWire(options) {
+    if (options.selectedWire < 9)
+        return undefined;
+    let timer;
+    const generation = options.generation ?? 'local';
+    if (!options.provider)
+        return { generation, revision: 1, desktop: null };
+    try {
+        const cap = Math.max(1, Math.min(DESKTOP_PROBE_CAP_MS, options.probeCapMs ?? DESKTOP_PROBE_CAP_MS));
+        const desktop = await Promise.race([
+            Promise.resolve().then(() => options.provider.probe()),
+            new Promise(resolve => { timer = setTimeout(() => resolve(unavailable()), cap); timer.unref?.(); }),
+        ]);
+        const compatible = desktop?.deviceOwnershipProtocol === 1 && options.selectedWire < 10 ? null : desktop;
+        const report = decodeCapabilityReport(JSON.stringify({ generation, revision: 1, desktop: compatible && { ...compatible, lobby: true } }));
+        decodeDesktopManagementFrame(JSON.stringify({ t: 'workstation_capabilities', ...report }));
+        return report;
+    }
+    catch {
+        return { generation, revision: 1, desktop: unavailable() };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class DesktopCapabilityReporter {
+    options;
+    current;
+    canonical;
+    running = false;
+    again = false;
+    disposed = false;
+    probe;
+    constructor(options) {
+        this.options = options;
+    }
+    get revision() { return this.current?.revision; }
+    refresh() {
+        if (this.disposed || this.options.selectedWire < 9)
+            return;
+        if (this.running) {
+            this.again = true;
+            return;
+        }
+        this.running = true;
+        void this.report().finally(() => {
+            this.running = false;
+            if (this.again) {
+                this.again = false;
+                this.refresh();
+            }
+        });
+    }
+    async report() {
+        const provider = this.options.provider;
+        // A wedged probe remains a single outstanding operation, even across repeated requests.
+        const boundedProvider = provider && { ...provider, probe: () => {
+                if (!this.probe) {
+                    const pending = Promise.resolve().then(() => provider.probe());
+                    this.probe = pending;
+                    void pending.then(() => { if (this.probe === pending)
+                        this.probe = undefined; }, () => { if (this.probe === pending)
+                        this.probe = undefined; });
+                }
+                return this.probe;
+            } };
+        const report = await capabilitiesForWire({ ...this.options, provider: boundedProvider });
+        if (this.disposed || !report)
+            return;
+        const canonical = canonicalDesktopJson(report.desktop);
+        const revision = this.current ? this.current.revision + (canonical === this.canonical ? 0 : 1) : 1;
+        if (!Number.isSafeInteger(revision)) {
+            this.dispose();
+            return;
+        }
+        this.canonical = canonical;
+        this.current = { ...report, revision };
+        try {
+            this.options.send(this.current);
+        }
+        catch { /* a later request/heartbeat retries the snapshot */ }
+    }
+    dispose() { this.disposed = true; this.again = false; }
+}

package/dist/workstation/desktopControl/captureModes.js

@@ -0,0 +1,9 @@
+/** Capture sampling presets preserve the source aspect and never change its display mode. */
+export function captureSamplingModes(width, height, pixelScale = 1) {
+    const w = width * pixelScale, h = height * pixelScale;
+    const modes = [1280, 1920, 2560, 3840, 4096].map(edge => {
+        const scale = Math.min(1, edge / Math.max(w, h), 4096 / w, 4096 / h, Math.sqrt(8847360 / (w * h)));
+        return { width: Math.max(2, Math.floor(w * scale / 2) * 2), height: Math.max(2, Math.floor(h * scale / 2) * 2) };
+    });
+    return modes.filter((mode, index) => modes.findIndex(m => m.width === mode.width && m.height === mode.height) === index);
+}

package/dist/workstation/desktopControl/captureTargetLabel.js

@@ -0,0 +1,9 @@
+export function captureTargetLabel(label) {
+    let result = '';
+    for (const char of label.replace(/[\x00-\x1f\x7f]/g, ' ')) {
+        if (Buffer.byteLength(result + char) > 128)
+            break;
+        result += char;
+    }
+    return result.trim() || 'Window';
+}

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);
+    }
+}