@ciphore/radiocli 0.2.2 → 0.2.4

package/dist/alarms/terminal-launcher.js

@@ -1,81 +1,32 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { createServer } from 'node:net';
 import { randomBytes } from 'node:crypto';
-import { basename, delimiter, join } from 'node:path';
-const linuxTerminals = new Set(['alacritty', 'foot', 'ghostty', 'gnome-terminal', 'kitty', 'konsole', 'mate-terminal', 'qterminal', 'terminator', 'tilix', 'wezterm', 'xfce4-terminal', 'x-terminal-emulator']);
-export function detectAlarmTerminal(platform = process.platform, env = process.env) {
-    const configured = env.RADIOCLI_ALARM_TERMINAL?.trim();
-    if (configured && validDescriptor(configured, platform))
-        return configured;
-    if (platform === 'darwin') {
-        const program = `${env.TERM_PROGRAM ?? ''} ${env.__CFBundleIdentifier ?? ''}`.toLowerCase();
-        if (program.includes('iterm'))
-            return 'darwin:iterm';
-        if (program.includes('wezterm'))
-            return 'darwin:wezterm';
-        if (program.includes('ghostty'))
-            return 'darwin:ghostty';
-        if (program.includes('kitty'))
-            return 'darwin:kitty';
-        return 'darwin:apple-terminal';
-    }
-    if (platform === 'win32')
-        return env.WT_SESSION ? 'win32:windows-terminal' : 'win32:console';
-    if (platform === 'linux') {
-        const requested = env.TERMINAL?.trim() || env.TERM_PROGRAM?.trim();
-        const resolved = requested ? resolveExecutable(requested, env) : undefined;
-        if (resolved && linuxTerminals.has(basename(resolved)))
-            return `linux:${resolved}`;
-        for (const command of ['ghostty', 'wezterm', 'kitty', 'gnome-terminal', 'konsole', 'xfce4-terminal', 'x-terminal-emulator']) {
-            const path = resolveExecutable(command, env);
-            if (path)
-                return `linux:${path}`;
-        }
-    }
-    return `${platform}:unsupported`;
-}
+import { listenLoopback } from '../platform/loopback.js';
+import { identifyPlatform, nativeAdapters } from '../platform/runtime.js';
+import { detectGraphicalTerminal, launchTerminalCommand } from '../platform/terminals.js';
 export async function openAlarmControls(options) {
     if (options.hasLiveTui?.())
         return { opened: false, terminal: 'existing-tui', message: 'An existing RadioCLI TUI will show the ringing controls.' };
-    const platform = options.platform ?? process.platform;
-    const env = options.env ?? process.env;
-    const terminal = detectAlarmTerminal(platform, env);
-    const command = shellCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME);
-    const directArgs = environmentCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME);
-    const launch = options.spawn ?? spawnDetached;
-    if (terminal === 'darwin:apple-terminal')
-        await launched(launch('/usr/bin/osascript', appleTerminalScript(command)));
-    else if (terminal === 'darwin:iterm')
-        await launched(launch('/usr/bin/osascript', iTermScript(command)));
-    else if (terminal === 'darwin:wezterm')
-        await launched(launch('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...directArgs]));
-    else if (terminal === 'darwin:ghostty')
-        await launched(launch('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...directArgs]));
-    else if (terminal === 'darwin:kitty')
-        await launched(launch('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...directArgs]));
-    else if (terminal === 'win32:windows-terminal')
-        await launched(launch('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI Alarm', options.nodePath, options.cliPath]));
-    else if (terminal === 'win32:console')
-        await launched(launch('cmd.exe', ['/d', '/c', 'start', 'RadioCLI Alarm', 'cmd.exe', '/k', windowsCommand(options.nodePath, options.cliPath, env.RADIOCLI_HOME)]));
-    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(launch(executable, [...prefix, ...directArgs]));
+    const terminal = await launchTerminalCommand({ ...options, args: [options.cliPath], title: 'RadioCLI Alarm' });
+    if (!options.hasLiveTui)
+        return { opened: false, requested: true, terminal, message: 'Requested RadioCLI alarm controls; TUI startup is unverified.' };
+    const deadline = Date.now() + (options.timeoutMs ?? 8_000);
+    while (true) {
+        if (options.hasLiveTui())
+            return { opened: true, requested: true, terminal, message: 'RadioCLI alarm controls are ready in the saved terminal.' };
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return { opened: false, requested: true, terminal, message: 'Requested RadioCLI alarm controls, but the TUI did not become ready before verification timed out. It may still be starting.' };
+        await new Promise(resolve => setTimeout(resolve, Math.min(50, remaining)));
     }
-    else
-        throw new Error('No supported graphical terminal was found. Open radiocli manually and press ! for alarm controls.');
-    return { opened: true, terminal, message: 'Opened RadioCLI alarm controls in the saved terminal.' };
 }
 /** Ask for macOS Automation access while the user is configuring the alarm. */
 export async function prepareAlarmTerminalAccess(options = {}) {
     const platform = options.platform ?? process.platform;
-    if (platform !== 'darwin')
+    const env = options.env ?? process.env;
+    if (nativeAdapters(identifyPlatform({ platform, env })).terminal !== 'macos')
         return;
-    const terminal = detectAlarmTerminal(platform, options.env ?? process.env);
+    const terminal = detectGraphicalTerminal(platform, env, options.resolve);
     const application = terminal === 'darwin:apple-terminal' ? 'Terminal' : terminal === 'darwin:iterm' ? 'iTerm' : undefined;
     if (!application)
         return;
@@ -94,88 +45,77 @@ export async function verifyAlarmTerminalLaunch(options = {}) {
     const platform = options.platform ?? process.platform;
     const env = options.env ?? process.env;
     await prepareAlarmTerminalAccess(options);
-    const terminal = detectAlarmTerminal(platform, env);
+    const terminal = detectGraphicalTerminal(platform, env, options.resolve);
     if (terminal.endsWith(':unsupported'))
         throw new Error('No supported graphical terminal was found for automatic alarm controls.');
     const token = randomBytes(24).toString('base64url');
     const server = createServer();
-    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', () => resolve()); });
-    const address = server.address();
-    if (!address || typeof address === 'string') {
-        server.close();
-        throw new Error('Unable to create the terminal verification channel.');
-    }
-    const script = "const n=require('node:net');const s=n.connect(Number(process.argv[1]),'127.0.0.1',()=>s.end(process.argv[2]));s.on('error',()=>process.exit(2));";
-    const direct = [options.nodePath ?? process.execPath, '-e', script, String(address.port), token];
-    const command = `${direct.map(shellQuote).join(' ')}; exit`;
-    const launch = options.spawn ?? spawnDetached;
-    const received = new Promise((resolve, reject) => { server.once('connection', socket => { let value = ''; socket.setEncoding('utf8'); socket.on('data', chunk => value += chunk); socket.on('end', () => value === token ? resolve() : reject(new Error('The terminal verification response was not authentic.'))); socket.on('error', reject); }); });
+    const address = await listenLoopback(server);
+    const script = "const n=require('node:net');const s=n.connect(Number(process.argv[1]),process.argv[3],()=>s.end(process.argv[2]));s.on('error',()=>process.exit(2));";
+    const nodePath = options.nodePath ?? process.execPath;
+    const args = ['-e', script, String(address.port), token, address.host];
+    const sockets = new Set();
+    const received = new Promise((resolve, reject) => {
+        server.on('connection', socket => {
+            sockets.add(socket);
+            socket.once('close', () => sockets.delete(socket));
+            let value = '';
+            socket.setEncoding('utf8');
+            socket.on('data', chunk => {
+                value += chunk;
+                if (value.length > token.length) {
+                    socket.destroy();
+                    reject(new Error('The terminal verification response was not authentic.'));
+                }
+            });
+            socket.on('end', () => value === token ? resolve() : reject(new Error('The terminal verification response was not authentic.')));
+            socket.on('error', reject);
+        });
+    });
+    // A callback can fail while the launcher is still reporting its own result.
+    // Keep the rejection observed until it is awaited below.
+    void received.catch(() => undefined);
     try {
-        if (terminal === 'darwin:apple-terminal')
-            await launched(launch('/usr/bin/osascript', appleTerminalScript(command)));
-        else if (terminal === 'darwin:iterm')
-            await launched(launch('/usr/bin/osascript', iTermScript(command)));
-        else if (terminal === 'darwin:wezterm')
-            await launched(launch('/usr/bin/open', ['-na', 'WezTerm', '--args', 'start', '--always-new-process', '--', ...direct]));
-        else if (terminal === 'darwin:ghostty')
-            await launched(launch('/usr/bin/open', ['-na', 'Ghostty', '--args', '-e', ...direct]));
-        else if (terminal === 'darwin:kitty')
-            await launched(launch('/usr/bin/open', ['-na', 'kitty', '--args', '--detach', ...direct]));
-        else if (terminal === 'win32:windows-terminal')
-            await launched(launch('wt.exe', ['-w', 'new', 'new-tab', '--title', 'RadioCLI Alarm Verification', ...direct]));
-        else if (terminal === 'win32:console')
-            await launched(launch('cmd.exe', ['/d', '/c', 'start', 'RadioCLI Alarm Verification', 'cmd.exe', '/c', windowsCommandArgs(direct)]));
-        else if (terminal.startsWith('linux:')) {
-            const executable = terminal.slice(6);
-            const name = basename(executable);
-            const prefix = name === 'gnome-terminal' || name === 'mate-terminal' || name === 'xfce4-terminal' ? ['--'] : name === 'wezterm' ? ['start', '--always-new-process', '--'] : ['-e'];
-            await launched(launch(executable, [...prefix, ...direct]));
-        }
-        else
-            throw new Error('The saved terminal is not supported for alarm controls.');
+        await launchTerminalCommand({ ...options, nodePath, args, title: 'RadioCLI Alarm Verification', closeOnExit: true });
         await withTimeout(received, options.timeoutMs ?? 8_000, 'The terminal opened but did not connect back to RadioCLI.');
         return terminal;
     }
     finally {
+        for (const socket of sockets)
+            socket.destroy();
         await new Promise(resolve => server.close(() => resolve()));
     }
 }
-function validDescriptor(value, platform) {
-    if (platform === 'darwin')
-        return ['darwin:apple-terminal', 'darwin:iterm', 'darwin:wezterm', 'darwin:ghostty', 'darwin:kitty'].includes(value);
-    if (platform === 'win32')
-        return value === 'win32:windows-terminal' || value === 'win32:console';
-    if (platform === 'linux' && value.startsWith('linux:'))
-        return linuxTerminals.has(basename(value.slice(6)));
-    return false;
+function spawnAttached(command, args) {
+    return spawn(command, [...args], { stdio: 'ignore', windowsHide: true });
 }
-function resolveExecutable(input, env) {
-    if (input.includes('/') && existsSync(input))
-        return input;
-    for (const directory of (env.PATH ?? '').split(delimiter)) {
-        const path = join(directory, input);
-        if (existsSync(path))
-            return path;
-    }
-    return undefined;
+function completed(child, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (work) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            work();
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            finish(() => reject(new Error('Timed out waiting for the macOS Automation permission response.')));
+        }, timeoutMs);
+        child.once('error', error => finish(() => reject(error)));
+        child.once('close', code => finish(() => resolve(code ?? 1)));
+    });
 }
-function shellQuote(value) { return `'${value.replaceAll("'", `'\\''`)}'`; }
-function shellCommand(nodePath, cliPath, home) { return `${home ? `RADIOCLI_HOME=${shellQuote(home)} ` : ''}${shellQuote(nodePath)} ${shellQuote(cliPath)}`; }
-function environmentCommand(nodePath, cliPath, home) { return home ? ['/usr/bin/env', `RADIOCLI_HOME=${home}`, nodePath, cliPath] : [nodePath, cliPath]; }
-function windowsCommand(nodePath, cliPath, home) { return `${home ? `set "RADIOCLI_HOME=${cmdEscape(home)}" && ` : ''}"${nodePath.replaceAll('"', '""')}" "${cliPath.replaceAll('"', '""')}"`; }
-function windowsCommandArgs(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 spawnAttached(command, args) { return spawn(command, [...args], { stdio: 'ignore', windowsHide: true }); }
-function launched(child) { return new Promise((resolve, reject) => { child.once('error', reject); child.once('spawn', () => { child.unref(); resolve(); }); }); }
-function completed(child, timeoutMs) { return new Promise((resolve, reject) => { let settled = false; const finish = (work) => { if (settled)
-    return; settled = true; clearTimeout(timer); work(); }; const timer = setTimeout(() => { child.kill('SIGTERM'); finish(() => reject(new Error('Timed out waiting for the macOS Automation permission response.'))); }, timeoutMs); child.once('error', error => finish(() => reject(error))); child.once('close', code => finish(() => resolve(code ?? 1))); }); }
-async function withTimeout(promise, milliseconds, message) { let timer; try {
-    return await Promise.race([promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(message)), milliseconds); })]);
+async function withTimeout(promise, milliseconds, message) {
+    let timer;
+    try {
+        return await Promise.race([promise, new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(message)), milliseconds);
+            })]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
-finally {
-    if (timer)
-        clearTimeout(timer);
-} }

package/dist/alarms/tui-presence.js

@@ -1,5 +1,5 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { join } from 'node:path';
 export function registerTuiPresence(root = runtimeDirectory(), pid = process.pid) {
     const directory = join(root, 'tui');
@@ -26,9 +26,7 @@ export function hasLiveTui(root = runtimeDirectory(), alive = processAlive) {
     }
     return false;
 }
-function runtimeDirectory() { if (process.env.RADIOCLI_HOME)
-    return join(process.env.RADIOCLI_HOME, 'runtime'); if (process.platform === 'win32')
-    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli'); }
+function runtimeDirectory() { return platformPaths().runtime; }
 function processAlive(pid) { try {
     process.kill(pid, 0);
     return true;

package/dist/cli.js

@@ -5,35 +5,71 @@ import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ProviderManager } from './providers/provider-manager.js';
 import { PlayerController } from './player/player-controller.js';
-import { JsonLibraryStore } from './storage/store.js';
-import { parsePlaylistFile, stationFromUrl, writeM3u } from './playlists/playlist.js';
+import { defaultLibraryPath, JsonLibraryStore } from './storage/store.js';
+import { parsePlaylistFile, writeM3u } from './playlists/playlist.js';
+import { importStreamUrl } from './streams/import-stream.js';
 import { detectPlaybackBackends, playbackBackendStatusLines } from './player/backend-install.js';
-import { resolveCommand } from './player/command.js';
+import { resolveCommand } from './platform/executables.js';
 import { diagnoseCommand } from './player/command-diagnostics.js';
 import { airPlaySenderHealth } from './player/airplay-sender-health.js';
 import { appVersion } from './version.js';
-import { checkForUpdate, updateCommandForInstall } from './update-check.js';
+import { checkForUpdate, installUpdate, updateCommandForInstall } from './update-check.js';
 import { runAlarmCommand } from './alarms/cli.js';
+import { createSchedulerAdapter } from './alarms/scheduler.js';
 import { runSetup } from './setup.js';
+import { runAgentCliCommand, runMcpCommand } from './agent/cli.js';
+import { decodeAgentCommand } from './agent/service.js';
+import { runHeadlessAgentHost } from './agent/headless-host.js';
+import { configureMcpIntegrations } from './agent/mcp-install.js';
+import { defaultAgentControlSettings } from './types.js';
+import { identifyPlatform } from './platform/runtime.js';
+import { platformCapabilities } from './platform/capabilities.js';
+import { hasGraphicalSession } from './platform/desktop.js';
+import { detectPackageManager } from './platform/packages.js';
+import { storageReadiness } from './platform/storage.js';
+import { resolveTerminalCapabilities } from './platform/terminal.js';
+import { networkDiagnostic } from './platform/network.js';
+import { assessPlatformSupport } from './platform/support.js';
+const runtime = { nodePath: process.execPath, cliPath: fileURLToPath(import.meta.url) };
 if (isDirectRun(process.argv[1], import.meta.url)) {
     const args = process.argv.slice(2);
-    if (args.length > 0) {
+    if (args[0] === 'agent-ui') {
+        const encoded = args[1];
+        if (!encoded)
+            throw new Error('Missing RadioCLI agent startup request.');
+        await renderTui(encoded);
+    }
+    else if (args[0] === 'agent-host') {
+        await runHeadlessAgentHost();
+    }
+    else if (args.length > 0) {
         await runCommand(args).catch(error => {
             console.error(error instanceof Error ? error.message : String(error));
             process.exitCode = 1;
         });
     }
     else {
-        const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
-        render(_jsx(App, {}), {
-            // App owns Ctrl+C so it can confirm before performing a clean shutdown.
-            exitOnCtrlC: false,
-            kittyKeyboard: {
-                mode: 'auto',
-                flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes']
-            }
-        });
+        await renderTui();
+    }
+}
+async function renderTui(encodedCommand) {
+    if (!process.stdin.isTTY) {
+        console.error('The interactive TUI needs terminal input. Use radiocli commands in a headless session, or connect with a terminal (for example, ssh -t).');
+        printHelp();
+        process.exitCode = 1;
+        return;
     }
+    const { configureTerminalRenderer } = await import('./ui/terminal-renderer.js');
+    const terminal = await configureTerminalRenderer(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
+    const [{ render }, { App }] = await Promise.all([import('ink'), import('./ui/App.js')]);
+    render(_jsx(App, { initialAgentCommand: encodedCommand ? decodeAgentCommand(encodedCommand) : undefined }), {
+        // App owns Ctrl+C so it can confirm before performing a clean shutdown.
+        exitOnCtrlC: false,
+        isScreenReaderEnabled: terminal.screenReader,
+        interactive: terminal.interactive ? undefined : false,
+        debug: !terminal.interactive,
+        kittyKeyboard: { mode: terminal.interactive ? 'auto' : 'disabled', flags: ['disambiguateEscapeCodes', 'reportEventTypes', 'reportAllKeysAsEscapeCodes'] }
+    });
 }
 export async function runCommand(args) {
     const [command, ...rest] = args;
@@ -49,6 +85,14 @@ export async function runCommand(args) {
         await runAlarmCommand(rest);
         return;
     }
+    if (command === 'mcp') {
+        await runMcpCommand(rest, runtime);
+        return;
+    }
+    if (command === 'agent') {
+        await runAgentCliCommand(rest, runtime);
+        return;
+    }
     if (command === 'setup') {
         if (rest.includes('--help') || rest.includes('-h')) {
             printSetupHelp();
@@ -63,16 +107,29 @@ export async function runCommand(args) {
     if (command === 'doctor') {
         const backends = detectPlaybackBackends();
         const mpvDiagnostic = diagnoseCommand('mpv');
+        const report = await doctorReport(backends, mpvDiagnostic);
         if (rest.includes('--json')) {
-            console.log(JSON.stringify(doctorReport(backends, mpvDiagnostic), null, 2));
+            console.log(JSON.stringify(report, null, 2));
             return;
         }
         console.log(`backends=${backends.join(',') || 'none'}`);
         printMpvDiagnostic(mpvDiagnostic);
         printPlaybackBackendStatus(backends);
+        for (const [name, capability] of Object.entries(report.capabilities)) {
+            console.log(`capability_${name}=${capability.status} ${capability.message}`);
+        }
+        console.log(`network=${report.network.status} ${report.network.message}`);
+        console.log(`support_tier=${report.support.tier} runtime=${report.support.runtime.status}`);
+        console.log(`support_scope=${report.support.scope}`);
+        console.log('support_note=Doctor checks this installation without running packed-install or audio acceptance tests; reference CI results are documented in the platform matrix.');
+        for (const reason of report.support.reasons)
+            console.log(`support_note=${reason}`);
         return;
     }
     if (command === 'update') {
+        const unknown = rest.filter(arg => arg !== '--install');
+        if (unknown.length > 0)
+            throw new Error('Usage: radiocli update [--install]');
         const updateCheck = await checkForUpdate();
         const updateCommand = updateCommandForInstall();
         if (updateCheck.error) {
@@ -84,6 +141,26 @@ export async function runCommand(args) {
             console.log(`available=${updateCheck.updateAvailable ? 'yes' : 'no'}`);
         }
         console.log(`command=${updateCommand.command}`);
+        if (rest.includes('--install')) {
+            const result = await installUpdate(updateCommand.command);
+            if (!result.ok)
+                throw new Error(`Update install failed. Run manually: ${result.command}${result.output ? `\n${result.output}` : ''}`);
+            console.log('updated=yes');
+            const agentControl = new JsonLibraryStore().snapshot().settings.agentControl ?? defaultAgentControlSettings;
+            if (agentControl.enabled) {
+                try {
+                    const repaired = await configureMcpIntegrations(true, runtime);
+                    const failed = repaired.filter(item => item.status === 'failed');
+                    console.log(`mcp_repaired=${failed.length ? 'partial' : 'yes'}`);
+                    if (failed.length)
+                        console.log(`mcp_failures=${failed.map(item => `${item.client}: ${item.detail}`).join('; ')}`);
+                }
+                catch (error) {
+                    console.log(`mcp_repaired=failed ${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            console.log('restart_required=yes');
+        }
         return;
     }
     if (command === 'check') {
@@ -122,12 +199,20 @@ export async function runCommand(args) {
         return;
     }
     if (command === 'import') {
-        const file = rest[0];
-        if (!file) {
-            throw new Error('Usage: radiocli import <playlist.m3u|playlist.pls|playlist.xspf>');
+        const target = rest[0];
+        if (!target) {
+            throw new Error('Usage: radiocli import <stream-url|playlist.m3u|playlist.pls|playlist.xspf> [station name]');
         }
-        const stations = parsePlaylistFile(file);
         const store = new JsonLibraryStore();
+        if (/^https?:\/\//i.test(target)) {
+            const result = await importStreamUrl(target, rest.slice(1).join(' ') || undefined);
+            store.addImported([result.station]);
+            console.log(`imported=${result.station.name}`);
+            if (result.warning)
+                console.log(`warning=${result.warning}`);
+            return;
+        }
+        const stations = parsePlaylistFile(target);
         store.addImported(stations);
         console.log(`imported=${stations.length}`);
         return;
@@ -140,17 +225,6 @@ export async function runCommand(args) {
         console.log(`exported=${file}`);
         return;
     }
-    if (command === 'add-url') {
-        const url = rest[0];
-        if (!url || !/^https?:\/\//i.test(url)) {
-            throw new Error('Usage: radiocli add-url <stream-url> [station name]');
-        }
-        const station = stationFromUrl(url, rest.slice(1).join(' ') || url);
-        const store = new JsonLibraryStore();
-        store.addImported([station]);
-        console.log(`added=${station.name}`);
-        return;
-    }
 }
 export function printHelp() {
     console.log(`RadioCLI
@@ -161,12 +235,14 @@ Usage:
   radiocli check           Show provider/backend health
   radiocli doctor [--json] Show local playback setup guidance
   radiocli setup           Install and verify native playback tools
+  radiocli mcp <command>   Install, inspect, or run the MCP integration
+  radiocli agent <command> Scriptable radio controls for local agents
   radiocli update          Show update availability and install command
+  radiocli update --install Install the latest release and repair enabled MCP entries
   radiocli countries       Print top countries
   radiocli search <query>  Search public stations
-  radiocli import <file>   Import .m3u, .pls, or .xspf streams
+  radiocli import <target> Import a stream URL or local playlist
   radiocli export [file]   Export favorites/imports as .m3u
-  radiocli add-url <url> [name]
   radiocli alarm <command> Manage alarms and scheduled radio
 `);
 }
@@ -182,7 +258,7 @@ export function isDirectRun(entryPath, moduleUrl) {
     }
 }
 function isKnownCommand(command) {
-    return ['check', 'doctor', 'setup', 'update', 'countries', 'search', 'import', 'export', 'add-url', 'alarm'].includes(command);
+    return ['check', 'doctor', 'setup', 'update', 'countries', 'search', 'import', 'export', 'alarm', 'mcp', 'agent'].includes(command);
 }
 function printSetupHelp() {
     console.log(`RadioCLI Setup
@@ -193,8 +269,14 @@ Usage:
   radiocli setup --all --yes             Install mpv, FFmpeg, and VLC
   radiocli setup --only mpv,ffmpeg       Select specific components
   radiocli setup --dry-run               Show commands without installing
+  radiocli setup --mcp                   Enable and configure agent MCP clients
+  radiocli setup --mcp --agent-ui        Open a terminal TUI for agent playback (default)
+  radiocli setup --mcp --headless-agent  Opt out of external terminal windows
+  radiocli setup --no-mcp                Disable and remove agent MCP entries
   radiocli setup --package-manager <pm>  Use brew, winget, scoop, choco,
-                                         apt, dnf, pacman, apk, or zypper
+                                         apt, dnf, pacman, apk, zypper,
+                                         pkg (FreeBSD), pkg_add, pkgin,
+                                         termux-pkg (Termux), or pkgman (Haiku)
 `);
 }
 function printPlaybackBackendStatus(backends) {
@@ -202,14 +284,46 @@ function printPlaybackBackendStatus(backends) {
         console.log(line);
     }
 }
-function doctorReport(backends, mpvDiagnostic) {
+async function doctorReport(backends, mpvDiagnostic) {
     const commands = Object.fromEntries(['mpv', 'ffplay', 'vlc', 'cvlc', 'ffmpeg', 'dns-sd'].map(command => [command, redactHome(resolveCommand(command))]));
     const airPlay = airPlaySenderHealth();
+    const host = identifyPlatform();
+    const terminal = resolveTerminalCapabilities(process.env, { isTTY: Boolean(process.stdout.isTTY), colorDepth: process.stdout.getColorDepth?.() });
+    let scheduler;
+    try {
+        const adapter = createSchedulerAdapter();
+        scheduler = await adapter.probeCapabilities?.();
+    }
+    catch {
+        scheduler = { supported: false, exactWake: false, catchUpAfterWake: false, message: 'The optional scheduler probe failed. Run radiocli alarm doctor for repair guidance.' };
+    }
+    const integrationCommands = [
+        'launchctl', 'schtasks.exe', 'systemctl', 'caffeinate', 'systemd-inhibit',
+        'powershell.exe', 'pwsh.exe', 'osascript', 'wpctl', 'pactl', 'amixer',
+        'open', 'explorer', 'xdg-open', 'pbcopy', 'clip', 'wl-copy', 'xclip', 'xsel',
+        'termux-open-url', 'termux-clipboard-set'
+    ].filter(command => resolveCommand(command) !== null);
+    const capabilities = platformCapabilities(host, {
+        backends,
+        commands: integrationCommands,
+        graphicalSession: hasGraphicalSession(host),
+        packageManager: detectPackageManager(process.platform, host.osRelease),
+        storageWritable: libraryWritesAvailable(),
+        scheduler,
+        unicode: terminal.unicode,
+        color: terminal.colorLevel > 0,
+        screenReader: terminal.screenReader
+    });
     return {
         radioCliVersion: appVersion(),
         nodeVersion: process.version,
         platform: process.platform,
         architecture: process.arch,
+        host: { id: host.id, arch: host.arch, armVersion: host.armVersion, endianness: host.endianness, release: host.release, libc: host.libc, isWsl: host.isWsl },
+        support: { scope: 'current-installation', ...assessPlatformSupport(host) },
+        capabilities,
+        terminal,
+        network: networkDiagnostic(),
         backends,
         commands,
         mpv: redactDiagnostic(mpvDiagnostic),
@@ -224,6 +338,14 @@ function doctorReport(backends, mpvDiagnostic) {
         guidance: playbackBackendStatusLines(backends)
     };
 }
+function libraryWritesAvailable() {
+    try {
+        return storageReadiness(defaultLibraryPath()).status === 'available';
+    }
+    catch {
+        return false;
+    }
+}
 function printMpvDiagnostic(diagnostic) {
     console.log(`mpv_path=${redactHome(diagnostic.path) ?? 'not-found'}`);
     console.log(`mpv_discovery=${diagnostic.discovery}`);

package/dist/platform/capabilities.js

@@ -0,0 +1,53 @@
+import { browserCommands, clipboardCandidates } from './desktop.js';
+import { nativeAdapters } from './runtime.js';
+const available = (message, adapter) => ({ status: 'available', message, ...(adapter ? { adapter } : {}) });
+const unavailable = (message) => ({ status: 'unavailable', message });
+const unverified = (message, adapter) => ({ status: 'unverified', message, ...(adapter ? { adapter } : {}) });
+/**
+ * Availability is independent per feature. Tool discovery never substitutes for
+ * desktop, scheduler, audio-device, permission, or upstream runtime verification.
+ */
+export function platformCapabilities(host, evidence) {
+    const adapters = nativeAdapters(host);
+    const commands = new Set(evidence.commands);
+    const has = (name) => commands.has(name);
+    const backend = ['mpv', 'ffplay', 'vlc', 'airplay'].find(name => evidence.backends.includes(name));
+    const desktop = evidence.graphicalSession;
+    const opener = browserCommands(host).find(item => has(item.command));
+    const clipboard = clipboardCandidates(host).find(item => has(item.command));
+    const schedulerTool = adapters.scheduler === 'launchd' ? 'launchctl'
+        : adapters.scheduler === 'task-scheduler' ? 'schtasks.exe' : adapters.scheduler === 'systemd' ? 'systemctl' : null;
+    const backgroundScheduling = evidence.scheduler
+        ? evidence.scheduler.supported ? available(evidence.scheduler.message, adapters.scheduler ?? undefined) : unavailable(evidence.scheduler.message)
+        : schedulerTool && has(schedulerTool) ? unverified('Native scheduler command found; verify the per-user session with radiocli alarm doctor.', adapters.scheduler ?? undefined)
+            : unavailable(adapters.scheduler ? `The ${schedulerTool} scheduler command is unavailable.` : `Reliable background scheduling has no verified adapter on ${host.id}.`);
+    const sleepTool = adapters.inhibitor === 'caffeinate' ? 'caffeinate' : adapters.inhibitor === 'logind' ? 'systemd-inhibit' : adapters.inhibitor === 'windows' ? 'powershell.exe' : null;
+    const volumeTool = adapters.volume === 'macos' ? has('osascript') ? 'osascript' : null
+        : adapters.volume === 'windows' ? ['powershell.exe', 'pwsh.exe'].find(has)
+            : adapters.volume === 'unix-audio' ? ['wpctl', 'pactl', 'amixer'].find(has) : null;
+    const storage = evidence.storageWritable === true ? available('The local data directory is writable; operations still verify each write.')
+        : evidence.storageWritable === false ? unavailable('Local data is not writable. Set RADIOCLI_HOME to a private writable directory; existing readable data can still be inspected.')
+            : unverified('Local JSON data uses the existing private user paths; writability is checked when used.');
+    return {
+        playback: backend ? available(`${backend} executable detected; stream and audio-device readiness are checked when tuning.`, backend) : unavailable('No playback backend detected. Run radiocli setup or configure a native player path.'),
+        playbackControls: backend === 'mpv' ? available('mpv IPC provides pause, mute, volume, metadata, and media keys.', 'mpv')
+            : unavailable(backend === 'airplay' ? 'AirPlay provides volume and mute; pause and media-key playback controls require local mpv.' : 'Pause, mute, volume, metadata, and media-key playback controls require mpv.'),
+        packageInstallation: evidence.packageManager ? available('Explicit setup plans require confirmation or --yes; --dry-run never installs.', evidence.packageManager) : unavailable('No supported package manager detected; install playback prerequisites manually.'),
+        storage,
+        filePermissions: adapters.posixPermissions ? available('Private files use mode 0600 and private directories use mode 0700; the filesystem must enforce POSIX permissions.') : available('Private user directories inherit Windows ACLs; POSIX modes do not configure Windows ACLs.'),
+        atomicWrites: evidence.storageWritable === false ? unavailable('Atomic replacement requires a writable destination directory.') : available('Temporary files are renamed within the destination directory; write failures are reported.'),
+        externalUrl: desktop && opener ? available('A desktop URL handler is available; execution is checked when used.', opener.command) : unavailable('No usable desktop URL handler/session detected. Open the station homepage manually.'),
+        clipboard: desktop && clipboard ? available('A clipboard command is available; execution is checked when used.', clipboard.command) : unavailable('No usable clipboard command/session detected. RadioCLI can display the text for manual copying.'),
+        terminalReopening: desktop && adapters.terminal ? unverified('A supported installed terminal must be found and its launch verified.', adapters.terminal) : unavailable('No supported graphical terminal session. Use the current TUI or explicitly select headless agent playback.'),
+        backgroundScheduling,
+        catchUp: backgroundScheduling.status === 'available' && evidence.scheduler?.catchUpAfterWake ? available('The native scheduler can deliver a missed occurrence; RadioCLI still enforces the configured grace window.')
+            : backgroundScheduling.status === 'unverified' ? unverified('Catch-up depends on an accessible native user scheduler and its session.') : unavailable('Catch-up delivery is not verified in this session.'),
+        wakeRequests: adapters.scheduler === 'task-scheduler' ? unverified('Task Scheduler can request WakeToRun; hardware, login state, and power policy decide delivery.') : unavailable('No privileged or exact wake request is made on this platform. Catch-up and idle-sleep inhibition are separate capabilities.'),
+        sleepInhibition: sleepTool && has(sleepTool) ? unverified('A sleep-inhibitor tool is installed; its lease must remain alive to provide protection.', sleepTool) : unavailable('No usable per-process sleep inhibitor. Normal playback remains available; sleep may interrupt it.'),
+        systemVolume: volumeTool ? unverified('The system mixer must respond before alarm volume can be raised and restored.', volumeTool) : unavailable('System output volume cannot be adjusted. Set the device volume manually; player volume remains independent.'),
+        unicode: evidence.unicode === false ? unavailable('ASCII decoration mode is selected; international station data is preserved.') : available('Unicode decoration is enabled; terminal font coverage determines glyph appearance.'),
+        color: evidence.color === false ? unavailable('Color is disabled for the terminal or by user preference.') : available('Color is enabled at the terminal supported depth.'),
+        screenReader: available(evidence.screenReader ? 'Screen-reader mode is enabled; decorative animation is disabled.' : 'Screen-reader mode is available through INK_SCREEN_READER=true.'),
+        airPlay: adapters.airPlay && evidence.backends.includes('airplay') ? available('Experimental macOS output; receiver selection and worker readiness are still required.', 'airplay') : unavailable(adapters.airPlay ? 'Experimental AirPlay requires FFmpeg, Bonjour, and the safe optional sender.' : 'AirPlay output is available only on macOS.')
+    };
+}