@platless/axom-cli 0.3.13 → 0.6.36

package/dist/workstation/desktopControl/audio.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+export const audioMode = z.enum(['off', 'auto', 'high', 'low']);
+export const AUDIO_HEADER_BYTES = 40;
+export const AUDIO_MAX_PAYLOAD = 1000;
+export const audioConfiguration = z.strictObject({
+    commandId: z.string().regex(/^[0-9a-f]{32}$/), audioEpoch: z.number().int().min(1).max(0xffffffff),
+    sampleRate: z.literal(48000), channels: z.literal(2), framesPerPacket: z.literal(960),
+    bitrate: z.number().int().min(64000).max(256000), lookaheadFrames: z.number().int().min(0).max(960),
+});
+function requireAudio(value) {
+    if (!value)
+        throw new Error('invalid_audio');
+}
+export function decodeAudio(bytes) {
+    requireAudio(bytes.length >= 41 && bytes.length <= 1040 && bytes.subarray(0, 4).equals(Buffer.from('AXDA')));
+    requireAudio(bytes[4] === 1 && bytes[5] === 0 && bytes.readUInt16BE(6) === 40 &&
+        bytes.readUInt16BE(32) === 960 && bytes[34] === 2 && bytes[35] === 0 &&
+        bytes.readUInt16BE(38) === 0 && bytes.readUInt16BE(36) === bytes.length - 40);
+    const packet = { epoch: bytes.readUInt32BE(8), sequence: bytes.readUInt32BE(12),
+        firstSample: Number(bytes.readBigUInt64BE(16)), captureTimestampUs: Number(bytes.readBigUInt64BE(24)),
+        payload: bytes.subarray(40) };
+    validate(packet);
+    return packet;
+}
+function validate(packet) {
+    requireAudio(Number.isInteger(packet.epoch) && packet.epoch >= 1 && packet.epoch <= 0xffffffff &&
+        Number.isInteger(packet.sequence) && packet.sequence >= 1 && packet.sequence <= 0xffffffff &&
+        Number.isSafeInteger(packet.firstSample) && packet.firstSample === (packet.sequence - 1) * 960 &&
+        Number.isSafeInteger(packet.captureTimestampUs) && packet.captureTimestampUs >= 0 &&
+        packet.payload.length >= 1 && packet.payload.length <= AUDIO_MAX_PAYLOAD);
+}
+export function encodeAudio(packet) {
+    validate(packet);
+    const bytes = Buffer.alloc(AUDIO_HEADER_BYTES + packet.payload.length);
+    bytes.write('AXDA');
+    bytes[4] = 1;
+    bytes.writeUInt16BE(40, 6);
+    bytes.writeUInt32BE(packet.epoch, 8);
+    bytes.writeUInt32BE(packet.sequence, 12);
+    bytes.writeBigUInt64BE(BigInt(packet.firstSample), 16);
+    bytes.writeBigUInt64BE(BigInt(packet.captureTimestampUs), 24);
+    bytes.writeUInt16BE(960, 32);
+    bytes[34] = 2;
+    bytes.writeUInt16BE(packet.payload.length, 36);
+    packet.payload.copy(bytes, 40);
+    return bytes;
+}
+export class AudioRateController {
+    mode;
+    ladder = [64000, 96000, 128000, 192000, 256000];
+    current = 128000;
+    bad = 0;
+    healthy = 0;
+    lastObservation = -Infinity;
+    lastDown = -Infinity;
+    lastUp = -Infinity;
+    constructor(mode = 'off') {
+        this.mode = mode;
+    }
+    get bitrate() {
+        return this.mode === 'off' ? 0 : this.mode === 'high' ? 256000 : this.mode === 'low' ? 64000 : this.current;
+    }
+    select(mode) {
+        audioMode.parse(mode);
+        if (mode !== this.mode) {
+            this.current = mode === 'auto' ? 128000 : this.current;
+            this.bad = this.healthy = 0;
+            this.lastObservation = this.lastDown = this.lastUp = -Infinity;
+        }
+        this.mode = mode;
+        return this.bitrate;
+    }
+    observe(now, feedback) {
+        if (this.mode !== 'auto' || !Number.isFinite(now) || now - this.lastObservation < 500)
+            return this.bitrate;
+        if (![feedback.queueMs, feedback.lateRatio, feedback.lostRatio, feedback.underruns].every(Number.isFinite) ||
+            feedback.queueMs < 0 || feedback.lateRatio < 0 || feedback.lateRatio > 1 ||
+            feedback.lostRatio < 0 || feedback.lostRatio > 1 || feedback.underruns < 0)
+            return this.bitrate;
+        this.lastObservation = now;
+        const adverse = feedback.congested || feedback.queueMs > 40 || feedback.lateRatio > 0.02 || feedback.lostRatio > 0.03;
+        const recovered = !adverse && feedback.headroom && feedback.queueMs < 15 &&
+            feedback.lateRatio < 0.005 && feedback.lostRatio < 0.005 && feedback.underruns === 0;
+        this.bad = adverse ? this.bad + 1 : 0;
+        this.healthy = recovered ? this.healthy + 1 : 0;
+        const index = this.ladder.indexOf(this.current);
+        if (this.bad >= 2 && now - this.lastDown >= 1000 && index > 0) {
+            this.current = this.ladder[index - 1];
+            this.bad = this.healthy = 0;
+            this.lastDown = now;
+        }
+        else if (this.healthy >= 10 && now - Math.max(this.lastUp, this.lastDown) >= 5000 && index < this.ladder.length - 1) {
+            this.current = this.ladder[index + 1];
+            this.bad = this.healthy = 0;
+            this.lastUp = now;
+        }
+        return this.bitrate;
+    }
+}

