@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/desktopControl/hostGrant.js

@@ -0,0 +1,65 @@
+import { promises as fs, constants } from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const deviceHostGrantSchema = z.strictObject({ schemaVersion: z.literal(2), hostGeneration: z.string().min(1).max(128),
+    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}$/) });
+async function verifiedSocketPath(socket, checks) {
+    const realpath = checks.realpath ?? ((file) => fs.realpath(file)), canonical = await realpath(socket);
+    if (canonical === socket)
+        return true;
+    // Older macOS producers stored /tmp while the OS resolves its root-owned system alias.
+    // Exact prefix substitution rejects every additional symlink or path normalization.
+    if ((checks.platform ?? process.platform) !== 'darwin' || !socket.startsWith('/tmp/') || canonical !== '/private' + socket)
+        return false;
+    try {
+        const lstat = checks.systemLstat ?? ((file) => fs.lstat(file));
+        const link = await lstat('/tmp'), target = await lstat('/private/tmp');
+        const destination = await (checks.systemReadlink ?? ((file) => fs.readlink(file)))('/tmp');
+        return link.isSymbolicLink() && link.uid === 0 && target.isDirectory() && target.uid === 0 && !!(target.mode & 0o1000) &&
+            (destination === 'private/tmp' || destination === '/private/tmp') && await realpath('/tmp') === '/private/tmp' && await realpath('/private/tmp') === '/private/tmp';
+    }
+    catch {
+        return false;
+    }
+}
+export async function readDeviceHostDescriptor(fileName) {
+    const parent = await fs.lstat(path.dirname(fileName));
+    if (!parent.isDirectory() || parent.uid !== process.getuid?.() || parent.mode & 0o077)
+        throw new Error('unsafe_native_host');
+    const file = await fs.open(fileName, 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 Error('unsafe_native_host');
+        grant = deviceHostGrantSchema.parse(JSON.parse(await file.readFile('utf8')));
+    }
+    finally {
+        await file.close();
+    }
+    return grant;
+}
+export async function readDeviceHostGrant(fileName, allowRootExecutable = false, checks = {}) {
+    const grant = await readDeviceHostDescriptor(fileName);
+    const parent = await fs.lstat(path.dirname(grant.socket)), socket = await fs.lstat(grant.socket);
+    if (!parent.isDirectory() || parent.uid !== process.getuid?.() || parent.mode & 0o077 || !socket.isSocket() || socket.uid !== process.getuid?.() || socket.mode & 0o077 ||
+        !await verifiedSocketPath(grant.socket, checks) || await (checks.realpath ?? ((file) => fs.realpath(file)))(grant.executable) !== grant.executable)
+        throw new Error('unsafe_native_host');
+    const executable = await fs.open(grant.executable, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await executable.stat();
+        if (!stat.isFile() || stat.uid !== process.getuid?.() && !(allowRootExecutable && stat.uid === 0) || stat.mode & 0o022 || stat.size > 32 * 1024 * 1024)
+            throw new Error('unsafe_native_host');
+        const hash = createHash('sha256');
+        for await (const bytes of executable.createReadStream({ autoClose: false }))
+            hash.update(bytes);
+        if (hash.digest('hex') !== grant.sha256)
+            throw new Error('unsafe_native_host');
+    }
+    finally {
+        await executable.close();
+    }
+    return grant;
+}

package/dist/workstation/desktopControl/lobby.js

@@ -14,7 +14,8 @@ const resolutionSchema = z.discriminatedUnion('mode', [z.strictObject({ mode: z.
 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() });
+    targetId: identifier.nullable().optional(), viewer: z.unknown().nullable().optional(),
+    backgroundVersion: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/).nullish() });
 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']),
@@ -40,8 +41,9 @@ export const wallpaperAssetSchema = z.strictObject({ assetId: z.string().min(1).
     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),
+    mimeType: z.enum(['image/jpeg', 'image/webp']).default('image/jpeg'),
     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));
