@addai/node 0.12.0 → 0.14.0

package/dist/capabilities.d.ts

@@ -1,3 +1,4 @@
+import type { EngineInfo } from './desktop/provider';
 import { type AutostartState } from './autostart';
 import { type AutoUpdateState } from './auto-update';
 import { type MachineSample } from './machine-metrics';
@@ -44,6 +45,10 @@ interface CapabilitiesShape {
      *  rather than a column of its own — same channel Studio already reads the
      *  harness grid from. */
     autostart?: AutostartState;
+    /** Container engine backing Entity Desktops, or null when none is
+     *  installed. Studio renders an install card in place of the create
+     *  button when this is null. */
+    container_engine?: EngineInfo | null;
     /** CPU / memory / disk / runs at the moment of this probe. The AiNode page
      *  has read this key since it was written; nothing produced it until now. */
     machine?: MachineSample;

package/dist/capabilities.js

@@ -41,6 +41,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.codexHome = codexHome;
 exports.codexAuthFromStore = codexAuthFromStore;
 exports.probeCapabilities = probeCapabilities;
+const engine_1 = require("./desktop/engine");
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -377,13 +378,14 @@ async function probeCapabilities() {
     // heartbeat — that would report the runtime permanently offline.
     const shield = (p, fallback) => p.catch(() => fallback);
     const unavailable = { available: false, authed: false };
-    const [claude, codex, kimi, gemini, grok, git] = await Promise.all([
+    const [claude, codex, kimi, gemini, grok, git, containerEngine] = await Promise.all([
         shield(probeClaude(), unavailable),
         shield(probeCodex(), unavailable),
         shield(probeKimi(), unavailable),
         shield(probeGemini(), unavailable),
         shield(probeGrok(), unavailable),
         shield(probeGit(), unavailable),
+        shield((0, engine_1.detectEngine)(), null),
     ]);
     // Decorate each harness with its registry facts (efforts, installability,
     // login strategy) so Studio and the TUI render from one source of truth.
@@ -400,6 +402,7 @@ async function probeCapabilities() {
     return {
         daemon_version: readDaemonVersion(),
         autostart: (0, autostart_1.status)(),
+        container_engine: containerEngine,
         auto_update: (0, auto_update_1.autoUpdateState)(),
         machine: (0, machine_metrics_1.sampleMachine)(),
         claude: deco('claude', claude),

package/dist/command-runner.js

@@ -45,6 +45,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setRestartHook = setRestartHook;
 exports.wake = wake;
 const child_process_1 = require("child_process");
+const crypto = __importStar(require("crypto"));
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -59,6 +60,9 @@ const self_update_1 = require("./self-update");
 const autostart_1 = require("./autostart");
 const paths_1 = require("./paths");
 const pty_helper_1 = require("./pty-helper");
+const docker_1 = require("./desktop/docker");
+const manager_1 = require("./desktop/manager");
+const creds_1 = require("./desktop/creds");
 const COMMAND_TIMEOUT_MS = 10 * 60 * 1000;
 /** Own version, read the same way index.ts does. Resolved here rather than
  *  imported from index.ts, which already imports this module. */
@@ -557,6 +561,118 @@ async function runSetAutostart(cmd) {
     }
     await update(cmd.id, 'completed', { autostart: state });
 }
+/* ── desktops ────────────────────────────────────────────────────────────
+ * All six desktop_* kinds. Progress streams into the command payload the
+ * same way install_harness does, so Studio's existing live-log panel renders
+ * the image pull with no new component. */
+const DESKTOP_KINDS = [
+    'desktop_create', 'desktop_start', 'desktop_stop',
+    'desktop_delete', 'desktop_rebuild', 'desktop_sync_logins',
+];
+/** Setup scripts run as a FILE, never as a `sh -c` string: a script with
+ *  quotes or newlines must not need escaping to survive. */
+async function runSetupScript(provider, row, onLog) {
+    const { confDir } = (0, manager_1.ensureDirs)(row.id);
+    fs.writeFileSync(path.join(confDir, 'setup.sh'), row.setup_script ?? '', { mode: 0o700 });
+    await (0, creds_1.execInDesktop)(provider, row, ['bash', '/conf/setup.sh'], onLog);
+}
+async function runDesktopCommand(cmd) {
+    if (!cmd.desktop_id) {
+        await update(cmd.id, 'failed', undefined, 'no desktop on command');
+        return;
+    }
+    // force: a user who just installed Docker should not have to restart the
+    // daemon for their first desktop to build.
+    const provider = await (0, docker_1.getProvider)(true);
+    if (!provider) {
+        const why = 'No container engine on this machine. Install Docker Desktop or Podman, then try again.';
+        await update(cmd.id, 'failed', undefined, why);
+        await (0, manager_1.setStatus)(cmd.desktop_id, { status: 'failed', status_message: why });
+        return;
+    }
+    const rows = await (0, manager_1.listDesktops)();
+    const row = rows.find(r => r.id === cmd.desktop_id);
+    if (!row) {
+        await update(cmd.id, 'failed', undefined, 'desktop row not found');
+        return;
+    }
+    let log = '';
+    const onLog = (chunk) => {
+        log = (log + chunk).slice(-LOG_TAIL_CHARS);
+        void update(cmd.id, null, { log });
+    };
+    try {
+        await update(cmd.id, 'running', { log });
+        switch (cmd.kind) {
+            case 'desktop_create':
+            case 'desktop_rebuild': {
+                if (cmd.kind === 'desktop_rebuild') {
+                    onLog('removing existing container\n');
+                    await provider.remove(row);
+                }
+                await (0, manager_1.setStatus)(row.id, { status: 'creating', status_message: null });
+                const { confDir, workDir } = (0, manager_1.ensureDirs)(row.id);
+                const vncPort = await (0, manager_1.allocateVncPort)();
+                // A fresh password on every build; it only ever travels between the
+                // daemon and the container on the same machine.
+                const vncPassword = crypto.randomBytes(12).toString('base64url');
+                const built = { ...row, vnc_password: vncPassword };
+                const containerId = await provider.create(built, { confDir, workDir, vncPort }, onLog);
+                await (0, manager_1.setStatus)(row.id, {
+                    status: 'running', container_id: containerId,
+                    engine: provider.id, vnc_port: vncPort, status_message: null,
+                    // Record the password we actually gave the container, or the viewer
+                    // will keep presenting the previous one.
+                    vnc_password: vncPassword,
+                });
+                await (0, creds_1.syncCredentials)(provider, built, onLog);
+                if (row.setup_script) {
+                    onLog('running setup script\n');
+                    try {
+                        await runSetupScript(provider, built, onLog);
+                    }
+                    catch (err) {
+                        // The desktop exists and works; the script did not. Record it and
+                        // do not destroy the box the user just waited minutes for.
+                        await (0, manager_1.setStatus)(row.id, {
+                            status_message: `Setup script failed: ${err.message}`.slice(0, 400),
+                        });
+                    }
+                }
+                break;
+            }
+            case 'desktop_start':
+                await (0, manager_1.setStatus)(row.id, { status: 'starting' });
+                await provider.start(row);
+                await (0, manager_1.setStatus)(row.id, { status: 'running', status_message: null });
+                break;
+            case 'desktop_stop':
+                await provider.stop(row);
+                await (0, manager_1.setStatus)(row.id, { status: 'stopped', status_message: null });
+                break;
+            case 'desktop_delete': {
+                await provider.remove(row);
+                // The server keeps the row until the machine confirms, so a delete
+                // issued to an offline node is not lost.
+                const t = token();
+                if (t)
+                    await (0, supabase_client_1.rpc)('runtime_desktop_deleted', { p_token: t, p_desktop_id: row.id });
+                break;
+            }
+            case 'desktop_sync_logins':
+                await (0, creds_1.syncCredentials)(provider, row, onLog);
+                break;
+        }
+        await update(cmd.id, 'completed', { log });
+    }
+    catch (err) {
+        const message = err.message.slice(0, 500);
+        await update(cmd.id, 'failed', { log }, message);
+        if (cmd.kind !== 'desktop_delete') {
+            await (0, manager_1.setStatus)(row.id, { status: 'failed', status_message: message });
+        }
+    }
+}
 /* ── dispatcher ──────────────────────────────────────────────────────── */
 async function execute(cmd) {
     // Not a harness command — dispatch before the harness lookup, which would
@@ -569,6 +685,10 @@ async function execute(cmd) {
         await runSetAutostart(cmd);
         return;
     }
+    if (DESKTOP_KINDS.includes(cmd.kind)) {
+        await runDesktopCommand(cmd);
+        return;
+    }
     const spec = (0, harness_registry_1.harness)(cmd.harness ?? '');
     if (!spec) {
         await update(cmd.id, 'failed', {}, `unknown harness: ${cmd.harness}`);

package/dist/desktop/creds.d.ts

@@ -0,0 +1,7 @@
+import { DesktopRow } from './spec';
+import { DesktopProvider } from './provider';
+/** Keep the auth fields, drop host MCP servers and project history. */
+export declare function stripMcpServers(raw: string): string;
+/** Run a command inside a desktop, streaming output to onLog. */
+export declare function execInDesktop(provider: DesktopProvider, row: DesktopRow, cmd: string[], onLog: (c: string) => void): Promise<void>;
+export declare function syncCredentials(provider: DesktopProvider, row: DesktopRow, onLog: (c: string) => void): Promise<void>;

package/dist/desktop/creds.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripMcpServers = stripMcpServers;
+exports.execInDesktop = execInDesktop;
+exports.syncCredentials = syncCredentials;
+// Harness logins are COPIED into a desktop, never bind-mounted.
+//
+// Bind-mounting ~/.claude would hand the box write access to every transcript
+// on this machine - which defeats the isolation the desktop exists for. The
+// entity already effectively holds these tokens, so copying the auth blob
+// costs nothing; the host's project history and MCP servers are what must not
+// travel, so they are stripped here.
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const win_1 = require("../win");
+const provider_1 = require("./provider");
+/** Keep the auth fields, drop host MCP servers and project history. */
+function stripMcpServers(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object')
+            throw new Error('not an object');
+    }
+    catch {
+        return '{"mcpServers":{}}';
+    }
+    delete parsed.projects;
+    parsed.mcpServers = {};
+    return JSON.stringify(parsed);
+}
+/** Run a command inside a desktop, streaming output to onLog. */
+function execInDesktop(provider, row, cmd, onLog) {
+    const args = (0, provider_1.buildExecArgs)(row, cmd, { cwd: '/work', env: {}, tty: false });
+    const inv = (0, win_1.resolveCliInvocation)(provider.id, args);
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(inv.file, inv.args, {
+            env: process.env, windowsHide: true, timeout: 10 * 60_000,
+        });
+        let err = '';
+        child.stdout?.on('data', b => onLog(b.toString('utf8')));
+        child.stderr?.on('data', b => { const s = b.toString('utf8'); err += s; onLog(s); });
+        child.on('error', reject);
+        child.on('exit', code => code === 0
+            ? resolve()
+            : reject(new Error(err.trim().slice(0, 400) || `exit ${code}`)));
+    });
+}
+/** Write a file into the container through stdin, so contents with quotes,
+ *  newlines or ESC bytes survive verbatim - nothing is ever interpolated
+ *  into a shell string. */
+function writeInto(provider, row, dest, contents) {
+    const args = (0, provider_1.buildExecArgs)(row, ['sh', '-c', 'mkdir -p "$(dirname "$1")" && cat > "$1"', '_', dest], { cwd: '/work', env: {}, tty: false });
+    const inv = (0, win_1.resolveCliInvocation)(provider.id, args);
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(inv.file, inv.args, { env: process.env, windowsHide: true });
+        child.on('error', reject);
+        child.on('exit', code => code === 0
+            ? resolve()
+            : reject(new Error(`write ${dest} failed (exit ${code})`)));
+        child.stdin?.end(contents);
+    });
+}
+function credFiles() {
+    const home = os.homedir();
+    return [
+        {
+            hostPath: path.join(home, '.claude.json'),
+            destPath: '/home/entity/.claude.json',
+            transform: stripMcpServers,
+        },
+        { hostPath: path.join(home, '.claude', '.credentials.json'),
+            destPath: '/home/entity/.claude/.credentials.json' },
+        { hostPath: path.join(home, '.codex', 'auth.json'),
+            destPath: '/home/entity/.codex/auth.json' },
+        { hostPath: path.join(home, '.gemini', 'oauth_creds.json'),
+            destPath: '/home/entity/.gemini/oauth_creds.json' },
+    ];
+}
+async function syncCredentials(provider, row, onLog) {
+    for (const f of credFiles()) {
+        let raw;
+        try {
+            raw = fs.readFileSync(f.hostPath, 'utf8');
+        }
+        catch {
+            continue;
+        } // not logged in here: nothing to copy
+        const body = f.transform ? f.transform(raw) : raw;
+        try {
+            await writeInto(provider, row, f.destPath, body);
+            onLog(`copied ${path.basename(f.destPath)}\n`);
+        }
+        catch (err) {
+            // One missing login must not abort the others.
+            onLog(`could not copy ${path.basename(f.destPath)}: ${err.message}\n`);
+        }
+    }
+}

package/dist/desktop/docker.d.ts

@@ -0,0 +1,19 @@
+import { DesktopRow } from './spec';
+import { DesktopProvider, EngineInfo, CreateOpts } from './provider';
+export declare class CliProvider implements DesktopProvider {
+    readonly id: 'docker' | 'podman';
+    private version;
+    constructor(id: 'docker' | 'podman', version: string);
+    private run;
+    probe(): Promise<EngineInfo | null>;
+    create(row: DesktopRow, opts: CreateOpts, onLog: (c: string) => void): Promise<string>;
+    start(row: DesktopRow): Promise<void>;
+    stop(row: DesktopRow): Promise<void>;
+    remove(row: DesktopRow): Promise<void>;
+    inspect(row: DesktopRow): Promise<{
+        running: boolean;
+        containerId: string;
+    } | null>;
+}
+export declare function getProvider(force?: boolean): Promise<DesktopProvider | null>;
+export declare function resetProviderCache(): void;

package/dist/desktop/docker.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliProvider = void 0;
+exports.getProvider = getProvider;
+exports.resetProviderCache = resetProviderCache;
+// Docker/Podman backend. One class serves both: the CLI surface we use
+// (run/start/stop/rm/inspect/exec) is compatible between them.
+const child_process_1 = require("child_process");
+const win_1 = require("../win");
+const provider_1 = require("./provider");
+const engine_1 = require("./engine");
+class CliProvider {
+    id;
+    version;
+    constructor(id, version) {
+        this.id = id;
+        this.version = version;
+    }
+    run(args, onLog, timeoutMs = 15 * 60_000) {
+        return new Promise(resolve => {
+            let stdout = '', stderr = '';
+            try {
+                const inv = (0, win_1.resolveCliInvocation)(this.id, args);
+                const child = (0, child_process_1.spawn)(inv.file, inv.args, {
+                    env: process.env, windowsHide: true, timeout: timeoutMs,
+                });
+                child.stdout?.on('data', b => { const s = b.toString('utf8'); stdout += s; onLog?.(s); });
+                child.stderr?.on('data', b => { const s = b.toString('utf8'); stderr += s; onLog?.(s); });
+                child.on('error', err => resolve({ ok: false, stdout, stderr: String(err) }));
+                child.on('exit', code => resolve({ ok: code === 0, stdout, stderr }));
+            }
+            catch (err) {
+                resolve({ ok: false, stdout, stderr: err.message });
+            }
+        });
+    }
+    async probe() {
+        return { id: this.id, version: this.version };
+    }
+    async create(row, opts, onLog) {
+        // Pull first so the slow, chatty image download streams into the command
+        // payload as its own phase rather than hiding inside `run`.
+        onLog(`pulling ${row.image}\n`);
+        const pull = await this.run(['pull', row.image], onLog);
+        if (!pull.ok) {
+            // A pull failure is only fatal if we have no copy. A locally built or
+            // side-loaded image has no registry to pull FROM, and a node that is
+            // briefly offline should still be able to start a desktop it already
+            // has. Only give up when neither the registry nor the disk has it.
+            const local = await this.run(['image', 'inspect', row.image], undefined, 30_000);
+            if (!local.ok)
+                throw new Error(`image pull failed: ${pull.stderr.trim().slice(0, 500)}`);
+            onLog(`pull failed; using the copy already on this machine\n`);
+        }
+        onLog(`creating ${(0, provider_1.containerName)(row)}\n`);
+        const res = await this.run((0, provider_1.buildCreateArgs)(row, opts), onLog);
+        if (!res.ok)
+            throw new Error(`create failed: ${res.stderr.trim().slice(0, 500)}`);
+        return res.stdout.trim().split('\n').pop() || '';
+    }
+    async start(row) {
+        const res = await this.run(['start', (0, provider_1.containerName)(row)], undefined, 60_000);
+        if (!res.ok)
+            throw new Error(`start failed: ${res.stderr.trim().slice(0, 300)}`);
+    }
+    async stop(row) {
+        const res = await this.run(['stop', '-t', '10', (0, provider_1.containerName)(row)], undefined, 60_000);
+        if (!res.ok)
+            throw new Error(`stop failed: ${res.stderr.trim().slice(0, 300)}`);
+    }
+    async remove(row) {
+        // -f so a running desktop deletes without a separate stop; -v drops its
+        // anonymous volumes, otherwise deleting leaks disk forever.
+        const res = await this.run(['rm', '-f', '-v', (0, provider_1.containerName)(row)], undefined, 120_000);
+        // "No such container" IS success for a delete.
+        if (!res.ok && !/no such container/i.test(res.stderr)) {
+            throw new Error(`remove failed: ${res.stderr.trim().slice(0, 300)}`);
+        }
+    }
+    async inspect(row) {
+        const res = await this.run(['inspect', '-f', '{{.Id}} {{.State.Running}}', (0, provider_1.containerName)(row)], undefined, 30_000);
+        if (!res.ok)
+            return null;
+        const [id, running] = res.stdout.trim().split(/\s+/);
+        if (!id)
+            return null;
+        return { running: running === 'true', containerId: id };
+    }
+}
+exports.CliProvider = CliProvider;
+let cached;
+async function getProvider(force = false) {
+    if (!force && cached !== undefined)
+        return cached;
+    const info = await (0, engine_1.detectEngine)();
+    cached = info ? new CliProvider(info.id, info.version) : null;
+    return cached;
+}
+function resetProviderCache() { cached = undefined; }

package/dist/desktop/engine.d.ts

@@ -0,0 +1,3 @@
+import { EngineInfo } from './provider';
+export declare function parseEngineVersion(stdout: string): string | null;
+export declare function detectEngine(): Promise<EngineInfo | null>;

package/dist/desktop/engine.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEngineVersion = parseEngineVersion;
+exports.detectEngine = detectEngine;
+// Which container engine is on this machine? Docker first (the verified
+// path), Podman second. Never installs anything: installing Docker Desktop
+// needs admin rights and, on Windows, a reboot for the WSL2 kernel, so the
+// daemon reports the absence and Studio shows guidance instead.
+const child_process_1 = require("child_process");
+const win_1 = require("../win");
+function parseEngineVersion(stdout) {
+    const m = /version\s+v?(\d+\.\d+\.\d+)/i.exec(stdout);
+    return m ? m[1] : null;
+}
+function runVersion(binary) {
+    return new Promise(resolve => {
+        try {
+            const inv = (0, win_1.resolveCliInvocation)(binary, ['--version']);
+            const child = (0, child_process_1.spawn)(inv.file, inv.args, {
+                env: process.env, windowsHide: true, timeout: 8_000,
+            });
+            let out = '';
+            child.stdout?.on('data', b => { out += b.toString('utf8'); });
+            child.on('error', () => resolve(null));
+            child.on('exit', code => resolve(code === 0 ? out : null));
+        }
+        catch {
+            // resolveCliInvocation throws when a Windows shim can't be resolved -
+            // that is "not installed" as far as this probe is concerned.
+            resolve(null);
+        }
+    });
+}
+async function detectEngine() {
+    for (const id of ['docker', 'podman']) {
+        const out = await runVersion(id);
+        if (!out)
+            continue;
+        const version = parseEngineVersion(out);
+        if (version)
+            return { id, version };
+    }
+    return null;
+}

package/dist/desktop/launcher.d.ts

@@ -0,0 +1,30 @@
+import { DesktopRow } from './spec';
+export interface Assignment {
+    desktop_id: string;
+    runtime_id: string;
+    is_default: boolean;
+}
+export interface Invocation {
+    file: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+}
+/** Resolution order from the spec: the chat/schedule picker, then the
+ *  entity's default on THIS node, then any assignment on this node, then the
+ *  host. Returns the desktop id, or null for "run on the host".
+ *
+ *  A desktop on another node is deliberately ignored rather than treated as
+ *  an error: a run that failed over to a second machine must still run. */
+export declare function resolveDesktopForRun(req: {
+    desktop_id: string | null;
+    runtime_id: string;
+}, assignments: Assignment[], desktops: {
+    id: string;
+    runtime_id: string;
+}[]): string | null;
+/** Turn a host invocation into a container one. */
+export declare function wrapInvocation(engine: 'docker' | 'podman', row: Pick<DesktopRow, 'id' | 'name'>, inv: Invocation, tty?: boolean): {
+    file: string;
+    args: string[];
+};

package/dist/desktop/launcher.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDesktopForRun = resolveDesktopForRun;
+exports.wrapInvocation = wrapInvocation;
+// Decides whether a run happens on the host or inside a desktop, and wraps
+// the spawn when it is the latter. Everything about HOW a session runs is
+// unchanged - only the argv it is launched with.
+const spec_1 = require("./spec");
+const provider_1 = require("./provider");
+/** Resolution order from the spec: the chat/schedule picker, then the
+ *  entity's default on THIS node, then any assignment on this node, then the
+ *  host. Returns the desktop id, or null for "run on the host".
+ *
+ *  A desktop on another node is deliberately ignored rather than treated as
+ *  an error: a run that failed over to a second machine must still run. */
+function resolveDesktopForRun(req, assignments, desktops) {
+    const onThisNode = (id) => desktops.some(d => d.id === id && d.runtime_id === req.runtime_id);
+    if (req.desktop_id && onThisNode(req.desktop_id))
+        return req.desktop_id;
+    const here = assignments.filter(a => a.runtime_id === req.runtime_id
+        && onThisNode(a.desktop_id));
+    const preferred = here.find(a => a.is_default) ?? here[0];
+    return preferred ? preferred.desktop_id : null;
+}
+/** Turn a host invocation into a container one. */
+function wrapInvocation(engine, row, inv, tty = false) {
+    // A cwd that isn't a posix absolute path is a HOST path (a Windows drive
+    // path, or a relative one) and means nothing inside the container. Falling
+    // back to the workspace root beats handing docker a path it will reject.
+    const cwd = inv.cwd.startsWith('/') ? inv.cwd : spec_1.WORK_ROOT;
+    const args = (0, provider_1.buildExecArgs)(row, [inv.file, ...inv.args], {
+        cwd, env: inv.env, tty,
+    });
+    return { file: engine, args };
+}

package/dist/desktop/manager.d.ts

@@ -0,0 +1,32 @@
+import { DesktopRow } from './spec';
+export type Action = 'none' | 'start' | 'mark_failed' | 'mark_stopped' | 'mark_running';
+/** Pure: given what the row claims and what the engine reports, what now?
+ *  `actual` is null when no such container exists. */
+export declare function reconcileAction(row: Pick<DesktopRow, 'status' | 'autostart'>, actual: {
+    running: boolean;
+} | null): Action;
+export declare function listDesktops(): Promise<DesktopRow[]>;
+export declare function setStatus(id: string, fields: {
+    status?: DesktopRow['status'];
+    status_message?: string | null;
+    container_id?: string | null;
+    engine?: string | null;
+    vnc_port?: number | null;
+    /** Written only on create/rebuild, when the daemon mints a fresh one. The
+     *  viewer authenticates with whatever is recorded here, so a password used
+     *  but not recorded means "password check failed" at the RFB handshake. */
+    vnc_password?: string | null;
+}): Promise<void>;
+/** A free loopback port for this desktop's VNC. Asking the OS for port 0 and
+ *  reading back what it bound is the only race-free way to pick one. */
+export declare function allocateVncPort(): Promise<number>;
+export declare function ensureDirs(desktopId: string): {
+    confDir: string;
+    workDir: string;
+};
+export declare function startDesktopManager(): void;
+export declare function stopDesktopManager(): void;
+/** Bring a desktop up and wait for it, for the run path. Returns the row when
+ *  running, null when it could not be started - the caller then falls back to
+ *  the host rather than failing the run. */
+export declare function ensureRunning(desktopId: string, timeoutMs?: number): Promise<DesktopRow | null>;

package/dist/desktop/manager.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileAction = reconcileAction;
+exports.listDesktops = listDesktops;
+exports.setStatus = setStatus;
+exports.allocateVncPort = allocateVncPort;
+exports.ensureDirs = ensureDirs;
+exports.startDesktopManager = startDesktopManager;
+exports.stopDesktopManager = stopDesktopManager;
+exports.ensureRunning = ensureRunning;
+// Keeps the desktops the server believes in and the containers that actually
+// exist in agreement. Modelled on projects.ts: a slow poll, no realtime, and
+// every transition reported back so a Studio row reflects the machine.
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const supabase_client_1 = require("../supabase-client");
+const store_1 = require("../store");
+const spec_1 = require("./spec");
+const docker_1 = require("./docker");
+// Desktops are not latency-sensitive: a container that died is a rare event
+// and 15s to notice it is fine. Slower interval = less pooler pressure.
+const POLL_INTERVAL_MS = 15_000;
+/** Pure: given what the row claims and what the engine reports, what now?
+ *  `actual` is null when no such container exists. */
+function reconcileAction(row, actual) {
+    // In-flight and terminal states belong to the command runner, not here -
+    // reconciling mid-create would fight the thing doing the creating.
+    if (row.status === 'creating' || row.status === 'starting'
+        || row.status === 'deleting' || row.status === 'pending'
+        || row.status === 'failed')
+        return 'none';
+    if (actual === null) {
+        // The row says this exists and it does not. Someone pruned it by hand.
+        return row.status === 'running' || row.status === 'stopped' ? 'mark_failed' : 'none';
+    }
+    if (row.status === 'running' && !actual.running) {
+        return row.autostart ? 'start' : 'mark_stopped';
+    }
+    if (row.status === 'stopped' && actual.running)
+        return 'mark_running';
+    return 'none';
+}
+function token() { return (0, store_1.readPairing)()?.daemonToken ?? null; }
+async function listDesktops() {
+    const t = token();
+    if (!t)
+        return [];
+    return (await (0, supabase_client_1.rpc)('runtime_desktops_list', { p_token: t })) ?? [];
+}
+async function setStatus(id, fields) {
+    const t = token();
+    if (!t)
+        return;
+    try {
+        await (0, supabase_client_1.rpc)('runtime_desktop_status_update', {
+            p_token: t, p_desktop_id: id,
+            p_status: fields.status ?? null,
+            p_status_message: fields.status_message ?? null,
+            p_container_id: fields.container_id ?? null,
+            p_engine: fields.engine ?? null,
+            p_vnc_port: fields.vnc_port ?? null,
+            p_vnc_password: fields.vnc_password ?? null,
+        });
+    }
+    catch (err) {
+        console.error('[desktops] status update failed:', err.message);
+    }
+}
+/** A free loopback port for this desktop's VNC. Asking the OS for port 0 and
+ *  reading back what it bound is the only race-free way to pick one. */
+function allocateVncPort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const port = srv.address().port;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+function ensureDirs(desktopId) {
+    const confDir = (0, spec_1.confDirFor)(desktopId);
+    const workDir = (0, spec_1.workDirFor)(desktopId);
+    fs.mkdirSync(confDir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(workDir, { recursive: true, mode: 0o700 });
+    return { confDir, workDir };
+}
+let timer = null;
+let inflight = false;
+async function tick() {
+    if (inflight)
+        return;
+    inflight = true;
+    try {
+        const provider = await (0, docker_1.getProvider)();
+        if (!provider)
+            return; // no engine: nothing to reconcile
+        const rows = await listDesktops();
+        for (const row of rows) {
+            const actual = await provider.inspect(row);
+            const action = reconcileAction(row, actual);
+            if (action === 'none')
+                continue;
+            try {
+                if (action === 'start') {
+                    await provider.start(row);
+                    await setStatus(row.id, { status: 'running', status_message: null });
+                }
+                else if (action === 'mark_failed') {
+                    await setStatus(row.id, {
+                        status: 'failed',
+                        status_message: 'Container no longer exists on this machine. Rebuild to recreate it.',
+                    });
+                }
+                else if (action === 'mark_stopped') {
+                    await setStatus(row.id, { status: 'stopped' });
+                }
+                else if (action === 'mark_running') {
+                    await setStatus(row.id, {
+                        status: 'running', container_id: actual?.containerId ?? null, status_message: null,
+                    });
+                }
+            }
+            catch (err) {
+                await setStatus(row.id, {
+                    status: 'failed', status_message: err.message.slice(0, 400),
+                });
+            }
+        }
+    }
+    catch (err) {
+        console.error('[desktops] reconcile failed:', err.message);
+    }
+    finally {
+        inflight = false;
+    }
+}
+function startDesktopManager() {
+    if (timer)
+        return;
+    void tick();
+    timer = setInterval(() => { void tick(); }, POLL_INTERVAL_MS);
+}
+function stopDesktopManager() {
+    if (timer) {
+        clearInterval(timer);
+        timer = null;
+    }
+}
+/** Bring a desktop up and wait for it, for the run path. Returns the row when
+ *  running, null when it could not be started - the caller then falls back to
+ *  the host rather than failing the run. */
+async function ensureRunning(desktopId, timeoutMs = 60_000) {
+    const provider = await (0, docker_1.getProvider)();
+    if (!provider)
+        return null;
+    const rows = await listDesktops();
+    const row = rows.find(r => r.id === desktopId);
+    if (!row)
+        return null;
+    const actual = await provider.inspect(row);
+    if (actual?.running)
+        return row;
+    if (!actual)
+        return null; // never created / pruned: cannot start
+    const deadline = Date.now() + timeoutMs;
+    try {
+        await provider.start(row);
+    }
+    catch {
+        return null;
+    }
+    while (Date.now() < deadline) {
+        const now = await provider.inspect(row);
+        if (now?.running) {
+            await setStatus(row.id, { status: 'running', status_message: null });
+            return row;
+        }
+        await new Promise(r => setTimeout(r, 1_000));
+    }
+    return null;
+}

package/dist/desktop/provider.d.ts

@@ -0,0 +1,35 @@
+import { DesktopRow } from './spec';
+export interface EngineInfo {
+    id: 'docker' | 'podman';
+    version: string;
+}
+export interface ExecOpts {
+    cwd: string;
+    env: Record<string, string>;
+    /** PTY-driven harnesses need a tty allocated inside the container. */
+    tty: boolean;
+}
+export interface CreateOpts {
+    confDir: string;
+    workDir?: string;
+    vncPort: number;
+}
+export interface DesktopProvider {
+    readonly id: 'docker' | 'podman';
+    probe(): Promise<EngineInfo | null>;
+    create(row: DesktopRow, opts: CreateOpts, onLog: (chunk: string) => void): Promise<string>;
+    start(row: DesktopRow): Promise<void>;
+    stop(row: DesktopRow): Promise<void>;
+    remove(row: DesktopRow): Promise<void>;
+    /** null when the container does not exist. */
+    inspect(row: DesktopRow): Promise<{
+        running: boolean;
+        containerId: string;
+    } | null>;
+}
+/** Docker/Podman object names allow [a-zA-Z0-9][a-zA-Z0-9_.-]*. The id suffix
+ *  keeps a renamed desktop from colliding with a leftover container of the
+ *  same name. */
+export declare function containerName(row: Pick<DesktopRow, 'id' | 'name'>): string;
+export declare function buildCreateArgs(row: DesktopRow, opts: CreateOpts): string[];
+export declare function buildExecArgs(row: DesktopRow, cmd: string[], opts: ExecOpts): string[];

package/dist/desktop/provider.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.containerName = containerName;
+exports.buildCreateArgs = buildCreateArgs;
+exports.buildExecArgs = buildExecArgs;
+// The interface every desktop backend implements, plus the pure command
+// builders. Kept free of I/O so the argv construction - the part most likely
+// to be subtly wrong, and the part that behaves differently on Windows - is
+// unit-testable with no container engine installed.
+const spec_1 = require("./spec");
+/** Docker/Podman object names allow [a-zA-Z0-9][a-zA-Z0-9_.-]*. The id suffix
+ *  keeps a renamed desktop from colliding with a leftover container of the
+ *  same name. */
+function containerName(row) {
+    const slug = row.name.toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 32) || 'desktop';
+    return `ainode-desktop-${slug}-${row.id.slice(0, 8)}`;
+}
+function buildCreateArgs(row, opts) {
+    const args = [
+        'run', '-d',
+        '--name', containerName(row),
+        '--cpus', String(row.cpus),
+        '--memory', `${row.memory_mb}m`,
+        '--shm-size', '512m', // Chromium crashes on the 64m default
+        '--restart', 'unless-stopped',
+        // Loopback ONLY. Binding 0.0.0.0 would expose a logged-in desktop to the
+        // whole LAN; the relay reaches it from the daemon on the same host.
+        '-p', `127.0.0.1:${opts.vncPort}:${spec_1.VNC_PORT_IN_CONTAINER}`,
+        '-v', `${opts.confDir}:${spec_1.CONF_ROOT}`,
+    ];
+    if (opts.workDir)
+        args.push('-v', `${opts.workDir}:${spec_1.WORK_ROOT}`);
+    if (row.vnc_password)
+        args.push('-e', `VNC_PASSWORD=${row.vnc_password}`);
+    args.push(row.image);
+    return args;
+}
+function buildExecArgs(row, cmd, opts) {
+    const args = ['exec', '-i'];
+    if (opts.tty)
+        args.push('-t');
+    args.push('-w', opts.cwd);
+    for (const [k, v] of Object.entries(opts.env))
+        args.push('-e', `${k}=${v}`);
+    args.push(containerName(row));
+    // cmd goes in as separate argv entries - never joined into a shell string.
+    // A prompt containing quotes, newlines or ESC bytes must survive verbatim.
+    args.push(...cmd);
+    return args;
+}

package/dist/desktop/relay-client.d.ts

@@ -0,0 +1,2 @@
+export declare function startRelayClient(): void;
+export declare function stopRelayClient(): void;

package/dist/desktop/relay-client.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startRelayClient = startRelayClient;
+exports.stopRelayClient = stopRelayClient;
+// Dial-out socket to the desktop relay.
+//
+// The daemon connects OUT whenever it has a running desktop, so there is no
+// inbound port and no NAT problem - and because the socket is already open,
+// attaching a viewer is instant rather than waiting on the 30s heartbeat.
+//
+// It carries RAW RFB bytes. The container serves RFB directly (no websockify),
+// so noVNC in the browser speaks RFB across this pipe unchanged.
+const ws_1 = __importDefault(require("ws"));
+const net = __importStar(require("net"));
+const store_1 = require("../store");
+const manager_1 = require("./manager");
+// The deployed relay. Overridable so a node can be pointed at a local one.
+const RELAY_URL = process.env.AINODE_RELAY_URL
+    ?? 'wss://desktop-relay-29522465016.europe-west2.run.app';
+const RECONNECT_MIN_MS = 2_000;
+const RECONNECT_MAX_MS = 60_000;
+/** Re-check whether any desktop is running this often while idle. */
+const IDLE_CHECK_MS = 60_000;
+/** How often to prove the socket is still alive. A machine that suspends
+ *  leaves a half-open socket that never fires 'close', so without this the
+ *  client sits holding a dead handle and never reconnects. */
+const PING_INTERVAL_MS = 30_000;
+let ws = null;
+let stopped = true;
+let backoff = RECONNECT_MIN_MS;
+let idleTimer = null;
+let liveTimer = null;
+/** Set on every pong; cleared when a ping goes out. Two misses = dead. */
+let missedPongs = 0;
+/** desktopId -> the local TCP socket to that desktop's published RFB port. */
+const bridges = new Map();
+function dropBridges() {
+    for (const s of bridges.values()) {
+        try {
+            s.destroy();
+        }
+        catch { /* gone */ }
+    }
+    bridges.clear();
+}
+async function anyDesktopRunning() {
+    try {
+        return (await (0, manager_1.listDesktops)()).some(d => d.status === 'running');
+    }
+    catch {
+        return false;
+    }
+}
+function scheduleReconnect() {
+    if (stopped)
+        return;
+    setTimeout(() => { void connect(); }, backoff);
+    backoff = Math.min(backoff * 2, RECONNECT_MAX_MS);
+}
+async function connect() {
+    if (stopped || ws)
+        return;
+    const token = (0, store_1.readPairing)()?.daemonToken;
+    if (!token) {
+        scheduleReconnect();
+        return;
+    }
+    // No point holding a socket open for a machine with nothing to show.
+    if (!(await anyDesktopRunning())) {
+        idleTimer = setTimeout(() => { void connect(); }, IDLE_CHECK_MS);
+        return;
+    }
+    const sock = new ws_1.default(`${RELAY_URL}/node?token=${encodeURIComponent(token)}`);
+    ws = sock;
+    sock.on('open', () => {
+        backoff = RECONNECT_MIN_MS;
+        missedPongs = 0;
+        if (liveTimer)
+            clearInterval(liveTimer);
+        // A suspended Mac comes back with a socket that looks open and is not.
+        // Ping until two go unanswered, then tear it down so the normal backoff
+        // path reconnects - the daemon's own sleep detector reports the same
+        // suspends this is guarding against.
+        liveTimer = setInterval(() => {
+            if (sock.readyState !== ws_1.default.OPEN) {
+                sock.terminate();
+                return;
+            }
+            if (missedPongs >= 2) {
+                console.warn('[relay] no pong in 60s — assuming the link died, reconnecting');
+                sock.terminate();
+                return;
+            }
+            missedPongs += 1;
+            try {
+                sock.ping();
+            }
+            catch {
+                sock.terminate();
+            }
+        }, PING_INTERVAL_MS);
+    });
+    sock.on('pong', () => { missedPongs = 0; });
+    sock.on('message', async (raw) => {
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        if (msg.type === 'attach') {
+            const row = (await (0, manager_1.listDesktops)()).find(d => d.id === msg.desktopId);
+            if (!row?.vnc_port)
+                return;
+            // Loopback only - the container published its RFB on 127.0.0.1 and this
+            // process is the only thing on the machine that reaches it.
+            const tcp = net.connect(row.vnc_port, '127.0.0.1');
+            tcp.on('data', chunk => {
+                if (sock.readyState === ws_1.default.OPEN) {
+                    sock.send(JSON.stringify({
+                        type: 'data', desktopId: msg.desktopId, b64: chunk.toString('base64'),
+                    }));
+                }
+            });
+            const forget = () => { bridges.delete(msg.desktopId); };
+            tcp.on('close', forget);
+            tcp.on('error', forget);
+            bridges.get(msg.desktopId)?.destroy();
+            bridges.set(msg.desktopId, tcp);
+            return;
+        }
+        if (msg.type === 'data' && msg.b64) {
+            bridges.get(msg.desktopId)?.write(Buffer.from(msg.b64, 'base64'));
+            return;
+        }
+        if (msg.type === 'detach') {
+            bridges.get(msg.desktopId)?.destroy();
+            bridges.delete(msg.desktopId);
+        }
+    });
+    const retry = () => {
+        if (liveTimer) {
+            clearInterval(liveTimer);
+            liveTimer = null;
+        }
+        if (ws !== sock)
+            return; // superseded by a newer socket
+        dropBridges();
+        ws = null;
+        scheduleReconnect();
+    };
+    sock.on('close', retry);
+    sock.on('error', retry);
+}
+function startRelayClient() {
+    if (!stopped)
+        return;
+    stopped = false;
+    backoff = RECONNECT_MIN_MS;
+    void connect();
+}
+function stopRelayClient() {
+    stopped = true;
+    if (idleTimer) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+    }
+    if (liveTimer) {
+        clearInterval(liveTimer);
+        liveTimer = null;
+    }
+    dropBridges();
+    try {
+        ws?.close();
+    }
+    catch { /* already closing */ }
+    ws = null;
+}

package/dist/desktop/spec.d.ts

@@ -0,0 +1,37 @@
+export interface DesktopRow {
+    id: string;
+    runtime_id: string;
+    name: string;
+    image: string;
+    engine: 'docker' | 'podman' | null;
+    container_id: string | null;
+    cpus: number;
+    memory_mb: number;
+    disk_gb: number;
+    setup_script: string | null;
+    enabled_mcps: string[];
+    enabled_skills: string[];
+    enabled_packages: string[];
+    autostart: boolean;
+    status: 'pending' | 'creating' | 'starting' | 'running' | 'stopped' | 'failed' | 'deleting';
+    status_message: string | null;
+    vnc_port: number | null;
+    vnc_password: string | null;
+}
+/** Workspace root inside the container. Projects clone to /work/<name>,
+ *  session cwds live at /work/.sessions/<requestId>. */
+export declare const WORK_ROOT = "/work";
+/** Where the daemon's generated files (MCP config, memory pack, attachments)
+ *  appear inside the container. Bind-mounted from the host. */
+export declare const CONF_ROOT = "/conf";
+/** The container's RAW RFB port, fixed by the image.
+ *
+ *  Raw, not websockified: the relay carries these bytes over its own
+ *  WebSocket and noVNC in the browser speaks RFB across it. Putting
+ *  websockify in the container too would mean a WebSocket handshake tunnelled
+ *  inside a WebSocket, which no client can read. */
+export declare const VNC_PORT_IN_CONTAINER = 5900;
+/** Host directory bind-mounted at CONF_ROOT for one desktop. */
+export declare function confDirFor(desktopId: string): string;
+/** Host directory holding the desktop's persistent /work volume. */
+export declare function workDirFor(desktopId: string): string;

package/dist/desktop/spec.js

@@ -0,0 +1,62 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VNC_PORT_IN_CONTAINER = exports.CONF_ROOT = exports.WORK_ROOT = void 0;
+exports.confDirFor = confDirFor;
+exports.workDirFor = workDirFor;
+// Shapes and paths shared by every desktop module. No I/O here.
+const path = __importStar(require("path"));
+const paths_1 = require("../paths");
+/** Workspace root inside the container. Projects clone to /work/<name>,
+ *  session cwds live at /work/.sessions/<requestId>. */
+exports.WORK_ROOT = '/work';
+/** Where the daemon's generated files (MCP config, memory pack, attachments)
+ *  appear inside the container. Bind-mounted from the host. */
+exports.CONF_ROOT = '/conf';
+/** The container's RAW RFB port, fixed by the image.
+ *
+ *  Raw, not websockified: the relay carries these bytes over its own
+ *  WebSocket and noVNC in the browser speaks RFB across it. Putting
+ *  websockify in the container too would mean a WebSocket handshake tunnelled
+ *  inside a WebSocket, which no client can read. */
+exports.VNC_PORT_IN_CONTAINER = 5900;
+/** Host directory bind-mounted at CONF_ROOT for one desktop. */
+function confDirFor(desktopId) {
+    return path.join(paths_1.RUNTIME_HOME, 'desktops', desktopId, 'conf');
+}
+/** Host directory holding the desktop's persistent /work volume. */
+function workDirFor(desktopId) {
+    return path.join(paths_1.RUNTIME_HOME, 'desktops', desktopId, 'work');
+}

package/dist/index.js

@@ -57,6 +57,8 @@ const sleep_detector_1 = require("./sleep-detector");
 const claude_config_1 = require("./claude-config");
 const request_pump_1 = require("./request-pump");
 const projects_1 = require("./projects");
+const manager_1 = require("./desktop/manager");
+const relay_client_1 = require("./desktop/relay-client");
 const session_runner_1 = require("./session-runner");
 const diskguard_1 = require("./diskguard");
 const pty_helper_1 = require("./pty-helper");
@@ -206,6 +208,10 @@ async function start(argv = []) {
     (0, request_pump_1.start)();
     // …and for pending projects (git clones, future MCP/skill installs).
     (0, projects_1.start)();
+    // …and to keep desktops and the containers behind them in agreement.
+    (0, manager_1.startDesktopManager)();
+    // …and dial out to the relay so a running desktop is watchable from Studio.
+    (0, relay_client_1.startRelayClient)();
     let stopped = false;
     // Outcome of the last drain, so a remote roll can report whether it left
     // work unfinished instead of claiming a clean restart either way.
@@ -217,6 +223,8 @@ async function start(argv = []) {
         // Stop accepting new work first — otherwise the pump would queue
         // another request between drain start and process exit.
         (0, projects_1.stop)();
+        (0, manager_1.stopDesktopManager)();
+        (0, relay_client_1.stopRelayClient)();
         (0, request_pump_1.stop)();
         (0, heartbeat_1.stop)();
         (0, auto_update_1.stop)();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@addai/node",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Daemon that pairs a machine with your +Ai account and runs Claude / Codex / Kimi / Gemini agents on its behalf. Reachable via Supabase from Vault, Entity Studio, or any other +Ai surface.",
   "license": "MIT",
   "keywords": [
@@ -50,7 +50,7 @@
   },
   "dependencies": {
     "node-pty": "^1.1.0",
-    "ws": "^8.21.1"
+    "ws": "^8.21.3"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",