robopark 2.8.36 → 3.0.0

package/dist/robopark/robot-runtime.js

@@ -0,0 +1,489 @@
+/**
+ * RoboPark robot runtime.
+ *
+ * One long-lived parent for a robot's mesh satellite, RoboVision camera/audio
+ * service, and preview agent. Starting these as unrelated detached commands
+ * allowed a healthy-looking mesh node with no motion service or no device
+ * inventory. The runtime starts dependencies in order and restarts a child if
+ * it exits unexpectedly.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, networkInterfaces } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { resolveInfinicodeBin } from './serve.js';
+import { findPython, findRobotSupervisorPath, prepareRobotPython } from './python-env.js';
+const VISION_URL = 'http://127.0.0.1:5000/api/media/inventory';
+const VISION_STATUS_URL = 'http://127.0.0.1:5000/api/camera/status';
+const MOTOR_SERVER_URL = 'http://127.0.0.1:8001';
+const RESTART_DELAY_MS = 5_000;
+const MEDIA_WATCHDOG_INTERVAL_MS = 10_000;
+const SCHEDULER_HEARTBEAT_INTERVAL_MS = 5_000;
+function currentLanIp() {
+    for (const addresses of Object.values(networkInterfaces())) {
+        for (const address of addresses ?? []) {
+            if (address.family === 'IPv4' && !address.internal)
+                return address.address;
+        }
+    }
+    return undefined;
+}
+function readSchedulerIdentity() {
+    const configDir = join(homedir(), '.robopark');
+    try {
+        const config = JSON.parse(readFileSync(join(configDir, 'preview_agent.json'), 'utf8'));
+        const deviceId = String(config.device_id ?? '').trim();
+        const fileToken = existsSync(join(configDir, 'device_token'))
+            ? readFileSync(join(configDir, 'device_token'), 'utf8').trim()
+            : '';
+        const deviceToken = fileToken || String(config.device_token ?? '').trim();
+        if (deviceId && deviceToken)
+            return { deviceId, deviceToken };
+    }
+    catch {
+        // First boot has no identity yet.
+    }
+    return undefined;
+}
+function persistSchedulerIdentity(identity, schedulerUrl) {
+    const configDir = join(homedir(), '.robopark');
+    const configPath = join(configDir, 'preview_agent.json');
+    mkdirSync(configDir, { recursive: true });
+    let config = {};
+    try {
+        config = JSON.parse(readFileSync(configPath, 'utf8'));
+    }
+    catch { /* first boot */ }
+    config.device_id = identity.deviceId;
+    config.device_token = identity.deviceToken;
+    config.scheduler_url = schedulerUrl;
+    writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+    writeFileSync(join(configDir, 'device_token'), identity.deviceToken, { encoding: 'utf8', mode: 0o600 });
+}
+function startSchedulerHeartbeat(opts, livekitUrl) {
+    let identity = readSchedulerIdentity();
+    let stopped = false;
+    let inFlight = false;
+    let motorDiscoveryQueued = false;
+    let lastMotorDiscoveryAttempt = 0;
+    const bootstrap = async () => {
+        const response = await fetch(`${opts.schedulerUrl.replace(/\/+$/, '')}/api/devices/bootstrap`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-robopark-mesh-token': opts.token,
+            },
+            body: JSON.stringify({
+                name: opts.name,
+                device_role: opts.deviceRole ?? 'combined',
+                character_id: opts.character,
+                lan_ip: currentLanIp(),
+                livekit_url: livekitUrl,
+                motor_server_url: opts.deviceRole === 'voice_vision' ? undefined : MOTOR_SERVER_URL,
+            }),
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new Error(`bootstrap HTTP ${response.status}`);
+        const data = await response.json();
+        const next = {
+            deviceId: String(data.device_id ?? '').trim(),
+            deviceToken: String(data.device_token ?? '').trim(),
+        };
+        if (!next.deviceId || !next.deviceToken)
+            throw new Error('bootstrap returned no device credentials');
+        persistSchedulerIdentity(next, opts.schedulerUrl);
+        return next;
+    };
+    const beat = async () => {
+        if (stopped || inFlight)
+            return;
+        inFlight = true;
+        try {
+            identity = readSchedulerIdentity() ?? identity;
+            if (!identity)
+                identity = await bootstrap();
+            let response = await fetch(`${opts.schedulerUrl.replace(/\/+$/, '')}/api/devices/${encodeURIComponent(identity.deviceId)}/heartbeat`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${identity.deviceToken}`,
+                    'content-type': 'application/json',
+                    'x-robopark-mesh-token': opts.token,
+                },
+                body: JSON.stringify({
+                    status: 'online', ip: currentLanIp(), livekit_url: livekitUrl,
+                    device_role: opts.deviceRole ?? 'combined',
+                    motor_server_url: opts.deviceRole === 'voice_vision' ? undefined : MOTOR_SERVER_URL,
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (response.status === 401 || response.status === 404) {
+                identity = await bootstrap();
+                response = await fetch(`${opts.schedulerUrl.replace(/\/+$/, '')}/api/devices/${encodeURIComponent(identity.deviceId)}/heartbeat`, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${identity.deviceToken}`,
+                        'content-type': 'application/json',
+                        'x-robopark-mesh-token': opts.token,
+                    },
+                    body: JSON.stringify({
+                        status: 'online', ip: currentLanIp(), livekit_url: livekitUrl,
+                        device_role: opts.deviceRole ?? 'combined',
+                        motor_server_url: opts.deviceRole === 'voice_vision' ? undefined : MOTOR_SERVER_URL,
+                    }),
+                    signal: AbortSignal.timeout(10_000),
+                });
+            }
+            if (!response.ok)
+                throw new Error(`heartbeat HTTP ${response.status}`);
+            if (opts.deviceRole !== 'voice_vision' && !motorDiscoveryQueued && Date.now() - lastMotorDiscoveryAttempt > 30_000) {
+                lastMotorDiscoveryAttempt = Date.now();
+                const discovery = await fetch(`${opts.schedulerUrl.replace(/\/+$/, '')}/api/robots/${encodeURIComponent(identity.deviceId)}/motors/discover`, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${identity.deviceToken}`,
+                        'x-robopark-mesh-token': opts.token,
+                    },
+                    signal: AbortSignal.timeout(10_000),
+                });
+                motorDiscoveryQueued = discovery.ok;
+                if (discovery.ok)
+                    console.log(chalk.green('  motor registry discovery queued'));
+            }
+        }
+        catch (error) {
+            console.error(chalk.yellow(`  scheduler heartbeat watchdog: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    void beat();
+    const timer = setInterval(() => { void beat(); }, SCHEDULER_HEARTBEAT_INTERVAL_MS);
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}
+function resetStaleEnrollment() {
+    const configDir = join(homedir(), '.robopark');
+    const tokenPath = join(configDir, 'device_token');
+    const configPath = join(configDir, 'preview_agent.json');
+    try {
+        if (existsSync(tokenPath))
+            rmSync(tokenPath);
+    }
+    catch { /* enrollment will report a real error */ }
+    if (!existsSync(configPath))
+        return;
+    try {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        delete config.device_id;
+        delete config.device_token;
+        writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+    }
+    catch {
+        // A malformed optional config must not block first boot.
+    }
+}
+function roboparkCliPath() {
+    // dist/robopark/robot-runtime.js -> package root -> dist/robopark-cli.js
+    const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+    const compiledCli = join(packageRoot, 'dist', 'robopark-cli.js');
+    return existsSync(compiledCli) ? compiledCli : process.argv[1];
+}
+function runtimeLog(label, foreground) {
+    if (foreground)
+        return 'inherit';
+    const logDir = join(homedir(), '.robopark', 'logs');
+    mkdirSync(logDir, { recursive: true });
+    return [
+        'ignore',
+        // spawn() accepts file descriptors, but not WriteStreams before their
+        // asynchronous open event. openSync makes detached startup reliable.
+        openSync(join(logDir, `${label}.log`), 'a'),
+        openSync(join(logDir, `${label}.err.log`), 'a'),
+    ];
+}
+async function waitForVision() {
+    const deadline = Date.now() + 120_000;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetch(VISION_URL, { signal: AbortSignal.timeout(1_500) });
+            if (response.ok)
+                return true;
+        }
+        catch {
+            // Dependency installation on a fresh Pi can take a little while.
+        }
+        await new Promise(resolve => setTimeout(resolve, 1_000));
+    }
+    return false;
+}
+export async function roboparkRobotRuntime(opts) {
+    const port = opts.port ?? '47913';
+    const network = opts.network ?? 'lan';
+    const foreground = opts.foreground === true;
+    const deviceRole = opts.deviceRole ?? 'combined';
+    const ownsVision = deviceRole !== 'motor' && opts.vision !== false;
+    const ownsPreview = deviceRole === 'combined';
+    const cli = roboparkCliPath();
+    const hub = new URL(opts.hubUrl);
+    const livekitUrl = `${hub.protocol === 'https:' ? 'wss:' : 'ws:'}//${hub.hostname}:7880`;
+    const children = [];
+    let stopping = false;
+    let recycling = false;
+    const requestedVideo = String(opts.videoDevice ?? '').trim();
+    const hardwareVideo = !requestedVideo || ['auto', 'default', 'first'].includes(requestedVideo.toLowerCase())
+        ? '/dev/video0'
+        : requestedVideo;
+    const infinicode = await resolveInfinicodeBin();
+    if (!infinicode)
+        throw new Error('could not resolve infinicode CLI');
+    const supervisorScript = await findRobotSupervisorPath();
+    if (!supervisorScript)
+        throw new Error('could not resolve RoboPark robot supervisor');
+    const supervisorPython = prepareRobotPython(findPython(), supervisorScript, ['httpx'], 'requirements-robot.txt');
+    if (!supervisorPython)
+        throw new Error('could not prepare RoboPark robot supervisor Python environment');
+    children.push({
+        label: 'mesh',
+        command: infinicode.node,
+        args: [infinicode.script, 'serve', '--role', 'satellite', '--name', opts.name,
+            '--port', port, '--token', opts.token, '--seed', opts.hubUrl,
+            network === 'tailscale' ? '--tailscale' : '--lan', '--auto-update', '--supervised'],
+    });
+    if (ownsVision) {
+        children.push({
+            label: 'vision',
+            command: process.execPath,
+            args: [cli, 'vision-agent', '--foreground', '--port', '5000',
+                '--motion-webhook-url', 'http://127.0.0.1:5057/'],
+            env: {
+                ROBOPARK_CAMERA_DEVICE: hardwareVideo,
+                ROBOPARK_MESH_TOKEN: opts.token,
+                ROBOPARK_MOTOR_TOKEN: opts.token,
+            },
+        });
+    }
+    children.push({
+        label: 'supervisor',
+        command: supervisorPython,
+        args: [supervisorScript, '--commands-only'],
+        env: { ROBOPARK_MESH_TOKEN: opts.token },
+    });
+    const previewArgs = [cli, 'preview-agent', '--foreground',
+        '--scheduler-url', opts.schedulerUrl, '--robot-id', opts.name,
+        '--video-device', hardwareVideo,
+        '--audio-device', opts.audioDevice ?? 'Usb Audio Device: USB Audio',
+        '--robovision-url', 'http://127.0.0.1:5000',
+        '--save-config'];
+    if (opts.enrollmentToken)
+        previewArgs.push('--enrollment-token', opts.enrollmentToken);
+    const preview = {
+        label: 'preview',
+        command: process.execPath,
+        args: previewArgs,
+        // Tailscale scheduler access goes through the authenticated hub proxy.
+        // Keep this in the child environment, never in the persisted robot config.
+        env: {
+            ROBOPARK_MESH_TOKEN: opts.token,
+            ROBOPARK_LIVEKIT_URL: livekitUrl,
+            // Keep internal service wiring out of the Commander argument boundary.
+            // This also lets preview start while RoboVision is still warming up.
+            ROBOVISION_URL: ownsVision ? 'http://127.0.0.1:5000' : '',
+            ROBOVISION_MEDIA_URL: ownsVision
+                ? 'http://127.0.0.1:5000/api/media/inventory'
+                : '',
+            ROBOVISION_CAMERA: ownsVision ? '1' : '0',
+            // Motion remains enabled, but it reads RoboVision's shared stream. Only
+            // RoboVision may open the physical V4L2 device.
+            LOCAL_CAMERA_MOTION: 'true',
+            // The first production sound is the greeting. A beep would occupy the
+            // same exclusive ALSA device and delay or clip TTS.
+            ROBOPARK_MOTION_CUE: 'false',
+            // Fleet hardware profile: resolve volatile ALSA hw:X,Y coordinates
+            // from these USB product labels on every inventory refresh.
+            ROBOPARK_AUDIO_INPUT_MATCH: 'Usb Audio Device: USB Audio',
+            ROBOPARK_AUDIO_OUTPUT_MATCH: 'USB Audio Device: -',
+            // Launch hardware has no acoustic echo cancellation. Suppress mic PCM
+            // only while audible robot speech is playing, then hold briefly for
+            // room echo decay so VAD cannot interrupt the robot with its own voice.
+            ROBOPARK_HALF_DUPLEX: 'true',
+            ROBOPARK_ECHO_TAIL_MS: '350',
+            ROBOPARK_ECHO_GATE_PEAK: '96',
+            // Keep ordinary speaker echo muted but reopen the microphone when a
+            // nearby voice rises decisively above the learned acoustic echo floor.
+            ROBOPARK_ADAPTIVE_BARGE_IN: 'true',
+            ROBOPARK_BARGE_IN_MIN_PEAK: '2200',
+            ROBOPARK_BARGE_IN_ECHO_RATIO: '2.4',
+            ROBOPARK_BARGE_IN_HOLD_MS: '1400',
+            // Inventory changes should reach the Control Center promptly.
+            HEARTBEAT_INTERVAL: '5',
+        },
+    };
+    const start = (entry) => {
+        const child = spawn(entry.command, entry.args, {
+            env: { ...process.env, ...entry.env, ROBOPARK_ROBOT_RUNTIME: '1' },
+            stdio: runtimeLog(`robot-${opts.name}-${entry.label}`, foreground),
+            // Give each launcher and its Python descendants one process group.
+            detached: process.platform !== 'win32',
+        });
+        entry.child = child;
+        child.on('error', error => console.error(chalk.red(`  ${entry.label} failed to start: ${error.message}`)));
+        child.on('exit', (code, signal) => {
+            entry.child = undefined;
+            if (stopping)
+                return;
+            // A clean mesh exit is how /update signals that npm replaced this
+            // package. Reload every child so the robot runs one coherent release.
+            if (entry.label === 'mesh' && code === 0) {
+                void recycleAfterMeshUpdate();
+                return;
+            }
+            if (recycling)
+                return;
+            console.error(chalk.yellow(`  ${entry.label} exited (${signal ?? code ?? 'unknown'}); restarting in 5s`));
+            setTimeout(() => { if (!stopping)
+                start(entry); }, RESTART_DELAY_MS);
+        });
+    };
+    const signalChild = (entry, signal) => {
+        const pid = entry.child?.pid;
+        if (!pid)
+            return;
+        try {
+            if (process.platform === 'win32')
+                entry.child?.kill(signal);
+            else
+                process.kill(-pid, signal);
+        }
+        catch {
+            // It may have exited between the liveness check and signal.
+        }
+    };
+    const stopChild = async (entry) => {
+        const child = entry.child;
+        if (!child)
+            return;
+        await new Promise(resolve => {
+            const timer = setTimeout(() => {
+                signalChild(entry, 'SIGKILL');
+                resolve();
+            }, 5_000);
+            child.once('exit', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            signalChild(entry, 'SIGTERM');
+        });
+    };
+    let visionFailureCount = 0;
+    let visionRecoveryInFlight = false;
+    const monitorVision = async () => {
+        if (stopping || recycling || visionRecoveryInFlight || !ownsVision)
+            return;
+        const vision = children.find(entry => entry.label === 'vision');
+        if (!vision?.child)
+            return;
+        let healthy = false;
+        try {
+            const response = await fetch(VISION_STATUS_URL, { signal: AbortSignal.timeout(2_000) });
+            if (response.ok) {
+                const status = await response.json();
+                const frameTooOld = status.worker_started === true
+                    && typeof status.last_frame_age_seconds === 'number'
+                    && status.last_frame_age_seconds > 15;
+                healthy = !status.read_stalled && !frameTooOld;
+            }
+        }
+        catch {
+            healthy = false;
+        }
+        visionFailureCount = healthy ? 0 : visionFailureCount + 1;
+        if (visionFailureCount < 3)
+            return;
+        visionRecoveryInFlight = true;
+        console.error(chalk.yellow('  media watchdog: RoboVision unhealthy for 30s; recycling camera/audio pair'));
+        try {
+            await stopChild(vision);
+            if (!stopping)
+                start(vision);
+            visionFailureCount = 0;
+        }
+        finally {
+            visionRecoveryInFlight = false;
+        }
+    };
+    const recycleAfterMeshUpdate = async () => {
+        if (stopping || recycling)
+            return;
+        recycling = true;
+        console.log(chalk.dim('  mesh updated; restarting RoboVision and preview on the new package...'));
+        await Promise.all([...children.filter(entry => entry.label !== 'mesh'), ...(ownsPreview ? [preview] : [])].map(stopChild));
+        if (stopping)
+            return;
+        for (const entry of children)
+            start(entry);
+        if (ownsPreview)
+            start(preview);
+        recycling = false;
+        console.log(chalk.green('  robot runtime updated and healthy'));
+        if (ownsVision) {
+            void waitForVision().then(ready => {
+                if (!stopping)
+                    console.log(ready
+                        ? chalk.green('  RoboVision camera/audio inventory ready')
+                        : chalk.yellow('  RoboVision is degraded; preview heartbeat remains online and will retry'));
+            });
+        }
+    };
+    console.log(chalk.bold('\n  robopark robot up'));
+    console.log(chalk.dim('  ' + '─'.repeat(52)));
+    console.log(`  robot:     ${chalk.cyan(opts.name)}`);
+    console.log(`  scheduler: ${chalk.cyan(opts.schedulerUrl)}`);
+    console.log(`  network:   ${chalk.cyan(network)}`);
+    console.log(`  role:      ${chalk.cyan(deviceRole)}`);
+    console.log(`  services:  ${deviceRole === 'motor' ? 'mesh + motor + command supervisor' : deviceRole === 'voice_vision' ? 'mesh + RoboVision + command supervisor' : ownsVision ? 'mesh + RoboVision + preview + command supervisor' : 'mesh + preview + command supervisor'}`);
+    console.log();
+    if (opts.enrollmentToken) {
+        console.log(chalk.dim('  clearing stale device identity for fresh enrollment…'));
+        resetStaleEnrollment();
+    }
+    // Identity and inventory reporting start immediately. RoboVision may still
+    // be installing or recovering without making the robot disappear.
+    const stopSchedulerHeartbeat = startSchedulerHeartbeat(opts, livekitUrl);
+    for (const entry of children)
+        start(entry);
+    if (ownsPreview)
+        start(preview);
+    if (ownsVision) {
+        console.log(chalk.dim('  RoboVision health check running in background…'));
+        void waitForVision().then(ready => {
+            if (!stopping)
+                console.log(ready
+                    ? chalk.green('  RoboVision camera/audio inventory ready')
+                    : chalk.yellow('  RoboVision is degraded; preview heartbeat remains online and will retry'));
+        });
+    }
+    const mediaWatchdog = setInterval(() => { void monitorVision(); }, MEDIA_WATCHDOG_INTERVAL_MS);
+    const shutdown = () => {
+        stopping = true;
+        stopSchedulerHeartbeat();
+        clearInterval(mediaWatchdog);
+        for (const entry of [...children, ...(ownsPreview ? [preview] : [])])
+            signalChild(entry, 'SIGTERM');
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    await new Promise(resolve => {
+        const check = setInterval(() => {
+            if (stopping && ![...children, ...(ownsPreview ? [preview] : [])].some(entry => entry.child)) {
+                clearInterval(check);
+                resolve();
+            }
+        }, 250);
+    });
+}

package/dist/robopark/scan.js

@@ -0,0 +1,97 @@
+/**
+ * RoboPark — `robopark scan`.
+ *
+ * Scans Tailscale + LAN + local config and emits ready-to-run setup commands
+ * for every machine in the fleet. No manual IP/token typing.
+ */
+import chalk from 'chalk';
+import { discoverContext, generateToken } from './discovery.js';
+function hubCommand(ctx, opts) {
+    const name = ctx.hub?.name ?? 'livekit-1';
+    const site = 'Tel Aviv'; // TODO: discover from role context or prompt
+    const token = opts.token ?? ctx.meshToken ?? generateToken();
+    const gw = opts.gateway !== false ? ctx.gateway : undefined;
+    const parts = [
+        'robopark setup --hub',
+        `--name ${name}`,
+        `--site "${site}"`,
+        `--token ${token}`,
+        '--start',
+        '--auto-start',
+    ];
+    if (ctx.tailscaleAuthKey)
+        parts.push(`--tailscale-auth ${ctx.tailscaleAuthKey}`);
+    if (gw)
+        parts.push(`--gateway ws://${gw.host}:${gw.port}`, `--gateway-token ${gw.token ?? 'SET_TOKEN'}`);
+    return parts.join(' ');
+}
+function robotCommand(robot, ctx, opts) {
+    const token = opts.token ?? ctx.meshToken ?? generateToken();
+    const hubUrl = ctx.hub ? `http://${ctx.hub.ip}:47913` : 'http://HUB_IP:47913';
+    const parts = [
+        'robopark setup --robot',
+        `--name ${robot.name}`,
+        `--hub-url ${hubUrl}`,
+        `--token ${token}`,
+        '--start',
+        '--auto-start',
+    ];
+    if (ctx.tailscaleAuthKey)
+        parts.push(`--tailscale-auth ${ctx.tailscaleAuthKey}`);
+    return parts.join(' ');
+}
+function controlCommand(ctx, opts) {
+    const token = opts.token ?? ctx.meshToken ?? generateToken();
+    const hubUrl = ctx.hub ? `http://${ctx.hub.ip}:47913` : 'http://HUB_IP:47913';
+    const parts = [
+        'robopark setup --control',
+        `--hub-url ${hubUrl}`,
+        `--token ${token}`,
+        '--start',
+        '--auto-start',
+    ];
+    return parts.join(' ');
+}
+export async function roboparkScan(opts = {}) {
+    console.log(chalk.bold('\n  robopark scan — auto-discovering your fleet\n'));
+    const ctx = await discoverContext();
+    if (!ctx.hub) {
+        console.log(chalk.yellow('  ⚠ no hub found on Tailscale. Look for a machine named like livekit-* / hub / scheduler.'));
+        console.log(chalk.dim('    make sure the hub box is online and tagged, or run `robopark setup --hub` on it first.'));
+    }
+    else {
+        console.log(`  ${chalk.green('✓')} hub found: ${chalk.cyan(ctx.hub.name)} @ ${chalk.cyan(ctx.hub.ip)}`);
+    }
+    if (!ctx.gateway) {
+        console.log(chalk.dim('  · no InfiniBot gateway discovered (set one with --gateway or INFINIBOT_GATEWAY env)'));
+    }
+    else {
+        console.log(`  ${chalk.green('✓')} gateway found: ${chalk.cyan(`${ctx.gateway.host}:${ctx.gateway.port}`)}`);
+    }
+    if (!ctx.robots.length) {
+        console.log(chalk.dim('  · no robots discovered yet. They will LAN-join after the hub is running.'));
+    }
+    else {
+        console.log(`  ${chalk.green('✓')} ${ctx.robots.length} robot(s) found:`);
+        for (const r of ctx.robots)
+            console.log(`    · ${chalk.cyan(r.name)} @ ${chalk.cyan(r.ip)}`);
+    }
+    const token = opts.token ?? ctx.meshToken ?? generateToken();
+    console.log(`\n  ${chalk.green('✓')} using mesh token: ${chalk.cyan(token)}`);
+    console.log(chalk.dim('    save it with: echo "${TOKEN}" > ~/.robopark/mesh.token'));
+    console.log(chalk.bold('\n  Generated setup commands:\n'));
+    console.log(chalk.dim('  # on the hub box'));
+    console.log('  ' + chalk.cyan(hubCommand(ctx, opts)));
+    console.log();
+    console.log(chalk.dim('  # on each robot'));
+    for (const r of ctx.robots) {
+        console.log('  ' + chalk.cyan(robotCommand(r, ctx, opts)));
+    }
+    if (!ctx.robots.length) {
+        console.log('  ' + chalk.cyan(robotCommand({ name: 'robobmw', ip: 'HUB_IP', online: true, source: 'tailscale' }, ctx, opts).replace('robobmw', '<ROBOT_NAME>')));
+    }
+    console.log();
+    console.log(chalk.dim('  # on this dev laptop'));
+    console.log('  ' + chalk.cyan(controlCommand(ctx, opts)));
+    console.log();
+}

package/dist/robopark/screen-control.js

@@ -0,0 +1,55 @@
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import chalk from 'chalk';
+import { registerAutoStart, unregisterAutoStart } from './auto-start.js';
+import { findPython, findScreenRuntimePath } from './python-env.js';
+function safeName(name) { return name.toLowerCase().replace(/[^a-z0-9]+/g, '-'); }
+function unit(name) { return `robopark-robot-screen-${safeName(name)}.service`; }
+export function roboparkScreenInstall() {
+    if (process.platform !== 'linux')
+        throw new Error('screen sharing installation is supported on Linux robot hosts');
+    const update = spawnSync('apt-get', ['update'], { stdio: 'inherit' });
+    if (update.status !== 0)
+        throw new Error('apt-get update failed');
+    const install = spawnSync('apt-get', ['install', '-y', 'wayvnc', 'x11vnc', 'novnc', 'websockify'], { stdio: 'inherit' });
+    if (install.status !== 0)
+        throw new Error('could not install wayvnc/x11vnc/noVNC/websockify');
+    console.log(chalk.green('  desktop relay dependencies installed'));
+}
+export async function roboparkScreenUp(name, desktopUser) {
+    if (process.platform !== 'linux')
+        throw new Error('screen sharing requires a Linux robot host');
+    const script = await findScreenRuntimePath();
+    if (!script)
+        throw new Error('screen_runtime.py is missing from this Infinicode installation');
+    for (const command of ['websockify']) {
+        if (spawnSync('sh', ['-c', `command -v ${command}`], { stdio: 'ignore' }).status !== 0) {
+            throw new Error(`missing ${command}; run \`sudo robopark screen install\` first`);
+        }
+    }
+    const dir = join(homedir(), '.robopark');
+    mkdirSync(dir, { recursive: true });
+    const config = join(dir, `screen-${safeName(name)}.json`);
+    writeFileSync(config, `${JSON.stringify({ name, desktop_user: desktopUser ?? '' }, null, 2)}\n`, { mode: 0o600 });
+    const pythonName = findPython();
+    const python = spawnSync('sh', ['-c', `command -v ${pythonName}`], { encoding: 'utf8' }).stdout.trim() || pythonName;
+    const result = await registerAutoStart({ role: 'robot-screen', name, command: resolve(python), args: [resolve(script), '--config', resolve(config)], workingDir: homedir() });
+    if (!result.ok)
+        throw new Error(result.message);
+    console.log(chalk.green(`  ${result.message}`));
+    console.log(`  dashboard: /fed/media/robots/${encodeURIComponent(name)}/screen/vnc.html`);
+}
+export function roboparkScreenRestart(name) {
+    const result = spawnSync('systemctl', ['restart', unit(name)], { encoding: 'utf8' });
+    if (result.status !== 0)
+        throw new Error(String(result.stderr || result.stdout).trim());
+    console.log(chalk.green(`  restarted ${unit(name)}`));
+}
+export function roboparkScreenDown(name) {
+    const result = unregisterAutoStart('robot-screen', name);
+    if (!result.ok)
+        throw new Error(result.message);
+    console.log(chalk.green(`  ${result.message}`));
+}

package/dist/robopark/secrets.js

@@ -0,0 +1,41 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import chalk from 'chalk';
+function updateEnv(contents, token) {
+    const line = `ROBOPARK_AGENT_TOKEN=${token}`;
+    const re = /^ROBOPARK_AGENT_TOKEN=.*$/m;
+    return re.test(contents)
+        ? contents.replace(re, line)
+        : `${contents.trimEnd()}\n${line}\n`;
+}
+/** Provision the scheduler's shared worker secret into a ROBOVOICE .env file. */
+export async function roboparkSecrets(opts) {
+    const base = opts.schedulerUrl.replace(/\/$/, '');
+    const response = await fetch(`${base}/api/settings/agent-token/provision`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ rotate: Boolean(opts.rotate) }),
+    });
+    if (!response.ok) {
+        throw new Error(`scheduler rejected secret provisioning (${response.status})`);
+    }
+    const body = await response.json();
+    if (!body.agent_token)
+        throw new Error('scheduler returned no agent token');
+    let current = '';
+    try {
+        current = await readFile(opts.workerEnv, 'utf8');
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const next = updateEnv(current, body.agent_token);
+    await mkdir(dirname(opts.workerEnv), { recursive: true });
+    const temp = `${opts.workerEnv}.tmp-${process.pid}`;
+    await writeFile(temp, next, { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, opts.workerEnv);
+    console.log(chalk.green(`  ✓ ROBOVOICE secret synchronized to ${opts.workerEnv}`));
+    if (opts.rotate)
+        console.log(chalk.yellow('  Restart the ROBOVOICE worker to use the rotated secret.'));
+}