+}).refine(asset => asset.width * asset.height <= 8_388_608 && (asset.coverage !== 'composited' || asset.compatibleDesktop != null));
 export function composeWallpaper(value, selected) {
     const asset = wallpaperAssetSchema.parse(value);
     const desktop = sourceModeSchema.parse(selected);

package/dist/workstation/desktopControl/macProvider.js

@@ -1,20 +1,20 @@
-import { promises as fs, constants } from 'node:fs';
+import { promises as fs } 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 { readDeviceHostGrant } from './hostGrant.js';
 import { desktopCapabilitiesSchema } from './protocol.js';
-import { normalizeWorkstationServer } from '../control/serverIdentity.js';
+import { NativeDeviceAdmission } from './nativeDeviceAdmission.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() }),
+export const macDesktopGrantSchema = z.strictObject({ schemaVersion: z.literal(2),
+    hostGeneration: z.string().min(1).max(128),
     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(),
@@ -39,45 +39,36 @@ export async function checkMacHost(grant) {
 /** Discovery can report permissions but cannot prompt, capture, encode or inject input. */
 export class MacProvider {
     directory;
-    binding;
+    sourceFile;
+    async prepareAutomation(binding) {
+        const provider = await this.liveProvider();
+        if (!provider)
+            throw new NativeCommandError('unavailable');
+        return provider.prepareAutomation(binding);
+    }
+    admission;
+    original;
+    get deviceAdmission() { return this.admission; }
+    static async connect(directory, sourceFile) {
+        const provider = new MacProvider(directory, undefined, sourceFile);
+        if (!await provider.liveProvider())
+            throw new NativeCommandError('unavailable');
+        return provider;
+    }
     provider;
     identity = '';
     revisions = new Map();
-    constructor(directory, binding) {
+    constructor(directory, _binding, sourceFile) {
         this.directory = directory;
-        this.binding = binding;
+        this.sourceFile = sourceFile;
     }
     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)
+        const grant = await readDeviceHostGrant(this.sourceFile ?? path.join(this.directory, 'desktop-provider.json'));
+        if (this.original && JSON.stringify(grant) !== JSON.stringify(this.original))
             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 execute('/usr/bin/codesign', ['--verify', '--strict', '-R', '=identifier "com.platless.axom.computer-use"', path.resolve(grant.executable, '../../..')], { timeout: 7000, maxBuffer: 65536 });
         await checkMacHost(grant);
         return grant;
     }
@@ -107,10 +98,20 @@ export class MacProvider {
     async liveProvider() {
         try {
             const grant = await this.grant(), identity = grant.sha256 + grant.token;
+            if (this.original && identity !== this.identity)
+                return null;
             if (identity !== this.identity) {
+                const admission = await NativeDeviceAdmission.connect(grant);
+                if (admission.hostLifetimeId !== grant.hostGeneration)
+                    throw new NativeCommandError('unavailable');
+                this.original = grant;
+                this.admission = admission;
                 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'); } });
+                    deviceAdmission: admission, environment: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token },
+                    enumerate: () => this.capabilities(), sessionHelperFactory: async (binding) => HelperProcess.launch(grant.executable, { ...process.env, AXOM_KEEPER_TARGET: binding.displayId,
+                        AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token,
+                        AXOM_DEVICE_CONTEXT: admission.context(binding.deviceGrant?.registrationId ?? '', binding.deviceGeneration, binding.sessionId, binding.deviceGrant) }, 'macos') });
             }
             return this.provider;
         }
@@ -131,19 +132,19 @@ export class MacProvider {
         }
         return this.capabilities();
     }
-    async prepare(selection, binding) {
+    async prepare(selection, binding, current) {
         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);
+        return provider.prepare(selection, binding, current);
     }
-    async wallpaper(targetId) {
+    async wallpaper(targetId, pixels = { width: 1920, height: 1080 }) {
         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,
+        const result = await execute(grant.executable, ['--wallpaper', targetId, String(pixels.width), String(pixels.height)], { timeout: 8000, maxBuffer: 3 * 1024 * 1024,
             env: { ...process.env, AXOM_KEEPER_SOCKET: grant.socket, AXOM_KEEPER_TOKEN: grant.token } });
         return decodeWallpaper(result.stdout);
     }

package/dist/workstation/desktopControl/nativeDeviceAdmission.js

@@ -0,0 +1,207 @@
+import { createConnection } from 'node:net';
+import { z } from 'zod';
+import { matchesDeviceGrant, nativeReceiptMatches } from './ownershipProtocol.js';
+const identity = z.string().min(1).max(128);
+const grantSchema = z.strictObject({ registrationId: identity, controllerId: identity, deviceEpoch: identity,
+    revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), authorization: identity });
+const receiptSchema = z.strictObject({ commandId: identity, hostLifetimeId: identity, action: z.enum(['admit', 'isolate']),
+    grant: grantSchema, admission: z.enum(['active', 'revoked']), physical: z.literal('completed') });
+const registrationReceiptSchema = z.strictObject({ commandId: identity, registrationId: identity, deviceGeneration: identity,
+    hostLifetimeId: identity, physical: z.literal('completed'), admission: z.literal('revoked') });
+const statusSchema = z.strictObject({ hostLifetimeId: identity, deviceEpoch: identity.nullable(), connected: z.boolean(), active: z.boolean(),
+    workers: z.number().int().min(0).max(1024), operations: z.number().int().min(0).max(64),
+    scopeCount: z.number().int().min(0).max(1024), scopeBudget: z.literal(1024), rotationRequired: z.boolean(), quiescent: z.boolean(),
+}).refine(value => value.quiescent === (!value.active && value.workers === 0 && value.operations === 0) &&
+    value.rotationRequired === (value.scopeCount === value.scopeBudget || !value.connected));
+const hostRetirementSchema = z.strictObject({ commandId: identity, hostLifetimeId: identity, action: z.literal('retireHost'),
+    admission: z.literal('revoked'), physical: z.literal('completed') });
+export function nativeDeviceRequest(original) {
+    const endpoint = { ...original };
+    return value => new Promise((resolve, reject) => {
+        const socket = createConnection(endpoint.socket);
+        let authenticated = false, settled = false, bytes = Buffer.alloc(0);
+        const finish = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.destroy();
+            if (error)
+                reject(error);
+            else
+                resolve(result);
+        };
+        const timer = setTimeout(() => finish(new Error('device_admission_unconfirmed')), 5000);
+        socket.once('connect', () => socket.write(endpoint.token));
+        socket.on('error', error => finish(error));
+        socket.on('end', () => finish(new Error('device_admission_unconfirmed')));
+        socket.on('data', chunk => {
+            bytes = Buffer.concat([bytes, chunk]);
+            if (!authenticated) {
+                if (bytes[0] !== 1) {
+                    finish(new Error('device_admission_unconfirmed'));
+                    return;
+                }
+                authenticated = true;
+                bytes = bytes.subarray(1);
+                socket.write(`device ${JSON.stringify(value)}\n`);
+            }
+            if (bytes.length > 8192) {
+                finish(new Error('device_admission_unconfirmed'));
+                return;
+            }
+            const newline = bytes.indexOf(10);
+            if (newline < 0)
+                return;
+            try {
+                finish(undefined, JSON.parse(bytes.subarray(0, newline).toString('utf8')));
+            }
+            catch {
+                finish(new Error('device_admission_unconfirmed'));
+            }
+        });
+    });
+}
+export class NativeDeviceAdmission {
+    hostLifetimeId;
+    request;
+    live = true;
+    nativeRetired = false;
+    retirementCommandId;
+    epoch;
+    retiredRevision = -1;
+    installed = new Map();
+    obligations = new Map();
+    revocations = new Map();
+    constructor(hostLifetimeId, request) {
+        this.hostLifetimeId = hostLifetimeId;
+        this.request = request;
+        identity.parse(hostLifetimeId);
+    }
+    static async connect(original) {
+        const request = nativeDeviceRequest(original);
+        const hello = z.strictObject({ hostLifetimeId: identity, deviceAdmissionProtocol: z.literal(1) }).parse(await request({ action: 'hello' }));
+        return new NativeDeviceAdmission(hello.hostLifetimeId, request);
+    }
+    current() { return this.live; }
+    async bindDeviceEpoch(commandId, deviceEpoch) {
+        identity.parse(deviceEpoch);
+        if (!this.live || this.epoch && this.epoch !== deviceEpoch)
+            throw Error('control_lost');
+        const schema = z.strictObject({ commandId: identity, hostLifetimeId: identity, action: z.literal('bindDeviceEpoch'), deviceEpoch: identity });
+        const receipt = schema.parse(await this.request({ action: 'bindDeviceEpoch', commandId, hostLifetimeId: this.hostLifetimeId, deviceEpoch }));
+        if (!this.live || receipt.commandId !== commandId || receipt.hostLifetimeId !== this.hostLifetimeId || receipt.deviceEpoch !== deviceEpoch)
+            throw Error('device_admission_unconfirmed');
+        this.epoch = deviceEpoch;
+    }
+    retire() { this.live = false; for (const grant of this.obligations.values())
+        this.revoke(grant); }
+    key(grant) { return JSON.stringify(grantSchema.parse(grant)); }
+    async admit(commandId, grant) {
+        const key = this.key(grant);
+        if (!this.live || grant.revision <= this.retiredRevision || (this.epoch && this.epoch !== grant.deviceEpoch))
+            throw new Error('control_lost');
+        const original = grantSchema.parse(grant);
+        this.epoch = original.deviceEpoch;
+        this.obligations.set(key, original);
+        try {
+            const receipt = receiptSchema.parse(await this.request({ action: 'admit', commandId, grant: original, hostLifetimeId: this.hostLifetimeId }));
+            if (!this.live || original.revision <= this.retiredRevision || !nativeReceiptMatches(this, commandId, original, 'admit', receipt))
+                throw new Error('device_admission_unconfirmed');
+            this.installed.set(key, original);
+            return receipt;
+        }
+        catch (error) {
+            if (this.nativeRetired)
+                this.obligations.delete(key);
+            else
+                this.revoke(original);
+            throw error;
+        }
+    }
+    revoke(grant) {
+        const key = this.key(grant);
+        if (this.nativeRetired)
+            return;
+        if (this.epoch && this.epoch !== grant.deviceEpoch)
+            throw new Error('control_lost');
+        this.epoch = grant.deviceEpoch;
+        this.retiredRevision = Math.max(this.retiredRevision, grant.revision);
+        this.installed.delete(key);
+        this.obligations.set(key, grantSchema.parse(grant));
+        if (this.revocations.has(key))
+            return;
+        const pending = this.request({ action: 'revoke', grant: grantSchema.parse(grant), hostLifetimeId: this.hostLifetimeId }).then(value => z.strictObject({}).parse(value));
+        this.revocations.set(key, pending);
+        void pending.catch(() => { if (this.revocations.get(key) === pending)
+            this.revocations.delete(key); });
+    }
+    async isolate(commandId, grant) {
+        this.revoke(grant);
+        await this.revocations.get(this.key(grant))?.catch(() => { });
+        const original = grantSchema.parse(grant);
+        const receipt = receiptSchema.parse(await this.request({ action: 'isolate', commandId, grant: original, hostLifetimeId: this.hostLifetimeId }));
+        if (!nativeReceiptMatches(this, commandId, original, 'isolate', receipt))
+            throw new Error('device_admission_unconfirmed');
+        const key = this.key(original);
+        this.installed.delete(key);
+        this.obligations.delete(key);
+        this.revocations.delete(key);
+        return receipt;
+    }
+    async isolateRegistration(commandId, registrationId, deviceGeneration) {
+        const receipt = registrationReceiptSchema.parse(await this.request({ action: 'isolateRegistration', commandId, registrationId,
+            deviceGeneration, hostLifetimeId: this.hostLifetimeId }));
+        if (receipt.commandId !== commandId || receipt.registrationId !== registrationId || receipt.deviceGeneration !== deviceGeneration ||
+            receipt.hostLifetimeId !== this.hostLifetimeId)
+            throw new Error('device_admission_unconfirmed');
+        return receipt;
+    }
+    async status() {
+        const status = statusSchema.parse(await this.request({ action: 'status', hostLifetimeId: this.hostLifetimeId }));
+        if (status.hostLifetimeId !== this.hostLifetimeId)
+            throw new Error('device_admission_unconfirmed');
+        return status;
+    }
+    async retireHost(commandId) {
+        const receipt = hostRetirementSchema.parse(await this.request({ action: 'retireHost', commandId, hostLifetimeId: this.hostLifetimeId }));
+        if (receipt.commandId !== commandId || receipt.hostLifetimeId !== this.hostLifetimeId)
+            throw new Error('device_admission_unconfirmed');
+        this.nativeRetired = true;
+        this.live = false;
+        this.installed.clear();
+        this.obligations.clear();
+        this.revocations.clear();
+        this.retirementCommandId = commandId;
+        return receipt;
+    }
+    async stopHost(commandId) {
+        const schema = z.strictObject({ commandId: identity, hostLifetimeId: identity, action: z.literal('stopHost'), admission: z.literal('revoked'), physical: z.literal('completed') });
+        const receipt = schema.parse(await this.request({ action: 'stopHost', commandId, hostLifetimeId: this.hostLifetimeId }));
+        if (receipt.commandId !== commandId || receipt.hostLifetimeId !== this.hostLifetimeId)
+            throw new Error('device_admission_unconfirmed');
+        this.live = false;
+        this.installed.clear();
+        return receipt;
+    }
+    async acknowledgeHostRetirement(commandId) {
+        if (!this.nativeRetired || !this.retirementCommandId)
+            throw new Error('device_admission_unconfirmed');
+        const schema = z.strictObject({ commandId: identity, hostLifetimeId: identity, action: z.literal('acknowledgeHostRetirement'), admission: z.literal('revoked'), physical: z.literal('completed') });
+        const receipt = schema.parse(await this.request({ action: 'acknowledgeHostRetirement', commandId, retirementCommandId: this.retirementCommandId, hostLifetimeId: this.hostLifetimeId }));
+        if (receipt.commandId !== commandId || receipt.hostLifetimeId !== this.hostLifetimeId)
+            throw new Error('device_admission_unconfirmed');
+        return receipt;
+    }
+    context(registrationId, deviceGeneration, consumerId, grant) {
+        identity.parse(registrationId);
+        identity.parse(deviceGeneration);
+        identity.parse(consumerId);
+        if (!this.live || !this.epoch)
+            throw new Error('control_lost');
+        if (grant && (grant.registrationId !== registrationId || grant.controllerId !== consumerId ||
+            ![...this.installed.values()].some(value => matchesDeviceGrant(value, grant))))
+            throw new Error('control_lost');
+        return JSON.stringify({ hostLifetimeId: this.hostLifetimeId, deviceEpoch: this.epoch, registrationId, deviceGeneration, consumerId, grant: grant ?? null });
+    }
+}

package/dist/workstation/desktopControl/nativeProvider.js

@@ -10,6 +10,7 @@ import { DesktopMediaStream, decodeMedia, desktopMediaLane, mediaRequire } from
 import { canonicalDesktopJson, decodeCapabilityReport, decodeDesktopControl, supportsDesktopMode, captureRegion } from './protocol.js';
 import { captureSamplingModes } from './captureModes.js';
 import { captureTargetLabel } from './captureTargetLabel.js';
+import { launchAutomationHelper } from './helperProcess.js';
 import { XfceWallpaperReader, decodeWallpaper } from './wallpaper.js';
 const execute = promisify(execFile);
 const totals = ['captured', 'encoded', 'videoPayloadBytes', 'headerBytes', 'rateReopens'];
@@ -51,6 +52,15 @@ class ViewerLifetime {
 /** No helper/session construction in discovery. Only the image's admitted software is offered. */
 export class NativeProvider {
     options;
+    async prepareAutomation(binding) {
+        await this.options.validateSession?.();
+        const admission = this.options.deviceAdmission;
+        if (binding.deviceGrant && !admission)
+            throw new NativeCommandError('control_lost');
+        const context = admission ? { AXOM_DEVICE_CONTEXT: admission.context(binding.registrationId ?? binding.deviceGrant?.registrationId ?? '', binding.route.deviceGeneration, binding.route.consumerId, binding.deviceGrant) } : {};
+        return launchAutomationHelper(this.executable, { ...this.environment, ...context }, binding);
+    }
+    get deviceAdmission() { return this.options.deviceAdmission; }
     lifetimes = new Map();
     revision = 1;
     geometry;
@@ -66,6 +76,7 @@ export class NativeProvider {
         this.displayId = '00000000000000000000000000000001';
         this.executable = options.helperPath;
         this.factory = options.helperFactory ?? (binding => HelperProcess.launch(this.executable, { ...this.environment,
+            ...(binding && options.deviceAdmission ? { AXOM_DEVICE_CONTEXT: options.deviceAdmission.context(binding.deviceGrant?.registrationId ?? '', binding.deviceGeneration, binding.sessionId, binding.deviceGrant) } : {}),
             ...(binding ? { AXOM_KEEPER_TARGET: binding.displayId } : {}) }));
     }
     get environment() {
@@ -98,7 +109,7 @@ export class NativeProvider {
         return next;
     }
     probe() { return this.withGeometry(() => this.probeCurrent()); }
-    async wallpaper(targetId) {
+    async wallpaper(targetId, pixels = { width: 1920, height: 1080 }) {
         mediaRequire(/^[a-f0-9]{32}$/.test(targetId));
         const capabilities = await this.probe();
         mediaRequire(capabilities?.displays.some(display => display.id === targetId));
@@ -108,10 +119,10 @@ export class NativeProvider {
             return result.stdout;
         });
         const discovered = await reader.discover();
-        const result = await execute(this.executable, ['--wallpaper-asset', discovered.file, discovered.background], { timeout: 4000, maxBuffer: 100000, env: this.environment });
+        const result = await execute(this.executable, ['--wallpaper-asset', discovered.file, discovered.background, String(pixels.width), String(pixels.height)], { timeout: 4000, maxBuffer: 3 * 1024 * 1024, env: this.environment });
         const wallpaper = decodeWallpaper(result.stdout);
         return { asset: { ...wallpaper.asset, placement: discovered.placement,
-                background: discovered.background, fidelity: discovered.fidelity === 'approximate' ? 'approximate' : wallpaper.asset.fidelity }, jpeg: wallpaper.jpeg };
+                background: discovered.background, fidelity: discovered.fidelity === 'approximate' ? 'approximate' : wallpaper.asset.fidelity }, bytes: wallpaper.bytes };
     }
     async probeCurrent() {
         if (this.options.enumerate)
@@ -192,9 +203,16 @@ export class NativeProvider {
             return actual;
         });
     }
-    async prepare(selection, binding) {
+    async prepare(selection, binding, current) {
+        const admitted = (beginEffect = false) => { if (current?.(beginEffect) === false)
+            throw new NativeCommandError('busy'); };
+        admitted();
+        if (binding.deviceGrant && !this.options.deviceAdmission)
+            throw new NativeCommandError('control_lost');
         await this.options.validateSession?.();
+        admitted();
         const caps = await this.probe();
+        admitted();
         mediaRequire(caps?.health === 'ready' && ['granted', 'not_applicable'].includes(caps.permission));
         if (selection.cursorVisible !== undefined)
             mediaRequire(caps.cursorVisibility === true);
@@ -225,14 +243,19 @@ export class NativeProvider {
             life = new ViewerLifetime();
             this.lifetimes.set(binding.sessionId, life);
         }
-        if (life.session)
+        admitted();
+        if (life.session) {
+            admitted(true);
             await life.session.stop();
+        }
+        admitted();
         life.bind(binding);
         let revision = Math.max(this.revision, display.revision);
         if ((display.captureViewport !== true && (selection.width !== display.width || selection.height !== display.height)) || selection.dpi !== undefined) {
             const physicalWidth = display.captureViewport === true ? display.width : selection.width;
             const physicalHeight = display.captureViewport === true ? display.height : selection.height;
             const actual = await this.geometryTransaction(async (displayRevision) => {
+                admitted(true);
                 const { stdout } = await execute(this.displayControl, ['--transaction', `${physicalWidth}x${physicalHeight}${selection.dpi === undefined ? '' : '@' + selection.dpi}`], { env: this.environment, timeout: 4500, maxBuffer: 4096 });
                 const result = z.object({ outcome: z.literal('applied'), width: z.literal(physicalWidth), height: z.literal(physicalHeight),
                     dpi: selection.dpi === undefined ? z.number().optional() : z.literal(selection.dpi) }).parse(JSON.parse(stdout));
@@ -240,12 +263,15 @@ export class NativeProvider {
             });
             revision = actual.displayRevision;
         }
+        admitted();
         const helper = await (this.options.sessionHelperFactory?.(binding) ?? this.factory(binding));
         const identity = { sessionId: binding.sessionId, deviceGeneration: binding.deviceGeneration,
             controlGeneration: binding.controlGeneration, displayRevision: revision };
         const reserved = life.reserve();
         try {
+            admitted();
             mediaRequire((await helper.request('verify_cleanup', identity)).result.verified === true);
+            admitted(true);
             const payload = { ...(selection.cursorVisible === undefined ? {} : { cursorVisible: selection.cursorVisible }), ...(effectiveRegion ? { captureRegion: effectiveRegion } : {}), width: selection.width, height: selection.height, fpsCeiling: life.prepared ? Math.min(life.appliedFps, selection.fpsCeiling) : selection.fpsCeiling,
                 rateTargetBps: life.appliedTargetBps, quality: selection.quality, backend: this.options.backend ?? 'libx264', leaseMs: 30000, representation: 1,
                 ...reserved, ...(life.prepared ? { continuation: { initialReservoirBits: life.initialReservoirBits, inputSequence: life.inputSequence,

package/dist/workstation/desktopControl/ownershipProtocol.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+const bounded = z.string().min(1).max(128).regex(/^[^\x00-\x1f\x7f]+$/);
+const revision = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+export const deviceAcquisitionSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('if_free') }),
+    z.strictObject({ kind: z.literal('takeover'), expectedDeviceEpoch: bounded, expectedRevision: revision }),
+]);
+export const deviceOwnershipSnapshotSchema = z.strictObject({ deviceEpoch: bounded, revision,
+    state: z.enum(['free', 'draining', 'active']),
+    controller: z.strictObject({ registrationId: bounded, controllerId: bounded, kind: bounded }).nullable(),
+});
+export const deviceOwnershipCommandSchema = z.strictObject({ t: z.literal('desktop_ownership'), ownershipProtocol: z.literal(1),
+    commandId: z.string().regex(/^[0-9a-f]{32}$/), deviceGeneration: bounded, controllerId: bounded,
+    kind: z.enum(['viewer', 'automation']), action: z.enum(['acquire', 'commit', 'release', 'cancel']),
+    requestSequence: revision.refine(value => value > 0).optional(), acquireCommandId: z.string().regex(/^[0-9a-f]{32}$/).optional(),
+    acquisition: deviceAcquisitionSchema.optional(), deviceEpoch: bounded.optional(), revision: revision.optional(),
+}).refine(value => value.action === 'acquire' ? value.acquisition != null && value.requestSequence != null :
+    value.action === 'cancel' ? value.acquireCommandId != null && value.requestSequence != null : value.deviceEpoch != null && value.revision != null);
+const reservationCauseSchema = z.strictObject({ acquireCommandId: z.string().regex(/^[0-9a-f]{32}$/), contenderControllerId: bounded, deviceGeneration: bounded });
+export const deviceOwnershipEventSchema = z.strictObject({ t: z.literal('desktop_ownership_result'), ownershipProtocol: z.literal(1),
+    commandId: z.string().regex(/^[0-9a-f]{32}$/), deviceGeneration: bounded, controllerId: bounded,
+    status: z.enum(['acquired', 'committed', 'released', 'cancelled', 'busy', 'conflict', 'unsupported', 'lost', 'snapshot']),
+    snapshot: deviceOwnershipSnapshotSchema, reservationCause: reservationCauseSchema.optional(),
+}).refine(value => value.reservationCause == null || value.status === 'lost');
+export const matchesDeviceGrant = (left, right) => left.deviceEpoch === right.deviceEpoch && left.revision === right.revision && left.registrationId === right.registrationId &&
+    left.controllerId === right.controllerId && left.authorization === right.authorization;
+export function nativeReceiptMatches(handle, commandId, grant, action, receipt) {
+    return (action === 'isolate' || handle.current()) && receipt.commandId === commandId && receipt.hostLifetimeId === handle.hostLifetimeId &&
+        receipt.action === action && receipt.physical === 'completed' && receipt.admission === (action === 'admit' ? 'active' : 'revoked') &&
+        matchesDeviceGrant(grant, receipt.grant);
+}