robopark 3.1.2 → 3.3.0

package/dist/robopark/standalone.js

@@ -1,562 +0,0 @@
-import chalk from 'chalk';
-import { spawn } from 'node:child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
-import { homedir, hostname, networkInterfaces } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { registerAutoStart } from './auto-start.js';
-import { findPython, findSchedulerPath, prepareRobotPython } from './python-env.js';
-import { roboparkServe, schedulerHealthy } from './serve.js';
-import { startControlServer } from './control-server.js';
-import { activateFromPairing } from './access.js';
-const STATE_DIR = process.env.ROBOPARK_HOME
-    ? resolve(process.env.ROBOPARK_HOME)
-    : join(homedir(), '.robopark');
-const CONNECTION_PATH = join(STATE_DIR, 'connection.json');
-const DESIRED_PATH = join(STATE_DIR, 'desired-runtime.json');
-const STATUS_PATH = join(STATE_DIR, 'runtime-status.json');
-const GATEWAY_PATH = join(STATE_DIR, 'gateway.json');
-const LOG_DIR = join(STATE_DIR, 'logs');
-function ensureStateDir() {
-    mkdirSync(STATE_DIR, { recursive: true });
-    mkdirSync(LOG_DIR, { recursive: true });
-}
-function atomicJson(path, value, mode = 0o600) {
-    ensureStateDir();
-    const temp = `${path}.${process.pid}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode });
-    renameSync(temp, path);
-}
-function normalizedUrl(value) {
-    const candidate = value.trim().replace(/\/+$/, '');
-    const url = new URL(candidate);
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
-        throw new Error('gateway URL must use http:// or https://');
-    }
-    return url.toString().replace(/\/+$/, '');
-}
-export function encodePairingToken(payload) {
-    return `rp1_${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url')}`;
-}
-export function decodePairingToken(value) {
-    const trimmed = value.trim();
-    let payload;
-    if (trimmed.startsWith('rp1_')) {
-        try {
-            payload = JSON.parse(Buffer.from(trimmed.slice(4), 'base64url').toString('utf8'));
-        }
-        catch {
-            throw new Error('invalid RoboPark connection token');
-        }
-    }
-    else if (/^https?:\/\//i.test(trimmed) && trimmed.includes('#')) {
-        const split = trimmed.lastIndexOf('#');
-        payload = {
-            v: 1,
-            schedulerUrl: trimmed.slice(0, split),
-            enrollmentToken: trimmed.slice(split + 1),
-        };
-    }
-    else {
-        throw new Error('invalid connection token; copy the complete token shown by `robopark gateway start`');
-    }
-    if (payload.v !== 1 || !payload.schedulerUrl || !payload.enrollmentToken) {
-        throw new Error('unsupported or incomplete RoboPark connection token');
-    }
-    payload.schedulerUrl = normalizedUrl(payload.schedulerUrl);
-    if (payload.expiresAt && Date.parse(payload.expiresAt) <= Date.now()) {
-        throw new Error('this connection token has expired; create a new token on the gateway');
-    }
-    return payload;
-}
-function readConnection() {
-    if (existsSync(CONNECTION_PATH)) {
-        const parsed = JSON.parse(readFileSync(CONNECTION_PATH, 'utf8'));
-        if (!parsed.schedulerUrl || !parsed.deviceId || !parsed.deviceToken) {
-            throw new Error(`invalid saved connection at ${CONNECTION_PATH}; reconnect this device`);
-        }
-        return parsed;
-    }
-    // Adopt the exact deployed preview-agent identity in place. Older releases
-    // predate connection.json but already persist everything required here.
-    const legacyPath = join(STATE_DIR, 'preview_agent.json');
-    if (existsSync(legacyPath)) {
-        try {
-            const legacy = JSON.parse(readFileSync(legacyPath, 'utf8'));
-            const tokenPath = join(STATE_DIR, 'device_token');
-            const deviceToken = existsSync(tokenPath)
-                ? readFileSync(tokenPath, 'utf8').trim()
-                : String(legacy.device_token ?? '').trim();
-            const schedulerUrl = String(legacy.scheduler_url ?? '').trim();
-            const deviceId = String(legacy.device_id ?? '').trim();
-            const name = String(legacy.robot_id ?? legacy.name ?? hostname().split('.')[0]).trim();
-            if (schedulerUrl && deviceId && deviceToken) {
-                const adopted = {
-                    version: 1,
-                    schedulerUrl: normalizedUrl(schedulerUrl),
-                    deviceId,
-                    deviceToken,
-                    name,
-                    connectedAt: new Date().toISOString(),
-                };
-                atomicJson(CONNECTION_PATH, adopted);
-                return adopted;
-            }
-        }
-        catch {
-            // Fall through to the actionable connect error.
-        }
-    }
-    throw new Error('this device is not connected; run `robopark connect <token>` first');
-}
-async function jsonRequest(url, init, timeoutMs = 10_000) {
-    const response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs) });
-    const body = await response.text();
-    let parsed = {};
-    try {
-        parsed = body ? JSON.parse(body) : {};
-    }
-    catch {
-        parsed = { detail: body };
-    }
-    if (!response.ok) {
-        const detail = typeof parsed === 'object' && parsed && 'detail' in parsed
-            ? String(parsed.detail)
-            : `HTTP ${response.status}`;
-        throw new Error(detail);
-    }
-    return parsed;
-}
-export async function connectDevice(token, opts = {}) {
-    const pairing = decodePairingToken(token);
-    const name = (opts.name ?? hostname().split('.')[0]).trim();
-    if (!name)
-        throw new Error('device name cannot be empty');
-    const enrolled = await jsonRequest(`${pairing.schedulerUrl}/api/devices/enroll`, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-            enrollment_token: pairing.enrollmentToken,
-            name,
-            device_role: 'voice_vision',
-        }),
-    });
-    const connection = {
-        version: 1,
-        // The gateway may bind on 0.0.0.0 and report its own loopback default.
-        // The pairing payload is the operator-selected device route.
-        schedulerUrl: pairing.schedulerUrl,
-        deviceId: enrolled.device_id,
-        deviceToken: enrolled.device_token,
-        name,
-        connectedAt: new Date().toISOString(),
-        controlPort: pairing.controlPort,
-    };
-    atomicJson(CONNECTION_PATH, connection);
-    writeFileSync(join(STATE_DIR, 'device_token'), connection.deviceToken, { encoding: 'utf8', mode: 0o600 });
-    activateFromPairing();
-    console.log(chalk.green(`\n  ✓ connected ${name}`));
-    console.log(`  gateway: ${chalk.cyan(connection.schedulerUrl)}`);
-    console.log(`  device:  ${chalk.cyan(connection.deviceId)}`);
-    console.log(chalk.dim('  credentials were saved locally; the pairing token was not retained.\n'));
-    return connection;
-}
-function cliEntry() {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const candidates = [
-        join(here, '..', '..', 'bin', 'robopark.js'),
-        join(here, '..', '..', '..', 'bin', 'robopark.js'),
-        join(process.cwd(), 'bin', 'robopark.js'),
-    ];
-    const found = candidates.find(existsSync);
-    if (!found)
-        throw new Error('could not resolve the packaged RoboPark CLI entry point');
-    return found;
-}
-async function updateDeviceConfiguration(desired) {
-    const c = desired.connection;
-    await jsonRequest(`${c.schedulerUrl}/api/devices/${encodeURIComponent(c.deviceId)}`, {
-        method: 'PATCH',
-        headers: {
-            'content-type': 'application/json',
-            authorization: `Bearer ${c.deviceToken}`,
-        },
-        body: JSON.stringify({
-            name: c.name,
-            character_id: desired.character || null,
-            video_device: desired.video ? desired.videoDevice : 'none',
-            audio_device: desired.voice ? desired.audioDevice : 'none',
-            device_role: 'voice_vision',
-            production_mode: true,
-        }),
-    });
-}
-function positiveInteger(value, fallback, label) {
-    const parsed = Number.parseInt(value ?? String(fallback), 10);
-    if (!Number.isFinite(parsed) || parsed <= 0)
-        throw new Error(`${label} must be a positive integer`);
-    return parsed;
-}
-function openBrowser(url) {
-    // Use detached platform-native launchers so this CLI remains usable from
-    // terminals and does not inherit browser stdio or lifecycle.
-    const command = process.platform === 'win32'
-        ? 'cmd.exe'
-        : process.platform === 'darwin'
-            ? 'open'
-            : 'xdg-open';
-    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
-    try {
-        spawn(command, args, { detached: true, stdio: 'ignore', windowsHide: true }).unref();
-    }
-    catch (err) {
-        console.log(chalk.yellow(`  ⚠ could not open browser: ${err instanceof Error ? err.message : String(err)}`));
-    }
-}
-/**
- * Opens the character-specific ElevenLabs voice-join page (served by the Park
- * Control Center, not the scheduler) for the device just configured. Best
- * effort only: a browser-less robot host or an unreachable control server
- * must never fail `robopark start`/`robopark connect`.
- */
-async function openCharacterCallPage(connection, character) {
-    try {
-        const preset = await jsonRequest(`${connection.schedulerUrl}/api/character-presets/${encodeURIComponent(character)}`, {});
-        if (!preset.elevenlabs_agent_id) {
-            console.log(chalk.yellow(`  ⚠ character "${character}" has no ElevenLabs agent configured; not opening a call page.`));
-            return;
-        }
-        const controlPort = connection.controlPort ?? 47913;
-        const controlHost = new URL(connection.schedulerUrl).hostname;
-        const params = new URLSearchParams({
-            character,
-            agent_id: preset.elevenlabs_agent_id,
-            mode: 'production',
-            robot: connection.deviceId,
-        });
-        if (preset.elevenlabs_branch_id)
-            params.set('branch_id', preset.elevenlabs_branch_id);
-        const url = `http://${controlHost}:${controlPort}/voice-join.html?${params.toString()}`;
-        console.log(`  call page: ${chalk.cyan(url)}`);
-        openBrowser(url);
-    }
-    catch (err) {
-        console.log(chalk.yellow(`  ⚠ could not open the character call page: ${err instanceof Error ? err.message : String(err)}`));
-    }
-}
-export async function startDevice(opts) {
-    const connection = readConnection();
-    const desired = {
-        version: 1,
-        connection,
-        voice: Boolean(opts.voice),
-        video: Boolean(opts.video),
-        character: opts.character?.trim() || undefined,
-        videoDevice: opts.videoDevice ?? 'auto',
-        audioDevice: opts.audioDevice ?? 'default',
-        width: positiveInteger(opts.width, 640, 'width'),
-        height: positiveInteger(opts.height, 480, 'height'),
-        fps: positiveInteger(opts.fps, 15, 'fps'),
-        updatedAt: new Date().toISOString(),
-    };
-    if (!desired.voice && !desired.video) {
-        throw new Error('select at least one media path: `--voice`, `--video`, or both');
-    }
-    await updateDeviceConfiguration(desired);
-    atomicJson(DESIRED_PATH, desired);
-    if (desired.character) {
-        await openCharacterCallPage(connection, desired.character);
-    }
-    if (opts.foreground) {
-        await superviseDevice(DESIRED_PATH);
-        return;
-    }
-    const registration = await registerAutoStart({
-        role: 'robot-runtime',
-        name: connection.name,
-        command: process.execPath,
-        args: [cliEntry(), '_supervise', '--config', DESIRED_PATH],
-        workingDir: homedir(),
-        exclusiveMedia: true,
-    });
-    if (!registration.ok) {
-        throw new Error(`${registration.message}. Retry from an elevated terminal or use --foreground.`);
-    }
-    console.log(chalk.green(`\n  ✓ RoboPark is supervising ${connection.name}`));
-    console.log(`  voice:     ${desired.voice ? chalk.green('on') : chalk.dim('off')}`);
-    console.log(`  video:     ${desired.video ? chalk.green('on') : chalk.dim('off')}`);
-    console.log(`  character: ${chalk.cyan(desired.character || 'gateway default')}`);
-    console.log(`  service:   ${chalk.dim(registration.message)}`);
-    console.log(`  status:    ${chalk.dim(STATUS_PATH)}\n`);
-}
-function status(state) {
-    atomicJson(STATUS_PATH, { ...state, updatedAt: new Date().toISOString(), pid: process.pid });
-}
-async function reportSupervisor(desired, state, detail) {
-    const c = desired.connection;
-    try {
-        await jsonRequest(`${c.schedulerUrl}/api/devices/${encodeURIComponent(c.deviceId)}/supervisor-status`, {
-            method: 'POST',
-            headers: {
-                'content-type': 'application/json',
-                authorization: `Bearer ${c.deviceToken}`,
-            },
-            body: JSON.stringify({
-                services: [{
-                        name: `robopark-device:${state}:${detail.slice(0, 120)}`,
-                        enabled: true,
-                        running: state === 'running' || state === 'starting',
-                        pid: process.pid,
-                        failure_count: 0,
-                    }],
-            }),
-        }, 4_000);
-    }
-    catch {
-        // The local status file remains authoritative while the gateway is offline.
-    }
-}
-async function heartbeatFresh(desired) {
-    const c = desired.connection;
-    try {
-        const device = await jsonRequest(`${c.schedulerUrl}/api/devices/${encodeURIComponent(c.deviceId)}`, { headers: { authorization: `Bearer ${c.deviceToken}` } }, 5_000);
-        const age = device.last_heartbeat ? Date.now() - Date.parse(device.last_heartbeat) : Number.POSITIVE_INFINITY;
-        return age < 45_000 && device.status !== 'offline';
-    }
-    catch {
-        // A gateway outage must not cause a restart storm. The worker's own retry
-        // loop will reconnect, and the watchdog resumes once the gateway answers.
-        return true;
-    }
-}
-function wait(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-function terminate(child) {
-    if (!child || child.killed)
-        return;
-    try {
-        child.kill('SIGTERM');
-    }
-    catch { /* already gone */ }
-    setTimeout(() => {
-        if (child.exitCode === null) {
-            try {
-                child.kill('SIGKILL');
-            }
-            catch { /* already gone */ }
-        }
-    }, 10_000).unref();
-}
-export async function superviseDevice(configPath = DESIRED_PATH) {
-    let desired = JSON.parse(readFileSync(configPath, 'utf8'));
-    const script = await findSchedulerPath();
-    if (!script)
-        throw new Error('packaged preview_agent.py was not found');
-    const python = prepareRobotPython(findPython(), script);
-    if (!python)
-        throw new Error('could not prepare the packaged RoboPark media runtime');
-    let child;
-    let stopping = false;
-    let failures = 0;
-    let startedAt = 0;
-    const shutdown = (signal) => {
-        stopping = true;
-        status({ state: 'stopping', signal });
-        terminate(child);
-    };
-    process.once('SIGINT', shutdown);
-    process.once('SIGTERM', shutdown);
-    while (!stopping) {
-        desired = JSON.parse(readFileSync(configPath, 'utf8'));
-        const c = desired.connection;
-        const args = [
-            script,
-            '--scheduler-url', c.schedulerUrl,
-            '--robot-id', c.name,
-            '--device-token', c.deviceToken,
-            '--video-device', desired.video ? desired.videoDevice : 'none',
-            '--audio-device', desired.voice ? desired.audioDevice : 'none',
-            '--width', String(desired.width),
-            '--height', String(desired.height),
-            '--fps', String(desired.fps),
-            '--save-config',
-        ];
-        startedAt = Date.now();
-        status({ state: 'starting', childFailures: failures, voice: desired.voice, video: desired.video });
-        await reportSupervisor(desired, 'starting', 'starting packaged camera/voice worker');
-        const outFd = openSync(join(LOG_DIR, 'device.log'), 'a');
-        const errFd = openSync(join(LOG_DIR, 'device.err.log'), 'a');
-        child = spawn(python, args, {
-            env: { ...process.env, ROBOPARK_DEVICE_ID: c.deviceId },
-            stdio: ['ignore', outFd, errFd],
-            windowsHide: true,
-        });
-        closeSync(outFd);
-        closeSync(errFd);
-        status({ state: 'running', childPid: child.pid, childFailures: failures });
-        await reportSupervisor(desired, 'running', `media worker pid ${child.pid ?? 'unknown'}`);
-        let watchdogFailures = 0;
-        const watchdog = setInterval(async () => {
-            if (!child || child.exitCode !== null || Date.now() - startedAt < 60_000)
-                return;
-            watchdogFailures = await heartbeatFresh(desired) ? 0 : watchdogFailures + 1;
-            if (watchdogFailures >= 3) {
-                status({ state: 'restarting', reason: 'heartbeat_stalled', childPid: child.pid });
-                await reportSupervisor(desired, 'degraded', 'heartbeat stalled; recycling media worker');
-                terminate(child);
-            }
-        }, 15_000);
-        watchdog.unref();
-        const exit = await new Promise((resolve, reject) => {
-            child?.once('error', reject);
-            child?.once('exit', (code, signal) => resolve({ code, signal }));
-        }).catch(error => ({ code: 1, signal: null, error }));
-        clearInterval(watchdog);
-        if (stopping)
-            break;
-        const ranFor = Date.now() - startedAt;
-        failures = ranFor > 5 * 60_000 ? 0 : failures + 1;
-        const delay = Math.min(30_000, 1_000 * 2 ** Math.min(failures, 5));
-        const detail = `worker stopped (${String('error' in exit ? exit.error : exit.signal ?? exit.code)}); restart in ${delay}ms`;
-        status({ state: 'backoff', detail, childFailures: failures, restartInMs: delay });
-        await reportSupervisor(desired, 'restarting', detail);
-        await wait(delay);
-    }
-    status({ state: 'stopped' });
-    await reportSupervisor(desired, 'stopped', 'device supervisor stopped');
-}
-function localPublicUrl(host, port, explicit) {
-    if (explicit)
-        return normalizedUrl(explicit);
-    let publicHost = host;
-    if (host === '0.0.0.0' || host === '::') {
-        const addresses = Object.entries(networkInterfaces())
-            .flatMap(([name, entries]) => (entries ?? [])
-            .filter(entry => entry.family === 'IPv4' && !entry.internal)
-            .map(entry => ({ name: name.toLowerCase(), address: entry.address })));
-        publicHost = addresses.find(entry => /tailscale|wireguard|wg/.test(entry.name))?.address
-            ?? addresses.find(entry => entry.address.startsWith('100.'))?.address
-            ?? addresses.find(entry => /ethernet|wi-?fi|wlan|eth/.test(entry.name))?.address
-            ?? addresses[0]?.address
-            ?? 'localhost';
-    }
-    return normalizedUrl(`http://${publicHost}:${port}`);
-}
-export async function gatewayStart(opts) {
-    const port = positiveInteger(opts.port, 8080, 'port');
-    const controlPort = positiveInteger(opts.controlPort, 47913, 'control port');
-    const host = opts.host ?? '0.0.0.0';
-    if (opts.foreground) {
-        await runGatewayService({
-            port: String(port),
-            controlPort: String(controlPort),
-            host,
-            dataDir: opts.dataDir,
-            open: opts.open,
-        });
-    }
-    else {
-        const args = [cliEntry(), '_gateway', '--port', String(port), '--host', host];
-        args.push('--control-port', String(controlPort));
-        if (opts.dataDir)
-            args.push('--data-dir', opts.dataDir);
-        const registration = await registerAutoStart({
-            role: 'hub-scheduler',
-            name: 'gateway',
-            command: process.execPath,
-            args,
-            workingDir: homedir(),
-        });
-        if (!registration.ok) {
-            throw new Error(`${registration.message}. Retry from an elevated terminal or add --foreground.`);
-        }
-        console.log(chalk.green(`  ✓ ${registration.message}`));
-    }
-    const schedulerUrl = localPublicUrl(host, port, opts.publicUrl);
-    const healthUrl = `http://127.0.0.1:${port}`;
-    const controlHealthUrl = `http://127.0.0.1:${controlPort}/fed/ui-build`;
-    const deadline = Date.now() + 30_000;
-    let schedulerReady = false;
-    let controlReady = false;
-    while (!schedulerReady || !controlReady) {
-        [schedulerReady, controlReady] = await Promise.all([
-            schedulerHealthy(healthUrl, 1_000),
-            fetch(controlHealthUrl, { signal: AbortSignal.timeout(1_000) })
-                .then(async (response) => {
-                if (!response.ok)
-                    return false;
-                const body = await response.json();
-                return body.owner === 'robopark';
-            })
-                .catch(() => false),
-        ]);
-        if (Date.now() >= deadline) {
-            throw new Error(`gateway did not become healthy (scheduler ${port}: ${schedulerReady ? 'ready' : 'down'}, `
-                + `Control Center ${controlPort}: ${controlReady ? 'ready' : 'down'})`);
-        }
-        await wait(500);
-    }
-    const token = await createGatewayTokenAt(healthUrl, schedulerUrl, controlPort);
-    const controlHost = new URL(schedulerUrl).hostname;
-    console.log(`  Park Control Center: ${chalk.cyan(`http://${controlHost}:${controlPort}/`)}`);
-    console.log(chalk.bold('\n  Connect a device'));
-    console.log(`  ${chalk.cyan(`robopark connect ${token}`)}`);
-    console.log(chalk.dim('  This pairing token expires in 24 hours. Connected devices keep their own durable credentials.\n'));
-}
-async function createGatewayTokenAt(localUrl, publicUrl, controlPort) {
-    await jsonRequest(`${localUrl}/api/settings`, {
-        method: 'PUT',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ production_mode: true }),
-    });
-    const result = await jsonRequest(`${localUrl}/api/settings/enrollment-token/rotate`, { method: 'POST' });
-    const pairing = encodePairingToken({
-        v: 1,
-        schedulerUrl: publicUrl,
-        enrollmentToken: result.enrollment_token,
-        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
-        controlPort,
-    });
-    atomicJson(GATEWAY_PATH, { schedulerUrl: publicUrl, pairingToken: pairing, createdAt: new Date().toISOString() });
-    return pairing;
-}
-export async function runGatewayService(opts) {
-    const schedulerPort = positiveInteger(opts.port, 8080, 'port');
-    const controlPort = positiveInteger(opts.controlPort, 47913, 'control port');
-    const host = opts.host ?? '0.0.0.0';
-    const control = await startControlServer({
-        host,
-        port: controlPort,
-        schedulerUrl: `http://127.0.0.1:${schedulerPort}`,
-    });
-    console.log(`  Park Control Center listening on ${host}:${controlPort}`);
-    try {
-        await roboparkServe({
-            port: String(schedulerPort),
-            host,
-            dataDir: opts.dataDir,
-            open: false,
-            foreground: true,
-        });
-        // roboparkServe wires the scheduler child's lifecycle handlers and then
-        // returns once it has launched. Keep this outer gateway process alive so
-        // the sibling Control Center server is not closed by the finally block.
-        await new Promise((resolve) => {
-            const stop = () => resolve();
-            process.once('SIGINT', stop);
-            process.once('SIGTERM', stop);
-        });
-    }
-    finally {
-        control.close();
-    }
-}
-export function printRuntimeStatus() {
-    if (!existsSync(STATUS_PATH)) {
-        console.log(chalk.yellow('  no local runtime status; run `robopark start --voice --video`'));
-        return;
-    }
-    const current = JSON.parse(readFileSync(STATUS_PATH, 'utf8'));
-    console.log(JSON.stringify(current, null, 2));
-}