@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/agent/session.js

@@ -1,13 +1,123 @@
-import { randomBytes } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { parseRadioCommand, parseRadioRequest } from './command-schema.js';
+import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer, request } from 'node:http';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
-export async function startRadioSession(handle, filePath = radioSessionPath()) {
+import { isLoopbackHost, listenLoopback } from '../platform/loopback.js';
+/** The wire protocol accepts appearance/MCP preferences, never experimental-output consent. */
+export function allowedRadioSessionSettings(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).every(key => ['theme', 'receiverStyle', 'agentControl'].includes(key));
+}
+/** Resolve desktop intent at the owner queue boundary, after earlier commands
+ * have completed. In particular, Play/PlayPause must not use a stale snapshot. */
+export function resolveDesktopTransport(action, status) {
+    const { playback, station, queue } = status;
+    const stopped = ['idle', 'stopped'].includes(playback.state);
+    if (action === 'play') {
+        if (playback.state === 'paused')
+            return { type: 'resume' };
+        return stopped && station ? { type: 'resume', restartStopped: true } : null;
+    }
+    if (action === 'pause')
+        return playback.state === 'playing' && playback.backend === 'mpv' ? { type: 'pause' } : null;
+    if (action === 'toggle') {
+        if (!station || playback.backend !== 'mpv')
+            throw new Error('This output cannot toggle pause.');
+        return playback.state === 'playing' ? { type: 'pause' } : playback.state === 'paused' ? { type: 'resume' } : stopped ? { type: 'resume', restartStopped: true } : null;
+    }
+    // Even an idle backend can have an unresolved tune or delayed retry to cancel.
+    if (action === 'stop')
+        return { type: 'stop', retainSelection: true };
+    return station && queue.length > 1 && (stopped || playback.state === 'playing' || playback.state === 'paused')
+        ? { type: action, preservePause: true, preserveStop: true } : null;
+}
+/** Agent and desktop controls must use the same owner queue. A failed command
+ * cannot strand the queue or allow a later command to overtake an active one. */
+export function serializeRadioCommands(handle, options = {}) {
+    let pending = Promise.resolve();
+    let tuning = Promise.resolve();
+    let admitted = 0;
+    const tunes = new Set();
+    return (input, permitted) => {
+        let command;
+        try {
+            command = parseRadioCommand(input);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const priority = command.type === 'stop' || command.type === 'alarm-preempt' || command.type === 'tui-cancel'
+            || command.type === 'desktop-transport' && command.action === 'stop';
+        const checkPermission = async () => { if (permitted && !await permitted())
+            throw new Error('Desktop media controls are suspended.'); };
+        if (options.responsive && command.type === 'status')
+            return Promise.resolve().then(async () => { await checkPermission(); return handle(command); });
+        if (options.responsive && priority) {
+            const interrupted = [...tunes];
+            const priorPending = pending;
+            const priorTuning = tuning;
+            const work = checkPermission().then(() => {
+                for (const controller of interrupted)
+                    controller.abort(new DOMException('Tuning canceled by Stop or alarm.', 'AbortError'));
+                return handle(command);
+            });
+            pending = work.then(() => undefined, () => priorPending);
+            tuning = work.then(() => undefined, () => priorTuning);
+            return work;
+        }
+        if (admitted >= (options.limit ?? 128))
+            return Promise.reject(new Error('RadioCLI control queue is busy. Status and Stop remain available.'));
+        admitted++;
+        const replacesTune = ['play', 'airplay-select', 'airplay-local'].includes(command.type);
+        const transport = replacesTune || ['pause', 'resume', 'next', 'previous', 'desktop-transport'].includes(command.type);
+        const long = options.responsive && (['play', 'resume', 'next', 'previous', 'airplay-select', 'airplay-local'].includes(command.type) || command.type === 'desktop-transport' && ['play', 'next', 'previous'].includes(command.action));
+        const replaced = options.responsive && replacesTune ? [...tunes] : [];
+        const priorTuning = tuning;
+        let executing = false;
+        const controller = new AbortController();
+        if (options.responsive && transport)
+            tunes.add(controller);
+        const fence = options.responsive && transport && !replacesTune ? Promise.all([pending, tuning]).then(() => undefined) : pending;
+        const start = abortableControl(fence, controller.signal).then(async () => {
+            await checkPermission();
+            controller.signal.throwIfAborted();
+            for (const earlier of replaced)
+                earlier.abort(new DOMException('Tuning canceled by a replacement.', 'AbortError'));
+            executing = true;
+            const result = handle(command, controller.signal);
+            return { result };
+        });
+        const result = abortableControl(start.then(({ result }) => result), controller.signal).finally(() => { admitted--; tunes.delete(controller); });
+        // Tune completion is separate from command admission. A later tune replaces
+        // an active one, while Stop and status bypass both queues entirely.
+        pending = (long ? start : result).then(() => undefined, () => undefined);
+        if (long)
+            tuning = result.then(() => undefined, () => executing ? undefined : priorTuning);
+        // Cancellation is an expected control outcome. Keep the rejection available
+        // to the caller without leaking it while another transport action is awaited.
+        void result.catch(() => undefined);
+        return result;
+    };
+}
+function abortableControl(work, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener('abort', abort); reject(signal.reason); };
+        signal.addEventListener('abort', abort, { once: true });
+        void work.then(value => { signal.removeEventListener('abort', abort); resolve(value); }, error => { signal.removeEventListener('abort', abort); reject(error); });
+    });
+}
+/** Use queue: 'owner' only when handle submits directly to the owner's shared
+ * serialized dispatcher. Other callers retain the session's own FIFO. */
+export async function startRadioSession(handle, filePath = radioSessionPath(), options = {}) {
     const ownerPath = `${filePath}.owner`;
     acquireOwner(ownerPath);
     const token = randomBytes(32).toString('hex');
     let serial = Promise.resolve();
+    const requests = new Map();
     const server = createServer((req, res) => {
         res.setHeader('content-type', 'application/json');
         if (req.headers.authorization !== `Bearer ${token}`) {
@@ -20,27 +130,51 @@ export async function startRadioSession(handle, filePath = radioSessionPath()) {
             res.end('{}');
             return;
         }
-        const work = serial.then(async () => {
+        const accept = async () => {
             const body = await readBody(req);
-            return handle(JSON.parse(body));
-        });
-        serial = work.then(() => undefined, () => undefined);
+            const { command, requestId } = parseRadioRequest(JSON.parse(body));
+            const execute = () => handle(command, req.headers['x-radiocli-client'] === 'cli' ? 'cli' : 'agent');
+            if (!requestId || command.type === 'status')
+                return execute();
+            const fingerprint = createHash('sha256').update(JSON.stringify(command)).digest('hex');
+            const existing = requests.get(requestId);
+            if (existing) {
+                if (existing.fingerprint !== fingerprint)
+                    throw new Error('This request ID was already used for a different command.');
+                return existing.result;
+            }
+            for (const [id, entry] of requests)
+                if (entry.settledAt && (Date.now() - entry.settledAt > 300_000 || requests.size >= 256))
+                    requests.delete(id);
+            if (requests.size >= 256) {
+                // Stop/preemption are intrinsically idempotent and must remain available
+                // even when ordinary requests occupy the entire bounded outcome cache.
+                if (command.type === 'stop' || command.type === 'alarm-preempt' || command.type === 'desktop-transport' && command.action === 'stop')
+                    return execute();
+                throw new Error('RadioCLI has too many active control requests.');
+            }
+            const entry = { fingerprint, result: Promise.resolve().then(execute) };
+            requests.set(requestId, entry);
+            void entry.result.then(() => { entry.settledAt = Date.now(); }, () => { entry.settledAt = Date.now(); });
+            return entry.result;
+        };
+        // An owner shared with desktop controls already serializes accepted work.
+        // Submit each authenticated, complete request directly to that queue so a
+        // later desktop action cannot overtake an earlier HTTP request here.
+        const work = options.queue === 'owner' ? accept() : serial.then(accept);
+        if (options.queue !== 'owner')
+            serial = work.then(() => undefined, () => undefined);
         void work.then(result => res.end(JSON.stringify(result))).catch(error => {
             res.statusCode = 400;
             res.end(JSON.stringify({ error: error instanceof Error ? error.message : 'Radio control failed.' }));
         });
     });
     try {
-        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')
-            throw new Error('Unable to create RadioCLI control endpoint.');
+        const address = await listenLoopback(server);
         const discovery = {
             version: 1,
-            host: '127.0.0.1',
+            protocol: 2,
+            host: address.host,
             port: address.port,
             token,
             pid: process.pid,
@@ -61,13 +195,14 @@ export async function startRadioSession(handle, filePath = radioSessionPath()) {
         throw error;
     }
 }
-export async function connectRadioSession(filePath = radioSessionPath()) {
+export async function connectRadioSession(filePath = radioSessionPath(), options = {}) {
+    options.signal?.throwIfAborted();
     if (!existsSync(filePath))
         return null;
     let discovery;
     try {
         discovery = JSON.parse(readFileSync(filePath, 'utf8'));
-        if (discovery.version !== 1 || discovery.host !== '127.0.0.1' || !Number.isInteger(discovery.port) || !discovery.token) {
+        if (discovery.version !== 1 || !isLoopbackHost(discovery.host) || !Number.isInteger(discovery.port) || !discovery.token) {
             throw new Error('invalid');
         }
     }
@@ -75,48 +210,72 @@ export async function connectRadioSession(filePath = radioSessionPath()) {
         rmSync(filePath, { force: true });
         return null;
     }
-    const call = async (command) => {
-        const payload = JSON.stringify(command);
+    const call = async (command, requestId = randomUUID()) => {
+        const validated = parseRadioCommand(command);
+        const payload = JSON.stringify(discovery.protocol === 2 ? { version: 2, requestId, command: validated } : validated);
         return new Promise((resolve, reject) => {
             const req = request({
-                host: '127.0.0.1',
+                host: discovery.host,
+                // Local control tokens must never be forwarded by an environment proxy.
+                agent: false,
+                signal: options.signal,
                 port: discovery.port,
                 path: '/command',
                 method: 'POST',
                 headers: {
                     authorization: `Bearer ${discovery.token}`,
+                    'x-radiocli-client': options.source ?? 'agent',
                     'content-type': 'application/json',
                     'content-length': Buffer.byteLength(payload)
                 }
             }, res => {
                 let text = '';
-                res.on('data', value => { text += String(value); });
+                res.setEncoding('utf8');
+                res.on('data', value => { text += String(value); if (Buffer.byteLength(text) > 8 * 1024 * 1024)
+                    res.destroy(new Error('RadioCLI response too large.')); });
+                res.once('error', reject);
                 res.on('end', () => {
-                    if (res.statusCode && res.statusCode < 300)
-                        resolve(JSON.parse(text));
-                    else
-                        reject(new Error(parseError(text)));
+                    try {
+                        if (res.statusCode && res.statusCode < 300) {
+                            const parsed = JSON.parse(text);
+                            if (typeof parsed.ok !== 'boolean' || typeof parsed.message !== 'string' || !parsed.status?.playback || !Array.isArray(parsed.status.queue))
+                                throw new Error('Invalid RadioCLI control response.');
+                            resolve(parsed);
+                        }
+                        else
+                            reject(new Error(parseError(text)));
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
                 });
             });
             req.once('error', reject);
-            req.setTimeout(15_000, () => req.destroy(new Error('RadioCLI control request timed out.')));
+            const timeout = command.type === 'status' ? 5000 : ['stop', 'alarm-preempt'].includes(command.type) ? 15_000 : 120_000;
+            req.setTimeout(timeout, () => req.destroy(new Error(`RadioCLI control request timed out. Request ID: ${requestId}. Retry with the same ID to retrieve its outcome.`)));
             req.end(payload);
         });
     };
     try {
         await call({ type: 'status' });
+        options.signal?.throwIfAborted();
         return { call, status: async () => (await call({ type: 'status' })).status };
     }
     catch {
-        if (!processAlive(discovery.pid) || discoveryAgeMs(filePath, discovery) > 60_000) {
+        options.signal?.throwIfAborted();
+        // A slow command does not prove that a playback host is dead. Retain both
+        // ownership records while its PID is alive so a second host cannot start.
+        if (!processAlive(discovery.pid)) {
             removeIfOwned(filePath, discovery);
             removeOwner(`${filePath}.owner`, discovery.pid);
         }
         return null;
     }
 }
-export async function ensureRadioSession(start, timeoutMs = 15_000) {
-    const existing = await connectRadioSession();
+export async function ensureRadioSession(start, timeoutMs = 15_000, options = {}) {
+    options.signal?.throwIfAborted();
+    const existing = await connectRadioSession(undefined, options);
+    options.signal?.throwIfAborted();
     if (existing)
         return existing;
     const lockPath = `${radioSessionPath()}.launch`;
@@ -124,16 +283,18 @@ export async function ensureRadioSession(start, timeoutMs = 15_000) {
     try {
         acquireOwner(lockPath);
         ownsLaunch = true;
-        const appeared = await connectRadioSession();
+        const appeared = await connectRadioSession(undefined, options);
+        options.signal?.throwIfAborted();
         if (appeared)
             return appeared;
         await start();
-        return await waitForSession(timeoutMs);
+        options.signal?.throwIfAborted();
+        return await waitForSession(timeoutMs, options);
     }
     catch (error) {
         if (ownsLaunch || !(error instanceof Error) || !error.message.includes('already active'))
             throw error;
-        return waitForSession(timeoutMs);
+        return waitForSession(timeoutMs, options);
     }
     finally {
         if (ownsLaunch)
@@ -143,22 +304,45 @@ export async function ensureRadioSession(start, timeoutMs = 15_000) {
 function radioSessionPath() {
     return join(runtimeDirectory(), 'agent-session.json');
 }
-async function waitForSession(timeoutMs) {
+/** Optional terminal recovery may fall back to inline playback only when no
+ * live or unknown owner could already be using this library's audio session. */
+export function radioSessionMayBeActive() {
+    for (const path of [`${radioSessionPath()}.owner`, `${radioSessionPath()}.launch`, radioSessionPath()]) {
+        try {
+            const text = readFileSync(path, 'utf8');
+            const pid = path.endsWith('.json') ? JSON.parse(text).pid : Number(text.trim());
+            if (!Number.isSafeInteger(pid) || pid <= 0 || processAlive(pid))
+                return true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                return true;
+        }
+    }
+    return false;
+}
+async function waitForSession(timeoutMs, options) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        const client = await connectRadioSession();
+        options.signal?.throwIfAborted();
+        const client = await connectRadioSession(undefined, options);
+        options.signal?.throwIfAborted();
         if (client)
             return client;
-        await new Promise(resolve => setTimeout(resolve, 100));
+        await controlPollDelay(options.signal);
     }
     throw new Error('RadioCLI was launched but its control session did not become ready.');
 }
+function controlPollDelay(signal) {
+    signal?.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); reject(signal?.reason); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, 100);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
 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');
+    return platformPaths().runtime;
 }
 function acquireOwner(path) {
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
@@ -214,23 +398,13 @@ function processAlive(pid) {
         return error.code === 'EPERM';
     }
 }
-function discoveryAgeMs(path, discovery) {
-    const created = Date.parse(discovery.createdAt);
-    if (Number.isFinite(created))
-        return Math.max(0, Date.now() - created);
-    try {
-        return Math.max(0, Date.now() - statSync(path).mtimeMs);
-    }
-    catch {
-        return 0;
-    }
-}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         let body = '';
+        req.setEncoding('utf8');
         req.on('data', value => {
             body += String(value);
-            if (body.length > 1_000_000)
+            if (Buffer.byteLength(body) > 4 * 1024 * 1024)
                 req.destroy(new Error('Request too large.'));
         });
         req.on('end', () => resolve(body));

package/dist/agent/tui-session.js

@@ -0,0 +1,213 @@
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:net';
+import { join } from 'node:path';
+import { PlayerController } from '../player/player-controller.js';
+import { launchHeadlessHost } from './launcher.js';
+import { platformPaths } from '../platform/paths.js';
+import { storageReadiness } from '../platform/storage.js';
+import { listenLoopback } from '../platform/loopback.js';
+import { ensureRadioSession, radioSessionMayBeActive } from './session.js';
+export async function openTuiSession() {
+    if (!radioSessionMayBeActive()) {
+        if (process.env.RADIOCLI_TUI_PLAYBACK === 'inline')
+            return { warning: 'Playback runs in this terminal. Crash recovery is disabled by RADIOCLI_TUI_PLAYBACK=inline.' };
+        if (storageReadiness(join(platformPaths().runtime, 'agent-session.json')).status === 'unavailable') {
+            return { warning: 'Playback recovery is unavailable: the runtime directory is not writable. Set RADIOCLI_HOME to a private writable directory.' };
+        }
+        const probe = createServer();
+        try {
+            await listenLoopback(probe);
+        }
+        catch {
+            return { warning: 'Playback recovery is unavailable: this environment blocks local loopback control. Playback runs in this terminal.' };
+        }
+        finally {
+            await new Promise(resolve => probe.close(() => resolve()));
+        }
+    }
+    return { session: await TuiSession.connect() };
+}
+/** A terminal is a view of the existing playback owner. Its death must never
+ * destroy the owner's IPC connection, queue, timers, or listening history. */
+export class TuiSession {
+    client;
+    clientId;
+    status;
+    listeners = new Set();
+    timer;
+    revision = 0;
+    closing;
+    closed = false;
+    constructor(client, clientId, status) {
+        this.client = client;
+        this.clientId = clientId;
+        this.status = status;
+    }
+    static async connect() {
+        const cli = fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../cli.tsx' : '../cli.js', import.meta.url));
+        const client = await ensureRadioSession(() => launchHeadlessHost(process.execPath, cli), 15_000, { source: 'cli' });
+        const clientId = randomUUID();
+        let result;
+        try {
+            result = await client.call({ type: 'tui-attach', pid: process.pid, clientId });
+        }
+        catch (error) {
+            if (error instanceof Error && /Invalid radio command|Unsupported radio command/i.test(error.message)) {
+                throw new Error('The running player predates TUI recovery. Run radiocli stop, then reopen radiocli to use the updated player.');
+            }
+            throw error;
+        }
+        if (!result.ok)
+            throw new Error(result.message);
+        if (!result.status.tui)
+            throw new Error('The playback host does not support terminal recovery. Stop the older session and reopen RadioCLI.');
+        const session = new TuiSession(client, clientId, result.status);
+        session.poll();
+        return session;
+    }
+    subscribe(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+    async call(command) {
+        if (this.closed)
+            throw new Error('RadioCLI terminal session is closed.');
+        const result = await this.client.call(command);
+        this.revision++;
+        this.status = result.status;
+        this.emit();
+        return result;
+    }
+    report(error) {
+        this.status = { ...this.status, persistenceWarning: error instanceof Error ? error.message : String(error) };
+        this.emit();
+    }
+    disconnect() {
+        clearTimeout(this.timer);
+        this.closed = true;
+        this.listeners.clear();
+    }
+    close() {
+        return this.closing ??= (async () => {
+            clearTimeout(this.timer);
+            try {
+                const result = await this.call({ type: 'tui-detach', clientId: this.clientId });
+                if (!result.ok)
+                    throw new Error(result.message);
+            }
+            finally {
+                this.disconnect();
+            }
+        })();
+    }
+    poll() {
+        this.timer = setTimeout(() => {
+            const revision = this.revision;
+            void this.client.status().then(status => {
+                if (!this.closed && revision === this.revision && JSON.stringify(status) !== JSON.stringify(this.status)) {
+                    this.status = status;
+                    this.emit();
+                }
+            }).catch(() => {
+                if (!this.closed && revision === this.revision) {
+                    this.status = { ...this.status, playback: { ...this.status.playback, state: 'error', ready: false,
+                            message: 'Playback host disconnected. Reopen RadioCLI to reconnect.' } };
+                    this.emit();
+                }
+            }).finally(() => { if (!this.closed && !this.closing)
+                this.poll(); });
+        }, 250);
+        this.timer.unref();
+    }
+    emit() { for (const listener of this.listeners)
+        listener(); }
+}
+/** Keep synchronous presentation queries local, while every audio mutation
+ * reaches the same owner used by CLI, agent, alarm, and desktop controls. */
+export class TuiPlayer extends PlayerController {
+    session;
+    constructor(session, settings) {
+        super(settings);
+        this.session = session;
+    }
+    getState() { return { ...this.session.status.playback }; }
+    onChange(listener) {
+        listener(this.getState());
+        return this.session.subscribe(() => listener(this.getState()));
+    }
+    onMetadata(listener) {
+        let previous;
+        return this.session.subscribe(() => {
+            const metadata = this.session.status.nowPlaying;
+            const key = JSON.stringify(metadata);
+            if (metadata && key !== previous) {
+                previous = key;
+                listener(metadata);
+            }
+        });
+    }
+    diagnostics() { return { ...this.session.status.tui.diagnostics }; }
+    desktopMediaCompatible() { return this.session.status.tui.desktopMediaCompatible; }
+    detectedBackends() { return [...this.session.status.tui.diagnostics.availableBackends]; }
+    refreshDetectedBackends() {
+        void this.session.call({ type: 'tui-refresh' }).catch(error => this.session.report(error));
+        return this.detectedBackends();
+    }
+    detectedAirPlayDevices() { return [...this.session.status.tui.devices]; }
+    airPlaySelectionRequired() { return this.session.status.tui.selectionRequired; }
+    async refreshAirPlayDevices() {
+        const result = await this.session.call({ type: 'airplay-list' });
+        if (!result.ok)
+            throw new Error(result.message);
+        return result.data ?? [];
+    }
+    async selectAirPlayDevice(deviceId) { return (await this.session.call({ type: 'tui-output', deviceId })).ok; }
+    async submitAirPlayPasscode(code) { return this.control({ type: 'airplay-passcode', code }); }
+    async pause() { return this.control({ type: 'pause' }); }
+    async resume() { return this.control({ type: 'resume' }); }
+    async togglePause() { return this.control({ type: 'tui-toggle-pause' }); }
+    async setVolume(volume, options = {}) {
+        return this.control({ type: 'set-volume', volume: Math.max(0, Math.min(100, Math.round(volume))), allowStopped: options.allowStopped });
+    }
+    async adjustVolume(delta) { return this.control({ type: 'tui-adjust-volume', delta }); }
+    async setMuted(muted, options = {}) { return this.control({ type: 'set-muted', muted, allowStopped: options.allowStopped }); }
+    async toggleMute() { return this.control({ type: 'tui-toggle-muted' }); }
+    async stop() { await this.session.call({ type: 'stop', retainSelection: true }); }
+    async play() { throw new Error('Terminal playback must use the shared radio engine.'); }
+    async control(command) {
+        const result = await this.session.call(command);
+        return { ok: result.ok, message: result.message };
+    }
+}
+export class TuiRadioEngine {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    snapshot() {
+        const status = this.session.status;
+        return { station: status.station, tuningStation: status.tui?.tuningStation ?? null, queue: [...status.queue],
+            playback: { ...status.playback }, nowPlaying: status.nowPlaying ?? null, warning: status.persistenceWarning, message: status.tui?.message };
+    }
+    onChange(listener) { listener(this.snapshot()); return this.session.subscribe(() => listener(this.snapshot())); }
+    clearWarning() { this.session.status.persistenceWarning = undefined; }
+    cancel() { void this.session.call({ type: 'tui-cancel' }).catch(error => this.session.report(error)); }
+    async tune(station, options = {}) {
+        options.signal?.throwIfAborted();
+        const abort = () => this.cancel();
+        options.signal?.addEventListener('abort', abort, { once: true });
+        try {
+            const result = await this.session.call({ type: 'play', station, queue: options.queue, startPaused: options.startPaused });
+            options.signal?.throwIfAborted();
+            if (!result.ok || !result.status.station)
+                throw new Error(result.message);
+            return result.status.station;
+        }
+        finally {
+            options.signal?.removeEventListener('abort', abort);
+        }
+    }
+    async stop(options = {}) { await this.session.call({ type: 'stop', ...options }); }
+    async pause() { const result = await this.session.call({ type: 'pause' }); return { ok: result.ok, message: result.message }; }
+    async resume() { const result = await this.session.call({ type: 'resume' }); return { ok: result.ok, message: result.message }; }
+    select(station, queue) { void this.session.call({ type: 'tui-select', station, queue }).catch(error => this.session.report(error)); }
+    close() { return this.session.close(); }
+}