package/dist/workstation/desktopControl/capabilities.js

@@ -0,0 +1,92 @@
+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 report = decodeCapabilityReport(JSON.stringify({ generation, revision: 1, desktop: desktop && { ...desktop, 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/deviceSockets.js

@@ -0,0 +1,246 @@
+import WebSocket from 'ws';
+import { randomBytes } from 'node:crypto';
+import { openQuicMedia } from './quicMedia.js';
+import { isTrustedPlaintextHost } from '../channels/url.js';
+import { decodeDesktopControl, encodeDesktopControl, parseDesktopJson } from './protocol.js';
+import { decodeDesktopTransport, encodeDesktopTransport } from './transport.js';
+import { bounded, DesktopQueue, NativeCommandError } from './helperProcess.js';
+import { mediaRequire } from './media.js';
+export function desktopSocketUrl(server, role, allow = false) {
+    const url = new URL(server);
+    mediaRequire(!url.username && !url.password && !url.search && !url.hash && ['https:', 'http:'].includes(url.protocol));
+    mediaRequire(url.protocol === 'https:' || allow && isTrustedPlaintextHost(url.hostname));
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/workstation/ws/desktop/${role}`;
+    return url;
+}
+/** Fixed paths, certificate validation on both legs, and no redirect/URL credential propagation. */
+export class DeviceSockets {
+    server;
+    allowPrivateWs;
+    quicRetryAt = 0;
+    constructor(server, allowPrivateWs = false) {
+        this.server = server;
+        this.allowPrivateWs = allowPrivateWs;
+    }
+    async uploadWallpaper(grant, wallpaper, unchanged = false) {
+        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' };
+        if (wallpaper) {
+            headers['X-Axom-Background-Asset'] = Buffer.from(JSON.stringify(wallpaper.asset)).toString('base64url');
+            headers['X-Axom-Background-Unchanged'] = unchanged ? '1' : '0';
+        }
+        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 });
+        if (!response.ok)
+            throw new NativeCommandError('transport_failed');
+        await response.body?.cancel();
+    }
+    async control(binding, signal, current) {
+        const queue = new DesktopQueue();
+        const socket = await this.open(binding, binding.controlGrant, 'control', signal, current, bytes => {
+            const raw = parseDesktopJson(bytes);
+            if (raw.type === 'media_grant') {
+                const grant = decodeDesktopTransport(bytes);
+                mediaRequire(grant.type === 'media_grant' && grant.controlGeneration === binding.controlGeneration && grant.sessionId === binding.sessionId);
+                queue.push(grant);
+            }
+            else {
+                const message = decodeDesktopControl(bytes);
+                mediaRequire(message.sessionId === binding.sessionId && !['clipboard_result', 'offer', 'configured', 'input_result', 'resize_result', 'media_open', 'appearance_result', 'motion_cut_barrier', 'motion_cut_prepared', 'motion_cut_request', 'motion_cut_ack', 'motion_cut_fence', 'audio_configured', 'audio_state'].includes(message.type));
+                queue.push(message);
+            }
+        }, () => queue.close());
+        let overview;
+        let audio;
+        let audioOpening;
+        let audioSerial = 0;
+        const audioCostId = randomBytes(16).toString('hex');
+        let audioBytes = 0;
+        const prepareAudio = async () => {
+            if (!socket.audioToken || !current() || signal.aborted)
+                throw new NativeCommandError('audio_unavailable');
+            const serial = audioSerial;
+            audioOpening ??= this.open(binding, socket.audioToken, 'audio', signal, current, () => { });
+            const connection = await audioOpening;
+            if (serial !== audioSerial || !current()) {
+                connection.close();
+                throw new NativeCommandError('audio_unavailable');
+            }
+            audio = connection;
+            void connection.closed.then(() => { if (audio === connection) {
+                audio = undefined;
+                audioOpening = undefined;
+            } });
+        };
+        let retryAt = 0;
+        return { messages: queue, send: message => socket.send(encodeDesktopControl(message)),
+            prepareAudio: socket.audioToken ? prepareAudio : undefined,
+            sendAudio: socket.audioToken ? async (bytes) => {
+                if (!current() || signal.aborted)
+                    return false;
+                const serial = audioSerial;
+                try {
+                    if (!audio)
+                        await prepareAudio();
+                    const connection = audio;
+                    if (serial !== audioSerial || !current()) {
+                        connection.close();
+                        return false;
+                    }
+                    audio = connection;
+                    await bounded(connection.send(bytes), 80, 'audio_stale');
+                    audioBytes += bytes.length + 32;
+                    return true;
+                }
+                catch {
+                    audio?.close();
+                    audio = undefined;
+                    audioOpening = undefined;
+                    return false;
+                }
+            } : undefined,
+            stopAudio: () => {
+                audioSerial++;
+                audio?.close();
+                void audioOpening?.then(connection => connection.close(), () => { });
+                audio = undefined;
+                audioOpening = undefined;
+            },
+            audioTransportCost: () => ({ id: audioCostId, totalBytes: audioBytes }),
+            sendOverview: socket.overviewToken ? async (bytes) => {
+                if (performance.now() < retryAt || !current() || signal.aborted)
+                    return false;
+                try {
+                    overview ??= await this.open(binding, socket.overviewToken, 'overview', signal, current, () => { });
+                    await overview.send(bytes);
+                    return true;
+                }
+                catch {
+                    overview?.close();
+                    overview = undefined;
+                    retryAt = performance.now() + 5000;
+                    return false;
+                }
+            } : undefined,
+            close: () => { audioSerial++; audio?.close(); overview?.close(); socket.close(); } };
+    }
+    async media(binding, grant, signal, current, quic) {
+        desktopSocketUrl(this.server, 'media', this.allowPrivateWs); // Apply the same origin/TLS policy before either transport.
+        if (quic && binding.mediaTransport !== 'wss' && (binding.mediaTransport === 'quic' || performance.now() >= this.quicRetryAt)) {
+            const native = await openQuicMedia(this.server, quic, signal, current);
+            if (native) {
+                // Once the single-use credential is sent, recovery needs a fresh epoch;
+                // never replay it over WSS after an ambiguous attachment acknowledgement.
+                try {
+                    await native.send(2, Buffer.from(encodeDesktopTransport({ type: 'device_attach', sessionId: binding.sessionId, grant })));
+                    const ack = await native.receive(5000);
+                    mediaRequire(ack.kind === 2);
+                    const attached = decodeDesktopTransport(ack.bytes);
+                    mediaRequire(attached.type === 'attached' && attached.sessionId === binding.sessionId && attached.role === 'device_media' && attached.controlGeneration === binding.controlGeneration);
+                    console.error(JSON.stringify({ event: 'desktop_media_attached', transport: 'quic', role: 'device_media', session: binding.sessionId }));
+                    void native.receive().then(() => native.close(), () => native.close());
+                    const id = randomBytes(16).toString('hex');
+                    return { sendAudio: native.sendAudio, transportCost: () => ({ id, totalBytes: native.transportCost() }), networkSample: () => { const stats = native.pathStats(); return stats ? { ...stats, id } : undefined; }, send: bytes => native.send(3, bytes), close: () => native.close(), closed: native.closed, cutEvents: native.cutEvents, cutCommand: native.cutCommand, finishCut: native.finishCut };
+                }
+                catch (error) {
+                    this.quicRetryAt = performance.now() + 60000;
+                    native.close();
+                    throw error;
+                }
+            }
+            else
+                this.quicRetryAt = performance.now() + 60000;
+        }
+        if (binding.mediaTransport === 'quic')
+            throw new NativeCommandError('transport_failed');
+        const socket = await this.open(binding, grant, 'media', signal, current, () => { throw new NativeCommandError('invalid_request'); });
+        console.error(JSON.stringify({ event: 'desktop_media_attached', transport: 'wss', role: 'device_media', fallback: !quic ? 'not_offered' : 'connect_failed_or_backoff', session: binding.sessionId }));
+        const id = randomBytes(16).toString('hex');
+        let framingBytes = 0;
+        return { transportCost: () => ({ id, totalBytes: framingBytes }), send: async (bytes) => {
+                await socket.send(bytes);
+                framingBytes += bytes.length < 126 ? 6 : bytes.length <= 65535 ? 8 : 14;
+            }, sendCutBarrier: message => socket.send(encodeDesktopControl(message)), close: socket.close, closed: socket.closed };
+    }
+    async open(binding, grant, role, signal, current, onMessage, onClose = () => { }) {
+        mediaRequire(current() && !signal.aborted);
+        const ws = new WebSocket(desktopSocketUrl(this.server, role, this.allowPrivateWs), {
+            headers: role === 'control' ? { 'X-Axom-Desktop-Quic': '1', 'X-Axom-Desktop-Overview': '1', 'X-Axom-Desktop-Audio': '1' } : {},
+            rejectUnauthorized: true, followRedirects: false, maxPayload: 49152, perMessageDeflate: false,
+        });
+        let overviewToken;
+        let audioToken;
+        let attached = false, settle, reject;
+        const opening = new Promise((resolve, fail) => { settle = resolve; reject = fail; });
+        const close = () => { if (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)
+            ws.terminate(); };
+        const closed = new Promise(resolve => ws.once('close', () => {
+            signal.removeEventListener('abort', close);
+            onClose();
+            resolve();
+            if (!attached)
+                reject(new NativeCommandError('authorization_lost'));
+        }));
+        signal.addEventListener('abort', close, { once: true });
+        ws.on('error', () => { reject(new NativeCommandError('transport_failed')); close(); });
+        ws.once('open', () => {
+            if (!current() || signal.aborted) {
+                close();
+                return;
+            }
+            ws.send(encodeDesktopTransport({ type: 'device_attach', sessionId: binding.sessionId, grant }));
+        });
+        ws.on('message', (data, binary) => {
+            try {
+                if (!current() || signal.aborted) {
+                    close();
+                    return;
+                }
+                mediaRequire(!binary);
+                const bytes = Buffer.isBuffer(data) ? data : Buffer.from(data);
+                if (!attached) {
+                    const ack = decodeDesktopTransport(bytes);
+                    mediaRequire(ack.type === 'attached' && ack.sessionId === binding.sessionId && ack.role === (role === 'overview' || role === 'audio' ? 'device_control' : `device_${role}`) && ack.controlGeneration === binding.controlGeneration);
+                    overviewToken = ack.overviewToken;
+                    audioToken = ack.audioToken;
+                    attached = true;
+                    settle();
+                }
+                else
+                    onMessage(bytes);
+            }
+            catch {
+                reject(new NativeCommandError('invalid_request'));
+                close();
+            }
+        });
+        try {
+            await bounded(opening, 5000);
+            mediaRequire(current() && !signal.aborted);
+        }
+        catch (error) {
+            close();
+            throw error;
+        }
+        let sendTail = Promise.resolve();
+        let pending = 0;
+        return { close, closed, overviewToken, audioToken, send: bytes => {
+                if (pending >= (role === 'media' ? 3 : 2))
+                    return Promise.reject(new NativeCommandError('transport_failed'));
+                pending++;
+                const perform = async () => {
+                    // This is the last check after any queued await, immediately before ws.send.
+                    mediaRequire(current() && !signal.aborted && ws.readyState === WebSocket.OPEN && ws.bufferedAmount <= (role === 'media' ? 524288 : 65600));
+                    await bounded(new Promise((resolve, fail) => ws.send(bytes, error => error ? fail(new NativeCommandError('transport_failed')) : resolve())), 5000);
+                };
+                const sent = role === 'media' ? perform() : sendTail.then(perform);
+                sendTail = sent.catch(() => { close(); }).finally(() => { pending--; });
+                return sent;
+            } };
+    }
+}