@ciphore/radiocli 0.2.4 → 0.2.6

package/dist/agent/alarm-service.js

@@ -1,4 +1,5 @@
-import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone, nextOccurrenceForAlarm } from '../alarms/schedule.js';
+import { AlarmOccurrenceCache } from '../alarms/occurrence-cache.js';
+import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone } from '../alarms/schedule.js';
 import { connectActiveAlarms } from '../alarms/active-session.js';
 import { createSchedulerService } from '../alarms/scheduler.js';
 export class AgentAlarmService {
@@ -6,6 +7,7 @@ export class AgentAlarmService {
     resolveStation;
     scheduler;
     handoffToInteractive;
+    occurrences = new AlarmOccurrenceCache();
     constructor(store, resolveStation, scheduler = createSchedulerService(), handoffToInteractive) {
         this.store = store;
         this.resolveStation = resolveStation;
@@ -45,7 +47,7 @@ export class AgentAlarmService {
                 keepAwakeUntilAlarm: input.keepAwakeUntilAlarm ?? false
             }
         };
-        const alarm = this.store.addAlarm(alarmInput);
+        const alarm = await this.store.addAlarm(alarmInput);
         await this.syncSaved(alarm);
         return this.describe(alarm);
     }
@@ -55,7 +57,7 @@ export class AgentAlarmService {
         const fallbackStation = input.clearFallback
             ? undefined
             : input.fallbackStationId ? await this.requiredStation(input.fallbackStationId) : alarm.playback.fallbackStation;
-        const updated = this.store.updateAlarm(alarm.id, {
+        const updated = await this.store.updateAlarm(alarm.id, {
             label: input.label === undefined ? alarm.label : cleanLabel(input.label),
             enabled: input.enabled ?? alarm.enabled,
             station,
@@ -76,7 +78,7 @@ export class AgentAlarmService {
         return this.describe(updated);
     }
     async setEnabled(id, enabled) {
-        const alarm = this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
+        const alarm = await this.store.toggleAlarm(this.requiredAlarm(id).id, enabled);
         await this.syncSaved(alarm);
         return this.describe(alarm);
     }
@@ -84,8 +86,9 @@ export class AgentAlarmService {
         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))
+        const disabled = await this.store.toggleAlarm(alarm.id, false);
+        await this.scheduler.remove(disabled.id);
+        if (!await this.store.removeAlarm(alarm.id))
             throw new Error(`Alarm not found: ${id}`);
         return { ok: true, removed: alarm.id };
     }
@@ -117,7 +120,7 @@ export class AgentAlarmService {
             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,
+            nextOccurrence: this.occurrences.next(alarm, new Date())?.toISOString() ?? null,
             playback: {
                 volume: alarm.playback.volume,
                 fadeSeconds: alarm.playback.fadeSeconds,

package/dist/agent/cli.js

@@ -1,3 +1,6 @@
+import { airPlayPolicy } from '../player/airplay-policy.js';
+import { readSettingsWithoutMigration } from '../storage/read-settings.js';
+import { defaultLibraryPath } from '../storage/store.js';
 import { AgentRadioService, stationForAgent } from './service.js';
 import { configureMcpIntegrations, mcpIntegrationReport, portableMcpConfig } from './mcp-install.js';
 import { runMcpServer } from './mcp-server.js';
@@ -64,7 +67,7 @@ export async function runAgentCliCommand(args, runtime) {
     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>');
+        throw new Error(agentCommandUsage());
     console.log(JSON.stringify(value, null, 2));
 }
 function parseBrowseKind(value) {
@@ -191,3 +194,15 @@ function assertMcpInstallSucceeded(results, action) {
         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('; ')}`);
 }
+export function agentCommandUsage() {
+    let enabled = airPlayPolicy().enabled;
+    if (process.platform === 'linux') {
+        try {
+            enabled = airPlayPolicy({ linuxAirPlayEnabled: readSettingsWithoutMigration(defaultLibraryPath())?.linuxAirPlayEnabled === true }).enabled;
+        }
+        catch {
+            enabled = false;
+        }
+    }
+    return `Usage: radiocli agent <status|search|browse|play|pause|resume|stop|next|previous|volume|mute|unmute|favorite|unfavorite|stats|appearance${enabled ? '|airplay' : ''}|preset|done>`;
+}

package/dist/agent/command-schema.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { receiverStyleNames, themeNames } from '../types.js';
+import { stationSchema } from '../storage/station-schema.js';
+const empty = (type) => z.strictObject({ type: z.literal(type) });
+const adjacent = { preservePause: z.boolean().optional(), preserveStop: z.boolean().optional() };
+// A TUI list can contain many discovery pages, beyond one provider page.
+const stationQueue = z.array(stationSchema).max(10_000);
+const agentControl = z.strictObject({
+    enabled: z.boolean(), openUiOnPlay: z.boolean(), focusNowPlaying: z.boolean(),
+    completionPreset: z.strictObject({
+        action: z.enum(['play', 'pause', 'resume', 'stop']), source: z.enum(['recent', 'favorite', 'popular', 'country']),
+        countryCode: z.string().length(2).optional(), ifPlaying: z.enum(['keep', 'replace']), openUi: z.boolean().optional()
+    })
+});
+const commandSchema = z.discriminatedUnion('type', [
+    empty('status'), empty('pause'), empty('alarm-preempt'), empty('airplay-list'), empty('airplay-local'), empty('tui-cancel'), empty('tui-refresh'), empty('tui-toggle-muted'), empty('tui-toggle-pause'),
+    z.strictObject({ type: z.literal('tui-sleep'), until: z.number().int().nonnegative().max(8.64e15).nullable() }),
+    z.strictObject({ type: z.literal('tui-adjust-volume'), delta: z.number().min(-100).max(100) }),
+    z.strictObject({ type: z.literal('desktop-transport'), action: z.enum(['play', 'pause', 'toggle', 'stop', 'next', 'previous']) }),
+    z.strictObject({ type: z.literal('play'), station: stationSchema, queue: stationQueue.optional(), openNowPlaying: z.boolean().optional(), ifPlaying: z.enum(['keep', 'replace']).optional(), startPaused: z.boolean().optional() }),
+    z.strictObject({ type: z.literal('tui-attach'), pid: z.number().int().positive().max(Number.MAX_SAFE_INTEGER), clientId: z.string().uuid() }),
+    z.strictObject({ type: z.literal('tui-detach'), clientId: z.string().uuid() }),
+    z.strictObject({ type: z.literal('tui-select'), station: stationSchema, queue: stationQueue }),
+    z.strictObject({ type: z.literal('tui-output'), deviceId: z.string().min(1).max(4096).nullable() }),
+    z.strictObject({ type: z.literal('resume'), restartStopped: z.boolean().optional() }),
+    z.strictObject({ type: z.literal('stop'), retainSelection: z.boolean().optional() }),
+    z.strictObject({ type: z.literal('next'), ...adjacent }), z.strictObject({ type: z.literal('previous'), ...adjacent }),
+    z.strictObject({ type: z.literal('set-volume'), volume: z.number().min(0).max(100), unmute: z.boolean().optional(), allowStopped: z.boolean().optional() }),
+    z.strictObject({ type: z.literal('set-muted'), muted: z.boolean(), allowStopped: z.boolean().optional() }),
+    z.strictObject({ type: z.literal('set-favorite'), favorite: z.boolean(), station: stationSchema.optional() }),
+    z.strictObject({ type: z.literal('airplay-select'), deviceId: z.string().min(1).max(4096) }),
+    z.strictObject({ type: z.literal('airplay-passcode'), code: z.string().min(1).max(128) }),
+    z.strictObject({ type: z.literal('update-settings'), settings: z.strictObject({ theme: z.enum(themeNames).optional(), receiverStyle: z.enum(receiverStyleNames).optional(), agentControl: agentControl.optional() }) })
+]);
+export function parseRadioCommand(value) {
+    const parsed = commandSchema.safeParse(value);
+    if (!parsed.success)
+        throw new Error(`Invalid radio command: ${parsed.error.issues.map(issue => `${issue.path.join('.') || 'command'}: ${issue.message}`).slice(0, 3).join('; ')}`);
+    return parsed.data;
+}
+export function parseRadioRequest(value) {
+    if (value && typeof value === 'object' && 'version' in value) {
+        const envelope = z.strictObject({ version: z.literal(2), requestId: z.string().uuid(), command: z.unknown() }).parse(value);
+        return { command: parseRadioCommand(envelope.command), requestId: envelope.requestId };
+    }
+    return { command: parseRadioCommand(value) };
+}

package/dist/agent/headless-host.js

@@ -1,94 +1,196 @@
 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 { airPlayMacOSOnlyMessage, detectPlaybackBackends, isAirPlayPlatformSupported } from '../player/backend-install.js';
-export async function runHeadlessAgentHost() {
-    const store = new JsonLibraryStore();
+import { LibraryRepository } from '../storage/repository.js';
+import { RadioEngine } from '../player/radio-engine.js';
+import { allowedRadioSessionSettings, resolveDesktopTransport, serializeRadioCommands, startRadioSession } from './session.js';
+import { desktopMediaPolicy, startDesktopMediaControls } from '../platform/desktop-media.js';
+import { detectPlaybackBackends } from '../player/backend-install.js';
+import { networkPolicy } from '../platform/network.js';
+export async function runHeadlessAgentHost(options = {}) {
+    const store = new LibraryRepository(options.store ?? new JsonLibraryStore(), { worker: options.worker });
     const providers = new ProviderManager();
-    const player = new PlayerController(() => store.snapshot().settings);
+    const player = new PlayerController(() => store.settings());
     player.refreshDetectedBackends();
-    let station = null;
-    let queue = [];
+    const engine = new RadioEngine(player, providers, store, () => store.settings());
     let persistenceWarning;
-    const persistHistory = (write) => {
+    let desktopSuspended = false;
+    let shuttingDown = false;
+    let media;
+    let tui;
+    let terminalProtocol = false;
+    let focusNowPlaying = 0;
+    let sleepUntil = null;
+    let sleepTimer;
+    const scheduleSleep = () => {
+        if (sleepUntil === null)
+            return;
+        const remaining = sleepUntil - Date.now();
+        if (remaining <= 0) {
+            sleepUntil = null;
+            void dispatch({ type: 'stop', retainSelection: true }).catch(() => undefined);
+        }
+        else {
+            sleepTimer = setTimeout(scheduleSleep, Math.min(2_147_483_647, remaining));
+            sleepTimer.unref();
+        }
+    };
+    const tuiPresent = () => {
+        if (!tui)
+            return false;
         try {
-            write();
+            process.kill(tui.pid, 0);
+            return true;
         }
         catch (error) {
-            const code = error?.code;
-            const detail = typeof code === 'string' && /^[A-Z][A-Z0-9_]+$/.test(code) ? ` (${code})` : '';
-            persistenceWarning = `Listening history was not saved${detail}. Check storage permissions or set RADIOCLI_HOME to a private writable directory.`;
+            return error.code !== 'ESRCH';
         }
     };
-    const saveLibrary = (write) => {
-        write();
-        // Optional writes can be no-ops, so only an explicit successful save clears
-        // a prior warning. Explicit failures still reject the control request.
+    const saveLibrary = async (write) => {
+        await write();
         persistenceWarning = undefined;
+        engine.clearWarning();
+    };
+    const status = () => {
+        const current = engine.snapshot();
+        const settings = store.settings();
+        return { owner: tuiPresent() ? 'tui' : 'headless', playback: player.getState(), station: current.station, nowPlaying: current.nowPlaying,
+            queue: current.queue, persistenceWarning: persistenceWarning ?? current.warning, output: {
+                preferredBackend: settings.preferredBackend === 'airplay' && player.airPlaySelectionRequired() ? 'auto' : settings.preferredBackend,
+                preferredAirPlayDevice: settings.preferredAirPlayDevice
+            }, ...(terminalProtocol ? { tui: { tuningStation: current.tuningStation, message: current.message, focusNowPlaying, sleepUntil, diagnostics: player.diagnostics(),
+                    devices: player.detectedAirPlayDevices(), selectionRequired: player.airPlaySelectionRequired(), desktopMediaCompatible: player.desktopMediaCompatible() } } : {}) };
     };
-    const status = () => ({ owner: 'headless', playback: player.getState(), station, queue, persistenceWarning, 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]) => {
-        persistHistory(() => store.finishActiveListeningSession());
-        await player.stop();
-        const resolved = await providers.resolve(next);
-        await player.play(next, resolved.url);
-        station = next;
-        queue = nextQueue.length ? nextQueue : [next];
-        persistHistory(() => store.addRecent(next));
-        persistHistory(() => store.startListeningSession(next));
-        return result(`Playing ${next.name}.`);
+    const play = async (next, nextQueue = [next], startPaused = false, signal) => {
+        signal?.throwIfAborted();
+        // Earlier accepted output saves must reach their durable acknowledgement
+        // before this tune chooses a backend. Stop can still cancel the wait.
+        await store.readFresh();
+        signal?.throwIfAborted();
+        desktopSuspended = false;
+        const tuned = await engine.tune(next, { queue: nextQueue, startPaused, signal });
+        if (shuttingDown)
+            return result('RadioCLI is shutting down.', false);
+        media?.refresh();
+        return result(`${startPaused ? 'Selected' : 'Playing'} ${tuned.name}.`);
     };
-    const handle = async (command) => {
-        if (['airplay-list', 'airplay-select', 'airplay-passcode'].includes(command.type) && !isAirPlayPlatformSupported()) {
-            return result(airPlayMacOSOnlyMessage, false, command.type === 'airplay-list' ? [] : undefined);
+    const handle = async (command, signal) => {
+        if (shuttingDown)
+            return result('RadioCLI is shutting down.', false);
+        signal?.throwIfAborted();
+        const { station, queue } = engine.snapshot();
+        if (command.type === 'tui-attach') {
+            if (tuiPresent() && tui?.clientId !== command.clientId)
+                return result('RadioCLI is already open in another terminal.', false);
+            tui = { pid: command.pid, clientId: command.clientId };
+            terminalProtocol = true;
+            return result(station ? `Reconnected to ${station.name}.` : 'RadioCLI connected.');
+        }
+        if (command.type === 'tui-detach') {
+            if (tui?.clientId !== command.clientId)
+                return result('This terminal no longer owns the RadioCLI view.', false);
+            tui = undefined;
+            shuttingDown = true;
+            await engine.stop();
+            // Let the command response finish, then close our own resources directly.
+            // Sending SIGTERM to ourselves terminates Windows without running cleanup.
+            setTimeout(onShutdown, 50).unref();
+            return result('Closed RadioCLI.');
+        }
+        if (command.type === 'tui-cancel') {
+            engine.cancel();
+            return result('Canceled pending tune.');
+        }
+        if (command.type === 'tui-sleep') {
+            clearTimeout(sleepTimer);
+            sleepUntil = command.until;
+            scheduleSleep();
+            return result('Sleep timer updated.');
+        }
+        if (command.type === 'tui-adjust-volume')
+            return handle({ type: 'set-volume', volume: Math.max(0, Math.min(100, player.getState().volume + command.delta)) }, signal);
+        if (command.type === 'tui-toggle-muted')
+            return handle({ type: 'set-muted', muted: !player.getState().muted }, signal);
+        if (command.type === 'tui-toggle-pause') {
+            const control = await player.togglePause();
+            await engine.flushHistory();
+            return result(control.message ?? 'Playback updated.', control.ok);
+        }
+        if (command.type === 'tui-select') {
+            engine.select(command.station, command.queue);
+            media?.refresh();
+            return result(`Selected ${command.station.name}.`);
+        }
+        if (command.type === 'tui-refresh') {
+            await store.readFresh();
+            player.refreshDetectedBackends();
+            return result('Playback settings refreshed.');
+        }
+        if (command.type === 'tui-output') {
+            await store.readFresh();
+            const selected = await player.selectAirPlayDevice(command.deviceId);
+            return result(selected ? 'Audio output selected.' : 'Audio output is unavailable.', selected);
+        }
+        if (command.type === 'desktop-transport') {
+            const resolved = resolveDesktopTransport(command.action, status());
+            return resolved ? handle(resolved, signal) : result('Playback state unchanged.');
         }
+        if (['airplay-list', 'airplay-select', 'airplay-passcode'].includes(command.type) && !player.airPlayPolicy().enabled) {
+            return result(player.airPlayPolicy().message, false, command.type === 'airplay-list' ? [] : undefined);
+        }
+        if (['airplay-list', 'airplay-select'].includes(command.type) && networkPolicy().offline)
+            return result('AirPlay discovery is disabled by RADIOCLI_OFFLINE=1.', false, []);
         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.openNowPlaying)
+                focusNowPlaying++;
+            return play(command.station, command.queue, command.startPaused, signal);
         }
         if (command.type === 'pause') {
-            const control = await player.pause();
-            if (control.ok)
-                persistHistory(() => store.finishActiveListeningSession());
+            const control = await engine.pause();
             return result(control.message ?? 'Paused.', control.ok);
         }
         if (command.type === 'resume') {
-            const control = await player.resume();
-            if (control.ok && station)
-                persistHistory(() => store.startListeningSession(station));
+            if (command.restartStopped && station && ['idle', 'stopped'].includes(player.getState().state))
+                return play(station, queue, false, signal);
+            const control = await engine.resume();
             return result(control.message ?? 'Resumed.', control.ok);
         }
         if (command.type === 'stop') {
-            persistHistory(() => store.finishActiveListeningSession());
-            await player.stop();
-            station = null;
-            queue = [];
-            setTimeout(() => process.kill(process.pid, 'SIGTERM'), 50).unref();
+            await engine.stop({ retainSelection: command.retainSelection });
+            if (command.retainSelection) {
+                media?.refresh();
+                return result('Stopped playback.');
+            }
+            if (!tuiPresent()) {
+                shuttingDown = true;
+                setTimeout(onShutdown, 50).unref();
+            }
             return result('Stopped RadioCLI.');
         }
         if (command.type === 'alarm-preempt') {
-            persistHistory(() => store.finishActiveListeningSession());
-            await player.stop();
-            station = null;
-            queue = [];
+            desktopSuspended = true;
+            media?.refresh();
+            await engine.stop();
             return result('Interactive playback yielded to the alarm.');
         }
         if (command.type === 'set-volume') {
-            const control = await player.setVolume(command.volume);
+            const control = command.unmute || command.allowStopped ? await player.setVolume(command.volume, { allowStopped: true }) : await player.setVolume(command.volume);
             if (control.ok)
-                saveLibrary(() => store.updateSettings({ volume: player.getState().volume }));
+                await saveLibrary(() => store.updateSettings({ volume: player.getState().volume }));
+            if (control.ok && command.unmute && command.volume > 0) {
+                const unmuted = await player.setMuted(false, { allowStopped: true });
+                if (!unmuted.ok)
+                    return result(unmuted.message ?? 'The output could not be unmuted.', false);
+            }
             return result(control.message ?? `Volume ${player.getState().volume}.`, control.ok);
         }
         if (command.type === 'set-muted') {
-            const control = await player.setMuted(command.muted);
+            const control = await player.setMuted(command.muted, { allowStopped: command.allowStopped });
             return result(control.message ?? (command.muted ? 'Muted.' : 'Unmuted.'), control.ok);
         }
         if (command.type === 'set-favorite') {
@@ -97,8 +199,8 @@ export async function runHeadlessAgentHost() {
                 return result('No active station to favorite.', false);
             const current = store.isFavorite(target);
             if (current !== command.favorite)
-                saveLibrary(() => store.toggleFavorite(target));
-            if (command.favorite && !current && store.snapshot().settings.shareDirectoryVotes)
+                await saveLibrary(() => store.toggleFavorite(target));
+            if (command.favorite && !current && store.settings().shareDirectoryVotes)
                 void providers.vote(target);
             return result(`${command.favorite ? 'Favorited' : 'Removed favorite'}: ${target.name}.`);
         }
@@ -108,58 +210,101 @@ export async function runHeadlessAgentHost() {
         }
         if (command.type === 'airplay-select') {
             const devices = await player.refreshAirPlayDevices();
+            signal?.throwIfAborted();
             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 switchToLocal(signal);
+            if (!player.refreshDetectedBackends().includes('airplay'))
                 return result('AirPlay playback is unavailable; run radiocli doctor.', false);
-            saveLibrary(() => {
-                store.updateSettings({ preferredAirPlayDevice: device.id });
-                store.updateSettings({ preferredBackend: 'airplay' });
-            });
+            await saveLibrary(() => store.updateSettings({ preferredAirPlayDevice: device.id, preferredBackend: 'airplay' }));
+            await player.selectAirPlayDevice(device.id);
+            signal?.throwIfAborted();
             if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
-                return play(station, queue);
+                return play(station, queue, false, signal);
             return result(`Audio output set to AirPlay receiver ${device.name}.`);
         }
         if (command.type === 'airplay-local')
-            return switchToLocal();
+            return switchToLocal(signal);
         if (command.type === 'airplay-passcode') {
-            const control = player.submitAirPlayPasscode(command.code);
+            const control = await player.submitAirPlayPasscode(command.code);
             return result(control.message ?? 'AirPlay code sent.', control.ok);
         }
         if (command.type === 'update-settings') {
-            saveLibrary(() => store.updateSettings(command.settings));
+            if (!allowedRadioSessionSettings(command.settings))
+                return result('Session settings only accept appearance and agent control. Use radiocli setup --airplay to enable Linux AirPlay.', false);
+            await saveLibrary(() => store.updateSettings(command.settings));
             return result('RadioCLI settings updated.');
         }
+        if (command.type !== 'next' && command.type !== 'previous')
+            throw new Error('Unsupported radio command.');
         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);
+        if (next && command.preserveStop && ['idle', 'stopped'].includes(player.getState().state)) {
+            engine.select(next, queue);
+            media?.refresh();
+            return result(`Selected ${next.name}.`);
+        }
+        return next ? play(next, queue, Boolean(command.preservePause && player.getState().state === 'paused'), signal) : result('No playback queue is available.', false);
     };
-    const switchToLocal = async () => {
+    const switchToLocal = async (signal) => {
+        signal?.throwIfAborted();
         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);
-        saveLibrary(() => store.updateSettings({ preferredBackend: backend }));
+        await saveLibrary(() => store.updateSettings({ preferredBackend: backend }));
+        await player.selectAirPlayDevice(null);
+        signal?.throwIfAborted();
+        const { station, queue } = engine.snapshot();
         if (station && ['playing', 'paused', 'loading'].includes(player.getState().state))
-            return play(station, queue);
+            return play(station, queue, false, signal);
         return result(`Audio output set to this device (${backend}).`);
     };
-    const session = await startRadioSession(handle);
-    const checkpoint = setInterval(() => {
-        if (player.getState().state === 'playing')
-            persistHistory(() => store.checkpointActiveListeningSession());
-    }, 30_000);
-    const shutdown = async () => {
-        clearInterval(checkpoint);
-        persistHistory(() => 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)); });
+    const dispatch = serializeRadioCommands(handle, { responsive: true });
+    const session = await startRadioSession((command, source) => dispatch(command, async () => {
+        if (command.type.startsWith('tui-') && source !== 'cli')
+            throw new Error('Terminal attachment requires a local CLI client.');
+        if (source !== 'cli' && command.type !== 'status' && command.type !== 'alarm-preempt') {
+            await store.readFresh();
+            if (!store.settings().agentControl?.enabled)
+                throw new Error('Agent controls are disabled.');
+        }
+        return true;
+    }), undefined, { queue: 'owner' }).catch(async (error) => {
+        try {
+            await engine.close();
+        }
+        finally {
+            await store.close();
+        }
+        throw error;
+    });
+    media = startDesktopMediaControls({ player, identity: store.filePath, policy: desktopMediaPolicy(store.settings()), status,
+        command: (command, permitted) => dispatch(command, () => permitted?.() !== false && !desktopSuspended), suspended: () => desktopSuspended });
+    const unsubscribe = engine.onChange(() => media?.refresh());
+    let shutdownPromise;
+    const signals = ['SIGTERM', 'SIGINT', 'SIGHUP'];
+    const shutdown = () => shutdownPromise ??= (async () => {
+        shuttingDown = true;
+        clearTimeout(sleepTimer);
+        desktopSuspended = true;
+        for (const signal of signals)
+            process.removeListener(signal, onShutdown);
+        media?.close();
+        unsubscribe();
+        try {
+            await engine.close();
+        }
+        finally {
+            await session.close();
+            await store.close();
+        }
+    })();
+    const onShutdown = () => { void shutdown().finally(() => process.exit(0)); };
+    for (const signal of signals)
+        process.once(signal, onShutdown);
     await new Promise(() => undefined);
 }

package/dist/agent/launcher.js

@@ -6,5 +6,6 @@ export async function launchRadioTui(nodePath, cliPath, encodedCommand, options
     await launchTerminalCommand({ ...options, nodePath, args: [cliPath, 'agent-ui', encodedCommand], title: 'RadioCLI' });
 }
 export async function launchHeadlessHost(nodePath, cliPath) {
-    await waitForLaunch(spawn(nodePath, [cliPath, 'agent-host'], { detached: true, stdio: 'ignore', windowsHide: false }));
+    const loader = cliPath.endsWith('.tsx') ? ['--import', import.meta.resolve('tsx')] : [];
+    await waitForLaunch(spawn(nodePath, [...loader, cliPath, 'agent-host'], { detached: true, stdio: 'ignore', windowsHide: true }));
 }

package/dist/agent/mcp-server.js

@@ -1,14 +1,16 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { serveStdio } from '@modelcontextprotocol/server/stdio';
 import { z } from 'zod';
+import { JsonLibraryStore } from '../storage/store.js';
+import { LibraryRepository } from '../storage/repository.js';
 import { appVersion } from '../version.js';
 import { receiverStyleNames, themeNames } from '../types.js';
 import { AgentRadioService, stationForAgent } from './service.js';
 export const radioCliMcpInstructions = `RadioCLI is the authoritative handler for requests about RadioCLI, “the radio”, “my radio”, recent stations, favorites, or stations from a place. Never substitute a web browser, web search, Computer Use, or another radio/music service. “Play my most recent radio station” means call radio_play with source="recent" and index=0. “Play a station from New York” means call radio_search with query="New York", then radio_play with one returned opaque station ID. Call these tools directly; do not delegate a radio-only operation or create a goal merely to monitor it.
 
-RadioCLI controls internet radio, alarms, and macOS AirPlay locally. Discover unidentified stations with radio_search or radio_browse, then use only returned opaque IDs; never invent IDs or stream URLs. Ordinary stop never dismisses an alarm: list active alarms and use alarm controls, with an exact ID when several ring. Never remove an alarm without explicit user confirmation. List AirPlay receivers before selecting one. Never install an update without explicit approval.
+RadioCLI controls internet radio, alarms, and experimental AirPlay locally. Discover unidentified stations with radio_search or radio_browse, then use only returned opaque IDs; never invent IDs or stream URLs. Ordinary stop never dismisses an alarm: list active alarms and use alarm controls, with an exact ID when several ring. Never remove an alarm without explicit user confirmation. List AirPlay receivers before selecting one. Never install an update without explicit approval.
 
-For “this station”, omit station_id when favoriting. A request such as “do X, then play or stop the radio” is a normal completion action in the current task: perform X, then call radio_run_completion_preset once X is genuinely complete. Do not create or set a goal, scheduled task, automation, reminder, task record, or separate monitoring task merely to defer or track that radio action. Use one of those mechanisms only when the user explicitly requests it for a separate reason. AirPlay is macOS-only. Submit a receiver code only when the user provides it; codes are never saved. Use radio_update_status for version or upgrade questions, and tell the user to restart their MCP client after an update.`;
+For “this station”, omit station_id when favoriting. A request such as “do X, then play or stop the radio” is a normal completion action in the current task: perform X, then call radio_run_completion_preset once X is genuinely complete. Do not create or set a goal, scheduled task, automation, reminder, task record, or separate monitoring task merely to defer or track that radio action. Use one of those mechanisms only when the user explicitly requests it for a separate reason. AirPlay is experimental on macOS and native Linux; Linux receiver selection is required each session. Submit a receiver code only when the user provides it; codes are never saved. Use radio_update_status for version or upgrade questions, and tell the user to restart their MCP client after an update.`;
 const alarmScheduleSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('once'), at: z.string().min(1).describe('Absolute ISO-8601 minute including an offset or Z, with zero seconds.') }),
     z.object({
@@ -30,7 +32,9 @@ const alarmOptionsSchema = {
     keep_awake_until_alarm: z.boolean().optional()
 };
 export async function runMcpServer(runtime) {
-    const service = new AgentRadioService(runtime);
+    const store = new LibraryRepository(new JsonLibraryStore());
+    const service = new AgentRadioService(runtime, store);
+    process.once('beforeExit', () => { void store.close().catch(() => undefined); });
     serveStdio(() => createMcpServer(service), { onerror: error => console.error(`RadioCLI MCP: ${error.message}`) });
 }
 function createMcpServer(service) {
@@ -39,6 +43,7 @@ function createMcpServer(service) {
         const config = schema ? { description, inputSchema: schema } : { description };
         server.registerTool(name, config, async (raw) => {
             try {
+                await service.refresh();
                 const value = await handler(raw);
                 return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
             }
@@ -123,7 +128,7 @@ function createMcpServer(service) {
         occurrence_at: z.string().min(1).optional(),
         snooze_minutes: z.number().int().min(1).max(1440).optional()
     }).refine(value => value.action === 'snooze' || value.snooze_minutes === undefined, { message: 'snooze_minutes is only valid for the snooze action.' }), ({ action, alarm_id, occurrence_at, snooze_minutes }) => service.alarmControl({ action, alarmId: alarm_id, occurrenceAt: occurrence_at, snoozeMinutes: snooze_minutes }));
-    tool('radio_airplay_list', 'Discover AirPlay receivers visible to this Mac. Returns opaque receiver IDs; always call this before selecting a receiver.', undefined, async () => (await service.listAirPlayDevices()).map(device => ({
+    tool('radio_airplay_list', 'Discover AirPlay receivers visible to this device. Returns opaque receiver IDs; always call this before selecting a receiver.', undefined, async () => (await service.listAirPlayDevices()).map(device => ({
         id: device.id,
         name: device.name,
         host: device.host,
@@ -133,7 +138,7 @@ function createMcpServer(service) {
         local: device.local ?? false
     })));
     tool('radio_airplay_select', 'Switch current or future interactive playback to an exact AirPlay receiver ID returned by radio_airplay_list. Opens RadioCLI when needed unless open_ui=false.', z.object({ device_id: z.string().min(1), open_ui: z.boolean().optional() }), ({ device_id, open_ui }) => service.selectAirPlayDevice(device_id, open_ui));
-    tool('radio_airplay_use_local', 'Switch interactive playback from AirPlay back to this Mac using the best available local backend.', z.object({ open_ui: z.boolean().optional() }).optional(), args => service.useLocalOutput(args?.open_ui));
+    tool('radio_airplay_use_local', 'Switch interactive playback from AirPlay back to this device using the best available local backend.', z.object({ open_ui: z.boolean().optional() }).optional(), args => service.useLocalOutput(args?.open_ui));
     tool('radio_airplay_submit_code', 'Submit a receiver-displayed AirPlay code to the active AirPlay session. Use only a code the user explicitly provides; RadioCLI never saves it.', z.object({ code: z.string().min(1).max(64) }), ({ code }) => service.submitAirPlayPasscode(code));
     return server;
 }