robopark 2.8.35 → 3.0.0

package/dist/robopark/conversation.js

@@ -0,0 +1,505 @@
+import chalk from 'chalk';
+import { spawn, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { registerAutoStart, unregisterAutoStart } from './auto-start.js';
+import { findConversationPath, findPython, findVisionPath, prepareRobotPython, VISION_REQUIRED_MODULES, } from './python-env.js';
+function schedulerTelemetryIdentity() {
+    const dir = join(homedir(), '.robopark');
+    try {
+        const preview = JSON.parse(readFileSync(join(dir, 'preview_agent.json'), 'utf8'));
+        const schedulerUrl = String(preview.scheduler_url ?? '').replace(/\/+$/, '');
+        const deviceId = String(preview.device_id ?? '').trim();
+        const tokenPath = join(dir, 'device_token');
+        const deviceToken = existsSync(tokenPath)
+            ? readFileSync(tokenPath, 'utf8').trim()
+            : String(preview.device_token ?? '').trim();
+        return schedulerUrl && deviceId && deviceToken ? { schedulerUrl, deviceId, deviceToken } : null;
+    }
+    catch {
+        return null;
+    }
+}
+const PI_AUDIO_PACKAGES = [
+    'python3', 'python3-venv', 'python3-pip', 'python3-dev', 'build-essential',
+    'libportaudio2', 'portaudio19-dev', 'libasound2-dev', 'alsa-utils',
+    'libsndfile1', 'python3-pyaudio', 'psmisc', 'procps', 'ca-certificates', 'curl',
+];
+/** Install the native and Python layers separately, then prove ALSA/PyAudio
+ * can see at least one real capture and playback device. Idempotent on Pi OS. */
+export async function roboparkConversationInstall(opts = {}) {
+    if (process.platform !== 'linux') {
+        throw new Error('conversation install is intended for Debian/Raspberry Pi Linux');
+    }
+    if (!opts.skipApt) {
+        const elevated = typeof process.getuid === 'function' && process.getuid() === 0;
+        const command = elevated ? 'apt-get' : 'sudo';
+        const prefix = elevated ? [] : ['apt-get'];
+        const env = { ...process.env, DEBIAN_FRONTEND: 'noninteractive' };
+        console.log(chalk.dim('  refreshing Raspberry Pi OS package metadata…'));
+        const update = spawnSync(command, [...prefix, 'update'], { stdio: 'inherit', env });
+        if (update.status !== 0)
+            throw new Error('apt-get update failed');
+        const packages = opts.withVision
+            ? [...PI_AUDIO_PACKAGES, 'python3-opencv', 'python3-numpy']
+            : PI_AUDIO_PACKAGES;
+        console.log(chalk.dim('  installing native audio/Python prerequisites…'));
+        const apt = spawnSync(command, [...prefix, 'install', '-y', '--no-install-recommends', ...packages], {
+            stdio: 'inherit', env,
+        });
+        if (apt.status !== 0)
+            throw new Error('native dependency installation failed');
+    }
+    const script = await findConversationPath();
+    if (!script)
+        throw new Error('packaged ElevenLabs conversation runtime was not found');
+    const python = prepareRobotPython(findPython(), script, ['elevenlabs', 'pyaudio', 'gpiozero'], 'requirements.txt');
+    if (!python)
+        throw new Error('could not prepare the robot conversation Python environment');
+    if (opts.withVision) {
+        const visionScript = await findVisionPath();
+        if (!visionScript)
+            throw new Error('packaged RoboVision camera runtime was not found');
+        if (!prepareRobotPython(python, visionScript, VISION_REQUIRED_MODULES, 'requirements_camera.txt')) {
+            throw new Error('could not prepare the RoboVision Python environment');
+        }
+    }
+    const probeCode = [
+        'import json, pyaudio',
+        'pa=pyaudio.PyAudio()',
+        'rows=[pa.get_device_info_by_index(i) for i in range(pa.get_device_count())]',
+        'ins=[{"index":int(d["index"]),"name":d["name"],"channels":int(d["maxInputChannels"]),"rate":int(d["defaultSampleRate"])} for d in rows if d["maxInputChannels"]>0]',
+        'outs=[{"index":int(d["index"]),"name":d["name"],"channels":int(d["maxOutputChannels"]),"rate":int(d["defaultSampleRate"])} for d in rows if d["maxOutputChannels"]>0]',
+        'pa.terminate()',
+        'print(json.dumps({"inputs":ins,"outputs":outs}))',
+    ].join(';');
+    const probe = spawnSync(python, ['-c', probeCode], { encoding: 'utf8' });
+    if (probe.status !== 0)
+        throw new Error(`PyAudio device probe failed: ${probe.stderr || probe.stdout}`);
+    const inventory = JSON.parse(probe.stdout.trim());
+    // PortAudio on Debian Trixie can omit a valid USB capture endpoint even
+    // though ALSA exposes it. The runtime intentionally captures that device
+    // through arecord, so accept the same proven fallback during installation.
+    const alsaCapture = spawnSync('arecord', ['-l'], { encoding: 'utf8' });
+    const alsaInputs = String(alsaCapture.stdout ?? '').split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => /^card\s+\d+:.*device\s+\d+:/i.test(line));
+    if (!inventory.inputs.length && !alsaInputs.length) {
+        throw new Error('no real microphone input device registered with ALSA or PyAudio');
+    }
+    if (!inventory.outputs.length)
+        throw new Error('no real speaker output device registered with ALSA/PyAudio');
+    console.log(chalk.green(`  ✓ conversation dependencies installed and verified`));
+    console.log(`  microphones: ${inventory.inputs.length
+        ? inventory.inputs.map(d => `${d.name} (#${d.index}, ${d.rate}Hz)`).join(', ')
+        : `${alsaInputs.join(', ')} (direct ALSA capture)`}`);
+    console.log(`  speakers:    ${inventory.outputs.map(d => `${d.name} (#${d.index}, ${d.rate}Hz)`).join(', ')}`);
+}
+function positiveNumber(value, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        throw new Error(`${label} must be greater than zero`);
+    return parsed;
+}
+function nonNegativeNumber(value, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        throw new Error(`${label} must be zero or greater`);
+    return parsed;
+}
+function configPath(name) {
+    const safe = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'robot';
+    return join(homedir(), '.robopark', `conversation-${safe}.json`);
+}
+function activeConversationPath() {
+    return join(homedir(), '.robopark', 'active-conversation.json');
+}
+function conversationUnit(name) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'robot';
+    return `robopark-robot-conversation-${slug}.service`;
+}
+function listConversationUnits() {
+    if (process.platform !== 'linux')
+        return [];
+    const units = new Set();
+    for (const args of [
+        ['list-unit-files', 'robopark-robot-conversation-*.service', '--no-legend', '--no-pager'],
+        ['list-units', '--all', 'robopark-robot-conversation-*.service', '--no-legend', '--no-pager'],
+    ]) {
+        const listed = spawnSync('systemctl', args, { encoding: 'utf8' });
+        for (const line of String(listed.stdout ?? '').split(/\r?\n/)) {
+            const unit = line.trim().split(/\s+/, 1)[0];
+            if (/^robopark-robot-conversation-[a-z0-9-]+\.service$/.test(unit))
+                units.add(unit);
+        }
+    }
+    return [...units].sort();
+}
+function resolveConversationTarget(name) {
+    if (name?.trim()) {
+        const selected = name.trim();
+        return { name: selected, unit: conversationUnit(selected), configPath: configPath(selected) };
+    }
+    try {
+        const marker = JSON.parse(readFileSync(activeConversationPath(), 'utf8'));
+        if (marker.name && marker.unit && marker.configPath
+            && spawnSync('systemctl', ['cat', marker.unit], { stdio: 'ignore' }).status === 0)
+            return marker;
+    }
+    catch { /* existing installations may not have a marker yet */ }
+    const units = listConversationUnits();
+    if (!units.length)
+        throw new Error('no local conversation service is installed; run conversation up once');
+    let candidates = units.filter(unit => spawnSync('systemctl', ['is-enabled', unit], { stdio: 'ignore' }).status === 0);
+    if (candidates.length !== 1)
+        candidates = units;
+    if (candidates.length !== 1) {
+        throw new Error(`multiple conversation services exist (${candidates.join(', ')}); use --name once to select one`);
+    }
+    const unit = candidates[0];
+    const slug = unit.replace(/^robopark-robot-conversation-/, '').replace(/\.service$/, '');
+    const fragment = spawnSync('systemctl', ['show', unit, '--property=FragmentPath', '--value'], { encoding: 'utf8' });
+    let selectedConfig = configPath(slug);
+    try {
+        const unitText = readFileSync(String(fragment.stdout ?? '').trim(), 'utf8');
+        const match = unitText.match(/--config\s+(?:'([^']+)'|"([^"]+)"|(\S+))/);
+        selectedConfig = match?.[1] || match?.[2] || match?.[3] || selectedConfig;
+    }
+    catch { /* conventional config path remains a safe fallback */ }
+    return { name: slug, unit, configPath: selectedConfig };
+}
+function detectTailscaleIpv4() {
+    if (process.platform !== 'linux')
+        return null;
+    const result = spawnSync('tailscale', ['ip', '-4'], { encoding: 'utf8' });
+    if (result.status !== 0)
+        return null;
+    return result.stdout.split(/\s+/).find(value => /^100\.\d+\.\d+\.\d+$/.test(value)) ?? null;
+}
+function parseMotors(values = []) {
+    const motors = {};
+    for (const value of values) {
+        const match = value.trim().match(/^(\d+)\s*[-:=]\s*([a-zA-Z][a-zA-Z0-9_-]*)$/);
+        if (!match)
+            throw new Error(`invalid motor '${value}'; use PIN-NAME, for example 17-head`);
+        const pin = Number(match[1]);
+        if (pin < 0 || pin > 27)
+            throw new Error(`motor pin must be a BCM GPIO from 0 to 27: ${value}`);
+        const motorName = match[2].toLowerCase().replace(/_/g, '-');
+        if (motors[motorName] !== undefined)
+            throw new Error(`duplicate motor name: ${motorName}`);
+        if (Object.values(motors).includes(pin))
+            throw new Error(`GPIO${pin} is registered more than once`);
+        motors[motorName] = pin;
+    }
+    return motors;
+}
+async function elevenLabsRequest(apiKey, path, init = {}) {
+    const response = await fetch(`https://api.elevenlabs.io${path}`, {
+        ...init,
+        headers: {
+            'Content-Type': 'application/json',
+            'xi-api-key': apiKey,
+            ...(init.headers ?? {}),
+        },
+    });
+    const text = await response.text();
+    const payload = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+        const detail = payload?.detail?.message ?? payload?.detail ?? payload?.message ?? text;
+        throw new Error(`ElevenLabs ${init.method ?? 'GET'} ${path} failed (${response.status}): ${typeof detail === 'string' ? detail : JSON.stringify(detail)}`);
+    }
+    return payload;
+}
+async function provisionMotorTool(apiKey, agentId) {
+    const listed = await elevenLabsRequest(apiKey, '/v1/convai/tools?page_size=100');
+    let tool = (listed.tools ?? []).find((candidate) => candidate?.tool_config?.type === 'client' && candidate?.tool_config?.name === 'robotMotor');
+    if (!tool) {
+        tool = await elevenLabsRequest(apiKey, '/v1/convai/tools', {
+            method: 'POST',
+            body: JSON.stringify({
+                tool_config: {
+                    type: 'client',
+                    name: 'robotMotor',
+                    description: 'Safely activate a named motor or relay registered by the current RoboPark robot. Use pulse for movement and off to deactivate.',
+                    expects_response: true,
+                    response_timeout_secs: 5,
+                    parameters: {
+                        type: 'object',
+                        required: ['name'],
+                        description: 'A bounded command for one registered robot output.',
+                        properties: {
+                            name: { type: 'string', description: 'Registered motor name supplied in the current robot context.' },
+                            action: { type: 'string', enum: ['pulse', 'on', 'activate', 'move', 'off'], description: 'Requested bounded action.' },
+                            duration_ms: { type: 'integer', minimum: 50, maximum: 3000, description: 'Activation duration in milliseconds.' },
+                        },
+                    },
+                },
+            }),
+        });
+    }
+    const toolId = tool.id;
+    if (!toolId)
+        throw new Error('ElevenLabs returned a motor tool without an id');
+    const agent = await elevenLabsRequest(apiKey, `/v1/convai/agents/${encodeURIComponent(agentId)}`);
+    const conversationConfig = structuredClone(agent?.conversation_config ?? {});
+    const agentConfig = conversationConfig.agent ??= {};
+    if (!String(agentConfig.first_message ?? '').trim()) {
+        const agentName = String(agent?.name ?? 'your RoboPark guide').trim() || 'your RoboPark guide';
+        agentConfig.first_message = `Hello, I am ${agentName}. How can I help you today?`;
+    }
+    const promptConfig = agentConfig.prompt ??= {};
+    const existingIds = promptConfig.tool_ids ?? [];
+    promptConfig.tool_ids = existingIds.includes(toolId) ? existingIds : [...existingIds, toolId];
+    // ElevenLabs may still return the deprecated inline field for older agents,
+    // but rejects PATCH payloads containing both it and the migrated tool IDs.
+    delete promptConfig.tools;
+    const motorPolicyMarker = '[RoboPark motor policy]';
+    const existingPrompt = String(promptConfig.prompt ?? '');
+    if (!existingPrompt.includes(motorPolicyMarker)) {
+        promptConfig.prompt = `${existingPrompt}\n\n${motorPolicyMarker}\nWhen a user asks the robot to move, turn, activate, test, or switch a physical part, you MUST call the robotMotor client tool before confirming the action. Map the requested part to one of the registered motor names supplied in the current session context. Use action \"pulse\" unless the user explicitly asks to switch it off. Never claim physical movement occurred unless the tool returned success.`.trim();
+    }
+    // Send the complete configuration back. A nested partial PATCH can replace
+    // sibling conversation/TTS fields and silently leave an agent in text-only
+    // mode, which produces transcripts but no speaker audio on the robot.
+    const sessionConfig = conversationConfig.conversation ??= {};
+    sessionConfig.text_only = false;
+    const clientEvents = sessionConfig.client_events ?? [];
+    sessionConfig.client_events = [...new Set([...clientEvents, 'audio', 'interruption'])];
+    const ttsConfig = conversationConfig.tts ??= {};
+    ttsConfig.agent_output_audio_format = 'pcm_16000';
+    await elevenLabsRequest(apiKey, `/v1/convai/agents/${encodeURIComponent(agentId)}`, {
+        method: 'PATCH',
+        body: JSON.stringify({
+            conversation_config: conversationConfig,
+            version_description: 'RoboPark robotMotor registration with audio settings preserved',
+        }),
+    });
+    return toolId;
+}
+export async function roboparkConversationUp(opts) {
+    const name = opts.name?.trim() || hostname();
+    const tailscaleIp = detectTailscaleIpv4();
+    const apiKey = opts.apiKey?.trim() || process.env.ELEVENLABS_API_KEY?.trim();
+    if (!opts.publicAgent && !apiKey) {
+        throw new Error('ELEVENLABS_API_KEY is required for a private agent (or pass --public-agent)');
+    }
+    const script = await findConversationPath();
+    if (!script)
+        throw new Error('packaged ElevenLabs conversation runtime was not found');
+    const python = prepareRobotPython(findPython(), script, ['elevenlabs', 'pyaudio'], 'requirements.txt');
+    if (!python)
+        throw new Error('could not prepare the robot conversation Python environment');
+    let visionScript = null;
+    let manageVision = opts.manageVision !== false && opts.motion !== false;
+    const visionUrl = new URL(opts.visionUrl);
+    if (manageVision && !['127.0.0.1', 'localhost', '::1'].includes(visionUrl.hostname)) {
+        manageVision = false;
+        console.log(chalk.yellow('  ! remote --vision-url detected; RoboVision process supervision is disabled'));
+    }
+    if (manageVision) {
+        visionScript = await findVisionPath();
+        if (!visionScript)
+            throw new Error('packaged RoboVision camera runtime was not found');
+        const visionPython = prepareRobotPython(findPython(), visionScript, VISION_REQUIRED_MODULES, 'requirements_camera.txt');
+        if (!visionPython)
+            throw new Error('could not prepare the RoboVision camera environment');
+        if (resolve(visionPython) !== resolve(python)) {
+            throw new Error('conversation and RoboVision must use the same managed Python environment');
+        }
+    }
+    const motors = parseMotors(opts.motor);
+    if (Object.keys(motors).length && opts.provisionAgentTools !== false) {
+        if (!apiKey)
+            throw new Error('an API key is required to provision the ElevenLabs motor tool');
+        const toolId = await provisionMotorTool(apiKey, opts.agentId.trim());
+        console.log(chalk.green(`  ✓ ElevenLabs robotMotor tool ready and attached (${toolId})`));
+    }
+    const path = configPath(name);
+    const statusToken = tailscaleIp ? randomBytes(24).toString('hex') : null;
+    const telemetry = schedulerTelemetryIdentity();
+    const config = {
+        agent_id: opts.agentId.trim(),
+        branch_id: opts.branchId?.trim() || null,
+        api_key: apiKey || null,
+        requires_auth: !opts.publicAgent,
+        always_on: Boolean(opts.alwaysOn),
+        robot_name: name,
+        audio_input: opts.audioInput,
+        audio_output: opts.audioOutput,
+        motion_enabled: opts.motion !== false,
+        voice_trigger_enabled: opts.voiceTrigger !== false,
+        motion_host: opts.motionHost,
+        status_bind_host: tailscaleIp ? '0.0.0.0' : opts.motionHost,
+        tailscale_status_ip: tailscaleIp,
+        tailscale_status_token: statusToken,
+        config_path: resolve(path),
+        motion_port: positiveNumber(opts.motionPort, 'motion port'),
+        vision_url: opts.visionUrl.replace(/\/$/, ''),
+        manage_vision: manageVision,
+        vision_script: visionScript ? resolve(visionScript) : null,
+        vision_python: manageVision ? resolve(python) : null,
+        vision_port: Number(visionUrl.port || (visionUrl.protocol === 'https:' ? 443 : 80)),
+        camera_device: opts.cameraDevice,
+        voice_threshold: positiveNumber(opts.voiceThreshold, 'voice threshold'),
+        idle_timeout: nonNegativeNumber(opts.idleTimeout, 'idle timeout'),
+        max_session: nonNegativeNumber(opts.maxSession, 'max session'),
+        cooldown: positiveNumber(opts.cooldown, 'cooldown'),
+        // The local supervisor owns repeated session disposal. Per-session process
+        // recycling creates avoidable ALSA and port races on long-running robots.
+        recycle_after_session: false,
+        voice_engine_default: 'elevenlabs',
+        robovoice_enabled: true,
+        allow_session_override: true,
+        apply_changes_when_idle: true,
+        desired_revision: 1,
+        applied_revision: 1,
+        character_id: name,
+        motors,
+        motor_active_high: Boolean(opts.motorActiveHigh),
+        motor_pulse_ms: positiveNumber(opts.motorPulseMs, 'motor pulse'),
+        scheduler_url: telemetry?.schedulerUrl ?? null,
+        scheduler_device_id: telemetry?.deviceId ?? null,
+        scheduler_device_token: telemetry?.deviceToken ?? null,
+    };
+    mkdirSync(join(homedir(), '.robopark'), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch { /* Windows has no POSIX mode enforcement. */ }
+    console.log(chalk.bold('\n  robopark conversation'));
+    console.log(chalk.dim('  ' + '─'.repeat(48)));
+    console.log(`  robot:   ${name}`);
+    console.log(`  agent:   ${opts.agentId}`);
+    if (config.branch_id)
+        console.log(`  branch:  ${config.branch_id}`);
+    console.log(`  mode:    ${config.always_on ? 'always-on with automatic reconnect' : 'triggered'}`);
+    console.log(`  input:   ${opts.audioInput}`);
+    console.log(`  output:  ${opts.audioOutput}`);
+    console.log(`  motion:  ${config.motion_enabled ? `http://${opts.motionHost}:${opts.motionPort}/` : 'off'}`);
+    console.log(`  vision:  ${config.motion_enabled ? (manageVision ? `managed camera ${opts.cameraDevice}` : opts.visionUrl) : 'off'}`);
+    console.log(`  voice:   ${config.voice_trigger_enabled ? `armed (threshold ${opts.voiceThreshold})` : 'off'}`);
+    console.log(`  timeout: ${opts.idleTimeout}s idle / ${opts.maxSession}s maximum\n`);
+    if (tailscaleIp)
+        console.log(`  devices: http://${tailscaleIp}:${opts.motionPort}/?token=${statusToken}\n`);
+    if (Object.keys(config.motors).length) {
+        console.log(`  motors:  ${Object.entries(config.motors).map(([motor, pin]) => `${motor}=GPIO${pin}`).join(', ')}`);
+        console.log('  tool:    robotMotor(name, action, duration_ms)\n');
+    }
+    console.log(`  oversight:${telemetry ? chalk.green(' centralized sessions + transcripts') : chalk.yellow(' local only (run robot setup once to register)')}\n`);
+    if (opts.autoStart) {
+        // The legacy unified runtime owns the same camera and ALSA devices. Retire
+        // it so one command cannot leave two services fighting over hardware.
+        const legacy = unregisterAutoStart('robot-runtime', name);
+        if (!legacy.ok)
+            throw new Error(`could not retire conflicting legacy runtime: ${legacy.message}`);
+        const result = await registerAutoStart({
+            role: 'robot-conversation',
+            name,
+            command: resolve(python),
+            args: [resolve(script), '--config', resolve(path)],
+            workingDir: homedir(),
+            env: { PYTHONUNBUFFERED: '1' },
+            // Every conversation mode ultimately opens the same physical devices.
+            // Ownership must therefore be exclusive even before its first trigger.
+            exclusiveMedia: true,
+        });
+        if (!result.ok)
+            throw new Error(result.message);
+        const selected = { name, unit: conversationUnit(name), configPath: resolve(path) };
+        writeFileSync(activeConversationPath(), `${JSON.stringify(selected, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        try {
+            chmodSync(activeConversationPath(), 0o600);
+        }
+        catch { /* Windows has no POSIX mode enforcement. */ }
+        await waitForConversationReady(Number(config.motion_port), Boolean(config.always_on));
+        console.log(chalk.dim(`  legacy: ${legacy.message}`));
+        console.log(chalk.green(`  ✓ ${result.message}`));
+        return;
+    }
+    const child = spawn(python, [script, '--config', path], {
+        stdio: 'inherit',
+        env: { ...process.env, PYTHONUNBUFFERED: '1' },
+    });
+    await new Promise((resolvePromise, reject) => {
+        child.once('error', reject);
+        child.once('exit', code => code === 0
+            ? resolvePromise()
+            : reject(new Error(`conversation runtime exited with code ${code}`)));
+    });
+}
+export function roboparkConversationDown(name) {
+    const target = resolveConversationTarget(name);
+    const result = unregisterAutoStart('robot-conversation', target.name);
+    if (!result.ok)
+        throw new Error(result.message);
+    console.log(chalk.green(`  ✓ ${result.message}`));
+}
+export function roboparkConversationStop(name) {
+    if (process.platform !== 'linux')
+        throw new Error('conversation stop currently requires systemd on Linux');
+    const units = name?.trim() ? [conversationUnit(name.trim())] : listConversationUnits();
+    if (!units.length)
+        throw new Error('no local conversation services were found');
+    const failures = [];
+    for (const unit of units) {
+        const stopped = spawnSync('systemctl', ['stop', unit], { encoding: 'utf8' });
+        if (stopped.status !== 0)
+            failures.push(`${unit}: ${stopped.stderr || stopped.stdout}`);
+    }
+    if (failures.length)
+        throw new Error(`could not stop conversation service: ${failures.join('; ')}`);
+    console.log(chalk.green(`  ✓ stopped ${units.join(', ')}`));
+}
+async function waitForConversationReady(port, requireAudio) {
+    const endpoint = `http://127.0.0.1:${port}/`;
+    let lastError = '';
+    for (let attempt = 0; attempt < 120; attempt += 1) {
+        try {
+            const response = await fetch(endpoint, { signal: AbortSignal.timeout(1000) });
+            if (response.ok) {
+                const status = await response.json();
+                lastError = status.last_error ?? '';
+                if (!requireAudio || (status.active && status.active_audio?.active))
+                    return;
+            }
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : String(error);
+        }
+        await new Promise(resolvePromise => setTimeout(resolvePromise, 500));
+    }
+    throw new Error(`conversation endpoint on port ${port} did not become ${requireAudio ? 'audio-ready' : 'ready'} within 60 seconds`
+        + (lastError ? `; last error: ${lastError}` : ''));
+}
+export async function roboparkConversationStart(name, trigger = false) {
+    if (process.platform !== 'linux')
+        throw new Error('conversation start currently requires systemd on Linux');
+    const target = resolveConversationTarget(name);
+    const unit = target.unit;
+    const slug = unit.replace(/^robopark-robot-conversation-/, '').replace(/\.service$/, '');
+    spawnSync('systemctl', ['stop', `robopark-robot-runtime-${slug}.service`], { stdio: 'ignore' });
+    spawnSync('systemctl', ['reset-failed', unit], { stdio: 'ignore' });
+    const restarted = spawnSync('systemctl', ['restart', unit], { encoding: 'utf8' });
+    if (restarted.status !== 0) {
+        throw new Error(`systemctl restart failed: ${restarted.stderr || restarted.stdout}`);
+    }
+    const config = JSON.parse(readFileSync(target.configPath, 'utf8'));
+    const port = config.motion_port || 5057;
+    const endpoint = `http://127.0.0.1:${port}/`;
+    await waitForConversationReady(port, Boolean(config.always_on));
+    console.log(chalk.green(`  ✓ ${unit} restarted and ready`));
+    if (trigger) {
+        const response = await fetch(endpoint, { method: 'POST', signal: AbortSignal.timeout(3000) });
+        const body = await response.text();
+        if (!response.ok)
+            throw new Error(`trigger failed (${response.status}): ${body}`);
+        console.log(chalk.green(`  ✓ conversation trigger accepted: ${body}`));
+    }
+}
+export async function roboparkConversationRestart(name, trigger = false) {
+    await roboparkConversationStart(name, trigger);
+}

package/dist/robopark/deployment-commands.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+function loadProductionConfig() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, '..', '..', 'scheduler', 'production_config.json'),
+        join(here, '..', '..', '..', 'packages', 'robopark', 'scheduler', 'production_config.json'),
+    ];
+    for (const path of candidates) {
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            // Try the source-tree or installed-package layout next.
+        }
+    }
+    throw new Error('packaged production character configuration was not found');
+}
+export function productionCharacters() {
+    return loadProductionConfig().characters
+        .filter(character => character.default_engine === 'elevenlabs' && character.elevenlabs_agent_id)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+export function deploymentCommandSheet(options) {
+    const install = `npm install -g robopark@${options.version}`;
+    const token = options.token?.trim() || 'rp1_<token-from-gateway>';
+    const publicUrl = options.publicUrl?.trim() || 'https://<gateway-tailnet-or-domain>';
+    const characters = productionCharacters();
+    const lines = [
+        'ROBOPARK DEPLOYMENT COMMANDS',
+        '',
+        'GATEWAY DEVICE',
+        install,
+        `robopark --password '<activation-password>' gateway start --public-url ${publicUrl}`,
+        '',
+        'EACH ROBOT DEVICE (run install/connect once, then its start command)',
+        install,
+        `robopark connect ${token}`,
+        '',
+    ];
+    for (const character of characters) {
+        lines.push(`${character.name}: robopark start --voice --video --character ${character.id}`);
+    }
+    lines.push('', 'OPERATIONS', 'robopark status', 'robopark gateway start', '', `${characters.length} verified character commands - production config revision ${loadProductionConfig().revision}`);
+    return lines.join('\n');
+}