@platless/axom-cli 0.5.9 → 0.6.36

package/dist/workstation/desktopControl/helperProcess.js

@@ -0,0 +1,353 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { DesktopProtocolError, parseDesktopJson } from './protocol.js';
+import { decodeMedia, mediaRequire } from './media.js';
+import { decodeAudio } from './audio.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'];
+const safe = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const handshakeSchema = z.strictObject({ ipc: z.literal(1), providerVersion: z.literal('axom-linux-1'),
+    representations: z.tuple([z.literal(1)]),
+    inputAbi: z.literal(1), rateAbi: z.literal(1), continuationAbi: z.literal(1), motionRecoveryAbi: z.literal(1), runtimeRateReconfigure: z.literal(false),
+    rateLimits: z.strictObject({ minBps: z.literal(500000), maxBps: z.literal(20000000), stepBps: z.literal(4000), maxFps: z.literal(60) }),
+    supportedCommands: z.array(z.string()).refine(a => commands.every(c => a.includes(c))) });
+export function validateNativeHandshake(value, platform = 'linux') {
+    (platform === 'linux' ? handshakeSchema : handshakeSchema.extend({ providerVersion: z.literal('axom-macos-1'),
+        rateLimits: handshakeSchema.shape.rateLimits.extend({ maxFps: z.literal(30) }) })).parse(value);
+}
+/** One waiter, pulled reads: a blocked media consumer never blocks the control reader. */
+export class NativeByteReader {
+    max;
+    iterator;
+    bytes = Buffer.alloc(0);
+    constructor(stream, max = 65600) {
+        this.max = max;
+        this.iterator = stream[Symbol.asyncIterator]();
+    }
+    async exact(size) {
+        mediaRequire(Number.isInteger(size) && size > 0 && size <= this.max);
+        while (this.bytes.length < size) {
+            const next = await this.iterator.next();
+            if (next.done)
+                throw new DesktopProtocolError('Native stream ended');
+            mediaRequire(Buffer.isBuffer(next.value) && this.bytes.length + next.value.length <= this.max + 65536);
+            this.bytes = Buffer.concat([this.bytes, next.value]);
+        }
+        const value = this.bytes.subarray(0, size);
+        this.bytes = this.bytes.subarray(size);
+        return value;
+    }
+}
+export class NativeControlReader {
+    reader;
+    constructor(stream) { this.reader = new NativeByteReader(stream, 49152); }
+    async read() {
+        const size = (await this.reader.exact(4)).readUInt32BE();
+        mediaRequire(size > 0 && size <= 49152);
+        // lastEncodeMs is the sole fractional native counter.
+        const bytes = await this.reader.exact(size);
+        return parseDesktopJson(bytes, 49152, nativeIntegerFields);
+    }
+}
+const nativeIntegerFields = new Set(['ipc', 'id', 'epoch', 'width', 'height', 'dpi', 'fpsCeiling', 'targetBps', 'rateTargetBps',
+    'motionRecoveryAbi', 'cutId', 'pictureThrough', 'frameThrough', 'continuationAbi', 'inputAbi', 'rateAbi', 'representations', 'representation', 'minBps', 'maxBps', 'stepBps', 'maxFps',
+    'maxRateBps', 'bufferBits', 'maxBFrames', 'nextFrameId', 'frameId', 'leaseMs', 'motionConsumedBytes', 'cursorConsumedBytes', 'exactConsumedBytes', 'windowBytes',
+    'hrdBitRate', 'hrdCpbSize', 'spsWidth', 'spsHeight', 'spsMaxReorderFrames',
+    'rcModeValue', 'blockLevelRateControl', 'spsMaxRateBps', 'spsBufferBits',
+    'controlGeneration', 'displayRevision', 'sequence', 'lastAllocatedFrameId', 'frameIdLimit', 'captured', 'encoded', 'sentPayloadBytes',
+    'videoPayloadBytes', 'headerBytes', 'rateReopens', 'refinementFrames', 'motionContinuations', 'pendingPayloadBytes', 'rateCooldownUntilMs', 'nowMs', 'initialAtMs',
+    'cacheId', 'exactSequence', 'initialReservoirBits', 'capacityBits', 'availableBits', 'integratedTargetBits', 'transportBytes', 'debtBits', 'appliedAtMonotonicMs', 'lastInputSequence', 'lastAppliedInputSequence', 'wireBytes',
+    'sourceCaptureUs', 'captureBeginUs', 'captureEndUs', 'captureCompareBeginUs', 'captureCompareEndUs', 'captureCopyBeginUs', 'captureCopyEndUs', 'encodeBeginUs', 'encodeEndUs', 'committedUs']);
+const budgetSchema = z.strictObject({ nowMs: safe, initialAtMs: safe, initialReservoirBits: safe, capacityBits: safe,
+    availableBits: safe, integratedTargetBits: safe, transportBytes: safe, debtBits: safe });
+const frameTimingSchema = z.strictObject({ clock: z.literal('steady_clock'), epoch: safe.min(1), frameId: safe.min(1), repair: z.boolean(),
+    sourceCaptureUs: safe, captureBeginUs: safe, captureEndUs: safe, captureCompareBeginUs: safe.default(0), captureCompareEndUs: safe.default(0),
+    captureCopyBeginUs: safe.default(0), captureCopyEndUs: safe.default(0), encodeBeginUs: safe, encodeEndUs: safe, committedUs: safe,
+}).refine(timing => timing.encodeBeginUs <= timing.encodeEndUs && timing.encodeEndUs <= timing.committedUs &&
+    (timing.repair ? timing.sourceCaptureUs === 0 && timing.captureBeginUs === 0 && timing.captureEndUs === 0 :
+        timing.captureBeginUs <= timing.captureEndUs && timing.captureEndUs <= timing.encodeBeginUs &&
+            (timing.captureCompareBeginUs === 0 && timing.captureCompareEndUs === 0 && timing.captureCopyBeginUs === 0 && timing.captureCopyEndUs === 0 ||
+                timing.captureCompareBeginUs <= timing.captureCompareEndUs &&
+                    timing.captureCompareEndUs <= timing.captureCopyBeginUs && timing.captureCopyBeginUs <= timing.captureCopyEndUs &&
+                    timing.captureCopyEndUs <= timing.captureEndUs)), 'Invalid native frame timing');
+const countersSchema = z.strictObject({ epoch: safe, lastAllocatedFrameId: safe, frameIdLimit: safe, captured: safe, encoded: safe,
+    sentPayloadBytes: safe, videoPayloadBytes: safe, headerBytes: safe, rateReopens: safe, targetBps: safe, fpsCeiling: safe,
+    pauseCapture: z.boolean(), lastEncodeMs: z.number().finite().min(0), lastFrameTiming: frameTimingSchema.nullable(), refinementFrames: safe.optional(), motionContinuations: safe.optional(), pendingPayloadBytes: safe, rateCooldownUntilMs: safe,
+    rateBudget: budgetSchema.optional(), inputAvailable: z.boolean(), lastInputSequence: safe });
+const replySchema = z.union([
+    z.strictObject({ ipc: z.literal(1), id: safe, ok: z.literal(true), result: z.record(z.string(), z.unknown()), counters: countersSchema }),
+    z.strictObject({ ipc: z.literal(1), id: safe, ok: z.literal(false), code: z.enum(['invalid_request', 'unavailable', 'conflict', 'busy',
+            'rate_limited', 'authorization_lost', 'encoder_failed']), counters: countersSchema }),
+]);
+export class NativeCommandError extends Error {
+    code;
+    counters;
+    constructor(code, counters) {
+        super(code);
+        this.code = code;
+        this.counters = counters;
+    }
+}
+/** Local queue retirement, created only before allocating an ID or writing bytes. */
+class NativeCommandCancelled extends NativeCommandError {
+    constructor() { super('cancelled'); }
+}
+export async function bounded(promise, ms, code = 'transport_failed') {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new NativeCommandError(code)), ms); })]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class HelperProcess {
+    executable;
+    env;
+    child;
+    reader;
+    media;
+    audio;
+    audioSupported = false;
+    id = 0;
+    queued = 0;
+    tail = Promise.resolve();
+    stopped = false;
+    termination;
+    pending = new Map();
+    active = new Set();
+    stopPromise;
+    exited = false;
+    closed;
+    counters;
+    constructor(executable, env) {
+        this.executable = executable;
+        this.env = env;
+        this.child = spawn(executable, ['--media-fd', '3'], { stdio: ['pipe', 'pipe', 'ignore', 'pipe', 'pipe'], env: { ...env, AXOM_KEEPER_AUDIO_FD: '4' }, detached: false });
+        this.child.stdin.on('error', () => { });
+        this.reader = new NativeControlReader(this.child.stdout);
+        this.media = new NativeByteReader(this.child.stdio[3]);
+        this.audio = new NativeByteReader(this.child.stdio[4]);
+        this.closed = new Promise(resolve => {
+            this.child.once('exit', () => { this.exited = true; this.rejectPending(new NativeCommandError('transport_failed')); resolve(); });
+            this.child.once('error', () => { this.exited = true; this.rejectPending(new NativeCommandError('transport_failed')); resolve(); });
+        });
+    }
+    static async launch(executable, env = process.env, platform = 'linux') {
+        const h = new HelperProcess(executable, env);
+        try {
+            const handshake = await bounded(h.reader.read(), 3000, 'unavailable');
+            validateNativeHandshake(handshake, platform);
+            h.audioSupported = handshake.supportedCommands.includes('audio_start');
+            void h.readReplies();
+            return h;
+        }
+        catch {
+            await h.terminate();
+            throw new NativeCommandError('unavailable');
+        }
+    }
+    get pid() { return this.child.pid; }
+    async readReplies() {
+        try {
+            while (!this.stopped && !this.exited) {
+                const reply = replySchema.parse(await this.reader.read());
+                const first = this.pending.entries().next();
+                mediaRequire(!first.done && reply.id === first.value[0]);
+                const [id, pending] = first.value;
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                this.counters = reply.counters;
+                if (reply.ok)
+                    pending.resolve({ result: reply.result, counters: reply.counters });
+                else
+                    pending.reject(new NativeCommandError(reply.code, reply.counters));
+            }
+        }
+        catch (error) {
+            if (!this.stopped)
+                this.fail(error);
+        }
+    }
+    rejectPending(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    fail(error) { this.rejectPending(error); void this.terminate(); }
+    request(command, binding, payload = {}, current = () => true) {
+        if (this.stopped || this.exited || ![...commands, 'cursor_visibility', 'audio_start', 'audio_rate', 'audio_stop', 'audio_status'].includes(command) || this.queued >= 32)
+            return Promise.reject(new NativeCommandError('transport_failed'));
+        const barrier = !['credit', 'status', 'input', 'transport_cost', 'cache_dependency'].includes(command);
+        const prior = barrier ? [...this.active] : [];
+        const identity = { ...binding }, epoch = this.counters?.epoch;
+        let data;
+        try {
+            data = structuredClone(payload);
+        }
+        catch (error) {
+            this.fail(error);
+            return Promise.reject(error);
+        }
+        this.queued++;
+        const queuedAt = performance.now();
+        let startedAt = queuedAt;
+        let response;
+        const issued = this.tail.then(async () => {
+            // A barrier drains prior validated replies and their owner continuations,
+            // then excludes every later write until its own reply has completed.
+            if (barrier)
+                await Promise.allSettled(prior);
+            startedAt = performance.now();
+            if (this.stopped || this.exited || !Number.isSafeInteger(this.id + 1))
+                throw new NativeCommandError('transport_failed');
+            if (!current() || command === 'input' && epoch !== undefined && this.counters?.epoch !== epoch)
+                throw new NativeCommandCancelled();
+            // The owner may withdraw capture authority while this rate command waits.
+            // All other payload fields retain their enqueue-time snapshot.
+            if (command === 'set_rate')
+                Object.assign(data, { pauseCapture: payload.pauseCapture });
+            const id = ++this.id, bytes = Buffer.from(JSON.stringify({ ipc: 1, id, command, binding: identity, payload: data }));
+            mediaRequire(bytes.length > 0 && bytes.length <= 49152);
+            response = new Promise((resolve, reject) => {
+                const timer = setTimeout(() => this.fail(new NativeCommandError('transport_failed')), 5000);
+                this.pending.set(id, { resolve, reject, timer });
+            });
+            // A reply can precede the write callback; retain its failure without an
+            // unhandled rejection while write ownership is still being confirmed.
+            void response.catch(() => { });
+            const prefix = Buffer.alloc(4);
+            prefix.writeUInt32BE(bytes.length);
+            await bounded(write(this.child.stdin, Buffer.concat([prefix, bytes])), 5000);
+        });
+        const run = issued.then(() => response);
+        const report = (error) => {
+            if (error instanceof NativeCommandCancelled)
+                return;
+            if (!(error instanceof NativeCommandError) || !['busy', 'rate_limited'].includes(error.code)) {
+                console.error(JSON.stringify({ event: 'desktop_native_command_failed', command,
+                    code: error instanceof NativeCommandError ? error.code : 'transport_failed', elapsedMs: Math.round(performance.now() - startedAt), queuedMs: Math.round(startedAt - queuedAt), queued: this.queued }));
+            }
+            if (!(error instanceof NativeCommandError) || !error.counters)
+                this.fail(error);
+        };
+        const completed = run.catch(error => { report(error); throw error; }).finally(() => {
+            this.queued--;
+            this.active.delete(completed);
+        });
+        this.active.add(completed);
+        // Observe issuance errors before allowing the next queued write. Reply
+        // failures are reported by completed; the reader independently fails all
+        // in-flight work on malformed or unknown replies.
+        this.tail = (barrier ? completed : issued).catch(error => {
+            if (!(error instanceof NativeCommandCancelled) && (!(error instanceof NativeCommandError) || !error.counters))
+                this.fail(error);
+        });
+        return completed;
+    }
+    get packets() {
+        const self = this;
+        return { async *[Symbol.asyncIterator]() {
+                while (!self.stopped && !self.exited) {
+                    const header = await self.media.exact(64), size = header.readUInt32BE(48);
+                    mediaRequire(size > 0 && size <= 65536);
+                    const bytes = Buffer.concat([header, await self.media.exact(size)]);
+                    decodeMedia(bytes);
+                    yield bytes;
+                }
+            } };
+    }
+    get audioPackets() {
+        const self = this;
+        return { async *[Symbol.asyncIterator]() {
+                while (!self.stopped && !self.exited) {
+                    const header = await self.audio.exact(40), size = header.readUInt16BE(36);
+                    mediaRequire(size > 0 && size <= 1000);
+                    const bytes = Buffer.concat([header, await self.audio.exact(size)]);
+                    decodeAudio(bytes);
+                    yield bytes;
+                }
+            } };
+    }
+    stop(binding) {
+        return this.stopPromise ??= (async () => {
+            if (!this.exited) {
+                try {
+                    await bounded(this.request('stop', binding), 750);
+                }
+                catch { /* EOF cleanup remains authoritative. */ }
+            }
+            await this.terminate();
+            await HelperProcess.verifyCleanup(this.executable, this.env);
+        })();
+    }
+    terminate() {
+        return this.termination ??= (async () => {
+            this.stopped = true;
+            this.rejectPending(new NativeCommandError('transport_failed'));
+            if (!this.exited) {
+                this.child.kill('SIGTERM');
+                try {
+                    await bounded(this.closed, 1000);
+                }
+                catch {
+                    this.child.kill('SIGKILL');
+                    await bounded(this.closed, 2000);
+                }
+            }
+            this.child.stdin?.destroy();
+            this.child.stdout?.destroy();
+            this.child.stdio[3]?.destroy();
+            this.child.stdio[4]?.destroy();
+        })();
+    }
+    static async verifyCleanup(executable, env = process.env) {
+        const deadline = performance.now() + 3000;
+        do {
+            try {
+                await execute(executable, ['--verify-input-cleanup'], { env, timeout: 750, maxBuffer: 4096 });
+                return;
+            }
+            catch {
+                await delay(25);
+            }
+        } while (performance.now() < deadline);
+        throw new NativeCommandError('unavailable');
+    }
+}
+function write(stream, bytes) {
+    return new Promise((resolve, reject) => stream.write(bytes, error => error ? reject(error) : resolve()));
+}
+/** A single bounded session/event consumer; overflow retires the session. */
+export class DesktopQueue {
+    limit;
+    values = [];
+    wake;
+    ended = false;
+    constructor(limit = 64) {
+        this.limit = limit;
+    }
+    push(value) {
+        if (this.ended)
+            return;
+        if (this.wake) {
+            const wake = this.wake;
+            this.wake = undefined;
+            wake({ value, done: false });
+        }
+        else {
+            mediaRequire(this.values.length < this.limit);
+            this.values.push(value);
+        }
+    }
+    close() { this.ended = true; this.values = []; this.wake?.({ value: undefined, done: true }); this.wake = undefined; }
+    [Symbol.asyncIterator]() {
+        return { next: () => this.values.length ? Promise.resolve({ value: this.values.shift(), done: false }) :
+                this.ended ? Promise.resolve({ value: undefined, done: true }) : new Promise(resolve => { mediaRequire(!this.wake); this.wake = resolve; }) };
+    }
+}

package/dist/workstation/desktopControl/lobby.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { decodeDesktopSessionRequest, parseDesktopJson } from './protocol.js';
+const identifier = z.string().regex(/^[a-f0-9]{32}$/);
+const safe = z.number().int().min(1).max(Number.MAX_SAFE_INTEGER);
+const sourceAxis = z.number().int().min(2).max(4096);
+const axis = sourceAxis.refine(value => value % 2 === 0);
+const sourceModeSchema = z.strictObject({ width: sourceAxis, height: sourceAxis });
+const modeSchema = z.strictObject({ width: axis, height: axis });
+const viewportSchema = z.strictObject({ widthDp: z.number().finite().positive().max(16384),
+    heightDp: z.number().finite().positive().max(16384), deviceScale: z.number().finite().min(0.5).max(8),
+    orientation: z.enum(['landscape', 'portrait']) });
+const resolutionSchema = z.discriminatedUnion('mode', [z.strictObject({ mode: z.literal('fit') }),
+    z.strictObject({ mode: z.literal('fixed'), width: axis, height: axis })]);
+export const lobbyRequestSchema = z.strictObject({ requestId: identifier, revision: safe, viewport: viewportSchema,
+    resolution: resolutionSchema, dpi: z.number().int().min(64).max(384).nullable(),
+    transports: z.array(z.enum(['quic', 'wss'])).min(1).max(2).refine(values => new Set(values).size === values.length),
+    targetId: identifier.nullable().optional(), viewer: z.unknown().nullable().optional() });
+const rangeSchema = z.strictObject({ minWidth: axis, minHeight: axis, maxWidth: axis, maxHeight: axis });
+export const lobbyPlanSchema = z.strictObject({ lobbyId: identifier, planId: identifier, revision: safe, targetId: identifier,
+    desktop: sourceModeSchema, dpi: z.number().int().min(64).max(384).nullable(), resize: z.enum(['none', 'modes', 'dynamic']),
+    modes: z.array(modeSchema).max(32), resizeRange: rangeSchema.nullable(), dynamicDpi: z.boolean(), canAcquire: z.boolean(),
+    reason: z.string().max(128).nullable(), maxDpi: z.number().int().min(64).max(384).nullable(), captureViewport: z.boolean(),
+    sampling: modeSchema, targets: z.array(z.strictObject({ id: identifier, label: z.string().min(1).max(128),
+        kind: z.enum(['display', 'window']), available: z.boolean() })).max(128) });
+export function decodeLobbyRequest(text) {
+    if (Buffer.byteLength(text) > 49152)
+        throw new Error('invalid_request');
+    const request = lobbyRequestSchema.parse(parseDesktopJson(text));
+    if (request.viewer != null)
+        decodeDesktopSessionRequest(JSON.stringify({ requestId: request.requestId,
+            displayId: request.targetId ?? request.requestId, viewer: request.viewer, viewport: request.viewport,
+            resolution: request.resolution, quality: 'auto', takeover: false }));
+    return request;
+}
+export const wallpaperAssetSchema = z.strictObject({ assetId: z.string().min(1).max(128), version: z.string().min(1).max(128),
+    originalWidth: z.number().int().min(1).max(65536), originalHeight: z.number().int().min(1).max(65536),
+    width: z.number().int().min(1).max(4096), height: z.number().int().min(1).max(4096),
+    placement: z.enum(['cover', 'fit', 'stretch', 'center', 'tile']).default('cover'),
+    coverage: z.enum(['full_asset', 'composited']).default('full_asset'), compatibleDesktop: sourceModeSchema.nullable().optional(),
+    anchorX: z.number().finite().min(0).max(1).default(0.5), anchorY: z.number().finite().min(0).max(1).default(0.5),
+    background: z.string().regex(/^#[a-fA-F0-9]{6}$/).default('#000000'),
+    intrinsicScale: z.number().finite().min(0.125).max(16).default(1),
+    fidelity: z.enum(['exact', 'approximate']).default('exact'), colorSpace: z.literal('srgb').default('srgb')
+}).refine(asset => asset.width * asset.height <= 4_000_000 && (asset.coverage !== 'composited' || asset.compatibleDesktop != null));
+export function composeWallpaper(value, selected) {
+    const asset = wallpaperAssetSchema.parse(value);
+    const desktop = sourceModeSchema.parse(selected);
+    if (asset.coverage === 'composited' && (asset.compatibleDesktop?.width !== desktop.width || asset.compatibleDesktop.height !== desktop.height))
+        throw new Error('incompatible_wallpaper');
+    const full = { x: 0, y: 0, width: 1, height: 1 };
+    if (asset.coverage === 'composited' || asset.placement === 'stretch')
+        return { source: full, destination: full, version: 1 };
+    const imageWidth = asset.originalWidth * asset.intrinsicScale;
+    const imageHeight = asset.originalHeight * asset.intrinsicScale;
+    if (asset.placement === 'tile')
+        return { source: full, destination: full,
+            tileWidth: imageWidth / desktop.width, tileHeight: imageHeight / desktop.height, version: 1 };
+    const scale = asset.placement === 'cover' ? Math.max(desktop.width / imageWidth, desktop.height / imageHeight) :
+        asset.placement === 'fit' ? Math.min(desktop.width / imageWidth, desktop.height / imageHeight) : 1;
+    const sourceWidth = Math.min(1, desktop.width / (imageWidth * scale));
+    const sourceHeight = Math.min(1, desktop.height / (imageHeight * scale));
+    const destinationWidth = Math.min(1, imageWidth * scale / desktop.width);
+    const destinationHeight = Math.min(1, imageHeight * scale / desktop.height);
+    return { source: { x: (1 - sourceWidth) * asset.anchorX, y: (1 - sourceHeight) * asset.anchorY,
+            width: sourceWidth, height: sourceHeight },
+        destination: { x: (1 - destinationWidth) * asset.anchorX, y: (1 - destinationHeight) * asset.anchorY,
+            width: destinationWidth, height: destinationHeight }, version: 1 };
+}
+export function planLobby(request, capabilities, lobbyId, planId, automaticDpi = true) {
+    const target = capabilities.displays.find(display => display.id === request.targetId) ??
+        (request.targetId == null ? capabilities.displays.find(display => display.kind !== 'window') : undefined);
+    if (!target)
+        throw new Error('unavailable');
+    const viewer = request.viewer == null ? null : decodeDesktopSessionRequest(JSON.stringify({ requestId: request.requestId,
+        displayId: target.id, viewer: request.viewer, viewport: request.viewport, resolution: request.resolution,
+        quality: 'auto', takeover: false })).viewer;
+    const limits = capabilities.encoderBackends.flatMap(backend => backend.formats).filter(format => format.cappedRate &&
+        capabilities.formats.includes(format.format) && (!viewer || viewer.formats.includes(format.format)));
+    const limit = limits.sort((first, second) => second.maxPixels - first.maxPixels)[0];
+    if (!limit || viewer && (viewer.protocols.min > 2 || viewer.protocols.max < 2))
+        throw new Error('unsupported_client');
+    const maxWidth = Math.min(viewer?.maxWidth ?? 4096, limit.maxWidth);
+    const maxHeight = Math.min(viewer?.maxHeight ?? 4096, limit.maxHeight);
+    const maxPixels = Math.min(viewer?.maxPixels ?? 4_000_000, limit.maxPixels);
+    const layoutScale = !automaticDpi && !target.captureViewport ? 1 : request.viewport.deviceScale;
+    const desired = request.resolution.mode === 'fixed' ? request.resolution : {
+        width: Math.max(2, Math.floor(request.viewport.widthDp * layoutScale / 2) * 2),
+        height: Math.max(2, Math.floor(request.viewport.heightDp * layoutScale / 2) * 2)
+    };
+    let desktop;
+    if (target.captureViewport || target.resize === 'none')
+        desktop = { width: target.width, height: target.height };
+    else if (target.resize === 'dynamic' && target.resizeRange) {
+        const range = target.resizeRange;
+        const factor = Math.min(1, Math.min(maxWidth, range.maxWidth) / desired.width, Math.min(maxHeight, range.maxHeight) / desired.height, Math.sqrt(Math.min(maxPixels, 4_000_000) / (desired.width * desired.height)));
+        desktop = { width: Math.max(range.minWidth, Math.floor(desired.width * factor / 2) * 2),
+            height: Math.max(range.minHeight, Math.floor(desired.height * factor / 2) * 2) };
+    }
+    else {
+        desktop = [...target.modes].filter(candidate => candidate.width <= maxWidth && candidate.height <= maxHeight &&
+            candidate.width * candidate.height <= maxPixels).sort((first, second) => {
+            const score = (candidate) => Math.abs(Math.log((candidate.width / candidate.height) / (desired.width / desired.height))) * 10 +
+                Math.abs(Math.log(candidate.width * candidate.height / (desired.width * desired.height)));
+            return score(first) - score(second);
+        })[0] ?? { width: target.width, height: target.height };
+    }
+    const maximumDpi = target.maxDpi == null ? undefined : Math.min(target.maxDpi, viewer?.maxDpi ?? target.maxDpi);
+    const baselineDpi = automaticDpi && request.resolution.mode === 'fit' ? Math.max(96, Math.round(96 * Math.min(desktop.width / request.viewport.widthDp, desktop.height / request.viewport.heightDp))) : 96;
+    const dpi = maximumDpi == null ? null : Math.min(maximumDpi, request.dpi ?? baselineDpi);
+    let sampling = desktop;
+    if (target.captureViewport) {
+        const density = Math.min(target.capturePixelScale ?? 1, request.resolution.mode === 'fixed' ?
+            Math.min(desired.width / desktop.width, desired.height / desktop.height) :
+            Math.min(request.viewport.widthDp / desktop.width, request.viewport.heightDp / desktop.height) * request.viewport.deviceScale);
+        const width = desktop.width * density, height = desktop.height * density;
+        const factor = Math.min(1, maxWidth / width, maxHeight / height, Math.sqrt(maxPixels / (width * height)));
+        sampling = { width: Math.max(2, Math.floor(width * factor / 2) * 2), height: Math.max(2, Math.floor(height * factor / 2) * 2) };
+    }
+    const supported = sampling.width <= maxWidth && sampling.height <= maxHeight && sampling.width * sampling.height <= maxPixels;
+    const modes = target.captureViewport ? [sampling] : target.resize === 'none' ? [desktop] : [...target.modes.filter(candidate => candidate.width <= maxWidth && candidate.height <= maxHeight && candidate.width * candidate.height <= maxPixels &&
+            (candidate.width !== desktop.width || candidate.height !== desktop.height)).slice(0, 31), desktop];
+    return { lobbyId, planId, revision: request.revision, targetId: target.id, desktop, dpi,
+        resize: target.captureViewport ? 'none' : target.resize, modes,
+        resizeRange: target.captureViewport ? null : target.resizeRange ?? null, dynamicDpi: maximumDpi != null,
+        maxDpi: maximumDpi ?? null, captureViewport: target.captureViewport ?? false, sampling,
+        canAcquire: supported && capabilities.configured && capabilities.health === 'ready' && ['granted', 'not_applicable'].includes(capabilities.permission),
+        reason: supported ? capabilities.reason : 'unsupported_client', targets: capabilities.displays.map(display => ({ id: display.id, label: display.label,
+            kind: display.kind ?? 'display', available: true })) };
+}

package/dist/workstation/desktopControl/macProvider.js

@@ -0,0 +1,155 @@
+import { promises as fs, constants } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createConnection } from 'node:net';
+import { z } from 'zod';
+import { NativeProvider } from './nativeProvider.js';
+import { HelperProcess, bounded, NativeCommandError } from './helperProcess.js';
+import { desktopCapabilitiesSchema } from './protocol.js';
+import { normalizeWorkstationServer } from '../control/serverIdentity.js';
+import { captureTargetLabel } from './captureTargetLabel.js';
+import { decodeWallpaper } from './wallpaper.js';
+import { captureSamplingModes as macCaptureModes } from './captureModes.js';
+const execute = promisify(execFile);
+export const macDesktopGrantSchema = z.strictObject({ schemaVersion: z.literal(1),
+    binding: z.strictObject({ server: z.string(), workstationId: z.string(), ownerUserId: z.string() }),
+    executable: z.string().startsWith('/').max(4096), sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    socket: z.string().startsWith('/').max(103), token: z.string().regex(/^[a-f0-9]{64}$/) });
+const target = z.object({ id: z.string().regex(/^[0-9a-f]{32}$/), kind: z.enum(['display', 'window']), label: z.string(), displayIdentity: z.string().min(1).max(256), capturePixelScale: z.number().min(1).max(16).optional(),
+    width: z.number().int().min(2).max(4096).refine(n => n % 2 === 0), height: z.number().int().min(2).max(4096).refine(n => n % 2 === 0) }).refine(t => t.width * t.height <= 16777216);
+const geometry = z.object({ targets: z.array(target).min(1).max(128), screenRecording: z.boolean(), accessibility: z.boolean(), independentCursor: z.boolean(), captureViewport: z.boolean().optional(), overview: z.boolean().optional(), cursorVisibility: z.boolean().optional(), audio: z.boolean().optional() });
+export { captureTargetLabel } from './captureTargetLabel.js';
+export { captureSamplingModes as macCaptureModes } from './captureModes.js';
+export async function checkMacHost(grant) {
+    const socket = createConnection(grant.socket);
+    try {
+        await bounded(new Promise((resolve, reject) => {
+            socket.once('error', reject);
+            socket.once('connect', () => socket.write(grant.token));
+            socket.once('data', bytes => bytes.length === 1 && bytes[0] === 1 ? resolve() : reject(new NativeCommandError('unavailable')));
+            socket.once('end', () => reject(new NativeCommandError('unavailable')));
+        }), 1000, 'unavailable');
+    }
+    finally {
+        socket.destroy();
+    }
+}
+/** Discovery can report permissions but cannot prompt, capture, encode or inject input. */
+export class MacProvider {
+    directory;
+    binding;
+    provider;
+    identity = '';
+    revisions = new Map();
+    constructor(directory, binding) {
+        this.directory = directory;
+        this.binding = binding;
+    }
+    async grant() {
+        const file = await fs.open(path.join(this.directory, 'desktop-provider.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+        let grant;
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077 || stat.size > 16384)
+                throw new NativeCommandError('unavailable');
+            grant = macDesktopGrantSchema.parse(JSON.parse(await file.readFile('utf8')));
+        }
+        finally {
+            await file.close();
+        }
+        if (normalizeWorkstationServer(grant.binding.server) !== normalizeWorkstationServer(this.binding.server) || grant.binding.workstationId !== this.binding.workstationId || grant.binding.ownerUserId !== this.binding.ownerUserId)
+            throw new NativeCommandError('unavailable');
+        if (!grant.executable.endsWith('/Axom Work Computer Use.app/Contents/MacOS/Axom Work Computer Use'))
+            throw new NativeCommandError('unavailable');
+        const executable = await fs.open(grant.executable, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await executable.stat();
+            if (!stat.isFile() || stat.size > 32 * 1024 * 1024 || stat.mode & 0o022)
+                throw new NativeCommandError('unavailable');
+            const hash = createHash('sha256');
+            for await (const bytes of executable.createReadStream({ autoClose: false }))
+                hash.update(bytes);
+            if (hash.digest('hex') !== grant.sha256)
+                throw new NativeCommandError('unavailable');
+        }
+        finally {
+            await executable.close();
+        }
+        await execute('/usr/bin/codesign', ['--verify', '--strict', path.resolve(grant.executable, '../../..')], { timeout: 7000, maxBuffer: 65536 });
+        await checkMacHost(grant);
+        return grant;
+    }
+    async capabilities() {
+        const grant = await this.grant();
+        const { stdout } = await execute(grant.executable, ['--probe'], { timeout: 7000, maxBuffer: 65536, env: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token } });
+        const g = geometry.parse(JSON.parse(stdout));
+        const displays = g.targets.map(t => {
+            const previous = this.revisions.get(t.id);
+            const identity = t.displayIdentity;
+            const revision = previous ? (previous.identity === identity ? previous.revision : previous.revision + 1) : 1;
+            this.revisions.set(t.id, { identity, revision });
+            return { ...(g.overview ? { overview: true } : {}), id: t.id, kind: t.kind, label: captureTargetLabel(t.label), width: t.width, height: t.height, revision, resize: g.captureViewport ? 'dynamic' : 'none', modes: g.captureViewport ? macCaptureModes(t.width, t.height, t.capturePixelScale ?? 1) : [], ...(g.captureViewport ? { captureViewport: true, capturePixelScale: t.capturePixelScale ?? 1, resizeRange: { minWidth: 2, minHeight: 2, maxWidth: Math.min(4096, Math.floor(t.width * (t.capturePixelScale ?? 1) / 2) * 2), maxHeight: Math.min(4096, Math.floor(t.height * (t.capturePixelScale ?? 1) / 2) * 2) } } : {}) };
+        });
+        const liveIds = new Set(displays.map(d => d.id));
+        for (const id of this.revisions.keys())
+            if (!liveIds.has(id))
+                this.revisions.delete(id);
+        const formats = ['h264-420-v1'];
+        const permission = g.screenRecording && g.accessibility, ready = permission && g.independentCursor;
+        return desktopCapabilitiesSchema.parse({ protocols: { min: 2, max: g.audio ? 3 : 2 }, providerId: 'macos-arm64-v1', providerVersion: 'axom-macos-1', configured: true, cursorEmbedded: false, cursorVisibility: g.cursorVisibility === true,
+            permission: permission ? 'granted' : 'required', health: ready ? 'ready' : 'unavailable', reason: ready ? null : permission ? 'cursor_unavailable' : 'permission_required', formats,
+            encoderBackends: [{ id: 'videotoolbox', kind: 'hardware', formats: formats.map(format => ({ format, maxWidth: 4096, maxHeight: 4096, maxPixels: 8847360, maxFps: 30, cappedRate: true })) }],
+            input: { pointer: true, physicalKeyboard: true, unicodeText: true, clipboard: true, textPaste: true },
+            displays });
+    }
+    async liveProvider() {
+        try {
+            const grant = await this.grant(), identity = grant.sha256 + grant.token;
+            if (identity !== this.identity) {
+                this.identity = identity;
+                this.provider = new NativeProvider({ helperPath: grant.executable, runtimeDir: this.directory, backend: 'videotoolbox',
+                    enumerate: () => this.capabilities(), sessionHelperFactory: async (binding) => { const current = await this.grant(); return HelperProcess.launch(current.executable, { ...process.env, AXOM_KEEPER_TARGET: binding.displayId, AXOM_KEEPER_SOCKET: current.socket, AXOM_KEEPER_TOKEN: current.token }, 'macos'); } });
+            }
+            return this.provider;
+        }
+        catch {
+            return null;
+        }
+    }
+    async probe() {
+        // Only explicit removal of the desktop grant disables discovery. A stopped or
+        // unresponsive keeper is a connection failure, not a disappearing capability.
+        try {
+            await fs.lstat(path.join(this.directory, 'desktop-provider.json'));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        }
+        return this.capabilities();
+    }
+    async prepare(selection, binding) {
+        const provider = await this.liveProvider();
+        if (!provider)
+            throw new NativeCommandError('unavailable');
+        // NativeProvider.prepare performs fresh permission/geometry admission itself.
+        // Repeating full enumeration here added another WindowServer round trip per window.
+        return provider.prepare(selection, binding);
+    }
+    async wallpaper(targetId) {
+        const grant = await this.grant();
+        if (!/^[a-f0-9]{32}$/.test(targetId))
+            throw new NativeCommandError('invalid_request');
+        const result = await execute(grant.executable, ['--wallpaper', targetId], { timeout: 8000, maxBuffer: 100000,
+            env: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token } });
+        return decodeWallpaper(result.stdout);
+    }
+    async recoverDisplay(binding, reserved) {
+        if (!await this.probe() || !this.provider)
+            throw new NativeCommandError('unavailable');
+        return this.provider.recoverDisplay(binding, reserved);
+    }
+}