@ciphore/radiocli 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -5,7 +5,52 @@ All notable changes to RadioCLI are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.2.3] - 2026-09-07
+
+### Added
+
+- Added opt-in local coding-agent control through both a typed stdio MCP server
+  and `radiocli agent` shell commands, covering discovery, playback, favorites,
+  listening stats, appearance, and configurable task-completion actions.
+- Added automatic MCP setup for detected Codex, Claude Code, OpenCode, Cursor,
+  Gemini CLI, VS Code/Copilot Agent Host, and Orca-backed runtimes, plus a
+  portable configuration for other MCP clients.
+- Added typed MCP and voice-accessible alarm management, active ringing
+  controls, and macOS AirPlay discovery, receiver selection, local-output
+  switching, and ephemeral passcode submission.
+- Added `radiocli update --install`, package-manager-aware upgrade commands,
+  an in-app update indicator, read-only MCP update status, and
+  `radiocli mcp repair`.
+- Added Agent settings for installing or repairing MCP integrations and choosing
+  between a visible terminal player and headless playback.
+- Added the animated Gallop receiver as the new default and a color-field
+  Crossfade receiver.
+
+### Fixed
+
+- Agent playback continues to open the terminal TUI by default on every platform,
+  while interactive setup now explains the macOS Automation prompt and offers an
+  explicit headless opt-out. MCP guidance prevents ordinary task-completion radio
+  actions from creating implicit goals or monitors.
+- MCP registrations now use upgrade-stable, directly executable launchers,
+  including a shell-free Node command on Windows, and enabled registrations are
+  repaired after an in-app or CLI update.
+- Active interactive or agent playback now yields cleanly when an alarm begins,
+  preventing overlapping streams while preserving the alarm if TUI handoff fails.
+- Kept the Countries station-count column fixed while scrolling, added focused
+  marquee reading for overlong country and station names across Explore,
+  Library, and Nearby, and aligned Overview descriptions behind a compact
+  separator-free title column.
+
+### Security
+
+- Agent playback uses a single-owner, authenticated loopback session with
+  serialized commands, private discovery files, and strict isolation from
+  active alarm sessions. Agent tools accept saved or RadioCLI-discovered station
+  IDs rather than arbitrary stream URLs.
+- Alarm removal requires an exact ID and explicit confirmation. AirPlay receiver
+  IDs must come from local discovery, and receiver passcodes are never persisted
+  or echoed by agent responses.
 
 ## [0.2.2] - 2026-09-04
 
