@ciphore/radiocli 0.2.2 → 0.2.3

package/dist/agent/mcp-server.js

@@ -0,0 +1,139 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod';
+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.
+
+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.`;
+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({
+        type: z.literal('recurring'),
+        time: z.string().regex(/^\d{2}:\d{2}$/).describe('24-hour local civil time, HH:mm.'),
+        weekdays: z.array(z.number().int().min(1).max(7)).min(1).describe('ISO weekdays, Monday=1 through Sunday=7.'),
+        timezone: z.string().min(1).describe('IANA timezone such as America/Los_Angeles.')
+    })
+]);
+const alarmOptionsSchema = {
+    label: z.string().min(1).max(120).optional(),
+    enabled: z.boolean().optional(),
+    volume: z.number().int().min(0).max(100).optional(),
+    fade_seconds: z.number().int().min(0).max(3600).optional(),
+    stop_after_minutes: z.number().int().min(1).max(10080).optional(),
+    fallback_station_id: z.string().min(1).optional(),
+    missed_run_grace_minutes: z.number().int().min(0).max(10080).optional(),
+    wake_if_supported: z.boolean().optional(),
+    keep_awake_until_alarm: z.boolean().optional()
+};
+export async function runMcpServer(runtime) {
+    const service = new AgentRadioService(runtime);
+    serveStdio(() => createMcpServer(service), { onerror: error => console.error(`RadioCLI MCP: ${error.message}`) });
+}
+function createMcpServer(service) {
+    const server = new McpServer({ name: 'radiocli', version: appVersion() }, { instructions: radioCliMcpInstructions });
+    const tool = (name, description, schema, handler) => {
+        const config = schema ? { description, inputSchema: schema } : { description };
+        server.registerTool(name, config, async (raw) => {
+            try {
+                const value = await handler(raw);
+                return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+            }
+            catch (error) {
+                return { content: [{ type: 'text', text: error instanceof Error ? error.message : 'RadioCLI request failed.' }], isError: true };
+            }
+        });
+    };
+    tool('radio_status', 'Get current playback, active station, queue, agent preferences, and whether alarm playback is active.', undefined, () => service.status());
+    tool('radio_update_status', 'Check the installed and latest RadioCLI versions and return the appropriate update command. This is read-only and never installs an update.', undefined, () => service.updateStatus());
+    tool('radio_search', 'Search RadioCLI’s public station directory by name, genre, language, city, region, or country. Use this—not web search or a browser—for requests such as “play a station from New York”, then pass a returned opaque id to radio_play.', z.object({
+        query: z.string().min(1).max(200),
+        limit: z.number().int().min(1).max(30).default(10),
+        country_code: z.string().length(2).optional()
+    }), async ({ query, limit, country_code }) => (await service.search(query, limit, country_code)).map(stationForAgent));
+    tool('radio_browse', 'List saved favorites, recent stations, popular stations, nearby stations, countries, or recent track titles.', z.object({
+        kind: z.enum(['favorites', 'recent', 'popular', 'nearby', 'countries', 'track-history']),
+        limit: z.number().int().min(1).max(50).default(20)
+    }), async ({ kind, limit }) => {
+        const values = await service.browse(kind, limit);
+        return kind === 'favorites' || kind === 'recent' || kind === 'popular' || kind === 'nearby'
+            ? values.map(stationForAgent)
+            : values;
+    });
+    tool('radio_play', 'Play through RadioCLI using a searched/saved station id, or choose from recent, favorites, popular, or a country. For “play my most recent radio station”, call this directly with source="recent" and index=0. By default this opens the normal RadioCLI TUI in a terminal window; set open_ui=false only when the user requests headless playback.', z.object({
+        station_id: z.string().min(1).optional(),
+        source: z.enum(['recent', 'favorite', 'popular', 'country']).default('recent'),
+        country_code: z.string().length(2).optional(),
+        index: z.number().int().min(0).optional(),
+        random: z.boolean().default(false),
+        open_ui: z.boolean().optional(),
+        if_playing: z.enum(['keep', 'replace']).default('replace')
+    }), ({ station_id, source, country_code, index, random, open_ui, if_playing }) => service.play({ stationId: station_id, source, countryCode: country_code, index, random, openUi: open_ui, ifPlaying: if_playing }));
+    tool('radio_pause', 'Pause playback. Safe to call repeatedly.', undefined, () => service.control({ type: 'pause' }));
+    tool('radio_resume', 'Resume paused playback without changing stations.', undefined, () => service.control({ type: 'resume' }));
+    tool('radio_stop', 'Stop ordinary interactive/headless playback. This never dismisses or modifies an alarm.', undefined, () => service.control({ type: 'stop' }));
+    tool('radio_next', 'Play the next station in the queue created by the last radio_play request.', undefined, () => service.control({ type: 'next' }));
+    tool('radio_previous', 'Play the previous station in the current queue.', undefined, () => service.control({ type: 'previous' }));
+    tool('radio_set_volume', 'Set playback volume from 0 through 100 and save it as the RadioCLI preference.', z.object({ volume: z.number().min(0).max(100) }), ({ volume }) => service.control({ type: 'set-volume', volume }));
+    tool('radio_set_muted', 'Explicitly mute or unmute playback; this is not a toggle.', z.object({ muted: z.boolean() }), ({ muted }) => service.control({ type: 'set-muted', muted }));
+    tool('radio_set_favorite', 'Explicitly add or remove a favorite. Omit station_id to act on the current station, as in “favorite this”.', z.object({ favorite: z.boolean().default(true), station_id: z.string().min(1).optional() }), ({ favorite, station_id }) => service.setFavorite(favorite, station_id));
+    tool('radio_stats', 'Get local listening time, stations heard, active days, and streak statistics.', undefined, () => service.stats());
+    tool('radio_get_appearance', 'List available display themes and receiver styles and show the current selections.', undefined, () => service.appearance());
+    tool('radio_set_appearance', 'Change the RadioCLI display color theme or visual receiver style. An open TUI updates immediately.', z.object({ theme: z.enum(themeNames).optional(), receiver_style: z.enum(receiverStyleNames).optional() }), ({ theme, receiver_style }) => service.updateAppearance({ theme, receiverStyle: receiver_style }));
+    tool('radio_set_agent_preferences', 'Choose whether agent-started playback opens the normal TUI and whether it switches an open TUI to Now Playing.', z.object({ open_ui_on_play: z.boolean().optional(), focus_now_playing: z.boolean().optional() }), ({ open_ui_on_play, focus_now_playing }) => service.updateAgentPreferences({ openUiOnPlay: open_ui_on_play, focusNowPlaying: focus_now_playing }));
+    tool('radio_run_completion_preset', 'Run the user-configured completion action immediately after the current task completes. This is a one-shot radio action, not a reason to create a goal, automation, reminder, task record, or monitoring task.', undefined, () => service.runCompletionPreset());
+    tool('radio_configure_completion_preset', 'Configure what radio_run_completion_preset does: play/stop/pause/resume, station source, conflict behavior, and optional UI override.', z.object({
+        action: z.enum(['play', 'pause', 'resume', 'stop']).optional(),
+        source: z.enum(['recent', 'favorite', 'popular', 'country']).optional(),
+        country_code: z.string().length(2).optional(),
+        if_playing: z.enum(['keep', 'replace']).optional(),
+        open_ui: z.boolean().optional()
+    }), ({ action, source, country_code, if_playing, open_ui }) => service.configureCompletionPreset({ action, source, countryCode: country_code, ifPlaying: if_playing, openUi: open_ui }));
+    tool('radio_alarm_list', 'List saved alarms with exact IDs, schedules, stations, next occurrences, playback settings, and last outcomes.', undefined, () => service.alarmList());
+    tool('radio_alarm_status', 'Get saved alarms, native scheduler health, and every currently ringing alarm occurrence.', undefined, () => service.alarmStatus());
+    tool('radio_alarm_create', 'Create and natively schedule a one-time or recurring radio alarm. Resolve the station with radio_search or radio_browse first.', z.object({
+        station_id: z.string().min(1),
+        schedule: alarmScheduleSchema,
+        ...alarmOptionsSchema
+    }), ({ station_id, schedule, label, enabled, volume, fade_seconds, stop_after_minutes, fallback_station_id, missed_run_grace_minutes, wake_if_supported, keep_awake_until_alarm }) => service.alarmCreate({
+        stationId: station_id, schedule: schedule, label, enabled, volume,
+        fadeSeconds: fade_seconds, stopAfterMinutes: stop_after_minutes, fallbackStationId: fallback_station_id,
+        missedRunGraceMinutes: missed_run_grace_minutes, wakeIfSupported: wake_if_supported, keepAwakeUntilAlarm: keep_awake_until_alarm
+    }));
+    tool('radio_alarm_update', 'Edit an existing alarm by exact ID. Omitted fields remain unchanged; pass the complete replacement schedule when changing time or recurrence.', z.object({
+        alarm_id: z.string().min(1),
+        station_id: z.string().min(1).optional(),
+        schedule: alarmScheduleSchema.optional(),
+        clear_fallback: z.boolean().optional(),
+        ...alarmOptionsSchema
+    }).refine(value => !(value.clear_fallback && value.fallback_station_id), { message: 'Choose either clear_fallback or fallback_station_id.' }), ({ alarm_id, station_id, schedule, clear_fallback, label, enabled, volume, fade_seconds, stop_after_minutes, fallback_station_id, missed_run_grace_minutes, wake_if_supported, keep_awake_until_alarm }) => service.alarmUpdate(alarm_id, {
+        stationId: station_id, schedule: schedule, clearFallback: clear_fallback,
+        label, enabled, volume, fadeSeconds: fade_seconds, stopAfterMinutes: stop_after_minutes, fallbackStationId: fallback_station_id,
+        missedRunGraceMinutes: missed_run_grace_minutes, wakeIfSupported: wake_if_supported, keepAwakeUntilAlarm: keep_awake_until_alarm
+    }));
+    tool('radio_alarm_set_enabled', 'Explicitly enable or disable an alarm by exact ID and reconcile its native scheduler job.', z.object({ alarm_id: z.string().min(1), enabled: z.boolean() }), ({ alarm_id, enabled }) => service.alarmSetEnabled(alarm_id, enabled));
+    tool('radio_alarm_remove', 'Permanently remove an alarm and its native scheduler job. First list alarms and obtain explicit user confirmation for the exact ID, then pass confirm=true.', z.object({ alarm_id: z.string().min(1), confirm: z.boolean() }), ({ alarm_id, confirm }) => service.alarmRemove(alarm_id, confirm));
+    tool('radio_alarm_sync', 'Reconcile every saved alarm with the operating system scheduler after setup, upgrades, timezone changes, or repair.', undefined, () => service.alarmSync());
+    tool('radio_alarm_control', 'Control one currently ringing alarm: dismiss it, snooze it, keep playing past its automatic stop, or hand it off to normal interactive playback. If multiple alarms ring, supply an exact alarm_id and optionally occurrence_at from radio_alarm_status.', z.object({
+        action: z.enum(['dismiss', 'snooze', 'keep-playing', 'handoff']),
+        alarm_id: z.string().min(1).optional(),
+        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 => ({
+        id: device.id,
+        name: device.name,
+        host: device.host,
+        port: device.port,
+        requiresPassword: device.requiresPassword,
+        airplay2: device.airplay2,
+        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_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;
+}

package/dist/agent/service.js

@@ -0,0 +1,347 @@
+import { randomInt } from 'node:crypto';
+import { defaultAgentControlSettings, themeNames, receiverStyleNames } from '../types.js';
+import { JsonLibraryStore, stationKey } from '../storage/store.js';
+import { ProviderManager } from '../providers/provider-manager.js';
+import { computeListeningStats } from '../activity/stats.js';
+import { connectActiveAlarms } from '../alarms/active-session.js';
+import { connectRadioSession, ensureRadioSession } from './session.js';
+import { launchHeadlessHost, launchRadioTui } from './launcher.js';
+import { PlayerController } from '../player/player-controller.js';
+import { detectPlaybackBackends } from '../player/backend-install.js';
+import { AgentAlarmService } from './alarm-service.js';
+import { appVersion } from '../version.js';
+import { checkForUpdate, updateCommandForInstall } from '../update-check.js';
+export class AgentRadioService {
+    runtime;
+    store;
+    providers;
+    stationCache = new Map();
+    alarms;
+    constructor(runtime, store = new JsonLibraryStore(), providers = new ProviderManager()) {
+        this.runtime = runtime;
+        this.store = store;
+        this.providers = providers;
+        this.alarms = new AgentAlarmService(this.store, id => this.resolveStationId(id), undefined, status => this.handoffAlarm(status));
+    }
+    settings() { return this.store.snapshot().settings; }
+    appearance() {
+        this.assertEnabled();
+        return { themes: themeNames, receiverStyles: receiverStyleNames, current: this.settings() };
+    }
+    async status() {
+        this.assertEnabled();
+        const client = await connectRadioSession();
+        const state = this.store.snapshot();
+        return {
+            connected: Boolean(client),
+            session: client ? await client.status() : null,
+            agentControl: this.agentSettings(),
+            favoriteCount: state.favorites.length,
+            recentCount: state.recent.length,
+            alarmActive: (await connectActiveAlarms()).length > 0,
+            audioOutput: {
+                preferredBackend: state.settings.preferredBackend,
+                preferredAirPlayDevice: state.settings.preferredAirPlayDevice
+            }
+        };
+    }
+    async updateStatus() {
+        this.assertEnabled();
+        const update = await checkForUpdate();
+        const install = updateCommandForInstall();
+        return {
+            installedVersion: appVersion(),
+            latestVersion: update.latestVersion ?? null,
+            updateAvailable: update.updateAvailable,
+            checkedAt: update.checkedAt,
+            error: update.error ?? null,
+            installMethod: install.method,
+            command: install.command,
+            note: 'RadioCLI does not install updates through MCP. Ask the user to approve the command or use Settings, then restart the MCP client.'
+        };
+    }
+    async search(query, limit = 10, countryCode) {
+        this.assertEnabled();
+        const stations = await this.providers.search(query, this.store.snapshot().settings, {
+            limit: clampLimit(limit),
+            countryCode
+        });
+        this.remember(stations);
+        return stations;
+    }
+    async browse(kind, limit = 20) {
+        this.assertEnabled();
+        const state = this.store.snapshot();
+        const bounded = clampLimit(limit, 50);
+        if (kind === 'favorites')
+            return this.remember(state.favorites.slice(0, bounded));
+        if (kind === 'recent')
+            return this.remember(state.recent.slice(0, bounded).map(item => item.station));
+        if (kind === 'track-history')
+            return state.trackHistory.slice(0, bounded);
+        if (kind === 'countries')
+            return this.providers.countries(bounded);
+        if (kind === 'popular')
+            return this.remember(await this.providers.popular(bounded));
+        if (!state.settings.enableNearbyLocation)
+            throw new Error('Nearby location lookup is disabled in RadioCLI settings.');
+        const location = await this.providers.detectLocation();
+        if (!location)
+            throw new Error('RadioCLI could not determine an approximate location.');
+        return this.remember(await this.providers.nearby(location, bounded));
+    }
+    stats() {
+        this.assertEnabled();
+        return computeListeningStats(this.store.snapshot().activity.sessions);
+    }
+    async play(input) {
+        this.assertEnabled();
+        if ((await connectActiveAlarms()).length > 0)
+            throw new Error('An alarm is currently active. Dismiss or keep the alarm from its ringing controls before starting interactive playback.');
+        const queue = await this.stationQueue(input.source ?? 'recent', input.countryCode);
+        if (!input.stationId && queue.length === 0)
+            throw new Error('No station is available for that request.');
+        const station = input.stationId
+            ? await this.findStation(input.stationId, queue)
+            : queue[input.random ? randomInt(queue.length) : Math.max(0, input.index ?? 0)];
+        if (!station)
+            throw new Error(input.stationId ? `Unknown station ID: ${input.stationId}. Search or browse first.` : 'No station is available for that request.');
+        const ordered = [station, ...queue.filter(item => stationKey(item) !== stationKey(station))];
+        return this.send({
+            type: 'play',
+            station,
+            queue: ordered,
+            openNowPlaying: this.agentSettings().focusNowPlaying,
+            ifPlaying: input.ifPlaying ?? 'replace'
+        }, input.openUi);
+    }
+    async control(command, openUi) {
+        this.assertEnabled();
+        const client = await connectRadioSession();
+        if (!client && command.type === 'set-volume') {
+            const volume = Math.min(100, Math.max(0, command.volume));
+            this.store.updateSettings({ volume });
+            return idleResult(`Saved volume ${volume}; no playback session is active.`);
+        }
+        if (!client && ['stop', 'pause', 'resume', 'next', 'previous', 'set-volume', 'set-muted'].includes(command.type)) {
+            if (command.type === 'stop' || command.type === 'pause')
+                return idleResult(command.type === 'stop' ? 'RadioCLI is already stopped.' : 'No playback session is active; pause is already satisfied.');
+            throw new Error('No interactive RadioCLI playback session is active.');
+        }
+        return this.send(command, openUi);
+    }
+    async setFavorite(favorite, stationId) {
+        this.assertEnabled();
+        const client = await connectRadioSession();
+        if (!stationId && client)
+            return client.call({ type: 'set-favorite', favorite });
+        const station = stationId ? await this.findStation(stationId, this.savedStations()) : undefined;
+        if (!station)
+            throw new Error('No station was supplied and no active station is available.');
+        const isFavorite = this.store.isFavorite(station);
+        if (isFavorite !== favorite)
+            this.store.toggleFavorite(station);
+        if (favorite && !isFavorite && this.store.snapshot().settings.shareDirectoryVotes)
+            void this.providers.vote(station);
+        return { ok: true, message: `${favorite ? 'Favorited' : 'Removed favorite'}: ${station.name}`, station };
+    }
+    async updateAppearance(input) {
+        this.assertEnabled();
+        if (input.theme && !themeNames.includes(input.theme))
+            throw new Error(`Unknown theme: ${input.theme}`);
+        if (input.receiverStyle && !receiverStyleNames.includes(input.receiverStyle))
+            throw new Error(`Unknown receiver style: ${input.receiverStyle}`);
+        const client = await connectRadioSession();
+        if (client)
+            return client.call({ type: 'update-settings', settings: input });
+        return this.store.updateSettings(input).settings;
+    }
+    async runCompletionPreset() {
+        const preset = this.agentSettings().completionPreset;
+        if (preset.action === 'play')
+            return this.play({ source: preset.source, countryCode: preset.countryCode, random: preset.source !== 'recent', openUi: preset.openUi, ifPlaying: preset.ifPlaying });
+        return this.control({ type: preset.action }, preset.openUi);
+    }
+    configureCompletionPreset(input) {
+        this.assertEnabled();
+        const agentControl = this.agentSettings();
+        const completionPreset = { ...agentControl.completionPreset, ...input };
+        if (completionPreset.source === 'country' && !completionPreset.countryCode)
+            throw new Error('A two-letter countryCode is required for the country preset source.');
+        if (completionPreset.countryCode)
+            completionPreset.countryCode = completionPreset.countryCode.toUpperCase();
+        return this.store.updateSettings({ agentControl: { ...agentControl, completionPreset } }).settings.agentControl;
+    }
+    async updateAgentPreferences(input) {
+        this.assertEnabled();
+        const agentControl = { ...this.agentSettings(), ...input };
+        const client = await connectRadioSession();
+        if (client)
+            return client.call({ type: 'update-settings', settings: { agentControl } });
+        return this.store.updateSettings({ agentControl }).settings.agentControl;
+    }
+    alarmList() { this.assertEnabled(); return this.alarms.list(); }
+    alarmStatus() { this.assertEnabled(); return this.alarms.status(); }
+    alarmCreate(input) { this.assertEnabled(); return this.alarms.create(input); }
+    alarmUpdate(id, input) { this.assertEnabled(); return this.alarms.update(id, input); }
+    alarmSetEnabled(id, enabled) { this.assertEnabled(); return this.alarms.setEnabled(id, enabled); }
+    alarmRemove(id, confirm) { this.assertEnabled(); return this.alarms.remove(id, confirm); }
+    alarmSync() { this.assertEnabled(); return this.alarms.sync(); }
+    alarmControl(input) { this.assertEnabled(); return this.alarms.controlActive(input); }
+    async listAirPlayDevices() {
+        this.assertEnabled();
+        this.assertAirPlayPlatform();
+        const client = await connectRadioSession();
+        if (client)
+            return (await client.call({ type: 'airplay-list' })).data ?? [];
+        const player = new PlayerController(() => this.store.snapshot().settings);
+        const backends = player.refreshDetectedBackends();
+        if (!backends.includes('airplay'))
+            throw new Error('AirPlay is unavailable on this Mac. Run radiocli doctor to check ffmpeg, dns-sd, and the sender package.');
+        return player.refreshAirPlayDevices();
+    }
+    async selectAirPlayDevice(deviceId, openUi) {
+        this.assertEnabled();
+        this.assertAirPlayPlatform();
+        const devices = await this.listAirPlayDevices();
+        const device = devices.find(item => item.id === deviceId);
+        if (!device)
+            throw new Error('Unknown AirPlay receiver ID. Refresh the receiver list and use an exact returned ID.');
+        if (device.local)
+            return this.useLocalOutput(openUi);
+        this.store.updateSettings({ preferredAirPlayDevice: device.id });
+        return this.send({ type: 'airplay-select', deviceId: device.id }, openUi);
+    }
+    async useLocalOutput(openUi) {
+        this.assertEnabled();
+        const client = await connectRadioSession();
+        if (!client) {
+            const backend = preferredLocalBackend(detectPlaybackBackends());
+            if (!backend)
+                throw new Error('No local playback backend is available. Run radiocli setup to install mpv.');
+            this.store.updateSettings({ preferredBackend: backend });
+            return idleResult(`Audio output set to this device (${backend}).`);
+        }
+        return this.send({ type: 'airplay-local' }, openUi);
+    }
+    async submitAirPlayPasscode(code) {
+        this.assertEnabled();
+        this.assertAirPlayPlatform();
+        const client = await connectRadioSession();
+        if (!client)
+            throw new Error('No active AirPlay session is waiting for a receiver code.');
+        return client.call({ type: 'airplay-passcode', code });
+    }
+    async resolveStationId(id) {
+        return this.findStation(id, this.savedStations());
+    }
+    async handoffAlarm(status) {
+        if (!status.station)
+            throw new Error('This alarm session does not expose a station for interactive handoff.');
+        const result = await this.send({
+            type: 'play',
+            station: status.station,
+            queue: [status.station],
+            openNowPlaying: true,
+            ifPlaying: 'replace'
+        }, undefined, true);
+        if (!result.ok || result.status.playback.state !== 'playing' || !result.status.playback.ready) {
+            throw new Error(result.message || 'Interactive playback did not become ready; the alarm is still playing.');
+        }
+    }
+    async send(command, openUi, allowActiveAlarm = false) {
+        const settings = this.settings();
+        const agentControl = settings.agentControl ?? defaultAgentControlSettings;
+        if (!agentControl.enabled)
+            throw new Error('Agent control is disabled. Run radiocli mcp enable or enable it in Settings.');
+        let client = await connectRadioSession();
+        if (!client) {
+            if (!allowActiveAlarm && (await connectActiveAlarms()).length > 0)
+                throw new Error('An alarm is currently active. Dismiss or keep the alarm from its ringing controls before starting interactive playback.');
+            const shouldOpen = openUi ?? agentControl.openUiOnPlay;
+            client = await ensureRadioSession(async () => {
+                if (shouldOpen)
+                    await launchRadioTui(this.runtime.nodePath, this.runtime.cliPath, encodeAgentCommand({ type: 'status' }));
+                else
+                    await launchHeadlessHost(this.runtime.nodePath, this.runtime.cliPath);
+            });
+        }
+        return client.call(command);
+    }
+    async stationQueue(source, countryCode) {
+        const state = this.store.snapshot();
+        let stations;
+        if (source === 'recent')
+            stations = state.recent.map(item => item.station);
+        else if (source === 'favorite')
+            stations = state.favorites;
+        else if (source === 'popular')
+            stations = await this.providers.popular(50);
+        else {
+            if (!countryCode || !/^[a-z]{2}$/i.test(countryCode))
+                throw new Error('countryCode must be a two-letter ISO country code.');
+            stations = await this.providers.byCountry(countryCode.toUpperCase(), 100);
+        }
+        return this.remember(stations);
+    }
+    savedStations() {
+        const state = this.store.snapshot();
+        return [...state.favorites, ...state.recent.map(item => item.station), ...state.imported, ...this.stationCache.values()];
+    }
+    async findStation(id, candidates) {
+        const normalized = id.trim();
+        const local = this.stationCache.get(normalized)
+            ?? candidates.find(station => opaqueStationId(station) === normalized || station.id === normalized);
+        if (local)
+            return local;
+        const separator = normalized.indexOf(':');
+        const provider = separator > 0 ? normalized.slice(0, separator) : 'radio-browser';
+        const providerId = separator > 0 ? normalized.slice(separator + 1) : normalized;
+        if (!['radio-browser', 'radio-garden', 'playlist'].includes(provider))
+            return undefined;
+        const station = await this.providers.byId(provider, providerId);
+        if (station)
+            this.remember([station]);
+        return station ?? undefined;
+    }
+    remember(stations) {
+        for (const station of stations)
+            this.stationCache.set(opaqueStationId(station), station);
+        return stations;
+    }
+    agentSettings() {
+        return this.settings().agentControl ?? defaultAgentControlSettings;
+    }
+    assertEnabled() {
+        if (!this.agentSettings().enabled)
+            throw new Error('Agent control is disabled. Run radiocli mcp enable or enable it in Settings.');
+    }
+    assertAirPlayPlatform() {
+        if (process.platform !== 'darwin')
+            throw new Error('AirPlay control is available only on macOS.');
+    }
+}
+function opaqueStationId(station) { return `${station.provider}:${station.id}`; }
+export function stationForAgent(station) {
+    return {
+        id: opaqueStationId(station),
+        name: station.name,
+        country: station.country,
+        countryCode: station.countryCode,
+        city: station.city,
+        language: station.language,
+        tags: station.tags.slice(0, 8),
+        codec: station.codec,
+        bitrate: station.bitrate,
+        distanceKm: station.distanceKm
+    };
+}
+function encodeAgentCommand(command) { return Buffer.from(JSON.stringify(command)).toString('base64url'); }
+export function decodeAgentCommand(value) { return JSON.parse(Buffer.from(value, 'base64url').toString('utf8')); }
+function clampLimit(value, max = 30) { return Math.min(max, Math.max(1, Math.round(value))); }
+function idleResult(message) {
+    return { ok: true, message, status: { owner: 'headless', station: null, queue: [], playback: { backend: 'none', state: 'idle', volume: 70, muted: false, ready: false } } };
+}
+function preferredLocalBackend(backends) {
+    return backends.includes('mpv') ? 'mpv' : backends.includes('ffplay') ? 'ffplay' : backends.includes('vlc') ? 'vlc' : null;
+}