@feralfile/cli 1.5.0 → 2.0.0

package/dist/src/config.js

@@ -10,10 +10,8 @@ exports.getBrowserConfig = getBrowserConfig;
 exports.getPlaylistConfig = getPlaylistConfig;
 exports.getFeedConfig = getFeedConfig;
 exports.getFF1DeviceConfig = getFF1DeviceConfig;
-exports.getModelConfig = getModelConfig;
 exports.validateConfig = validateConfig;
 exports.createSampleConfig = createSampleConfig;
-exports.listAvailableModels = listAvailableModels;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -58,62 +56,12 @@ function getConfigPaths() {
  * Load configuration from config.json or environment variables
  * Priority: config.json > .env > defaults
  *
- * @returns {Object} Configuration object with model settings
- * @returns {string} returns.defaultModel - Name of the default model to use
- * @returns {Object} returns.models - Available models configuration
+ * @returns {Object} Configuration object
  * @returns {number} returns.defaultDuration - Default duration per item in seconds
  */
 function loadConfig() {
     const { localPath, userPath } = getConfigPaths();
-    // Default configuration supporting Grok as default
     const defaultConfig = {
-        defaultModel: process.env.DEFAULT_MODEL || 'claude',
-        models: {
-            claude: {
-                apiKey: process.env.ANTHROPIC_API_KEY || '',
-                baseURL: 'https://api.anthropic.com/v1/',
-                model: 'claude-sonnet-4-6',
-                availableModels: ['claude-opus-4-7', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
-                timeout: 30000,
-                maxRetries: 3,
-                temperature: 0.3,
-                maxTokens: 4000,
-                supportsFunctionCalling: true,
-            },
-            grok: {
-                apiKey: process.env.GROK_API_KEY || '',
-                baseURL: process.env.GROK_API_BASE_URL || 'https://api.x.ai/v1',
-                model: process.env.GROK_MODEL || 'grok-beta',
-                availableModels: ['grok-beta', 'grok-2-1212', 'grok-2-vision-1212'],
-                timeout: parseInt(process.env.TIMEOUT || '30000', 10),
-                maxRetries: parseInt(process.env.MAX_RETRIES || '3', 10),
-                temperature: parseFloat(process.env.TEMPERATURE || '0.3'),
-                maxTokens: parseInt(process.env.MAX_TOKENS || '4000', 10),
-                supportsFunctionCalling: true,
-            },
-            gpt: {
-                apiKey: process.env.OPENAI_API_KEY || '',
-                baseURL: 'https://api.openai.com/v1',
-                model: 'gpt-4.1',
-                availableModels: ['gpt-4.1', 'gpt-4.1-mini', 'gpt-4o', 'gpt-4o-mini', 'gpt-4-turbo'],
-                timeout: 30000,
-                maxRetries: 3,
-                temperature: 0.3,
-                maxTokens: 4000,
-                supportsFunctionCalling: true,
-            },
-            gemini: {
-                apiKey: process.env.GEMINI_API_KEY || '',
-                baseURL: 'https://generativelanguage.googleapis.com/v1beta/openai/',
-                model: 'gemini-2.5-flash',
-                availableModels: ['gemini-2.5-flash-lite', 'gemini-2.5-flash', 'gemini-flash-lite-latest'],
-                timeout: 30000,
-                maxRetries: 3,
-                temperature: 0.3,
-                maxTokens: 4000,
-                supportsFunctionCalling: true,
-            },
-        },
         defaultDuration: parseInt(process.env.DEFAULT_DURATION || '10', 10),
         browser: {
             timeout: parseInt(process.env.BROWSER_TIMEOUT || '90000', 10),
@@ -130,21 +78,10 @@ function loadConfig() {
     if (fs_1.default.existsSync(configPath)) {
         try {
             const fileConfig = JSON.parse(fs_1.default.readFileSync(configPath, 'utf-8'));
-            // Deep merge models configuration
-            const mergedModels = { ...defaultConfig.models };
-            if (fileConfig.models) {
-                Object.keys(fileConfig.models).forEach((modelName) => {
-                    mergedModels[modelName] = {
-                        ...(defaultConfig.models[modelName] || {}),
-                        ...fileConfig.models[modelName],
-                    };
-                });
-            }
             // Merge with defaults, file config takes precedence
             return {
                 ...defaultConfig,
                 ...fileConfig,
-                models: mergedModels,
             };
         }
         catch (error) {
@@ -290,67 +227,16 @@ function getFF1DeviceConfig() {
     };
 }
 /**
- * Get configuration for a specific model
- *
- * @param {string} [modelName] - Name of the model (defaults to defaultModel from config)
- * @returns {Object} Model configuration
- * @returns {string} returns.apiKey - API key for the model
- * @returns {string} returns.baseURL - Base URL for the API
- * @returns {string} returns.model - Model name/identifier
- * @returns {number} returns.timeout - Request timeout in milliseconds
- * @returns {number} returns.maxRetries - Maximum number of retries
- * @returns {number} returns.temperature - Temperature for generation
- * @returns {number} returns.maxTokens - Maximum tokens for generation
- * @returns {boolean} returns.supportsFunctionCalling - Whether model supports function calling
- * @throws {Error} If model is not configured or doesn't support function calling
- */
-function getModelConfig(modelName) {
-    const config = getConfig();
-    const selectedModel = modelName || config.defaultModel;
-    if (!config.models[selectedModel]) {
-        throw new Error(`Model "${selectedModel}" is not configured. Available models: ${Object.keys(config.models).join(', ')}`);
-    }
-    const modelConfig = config.models[selectedModel];
-    if (!modelConfig.supportsFunctionCalling) {
-        throw new Error(`Model "${selectedModel}" does not support function calling`);
-    }
-    const normalizedBaseURL = modelConfig.baseURL?.replace(/\/+$/, '');
-    return {
-        ...modelConfig,
-        baseURL: normalizedBaseURL,
-        defaultDuration: config.defaultDuration,
-    };
-}
-/**
- * Validate configuration for a specific model
+ * Validate configuration
  *
- * @param {string} [modelName] - Name of the model to validate
  * @returns {Object} Validation result
  * @returns {boolean} returns.valid - Whether the configuration is valid
  * @returns {Array<string>} returns.errors - List of validation errors
  */
-function validateConfig(modelName) {
+function validateConfig() {
     const errors = [];
     try {
         const config = getConfig();
-        const selectedModel = modelName || config.defaultModel;
-        if (!config.models[selectedModel]) {
-            errors.push(`Model "${selectedModel}" is not configured. Available: ${Object.keys(config.models).join(', ')}`);
-            return { valid: false, errors };
-        }
-        const modelConfig = config.models[selectedModel];
-        if ((0, config_placeholders_1.isMissingConfigValue)(modelConfig.apiKey)) {
-            errors.push(`API key for "${selectedModel}" is missing or not configured`);
-        }
-        if (!modelConfig.baseURL) {
-            errors.push(`Base URL for "${selectedModel}" is missing`);
-        }
-        if (!modelConfig.model) {
-            errors.push(`Model identifier for "${selectedModel}" is not set`);
-        }
-        if (!modelConfig.supportsFunctionCalling) {
-            errors.push(`Model "${selectedModel}" does not support function calling (required)`);
-        }
         // Validate browser configuration
         if (config.browser) {
             if (config.browser.timeout && typeof config.browser.timeout !== 'number') {
@@ -431,12 +317,3 @@ async function createSampleConfig(targetPath) {
     fs_1.default.writeFileSync(configPath, exampleConfig, 'utf-8');
     return configPath;
 }
-/**
- * List all available models
- *
- * @returns {Array<string>} List of available model names
- */
-function listAvailableModels() {
-    const config = getConfig();
-    return Object.keys(config.models);
-}

package/dist/src/main.js

@@ -1,54 +1,12 @@
 "use strict";
 /**
  * Main Flow Controller
- * Handles both deterministic and AI-driven playlist creation
+ * Builds DP-1 playlists deterministically from structured parameters.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SEND_SHORTCUT_PATTERN = void 0;
-exports.resolveSendShortcutDevice = resolveSendShortcutDevice;
-exports.resolveEffectiveDeviceName = resolveEffectiveDeviceName;
-exports.resolveSendPlaylistDeviceName = resolveSendPlaylistDeviceName;
-exports.sendPreparedPlaylistToDevice = sendPreparedPlaylistToDevice;
 exports.validateRequirements = validateRequirements;
 exports.applyPlaylistDefaults = applyPlaylistDefaults;
 exports.buildPlaylistDirect = buildPlaylistDirect;
-exports.buildPlaylist = buildPlaylist;
 // Suppress Ed25519 experimental warning immediately
 const originalEmitWarning = process.emitWarning;
 process.emitWarning = function (warning, type, ctor) {
@@ -60,83 +18,10 @@ process.emitWarning = function (warning, type, ctor) {
     }
     return originalEmitWarning.apply(this, [warning, type, ctor]);
 };
-const chalk_1 = __importDefault(require("chalk"));
-const readline = __importStar(require("readline"));
 const config_1 = require("./config");
-const logger = __importStar(require("./logger"));
-// Lazy load utilities and orchestrator to avoid circular dependencies
+// Lazy load utilities to avoid circular dependencies
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const getUtilities = () => require('./utilities');
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const getIntentParser = () => require('./intent-parser');
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const getAIOrchestrator = () => require('./ai-orchestrator');
-/**
- * Regex that matches the inline "send last / send playlist / send to <device>"
- * shortcut inside the chat flow. Exported for testing.
- */
-exports.SEND_SHORTCUT_PATTERN = /^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i;
-/**
- * Extract the target device from a sendMatch result, falling back to the CLI
- * --device flag. Exported for testing.
- */
-function resolveSendShortcutDevice(match, cliDefault) {
-    return match[1]?.trim() || cliDefault;
-}
-/**
- * Resolve the effective device name for a send operation.
- * The intent (from NL parsing) takes precedence; CLI flag is the fallback.
- * Exported for testing.
- */
-function resolveEffectiveDeviceName(fromIntent, fromCLI) {
-    return fromIntent || fromCLI;
-}
-/**
- * Sanitize and resolve the device name for the direct send_playlist action path.
- *
- * The intent parser can emit literal "null" or "" as a device name string; these
- * must be treated as absent so the CLI --device fallback is used instead.
- * Exported for testing — mirrors the sanitization in confirmPlaylistForSending().
- */
-function resolveSendPlaylistDeviceName(intentDeviceName, cliDeviceName) {
-    const sanitized = intentDeviceName === 'null' ||
-        intentDeviceName === '' ||
-        intentDeviceName === null ||
-        intentDeviceName === undefined
-        ? undefined
-        : intentDeviceName;
-    return resolveEffectiveDeviceName(sanitized, cliDeviceName);
-}
-/**
- * Verify a playlist for device delivery and send it using the supplied transport.
- *
- * This helper keeps the send branches in `buildPlaylist` testable without
- * duplicating the verification and transport wiring in tests.
- */
-async function sendPreparedPlaylistToDevice(playlist, deps) {
-    const verificationResult = await deps.verifyPlaylist(playlist);
-    if (!verificationResult.valid) {
-        return {
-            success: false,
-            error: verificationResult.error || 'Failed to verify playlist before sending',
-            playlist: null,
-        };
-    }
-    const sendResult = await deps.sendToDevice(playlist, deps.resolveDeviceName());
-    if (sendResult.success) {
-        return {
-            success: true,
-            playlist,
-            deviceName: sendResult.deviceName,
-            device: sendResult.device,
-        };
-    }
-    return {
-        success: false,
-        error: sendResult.error || 'Failed to send playlist',
-        playlist: null,
-    };
-}
 /**
  * Validate and apply constraints to requirements
  *
@@ -242,7 +127,6 @@ function applyPlaylistDefaults(settings = {}) {
 }
 /**
  * Build playlist deterministically from structured parameters
- * Path 1: Direct execution (no AI)
  *
  * @param {Object} params - Playlist parameters
  * @param {Array<Object>} params.requirements - Array of requirements
@@ -261,246 +145,3 @@ async function buildPlaylistDirect(params, options = {}) {
     utilities.initializeUtilities(config);
     return await utilities.buildPlaylistDirect({ requirements, playlistSettings }, options);
 }
-/**
- * Build playlist from natural language request
- * Path 2: AI-driven execution (intent parser → AI orchestrator → utilities)
- *
- * @param {string} userRequest - Natural language request
- * @param {Object} options - Options
- * @param {boolean} [options.verbose=false] - Verbose output
- * @param {string} [options.outputPath='playlist.json'] - Output path
- * @param {string} [options.modelName] - AI model to use
- * @param {boolean} [options.interactive=true] - Interactive mode (allow clarification prompts)
- * @returns {Promise<Object>} Result with playlist
- */
-async function buildPlaylist(userRequest, options = {}) {
-    const { verbose = false, outputPath = 'playlist.json', modelName, interactive = true, deviceName: defaultDeviceName, } = options;
-    // Enable verbose logging if requested
-    if (verbose) {
-        logger.setVerbose(true);
-    }
-    // Initialize utilities with config (indexer endpoint, API key, etc.)
-    const utilities = getUtilities();
-    const config = (0, config_1.getConfig)();
-    utilities.initializeUtilities(config);
-    try {
-        const trimmedRequest = userRequest.trim();
-        const sendMatch = trimmedRequest.match(/^send(?:\s+(?:last|playlist|the playlist))?(?:\s+to\s+(.+))?$/i);
-        if (sendMatch) {
-            const deviceName = sendMatch[1]?.trim() || defaultDeviceName;
-            const { confirmPlaylistForSending } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-send')));
-            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
-            const confirmation = await confirmPlaylistForSending(outputPath, deviceName);
-            if (!confirmation.success) {
-                if (confirmation.message) {
-                    console.log(chalk_1.default.red(`\n${confirmation.message}`));
-                }
-                return {
-                    success: false,
-                    error: confirmation.error || 'Failed to prepare playlist for sending',
-                    action: 'send_playlist',
-                    playlist: null,
-                };
-            }
-            const sendResult = await sendPreparedPlaylistToDevice(confirmation.playlist, {
-                verifyPlaylist,
-                sendToDevice: utilities.sendToDevice,
-                resolveDeviceName: () => confirmation.deviceName,
-            });
-            if (sendResult.success) {
-                console.log(chalk_1.default.green('\nPlaylist sent'));
-                if (sendResult.deviceName) {
-                    console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
-                }
-                console.log();
-                return {
-                    success: true,
-                    playlist: sendResult.playlist,
-                    action: 'send_playlist',
-                };
-            }
-            console.log();
-            console.error(chalk_1.default.red('Send failed'));
-            if (sendResult.error) {
-                console.error(chalk_1.default.red(`  ${sendResult.error}`));
-            }
-            return {
-                success: false,
-                error: sendResult.error || 'Failed to send playlist',
-                playlist: null,
-                action: 'send_playlist',
-            };
-        }
-        // STEP 1: INTENT PARSER
-        // Parse user intent into structured requirements
-        const { processIntentParserRequest } = getIntentParser();
-        let intentParserResult = await processIntentParserRequest(userRequest, {
-            modelName,
-            defaultDeviceName,
-        });
-        // Handle interactive clarification loop
-        while (intentParserResult.needsMoreInfo) {
-            if (!interactive) {
-                // Non-interactive mode: cannot ask for clarification
-                console.error(chalk_1.default.red('\nNeed more information, but running in non-interactive mode. Provide a complete request.'));
-                if (intentParserResult.question) {
-                    console.error(chalk_1.default.yellow('\nQuestion: ') + intentParserResult.question);
-                }
-                process.exit(1);
-            }
-            // Ask user for clarification
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            // Display the AI's question before asking for input
-            if (intentParserResult.question) {
-                console.log(chalk_1.default.cyan('\n') + intentParserResult.question);
-            }
-            const userResponse = await new Promise((resolve) => {
-                rl.question(chalk_1.default.yellow('Your response: '), (answer) => {
-                    rl.close();
-                    resolve(answer.trim());
-                });
-            });
-            if (!userResponse) {
-                console.error(chalk_1.default.red('\nNo response provided. Exiting.'));
-                process.exit(1);
-            }
-            console.log();
-            // Continue intent parser conversation
-            intentParserResult = await processIntentParserRequest(userResponse, {
-                modelName,
-                defaultDeviceName,
-                conversationContext: {
-                    messages: intentParserResult.messages,
-                },
-            });
-        }
-        if (!intentParserResult.approved) {
-            console.error(chalk_1.default.red('\nRequest not approved by intent parser'));
-            return null;
-        }
-        const params = intentParserResult.params;
-        // NOTE: do NOT merge defaultDeviceName into playlistSettings here.
-        // buildPlaylistDirect (src/utilities/index.js) sends whenever
-        // playlistSettings.deviceName is defined, so setting it here would turn
-        // every build-only `chat --device` invocation into an implicit network send.
-        // The CLI --device flag is used only in the two explicit send paths below
-        // (sendMatch shortcut and send_playlist action) via resolveEffectiveDeviceName.
-        // Check if this is a send_playlist action
-        if (params && params.action === 'send_playlist') {
-            // Handle playlist sending directly
-            const sendParams = params;
-            const utilities = getUtilities();
-            const { verifyPlaylist } = await Promise.resolve().then(() => __importStar(require('./utilities/playlist-verifier')));
-            console.log();
-            console.log(chalk_1.default.cyan('Sending to device'));
-            const sendResult = await sendPreparedPlaylistToDevice(sendParams.playlist, {
-                verifyPlaylist,
-                sendToDevice: utilities.sendToDevice,
-                resolveDeviceName: () => resolveSendPlaylistDeviceName(sendParams.deviceName, defaultDeviceName),
-            });
-            if (!sendResult.success) {
-                console.log();
-                console.error(chalk_1.default.red('Send failed'));
-                if (sendResult.error) {
-                    console.error(chalk_1.default.red(`  ${sendResult.error}`));
-                }
-                return {
-                    success: false,
-                    error: sendResult.error || 'Failed to send playlist',
-                    playlist: null,
-                    action: 'send_playlist',
-                };
-            }
-            console.log(chalk_1.default.green('\nPlaylist sent'));
-            if (sendResult.deviceName) {
-                console.log(chalk_1.default.dim(`  Device: ${sendResult.deviceName}`));
-            }
-            console.log();
-            return {
-                success: true,
-                playlist: sendResult.playlist,
-                action: 'send_playlist',
-            };
-        }
-        // Check if this is a publish_playlist action
-        if (params && params.action === 'publish_playlist') {
-            // Publishing was already handled by intent parser, just return the result
-            const publishParams = params;
-            if (publishParams.success) {
-                return {
-                    success: true,
-                    action: 'publish_playlist',
-                    playlistId: publishParams.playlistId,
-                    feedServer: publishParams.feedServer,
-                };
-            }
-            else {
-                return {
-                    success: false,
-                    error: publishParams.error,
-                    action: 'publish_playlist',
-                };
-            }
-        }
-        // STEP 2: AI ORCHESTRATOR (Function Calling)
-        // AI orchestrates function calls to build playlist
-        const { buildPlaylistWithAI } = getAIOrchestrator();
-        let result = await buildPlaylistWithAI(params, {
-            modelName,
-            verbose,
-            outputPath,
-            interactive,
-            defaultDeviceName,
-        });
-        // Handle confirmation loop in interactive mode
-        while (result.needsConfirmation && interactive) {
-            console.log(chalk_1.default.yellow('\n' + result.question));
-            console.log();
-            const rl = readline.createInterface({
-                input: process.stdin,
-                output: process.stdout,
-            });
-            const userResponse = await new Promise((resolve) => {
-                rl.question(chalk_1.default.cyan('Your response: '), (answer) => {
-                    rl.close();
-                    resolve(answer.trim());
-                });
-            });
-            if (!userResponse) {
-                console.error(chalk_1.default.red('\nNo response provided. Canceling.'));
-                return null;
-            }
-            console.log();
-            // Continue orchestrator with user's response
-            result = await buildPlaylistWithAI(result.params, {
-                modelName,
-                verbose,
-                outputPath,
-                interactive,
-                defaultDeviceName,
-                conversationContext: {
-                    messages: result.messages,
-                    userResponse,
-                },
-            });
-        }
-        // If no playlist was built, display the AI's message
-        if (!result.playlist && result.message) {
-            console.log(chalk_1.default.yellow('\n' + result.message));
-        }
-        else if (!result.playlist && result.error) {
-            console.error(chalk_1.default.red('\n' + result.error));
-        }
-        return result;
-    }
-    catch (error) {
-        console.error(chalk_1.default.red('\nError:'), error.message);
-        if (verbose) {
-            console.error(chalk_1.default.dim(error.stack));
-        }
-        throw error;
-    }
-}

package/dist/src/utilities/ff1-device.js

@@ -38,11 +38,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isTransientDeviceNetworkError = isTransientDeviceNetworkError;
+exports.parseRetryAfterMs = parseRetryAfterMs;
 exports.sendPlaylistToDevice = sendPlaylistToDevice;
 const logger = __importStar(require("../logger"));
 const ff1_compatibility_1 = require("./ff1-compatibility");
 const SEND_RETRY_ATTEMPTS = 3;
 const SEND_RETRY_BASE_DELAY_MS = 750;
+const RATE_LIMIT_STATUS = 429;
+// Cap how long a device-supplied Retry-After can stall the CLI, so a buggy or
+// hostile device cannot pin a command for minutes/hours.
+const MAX_RETRY_DELAY_MS = 30_000;
 /**
  * Sleep for a short duration before retrying transient network errors.
  *
@@ -96,6 +101,36 @@ function isTransientDeviceNetworkError(error) {
         : undefined;
     return Boolean(causeCode && networkCodes.has(causeCode));
 }
+/**
+ * parseRetryAfterMs converts an HTTP `Retry-After` header into milliseconds.
+ *
+ * Supports both forms from RFC 7231: a delta-seconds integer (e.g. "5") and an
+ * HTTP-date (e.g. "Wed, 21 Oct 2025 07:28:00 GMT"). Returns undefined when the
+ * header is absent or unparseable, so callers can fall back to their own
+ * backoff. A past date clamps to 0 (retry immediately).
+ *
+ * @param {string | null | undefined} headerValue - Raw Retry-After header value
+ * @returns {number | undefined} Delay in milliseconds, or undefined if unknown
+ */
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue) {
+        return undefined;
+    }
+    const trimmed = headerValue.trim();
+    if (/^\d+$/.test(trimmed)) {
+        return Number(trimmed) * 1000;
+    }
+    // A valid HTTP-date always contains letters (month/day names, or the ISO
+    // 'T'/'Z'). Requiring one rejects bare numeric junk (e.g. "-5", "5.5") that
+    // Date.parse would otherwise misinterpret as a date.
+    if (/[a-zA-Z]/.test(trimmed)) {
+        const dateMs = Date.parse(trimmed);
+        if (!Number.isNaN(dateMs)) {
+            return Math.max(0, dateMs - Date.now());
+        }
+    }
+    return undefined;
+}
 /**
  * Send a DP1 playlist to an FF1 device using the cast API
  *
@@ -185,6 +220,17 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
                     headers,
                     body: JSON.stringify(requestBody),
                 });
+                // The device sheds bursts of commands with HTTP 429 to protect itself.
+                // Treat it as transient: honor Retry-After when present, otherwise back
+                // off, and retry within the bounded attempt budget.
+                if (response.status === RATE_LIMIT_STATUS && attempt < SEND_RETRY_ATTEMPTS) {
+                    const retryAfterMs = parseRetryAfterMs(response.headers.get('retry-after'));
+                    const retryDelay = Math.min(retryAfterMs ?? SEND_RETRY_BASE_DELAY_MS * attempt, MAX_RETRY_DELAY_MS);
+                    logger.warn(`Device rate-limited the command (attempt ${attempt}/${SEND_RETRY_ATTEMPTS}); retrying in ${retryDelay}ms`);
+                    response = null;
+                    await waitForRetry(retryDelay);
+                    continue;
+                }
                 break;
             }
             catch (error) {
@@ -212,6 +258,15 @@ async function sendPlaylistToDevice({ playlist, deviceName, }) {
             const errorText = await response.text();
             logger.error(`Failed to cast to device: ${response.status} ${response.statusText}`);
             logger.debug(`Error details: ${errorText}`);
+            if (response.status === RATE_LIMIT_STATUS) {
+                const deviceLabel = device.name || device.host;
+                return {
+                    success: false,
+                    error: `Device "${deviceLabel}" is busy and rate-limited the command`,
+                    details: 'The Art Computer is shedding a burst of commands to protect itself. ' +
+                        'Wait a few seconds and try again.',
+                };
+            }
             return {
                 success: false,
                 error: `Device returned error ${response.status}: ${response.statusText}`,