@@ -351,6 +396,7 @@ Initial public release.
 [0.2.0]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.0
 [0.2.1]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.1
 [0.2.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.2
+[0.2.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.2.3
 [0.1.4]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.4
 [0.1.3]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.3
 [0.1.2]: https://github.com/Ciphore/RadioCLI/releases/tag/v0.1.2

package/README.md

@@ -94,6 +94,24 @@ covers filters, playback, media-key learning, AirPlay, and every command.
 
 ## CLI
 
+RadioCLI can also be controlled by local coding agents. Run `radiocli setup`
+and opt into MCP, or use `radiocli setup --mcp`, to configure detected Codex,
+Claude, OpenCode, Cursor, Gemini, VS Code/Copilot, and Orca-backed runtimes
+automatically. From the TUI, open **Settings → Agent control & MCP** and turn on
+**Allow local agent control** for the same one-step setup—no terminal command is
+required. The same actions are
+available to non-MCP harnesses through `radiocli agent` and `radiocli alarm`:
+search and play stations, browse recents/favorites/nearby stations, favorite the
+current station, inspect listening stats, create and control alarms, control
+macOS AirPlay, change the receiver look, or run a user-configured completion
+preset. Codex Voice can invoke those same typed MCP tools. Agent playback opens
+the normal RadioCLI TUI in a terminal window by default on macOS, Windows, and
+Linux. Interactive setup explains that macOS may require the agent host to approve
+a one-time Automation prompt; users can explicitly opt into headless playback.
+Scheduled alarms remain isolated and always use local output rather than
+unattended AirPlay. See the
+[CLI guide](apps/docs/content/docs/getting-started/cli.mdx#local-agent-and-mcp-control).
+
 ```bash
 radiocli                 # Start the TUI
 radiocli check           # Check providers, playback tools, and the local store
@@ -105,8 +123,20 @@ radiocli export favorites.m3u
 radiocli add-url <stream-url> [station name]
 radiocli alarm list
 radiocli alarm doctor
+radiocli update --install # Upgrade and repair enabled MCP registrations
 ```
 
+Existing installations keep their library and preferences when upgraded. Use
+`radiocli update` to inspect the detected Homebrew, npm, pnpm, or Bun command,
+or `radiocli update --install` to run it. MCP registrations use an
+upgrade-stable launcher so versioned package paths do not break them. On
+Windows this is a shell-free Node command; on Unix it uses the `radiocli` shim.
+Run `radiocli mcp status` to inspect registrations and `radiocli mcp repair`
+after moving an installation or when an agent client reports a stale server;
+fully quit and reopen agent clients after enabling, repairing, or upgrading.
+Until that restart, even a newly created task in an already-running client will
+not have RadioCLI's tools and may incorrectly fall back to browser playback.
+
 RadioCLI imports `.m3u`, `.pls`, and `.xspf` playlists. It exports favorites
 and imported streams as `.m3u`.
 

package/dist/agent/alarm-service.js

@@ -0,0 +1,210 @@
+import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone, nextOccurrenceForAlarm } from '../alarms/schedule.js';
+import { connectActiveAlarms } from '../alarms/active-session.js';
+import { createSchedulerService } from '../alarms/scheduler.js';
+export class AgentAlarmService {
+    store;
+    resolveStation;
+    scheduler;
+    handoffToInteractive;
+    constructor(store, resolveStation, scheduler = createSchedulerService(), handoffToInteractive) {
+        this.store = store;
+        this.resolveStation = resolveStation;
+        this.scheduler = scheduler;
+        this.handoffToInteractive = handoffToInteractive;
+    }
+    async list() {
+        return Promise.all(this.store.listAlarms().map(alarm => this.describe(alarm)));
+    }
+    async status() {
+        const alarms = this.store.listAlarms();
+        return {
+            active: await this.activeStatuses(),
+            scheduler: await this.scheduler.runtimeStatus(alarms),
+            alarms: await Promise.all(alarms.map(alarm => this.describe(alarm)))
+        };
+    }
+    async create(input) {
+        const station = await this.requiredStation(input.stationId);
+        const fallbackStation = input.fallbackStationId
+            ? await this.requiredStation(input.fallbackStationId)
+            : undefined;
+        const alarmInput = {
+            label: cleanLabel(input.label ?? station.name),
+            enabled: input.enabled ?? true,
+            station,
+            schedule: normalizeSchedule(input.schedule),
+            playback: {
+                volume: boundedInteger(input.volume ?? 40, 'volume', 0, 100),
+                fadeSeconds: boundedInteger(input.fadeSeconds ?? 0, 'fadeSeconds', 0, 3600),
+                stopAfterMinutes: boundedInteger(input.stopAfterMinutes ?? 60, 'stopAfterMinutes', 1, 10080),
+                ...(fallbackStation ? { fallbackStation } : {})
+            },
+            reliability: {
+                missedRunGraceMinutes: boundedInteger(input.missedRunGraceMinutes ?? 10, 'missedRunGraceMinutes', 0, 10080),
+                wakeIfSupported: input.wakeIfSupported ?? false,
+                keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? false
+            }
+        };
+        const alarm = this.store.addAlarm(alarmInput);
+        await this.syncSaved(alarm);
+        return this.describe(alarm);
+    }
+    async update(id, input) {
+        const alarm = this.requiredAlarm(id);
+        const station = input.stationId ? await this.requiredStation(input.stationId) : alarm.station;
+        const fallbackStation = input.clearFallback
+            ? undefined
+            : input.fallbackStationId ? await this.requiredStation(input.fallbackStationId) : alarm.playback.fallbackStation;
+        const updated = this.store.updateAlarm(alarm.id, {
+            label: input.label === undefined ? alarm.label : cleanLabel(input.label),
+            enabled: input.enabled ?? alarm.enabled,
+            station,
+            schedule: input.schedule ? normalizeSchedule(input.schedule) : alarm.schedule,
+            playback: {
+                volume: boundedInteger(input.volume ?? alarm.playback.volume, 'volume', 0, 100),
+                fadeSeconds: boundedInteger(input.fadeSeconds ?? alarm.playback.fadeSeconds, 'fadeSeconds', 0, 3600),
+                stopAfterMinutes: boundedInteger(input.stopAfterMinutes ?? alarm.playback.stopAfterMinutes, 'stopAfterMinutes', 1, 10080),
+                ...(fallbackStation ? { fallbackStation } : {})
+            },
+            reliability: {
+                missedRunGraceMinutes: boundedInteger(input.missedRunGraceMinutes ?? alarm.reliability.missedRunGraceMinutes, 'missedRunGraceMinutes', 0, 10080),
+                wakeIfSupported: input.wakeIfSupported ?? alarm.reliability.wakeIfSupported,
+                keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? alarm.reliability.keepAwakeUntilAlarm
+            }
+        });
+        await this.syncSaved(updated);
+        return this.describe(updated);
+    }
+    async setEnabled(id, enabled) {
+        const alarm = this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
+        await this.syncSaved(alarm);
+        return this.describe(alarm);
+    }
+    async remove(id, confirm) {
+        if (!confirm)
+            throw new Error('Alarm removal requires confirm=true. List alarms first and confirm the exact alarm ID with the user.');
+        const alarm = this.requiredAlarm(id);
+        await this.scheduler.remove(alarm.id);
+        if (!this.store.removeAlarm(alarm.id))
+            throw new Error(`Alarm not found: ${id}`);
+        return { ok: true, removed: alarm.id };
+    }
+    async sync() {
+        return this.scheduler.syncAll(this.store.listAlarms());
+    }
+    async controlActive(input) {
+        const { client, status } = await this.selectActive(input.alarmId, input.occurrenceAt);
+        if (input.action === 'dismiss')
+            await client.dismiss();
+        else if (input.action === 'keep-playing')
+            await client.keepPlaying();
+        else if (input.action === 'handoff') {
+            if (status.state !== 'playing')
+                throw new Error('Alarm playback is still starting.');
+            if (!this.handoffToInteractive)
+                throw new Error('Interactive playback handoff is unavailable.');
+            await this.handoffToInteractive(status);
+            await client.handoff();
+        }
+        else
+            await client.snooze(boundedInteger(input.snoozeMinutes ?? 10, 'snoozeMinutes', 1, 1440));
+        return { ok: true, action: input.action, alarm: activeStatusForAgent(status) };
+    }
+    async describe(alarm) {
+        return {
+            id: alarm.id,
+            label: alarm.label,
+            enabled: alarm.enabled,
+            station: { id: `${alarm.station.provider}:${alarm.station.id}`, name: alarm.station.name },
+            schedule: alarm.schedule,
+            nextOccurrence: nextOccurrenceForAlarm(alarm, new Date())?.toISOString() ?? null,
+            playback: {
+                volume: alarm.playback.volume,
+                fadeSeconds: alarm.playback.fadeSeconds,
+                stopAfterMinutes: alarm.playback.stopAfterMinutes,
+                ...(alarm.playback.fallbackStation ? { fallbackStation: {
+                        id: `${alarm.playback.fallbackStation.provider}:${alarm.playback.fallbackStation.id}`,
+                        name: alarm.playback.fallbackStation.name
+                    } } : {})
+            },
+            reliability: alarm.reliability,
+            lastRun: alarm.lastRun,
+            snoozedUntil: alarm.nextOverride?.at
+        };
+    }
+    async activeStatuses() {
+        return (await Promise.all((await connectActiveAlarms()).map(client => client.status()))).map(activeStatusForAgent);
+    }
+    async selectActive(alarmId, occurrenceAt) {
+        const matches = [];
+        for (const client of await connectActiveAlarms()) {
+            const status = await client.status();
+            if ((!alarmId || status.alarmId === alarmId) && (!occurrenceAt || status.scheduledAt === occurrenceAt))
+                matches.push({ client, status });
+        }
+        if (!matches.length)
+            throw new Error('No matching alarm is currently ringing.');
+        if (matches.length > 1)
+            throw new Error('Multiple alarms are ringing. List alarm status, then provide alarm_id and optionally occurrence_at.');
+        return matches[0];
+    }
+    requiredAlarm(id) {
+        const alarm = this.store.getAlarm(id);
+        if (!alarm)
+            throw new Error(`Alarm not found: ${id}`);
+        return alarm;
+    }
+    async requiredStation(id) {
+        const station = await this.resolveStation(id);
+        if (!station)
+            throw new Error(`Unknown station ID: ${id}. Search or browse first.`);
+        return station;
+    }
+    async syncSaved(alarm) {
+        try {
+            await this.scheduler.sync(alarm);
+        }
+        catch (error) {
+            throw new Error(`Alarm ${alarm.id} was saved, but scheduler setup is degraded: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function normalizeSchedule(schedule) {
+    if (schedule.type === 'once') {
+        const instant = new Date(schedule.at);
+        if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(schedule.at) || !Number.isFinite(instant.getTime()) || instant.getUTCSeconds() !== 0 || instant.getUTCMilliseconds() !== 0) {
+            throw new Error('One-time alarms require an absolute ISO-8601 minute with an offset or Z and zero seconds.');
+        }
+        if (instant.getTime() <= Date.now())
+            throw new Error('One-time alarms must be scheduled in the future.');
+        return { type: 'once', at: instant.toISOString() };
+    }
+    return {
+        type: 'recurring',
+        time: canonicalizeAlarmTime(schedule.time),
+        weekdays: canonicalizeIsoWeekdays(schedule.weekdays),
+        timezone: canonicalizeTimeZone(schedule.timezone)
+    };
+}
+function boundedInteger(value, label, min, max) {
+    if (!Number.isInteger(value) || value < min || value > max)
+        throw new Error(`${label} must be an integer from ${min} to ${max}.`);
+    return value;
+}
+function cleanLabel(value) {
+    const label = value.trim();
+    if (!label || label.length > 120 || /[\u0000-\u001F\u007F-\u009F]/.test(label))
+        throw new Error('Alarm label must be 1-120 printable characters.');
+    return label;
+}
+function activeStatusForAgent(status) {
+    return {
+        alarmId: status.alarmId,
+        scheduledAt: status.scheduledAt,
+        stationName: status.stationName,
+        ...(status.station ? { station: { id: `${status.station.provider}:${status.station.id}`, name: status.station.name } } : {}),
+        startedAt: status.startedAt,
+        state: status.state,
+        keepPlaying: status.keepPlaying
+    };
+}

package/dist/agent/cli.js

@@ -0,0 +1,193 @@
+import { AgentRadioService, stationForAgent } from './service.js';
+import { configureMcpIntegrations, mcpIntegrationReport, portableMcpConfig } from './mcp-install.js';
+import { runMcpServer } from './mcp-server.js';
+export async function runMcpCommand(args, runtime) {
+    const command = args[0] ?? 'status';
+    if (command === 'serve')
+        return runMcpServer(runtime);
+    if (command === 'enable' || command === 'install' || command === 'repair') {
+        assertMcpInstallSucceeded(await configureMcpIntegrations(true, runtime), 'configured');
+        return;
+    }
+    if (command === 'disable' || command === 'remove') {
+        assertMcpInstallSucceeded(await configureMcpIntegrations(false, runtime), 'removed');
+        return;
+    }
+    if (command === 'config') {
+        console.log(JSON.stringify(portableMcpConfig(runtime), null, 2));
+        return;
+    }
+    if (command === 'status' || command === 'doctor') {
+        console.log(JSON.stringify(await mcpIntegrationReport(runtime), null, 2));
+        return;
+    }
+    throw new Error('Usage: radiocli mcp <enable|install|repair|disable|status|config|serve>');
+}
+export async function runAgentCliCommand(args, runtime) {
+    const service = new AgentRadioService(runtime);
+    const [command = 'status', ...rest] = args;
+    let value;
+    if (command === 'status')
+        value = await service.status();
+    else if (command === 'search')
+        value = (await service.search(requiredText(rest, 'Usage: radiocli agent search <query>'))).map(stationForAgent);
+    else if (command === 'browse') {
+        const kind = parseBrowseKind(rest[0]);
+        if (rest.length > 2)
+            throw new Error('Usage: radiocli agent browse [favorites|recent|popular|nearby|countries|track-history] [1-50]');
+        const items = await service.browse(kind, rest[1] === undefined ? 20 : integerInRange(rest[1], 1, 50, 'Browse limit'));
+        value = ['favorites', 'recent', 'popular', 'nearby'].includes(kind)
+            ? items.map(stationForAgent)
+            : items;
+    }
+    else if (command === 'play')
+        value = await service.play(parsePlayArgs(rest));
+    else if (command === 'pause' || command === 'resume' || command === 'stop' || command === 'next' || command === 'previous')
+        value = await service.control({ type: command });
+    else if (command === 'volume') {
+        if (rest.length !== 1)
+            throw new Error('Usage: radiocli agent volume <0-100>');
+        value = await service.control({ type: 'set-volume', volume: numberInRange(rest[0], 0, 100, 'Volume') });
+    }
+    else if (command === 'mute' || command === 'unmute')
+        value = await service.control({ type: 'set-muted', muted: command === 'mute' });
+    else if (command === 'favorite' || command === 'unfavorite')
+        value = await service.setFavorite(command === 'favorite', rest[0]);
+    else if (command === 'stats')
+        value = service.stats();
+    else if (command === 'appearance')
+        value = await parseAppearance(rest, service);
+    else if (command === 'airplay')
+        value = await runAirPlayCommand(rest, service);
+    else if (command === 'preset')
+        value = service.configureCompletionPreset(parsePreset(rest));
+    else if (command === 'done')
+        value = await service.runCompletionPreset();
+    else
+        throw new Error('Usage: radiocli agent <status|search|browse|play|pause|resume|stop|next|previous|volume|mute|unmute|favorite|unfavorite|stats|appearance|airplay|preset|done>');
+    console.log(JSON.stringify(value, null, 2));
+}
+function parseBrowseKind(value) {
+    const kind = value ?? 'recent';
+    if (!['favorites', 'recent', 'popular', 'nearby', 'countries', 'track-history'].includes(kind))
+        throw new Error('Browse kind must be favorites, recent, popular, nearby, countries, or track-history.');
+    return kind;
+}
+function parsePlayArgs(args) {
+    const result = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--source')
+            result.source = stationSource(required(args[++index], '--source requires recent, favorite, popular, or country.'));
+        else if (arg === '--country') {
+            result.source = 'country';
+            result.countryCode = countryCode(required(args[++index], '--country requires a two-letter code.'));
+        }
+        else if (arg === '--random')
+            result.random = true;
+        else if (arg === '--no-ui')
+            result.openUi = false;
+        else if (arg === '--keep-playing')
+            result.ifPlaying = 'keep';
+        else if (!result.stationId)
+            result.stationId = arg;
+        else
+            throw new Error(`Unknown play option: ${arg}`);
+    }
+    return result;
+}
+function parseAppearance(args, service) {
+    if (args.length === 0)
+        return service.appearance();
+    const input = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--theme')
+            input.theme = required(args[++index], '--theme requires a theme name.');
+        else if (arg === '--receiver-style')
+            input.receiverStyle = required(args[++index], '--receiver-style requires a style name.');
+        else
+            throw new Error(`Unknown appearance option: ${arg}`);
+    }
+    return service.updateAppearance(input);
+}
+function parsePreset(args) {
+    const input = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--action')
+            input.action = presetAction(required(args[++index], '--action requires play, pause, resume, or stop.'));
+        else if (arg === '--source')
+            input.source = stationSource(required(args[++index], '--source requires recent, favorite, popular, or country.'));
+        else if (arg === '--country') {
+            input.source = 'country';
+            input.countryCode = countryCode(required(args[++index], '--country requires a two-letter code.'));
+        }
+        else if (arg === '--keep-playing')
+            input.ifPlaying = 'keep';
+        else if (arg === '--replace')
+            input.ifPlaying = 'replace';
+        else if (arg === '--open-ui')
+            input.openUi = true;
+        else if (arg === '--no-ui')
+            input.openUi = false;
+        else
+            throw new Error(`Unknown preset option: ${arg}`);
+    }
+    return input;
+}
+async function runAirPlayCommand(args, service) {
+    const [action = 'list', ...rest] = args;
+    if (action === 'list')
+        return service.listAirPlayDevices();
+    if (action === 'select')
+        return service.selectAirPlayDevice(required(rest[0], 'Usage: radiocli agent airplay select <receiver-id>'), !rest.includes('--no-ui'));
+    if (action === 'local')
+        return service.useLocalOutput();
+    if (action === 'code')
+        return service.submitAirPlayPasscode(required(rest[0], 'Usage: radiocli agent airplay code <receiver-code>'));
+    throw new Error('Usage: radiocli agent airplay <list|select|local|code>');
+}
+function required(value, error) { if (!value)
+    throw new Error(error); return value; }
+function requiredText(values, error) {
+    const value = values.join(' ').trim();
+    if (!value)
+        throw new Error(error);
+    return value;
+}
+function numberInRange(value, minimum, maximum, label) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < minimum || parsed > maximum) {
+        throw new Error(`${label} must be a number from ${minimum} through ${maximum}.`);
+    }
+    return parsed;
+}
+function integerInRange(value, minimum, maximum, label) {
+    const parsed = numberInRange(value, minimum, maximum, label);
+    if (!Number.isInteger(parsed))
+        throw new Error(`${label} must be a whole number from ${minimum} through ${maximum}.`);
+    return parsed;
+}
+function stationSource(value) {
+    if (!['recent', 'favorite', 'popular', 'country'].includes(value)) {
+        throw new Error('Source must be recent, favorite, popular, or country.');
+    }
+    return value;
+}
+function presetAction(value) {
+    if (!['play', 'pause', 'resume', 'stop'].includes(value))
+        throw new Error('Action must be play, pause, resume, or stop.');
+    return value;
+}
+function countryCode(value) {
+    if (!/^[a-z]{2}$/i.test(value))
+        throw new Error('Country must be a two-letter ISO country code.');
+    return value.toUpperCase();
+}
+function assertMcpInstallSucceeded(results, action) {
+    const failed = results.filter(result => result.status === 'failed');
+    if (failed.length === 0)
+        return;
+    throw new Error(`RadioCLI was ${action} where possible, but ${failed.length} integration${failed.length === 1 ? '' : 's'} failed: ${failed.map(result => `${result.client} (${result.detail})`).join('; ')}`);
+}

package/dist/agent/headless-host.js

@@ -0,0 +1,143 @@
+import { PlayerController } from '../player/player-controller.js';
+import { ProviderManager } from '../providers/provider-manager.js';
+import { JsonLibraryStore, stationKey } from '../storage/store.js';
+import { startRadioSession } from './session.js';
+import { detectPlaybackBackends } from '../player/backend-install.js';
+export async function runHeadlessAgentHost() {
+    const store = new JsonLibraryStore();
+    const providers = new ProviderManager();
+    const player = new PlayerController(() => store.snapshot().settings);
+    player.refreshDetectedBackends();
+    let station = null;
+    let queue = [];
+    const status = () => ({ owner: 'headless', playback: player.getState(), station, queue, output: {
+            preferredBackend: store.snapshot().settings.preferredBackend,
+            preferredAirPlayDevice: store.snapshot().settings.preferredAirPlayDevice
+        } });
+    const result = (message, ok = true, data) => ({ ok, message, status: status(), ...(data ? { data } : {}) });
+    const play = async (next, nextQueue = [next]) => {
+        store.finishActiveListeningSession();
+        await player.stop();
+        const resolved = await providers.resolve(next);
+        await player.play(next, resolved.url);
+        station = next;
+        queue = nextQueue.length ? nextQueue : [next];
+        store.addRecent(next);
+        store.startListeningSession(next);
+        return result(`Playing ${next.name}.`);
+    };
+    const handle = async (command) => {
+        if (command.type === 'status')
+            return result(station ? `${player.getState().state}: ${station.name}` : 'RadioCLI is idle.');
+        if (command.type === 'play') {
+            if (command.ifPlaying === 'keep' && ['playing', 'paused', 'loading'].includes(player.getState().state))
+                return result(`Kept current station ${station?.name ?? ''}.`);
+            return play(command.station, command.queue);
+        }
+        if (command.type === 'pause') {
+            const control = await player.pause();
+            if (control.ok)
+                store.finishActiveListeningSession();
+            return result(control.message ?? 'Paused.', control.ok);
+        }
+        if (command.type === 'resume') {
+            const control = await player.resume();
+            if (control.ok && station)
+                store.startListeningSession(station);
+            return result(control.message ?? 'Resumed.', control.ok);
+        }
+        if (command.type === 'stop') {
+            store.finishActiveListeningSession();
+            await player.stop();
+            station = null;
+            queue = [];
+            setTimeout(() => process.kill(process.pid, 'SIGTERM'), 50).unref();
+            return result('Stopped RadioCLI.');
+        }
+        if (command.type === 'alarm-preempt') {
+            store.finishActiveListeningSession();
+            await player.stop();
+            station = null;
+            queue = [];
+            return result('Interactive playback yielded to the alarm.');
+        }
+        if (command.type === 'set-volume') {
+            const control = await player.setVolume(command.volume);
+            if (control.ok)
+                store.updateSettings({ volume: player.getState().volume });
+            return result(control.message ?? `Volume ${player.getState().volume}.`, control.ok);
+        }
+        if (command.type === 'set-muted') {
+            const control = await player.setMuted(command.muted);
+            return result(control.message ?? (command.muted ? 'Muted.' : 'Unmuted.'), control.ok);
+        }
+        if (command.type === 'set-favorite') {
+            const target = command.station ?? station;
+            if (!target)
+                return result('No active station to favorite.', false);
+            const current = store.isFavorite(target);
+            if (current !== command.favorite)
+                store.toggleFavorite(target);
+            if (command.favorite && !current && store.snapshot().settings.shareDirectoryVotes)
+                void providers.vote(target);
+            return result(`${command.favorite ? 'Favorited' : 'Removed favorite'}: ${target.name}.`);
+        }
+        if (command.type === 'airplay-list') {
+            const devices = await player.refreshAirPlayDevices();
+            return result(devices.length ? `${devices.length} AirPlay receiver(s) found.` : 'No AirPlay receivers found.', true, devices);
+        }
+        if (command.type === 'airplay-select') {
+            const devices = await player.refreshAirPlayDevices();
+            const device = devices.find(item => item.id === command.deviceId);
+            if (!device)
+                return result('AirPlay receiver not found. Refresh and use an exact receiver ID.', false, devices);
+            if (device.local)
+                return switchToLocal();
+            if (!detectPlaybackBackends().includes('airplay'))
+                return result('AirPlay playback is unavailable; run radiocli doctor.', false);
+            store.updateSettings({ preferredAirPlayDevice: device.id });
+            store.updateSettings({ preferredBackend: 'airplay' });
+            if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
+                return play(station, queue);
+            return result(`Audio output set to AirPlay receiver ${device.name}.`);
+        }
+        if (command.type === 'airplay-local')
+            return switchToLocal();
+        if (command.type === 'airplay-passcode') {
+            const control = player.submitAirPlayPasscode(command.code);
+            return result(control.message ?? 'AirPlay code sent.', control.ok);
+        }
+        if (command.type === 'update-settings') {
+            store.updateSettings(command.settings);
+            return result('RadioCLI settings updated.');
+        }
+        const currentIndex = station ? queue.findIndex(item => stationKey(item) === stationKey(station)) : -1;
+        const delta = command.type === 'next' ? 1 : -1;
+        const next = queue.length ? queue[(Math.max(0, currentIndex) + delta + queue.length) % queue.length] : undefined;
+        return next ? play(next, queue) : result('No playback queue is available.', false);
+    };
+    const switchToLocal = async () => {
+        const backends = detectPlaybackBackends();
+        const backend = backends.includes('mpv') ? 'mpv' : backends.includes('ffplay') ? 'ffplay' : backends.includes('vlc') ? 'vlc' : null;
+        if (!backend)
+            return result('No local playback backend is available. Run radiocli setup to install mpv.', false);
+        store.updateSettings({ preferredBackend: backend });
+        if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
+            return play(station, queue);
+        return result(`Audio output set to this device (${backend}).`);
+    };
+    const session = await startRadioSession(handle);
+    const checkpoint = setInterval(() => {
+        if (player.getState().state === 'playing')
+            store.checkpointActiveListeningSession();
+    }, 30_000);
+    const shutdown = async () => {
+        clearInterval(checkpoint);
+        store.finishActiveListeningSession();
+        await player.stop();
+        await session.close();
+    };
+    process.once('SIGTERM', () => { void shutdown().finally(() => process.exit(0)); });
+    process.once('SIGINT', () => { void shutdown().finally(() => process.exit(0)); });
+    await new Promise(() => undefined);
+}