@ciphore/radiocli 0.2.3 → 0.2.5

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,74 +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 { 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';
-export async function runHeadlessAgentHost() {
-    const store = new JsonLibraryStore();
+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 status = () => ({ owner: 'headless', playback: player.getState(), station, queue, output: {
-            preferredBackend: store.snapshot().settings.preferredBackend,
-            preferredAirPlayDevice: store.snapshot().settings.preferredAirPlayDevice
-        } });
+    const engine = new RadioEngine(player, providers, store, () => store.settings());
+    let persistenceWarning;
+    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 {
+            process.kill(tui.pid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code !== 'ESRCH';
+        }
+    };
+    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 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 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) => {
+    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)
-                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)
-                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') {
-            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') {
-            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)
-                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') {
@@ -77,8 +199,8 @@ export async function runHeadlessAgentHost() {
                 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)
+                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}.`);
         }
@@ -88,56 +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);
-            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') {
-            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);
-        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')
-            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)); });
+    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

@@ -1,71 +1,11 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
-import { detectAlarmTerminal } from '../alarms/terminal-launcher.js';
-const linuxTerminals = new Set(['alacritty', 'foot', 'ghostty', 'gnome-terminal', 'kitty', 'konsole', 'mate-terminal', 'qterminal', 'terminator', 'tilix', 'wezterm', 'xfce4-terminal', 'x-terminal-emulator']);
-export async function launchRadioTui(nodePath, cliPath, encodedCommand) {
-    const terminal = detectAlarmTerminal();
-    const direct = environmentCommand(nodePath, cliPath, ['agent-ui', encodedCommand]);
-    const command = `${direct.map(shellQuote).join(' ')}`;
-    if (terminal === 'darwin:apple-terminal')
-        await launched(spawnDetached('/usr/bin/osascript', appleTerminalScript(command)));
-    else if (terminal === 'darwin:iterm')
-        await launched(spawnDetached('/usr/bin/osascript', iTermScript(command)));
-    else if (terminal === 'darwin:wezterm')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...direct]));
-    else if (terminal === 'darwin:ghostty')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...direct]));
-    else if (terminal === 'darwin:kitty')
-        await launched(spawnDetached('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...direct]));
-    else if (terminal === 'win32:windows-terminal')
-        await launched(spawnDetached('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI', ...direct]));
-    else if (terminal === 'win32:console')
-        await launched(spawnDetached('cmd.exe', ['/d', '/c', 'start', 'RadioCLI', 'cmd.exe', '/k', windowsCommand(direct)]));
-    else if (terminal.startsWith('linux:')) {
-        const executable = terminal.slice('linux:'.length);
-        if (!linuxTerminals.has(basename(executable)))
-            throw new Error('Saved Linux terminal is not supported.');
-        const name = basename(executable);
-        const prefix = name === 'gnome-terminal' || name === 'mate-terminal' || name === 'xfce4-terminal'
-            ? ['--']
-            : name === 'wezterm' ? ['start', '--always-new-process', '--'] : ['-e'];
-        await launched(spawnDetached(executable, [...prefix, ...direct]));
-    }
-    else {
-        throw new Error('No supported graphical terminal was found. Set agentControl.openUiOnPlay to false or open radiocli manually.');
-    }
+import { launchTerminalCommand } from '../platform/terminals.js';
+import { waitForLaunch } from '../platform/launch-command.js';
+/** The agent service verifies the authenticated session after this request. */
+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 launched(spawnDetached(nodePath, [cliPath, 'agent-host']));
-}
-function environmentCommand(nodePath, cliPath, args) {
-    const command = [nodePath, cliPath, ...args];
-    const radioCliHome = process.env.RADIOCLI_HOME;
-    if (!radioCliHome)
-        return command;
-    if (process.platform === 'win32') {
-        return ['cmd.exe', '/d', '/c', `set "RADIOCLI_HOME=${cmdEscape(radioCliHome)}" && ${windowsCommand(command)}`];
-    }
-    return ['/usr/bin/env', `RADIOCLI_HOME=${radioCliHome}`, ...command];
-}
-function shellQuote(value) { return `'${value.replaceAll("'", `'\\''`)}'`; }
-function windowsCommand(values) { return values.map(value => `"${value.replaceAll('"', '""')}"`).join(' '); }
-function cmdEscape(value) { return value.replaceAll('%', '%%').replaceAll('"', '""').replaceAll('^', '^^').replaceAll('&', '^&').replaceAll('|', '^|').replaceAll('<', '^<').replaceAll('>', '^>'); }
-function appleTerminalScript(command) { return ['-e', 'on run argv', '-e', 'tell application "Terminal"', '-e', 'activate', '-e', 'do script (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function iTermScript(command) { return ['-e', 'on run argv', '-e', 'tell application "iTerm"', '-e', 'activate', '-e', 'set w to (create window with default profile)', '-e', 'tell current session of w to write text (item 1 of argv)', '-e', 'end tell', '-e', 'end run', command]; }
-function spawnDetached(command, args) { return spawn(command, [...args], { detached: true, stdio: 'ignore', windowsHide: false }); }
-function launched(child) { return new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', () => { child.unref(); resolve(); }); }); }
-export function resolveExecutable(input, env = process.env, platform = process.platform) {
-    if ((input.includes('/') || input.includes('\\')) && existsSync(input))
-        return input;
-    const suffixes = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
-    const pathDelimiter = platform === 'win32' ? ';' : ':';
-    for (const directory of (env.PATH ?? '').split(pathDelimiter)) {
-        for (const suffix of suffixes) {
-            const path = join(directory, `${input}${suffix}`);
-            if (existsSync(path))
-                return path;
-        }
-    }
-    return undefined;
+    const loader = cliPath.endsWith('.tsx') ? ['--import', import.meta.resolve('tsx')] : [];
+    await waitForLaunch(spawn(nodePath, [...loader, cliPath, 'agent-host'], { detached: true, stdio: 'ignore', windowsHide: true }));
 }