@williamzujkowski/live-coding-music-mcp 4.0.0 → 4.1.0

package/dist/services/engineChildPath.js

@@ -0,0 +1,28 @@
+/**
+ * Locates the isolated-engine child entrypoint (#307).
+ *
+ * This is its own module, reached by dynamic import, for one reason:
+ * `import.meta` is a **parse error** under this project's Jest setup,
+ * which runs the codebase as CommonJS (there is no
+ * `--experimental-vm-modules`). Any module that so much as mentions
+ * `import.meta` becomes unimportable from a test, and the runner has to
+ * stay testable. Tests pass an explicit child path, so they never load
+ * this file. Same reason `scripts/` is the only other place using it.
+ */
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+/**
+ * Resolves the child entrypoint as a sibling of this module, matching the
+ * extension we are ourselves running as: `.js` from `dist/`, `.ts` under
+ * `tsx`.
+ *
+ * @returns Absolute path to the child, and whether it needs a TS loader
+ */
+export function resolveChildEntrypoint() {
+    const here = fileURLToPath(import.meta.url);
+    const needsTsx = here.endsWith('.ts');
+    return {
+        childPath: path.join(path.dirname(here), needsTsx ? 'engineChild.ts' : 'engineChild.js'),
+        needsTsx,
+    };
+}

package/dist/utils/CategorisedError.js

@@ -0,0 +1,59 @@
+/**
+ * Errors that carry their own category (#382).
+ *
+ * `categorizeError` decides retryability by matching phrases in the
+ * message — `invalid`, `must be`, `not found`, `timed out`. Anything it
+ * does not recognise falls through to `internal`, which is not
+ * retryable and reads to an agent as "the server is broken".
+ *
+ * An audit of every `throw new Error(...)` in `src/` put 47 messages in
+ * that bucket, and at least eleven of them were plainly the caller's
+ * input:
+ *
+ *   Steps cannot exceed 256, got 512
+ *   Hits (9) cannot exceed steps (8)
+ *   Number of sounds must match number of patterns
+ *   MIDI input too large (900000 > 512000 bytes)
+ *
+ * None contains a phrase the matcher looks for, and the difference
+ * decides whether an agent edits its argument or gives up.
+ *
+ * Growing the matcher is the treadmill this replaces: "cannot exceed"
+ * would be the fourth phrase patched in after the fact, after the
+ * `'timed out'` vs `'timeout'` fix and the rate-limit class of #380.
+ * A thrower that knows what kind of failure it has should say so.
+ */
+/** The caller passed something that cannot be accepted. Not retryable; change the argument. */
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * The request is well-formed but the system is not in a state to serve
+ * it, and the message names the action that would fix that — create a
+ * session, destroy one, run init.
+ */
+export class BusinessError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'BusinessError';
+    }
+}
+/**
+ * A failure that may not recur: the model returned something
+ * unparseable, a network hiccup, a service that was briefly unwell.
+ *
+ * The distinction that matters to a caller is whether trying again could
+ * help. `No JSON found in response` means the model produced prose where
+ * a JSON block was asked for — the next attempt often does not, and the
+ * message contains no word the phrase matcher recognises, so it landed
+ * in `internal` and told the caller not to bother.
+ */
+export class TransientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TransientError';
+    }
+}

package/dist/utils/ErrorRecovery.js

@@ -6,7 +6,51 @@ import { Logger } from './Logger.js';
 export class ErrorRecovery {
     logger;
     errorHistory = new Map();
+    /**
+     * Failures that a retry or fallback went on to rescue.
+     *
+     * Kept apart from `errorHistory` because success calls
+     * clearErrorHistory, which used to erase exactly the case an operator
+     * most wants to see — "writes are flaky but recovering on retry 2".
+     * Measured before this: a run that failed once then succeeded
+     * reported `{}`, indistinguishable from a run with no trouble at all
+     * (#286).
+     */
+    recoveredHistory = new Map();
+    /**
+     * Operations that actually feed these statistics. Only
+     * handlePatternWrite routes through executeWithRetry today, so an
+     * empty map meant "nothing instrumented reported trouble", not "the
+     * system is healthy" — and the Record<string, …> shape implied
+     * coverage that did not exist. Reported explicitly so a reader can
+     * tell the two apart (#286).
+     */
+    /**
+     * Operations `getErrorStats` seeds with an explicit zero row.
+     *
+     * This named 'Pattern Write' — which nothing calls: its only path,
+     * `handlePatternWrite`, is reached solely from
+     * `writePatternWithValidation`, and nothing in `src/server` calls
+     * that. So diagnostics carried a permanent all-zero row for dead code
+     * while omitting the one operation that does run (#445).
+     *
+     * 'Browser Init' is the live one, from `StrudelController.ts:199`
+     * (#315). A zero row for it is the useful kind: it says the retry
+     * path exists and has not fired, which is exactly what an operator
+     * wants to know before a failure rather than after.
+     */
+    static INSTRUMENTED_OPERATIONS = ['Browser Init'];
     ERROR_WINDOW = 60000; // 1 minute window for error tracking
+    /**
+     * Operations this instance has handled, successfully or not.
+     *
+     * The seed list above says which paths EXIST; this says which have
+     * RUN. A clean run has no error and no recovery to record, so without
+     * it a successful operation left no row and looked identical to one
+     * nothing ever watched — the ambiguity #288 removed for the seeded
+     * names and left everywhere else.
+     */
+    seenOperations = new Set();
     constructor() {
         this.logger = new Logger();
     }
@@ -17,18 +61,47 @@ export class ErrorRecovery {
      * @param strategy - Recovery strategy configuration
      * @returns Result of the operation
      */
+    /**
+     * Note on reachability: the only production entry point into this
+     * class is `handlePatternWrite`, which calls this. `executeWithRetry`
+     * and `clearErrorHistory` are public because they are the seam the
+     * retry tests drive directly, not because anything else calls them.
+     *
+     * Seven methods that nothing called at all — handleBrowserInit,
+     * handleNetworkOperation, createCircuitBreaker, isFrequentlyFailing,
+     * executeWithTimeout, executeWithRetryAndTimeout and
+     * clearAllErrorHistory — were removed in #309. They were fully tested,
+     * which is how the file reported 100% coverage while most of it was
+     * unreachable, and how the docs could describe an `ErrorRecovery.withRetry`
+     * that never existed without anything noticing.
+     *
+     * Browser init and strudel.cc requests still have no retry. That gap
+     * is real and is tracked separately: reviving deleted machinery
+     * deserves the scrutiny of new code, not a restore from history.
+     */
     async executeWithRetry(operation, operationName, strategy = {
         maxRetries: 3,
         retryDelay: 1000,
         exponentialBackoff: true
     }) {
+        // Recorded on entry: an operation that ran and succeeded should
+        // report an explicit zero rather than no row at all (#288's
+        // distinction, which only the seeded names used to get).
+        this.seenOperations.add(operationName);
         let lastError = null;
         for (let attempt = 0; attempt <= strategy.maxRetries; attempt++) {
             try {
                 this.logger.debug(`Executing ${operationName} (attempt ${attempt + 1}/${strategy.maxRetries + 1})`);
                 const result = await operation();
-                // Success - clear error history for this operation
-                this.clearErrorHistory(operationName);
+                // Success. The failures that preceded it still happened, so
+                // move them to the recovered log rather than dropping them —
+                // dropping them is what made recovered flakiness invisible
+                // (#286). recordRecovery clears the outstanding bucket itself.
+                this.recordRecovery(operationName);
+                // The error bucket only — not `clearErrorHistory`, which also
+                // forgets that the operation ran and would make every success
+                // erase its own zero row (#445).
+                this.errorHistory.delete(operationName);
                 return result;
             }
             catch (error) {
@@ -37,9 +110,13 @@ export class ErrorRecovery {
                 this.logger.warn(`${operationName} failed (attempt ${attempt + 1}/${strategy.maxRetries + 1})`, { error: error.message });
                 // Don't retry on last attempt
                 if (attempt < strategy.maxRetries) {
-                    const delay = strategy.exponentialBackoff
+                    const base = strategy.exponentialBackoff
                         ? strategy.retryDelay * Math.pow(2, attempt)
                         : strategy.retryDelay;
+                    // Full-jitter-lite: half the computed delay plus a random half.
+                    const delay = strategy.jitter
+                        ? Math.round(base * (0.5 + Math.random() * 0.5))
+                        : base;
                     this.logger.debug(`Waiting ${delay}ms before retry`);
                     await this.sleep(delay);
                 }
@@ -51,7 +128,10 @@ export class ErrorRecovery {
         if (strategy.fallbackAction) {
             this.logger.info(`Executing fallback for ${operationName}`);
             try {
-                return await strategy.fallbackAction();
+                const fallbackResult = await strategy.fallbackAction();
+                // The fallback rescued it, so these failures are recovered too.
+                this.recordRecovery(operationName);
+                return fallbackResult;
             }
             catch (fallbackError) {
                 this.logger.error(`Fallback failed for ${operationName}`, fallbackError);
@@ -59,47 +139,6 @@ export class ErrorRecovery {
         }
         throw new Error(`${operationName} failed after ${strategy.maxRetries + 1} attempts: ${lastError?.message}`);
     }
-    /**
-     * Wraps an operation with timeout protection
-     * @param operation - Async function to execute
-     * @param timeout - Timeout in milliseconds
-     * @param operationName - Name for error messages
-     * @returns Result of the operation
-     */
-    async executeWithTimeout(operation, timeout, operationName) {
-        return Promise.race([
-            operation(),
-            this.createTimeout(timeout, operationName)
-        ]);
-    }
-    /**
-     * Combines retry logic with timeout protection
-     * @param operation - Async function to execute
-     * @param operationName - Name for logging
-     * @param timeout - Timeout per attempt in milliseconds
-     * @param strategy - Recovery strategy
-     * @returns Result of the operation
-     */
-    async executeWithRetryAndTimeout(operation, operationName, timeout, strategy) {
-        return this.executeWithRetry(() => this.executeWithTimeout(operation, timeout, operationName), operationName, strategy);
-    }
-    /**
-     * Gracefully handles browser initialization errors
-     * @param initFunction - Browser initialization function
-     * @returns Initialization result
-     */
-    async handleBrowserInit(initFunction) {
-        return this.executeWithRetryAndTimeout(initFunction, 'Browser Initialization', 30000, // 30 second timeout
-        {
-            maxRetries: 2,
-            retryDelay: 2000,
-            exponentialBackoff: true,
-            fallbackAction: async () => {
-                this.logger.warn('Browser initialization failed, suggesting headless mode');
-                return 'Browser initialization failed. Try setting headless:true in config.json';
-            }
-        });
-    }
     /**
      * Handles pattern write errors with validation
      * @param writeFunction - Pattern write function
@@ -119,19 +158,6 @@ export class ErrorRecovery {
             }
         });
     }
-    /**
-     * Checks if an operation is experiencing repeated failures
-     * @param operationName - Name of operation to check
-     * @param threshold - Number of errors to consider "frequent"
-     * @returns True if operation is failing frequently
-     */
-    isFrequentlyFailing(operationName, threshold = 3) {
-        const errors = this.errorHistory.get(operationName) || [];
-        const now = Date.now();
-        // Count errors within the time window
-        const recentErrors = errors.filter(timestamp => now - timestamp < this.ERROR_WINDOW);
-        return recentErrors.length >= threshold;
-    }
     /**
      * Gets error statistics for monitoring
      * @returns Error statistics by operation
@@ -139,13 +165,26 @@ export class ErrorRecovery {
     getErrorStats() {
         const stats = {};
         const now = Date.now();
-        this.errorHistory.forEach((timestamps, operation) => {
-            const recentErrors = timestamps.filter(ts => now - ts < this.ERROR_WINDOW);
+        const recent = (ts) => ts.filter(t => now - t < this.ERROR_WINDOW);
+        // Seed with every instrumented operation so an all-zero row is
+        // distinguishable from an operation nothing ever watched. `{}` used
+        // to mean both.
+        const operations = new Set([
+            ...ErrorRecovery.INSTRUMENTED_OPERATIONS,
+            ...this.seenOperations,
+            ...this.errorHistory.keys(),
+            ...this.recoveredHistory.keys(),
+        ]);
+        for (const operation of operations) {
+            const failed = recent(this.errorHistory.get(operation) ?? []);
+            const rescued = recent(this.recoveredHistory.get(operation) ?? []);
             stats[operation] = {
-                count: recentErrors.length,
-                lastError: recentErrors.length > 0 ? new Date(Math.max(...recentErrors)) : null
+                count: failed.length,
+                lastError: failed.length > 0 ? new Date(Math.max(...failed)) : null,
+                recovered: rescued.length,
+                lastRecovery: rescued.length > 0 ? new Date(Math.max(...rescued)) : null,
             };
-        });
+        }
         return stats;
     }
     /**
@@ -153,13 +192,38 @@ export class ErrorRecovery {
      * @param operationName - Operation to clear
      */
     clearErrorHistory(operationName) {
+        // Forgotten entirely, including that it ever ran — "clear this
+        // operation's history" that left a zero row behind would be a
+        // different promise than this method's name makes.
+        //
+        // The success path inside `executeWithRetry` does NOT use this: it
+        // clears the error bucket directly, because an operation that just
+        // succeeded has run and should report an explicit zero rather than
+        // vanish (#288, #445).
+        this.seenOperations.delete(operationName);
         this.errorHistory.delete(operationName);
     }
     /**
-     * Clears all error history
+     * Moves an operation's recorded failures into the recovered log.
+     *
+     * Called when a retry or fallback rescues the operation, so the
+     * failures survive the clearErrorHistory that follows.
+     *
+     * @param operationName - Name of the operation
      */
-    clearAllErrorHistory() {
-        this.errorHistory.clear();
+    recordRecovery(operationName) {
+        const failures = this.errorHistory.get(operationName);
+        if (!failures || failures.length === 0)
+            return;
+        const now = Date.now();
+        const existing = this.recoveredHistory.get(operationName) ?? [];
+        const merged = [...existing, ...failures]
+            .filter(ts => now - ts < this.ERROR_WINDOW);
+        this.recoveredHistory.set(operationName, merged);
+        // A move, not a copy: a failure belongs in exactly one bucket, or
+        // the fallback path reports the same three failures as both
+        // outstanding and rescued.
+        this.errorHistory.delete(operationName);
     }
     /**
      * Records an error occurrence
@@ -173,19 +237,6 @@ export class ErrorRecovery {
         const recentErrors = errors.filter(ts => now - ts < this.ERROR_WINDOW);
         this.errorHistory.set(operationName, recentErrors);
     }
-    /**
-     * Creates a timeout promise
-     * @param ms - Timeout in milliseconds
-     * @param operationName - Name for error message
-     * @returns Promise that rejects after timeout
-     */
-    createTimeout(ms, operationName) {
-        return new Promise((_, reject) => {
-            setTimeout(() => {
-                reject(new Error(`${operationName} timed out after ${ms}ms`));
-            }, ms);
-        });
-    }
     /**
      * Sleep utility
      * @param ms - Milliseconds to sleep
@@ -214,35 +265,4 @@ export class ErrorRecovery {
         });
         return simplified;
     }
-    /**
-     * Handles network-related errors
-     * @param operation - Operation that may fail due to network
-     * @param operationName - Name for logging
-     * @returns Operation result
-     */
-    async handleNetworkOperation(operation, operationName) {
-        return this.executeWithRetry(operation, operationName, {
-            maxRetries: 5,
-            retryDelay: 2000,
-            exponentialBackoff: true,
-            fallbackAction: async () => {
-                throw new Error(`Network operation ${operationName} failed - check internet connection`);
-            }
-        });
-    }
-    /**
-     * Creates a circuit breaker for operations that fail frequently
-     * @param operation - Operation to protect
-     * @param operationName - Name for tracking
-     * @param threshold - Number of failures before circuit opens
-     * @returns Protected operation
-     */
-    createCircuitBreaker(operation, operationName, threshold = 5) {
-        return async () => {
-            if (this.isFrequentlyFailing(operationName, threshold)) {
-                throw new Error(`Circuit breaker open for ${operationName} - operation disabled due to repeated failures`);
-            }
-            return operation();
-        };
-    }
 }

package/dist/utils/InputValidator.js

@@ -9,6 +9,7 @@
  *
  * All methods throw descriptive errors for invalid inputs.
  */
+import { ValidationError } from './CategorisedError.js';
 export class InputValidator {
     // Valid scale names from MusicTheory service
     static VALID_SCALES = [
@@ -108,11 +109,11 @@ export class InputValidator {
             throw new Error('Steps must be a positive integer');
         }
         if (steps > 256) {
-            throw new Error(`Steps cannot exceed 256, got ${steps}`);
+            throw new ValidationError(`Steps cannot exceed 256, got ${steps}`);
         }
         // Validate relationship
         if (hits > steps) {
-            throw new Error(`Hits (${hits}) cannot exceed steps (${steps})`);
+            throw new ValidationError(`Hits (${hits}) cannot exceed steps (${steps})`);
         }
     }
     /**
@@ -182,7 +183,9 @@ export class InputValidator {
      *
      * @example
      * InputValidator.validateRootNote('C');    // ✓ Valid
-     * InputValidator.validateRootNote('f#');   // ✓ Valid (normalized to F#)
+     * InputValidator.validateRootNote('f#');   // ✓ Valid — accepted, NOT
+     *                                          //   normalized; returns void
+     *                                          //   and the caller keeps 'f#' (#491)
      * InputValidator.validateRootNote('X');    // ✗ Throws: Invalid root note
      */
     static validateRootNote(note) {
@@ -201,14 +204,45 @@ export class InputValidator {
             throw new Error(`Invalid root note: ${note}. Valid notes: ${this.VALID_ROOT_NOTES.join(', ')}`);
         }
     }
+    /**
+     * Validates that a value is a plain JavaScript-style identifier.
+     *
+     * Use this wherever a caller-supplied name is interpolated into a
+     * RegExp or into generated pattern source. `effect({action:"remove"})`
+     * built `new RegExp(`\\.${args.effect}\\(...`)` from a raw argument,
+     * so `effect: "(a+)+Z"` against a crafted pattern blocked the event
+     * loop for 25 seconds — the server stops answering stdio entirely (#236).
+     *
+     * @param value - Value to validate
+     * @param fieldName - Field name for the error message
+     * @throws {Error} When the value is not a plain identifier
+     *
+     * @example
+     * InputValidator.validateIdentifier('lpf', 'effect');       // ✓ Valid
+     * InputValidator.validateIdentifier('(a+)+Z', 'effect');    // ✗ Throws
+     *
+     * @nist si-10 "Information input validation"
+     */
+    static validateIdentifier(value, fieldName) {
+        if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+            throw new Error(`Invalid ${fieldName}: ${String(value)}. ` +
+                'Must be a plain identifier (letters, digits and underscore, not starting with a digit).');
+        }
+    }
     /**
      * Validates string length to prevent resource exhaustion
      *
      * @param str - String to validate
      * @param fieldName - Field name for error messages
-     * @param maxLength - Maximum allowed length (default: 1000)
-     * @param allowEmpty - Whether to allow empty strings (default: false for identifiers, true for content)
-     * @throws {Error} When string exceeds maximum length or is not a string
+     * @param maxLength - Maximum allowed length, in UTF-16 code units
+     *   (default: 1000). Must be a finite non-negative number.
+     * @param allowEmpty - Whether to allow empty strings. The default is
+     *   `true`; callers that need an identifier pass `false` explicitly.
+     *   This said "false for identifiers, true for content", describing a
+     *   default that varies by field name and never existed — the default
+     *   is one value and it is `true` (#491).
+     * @throws {Error} When string exceeds maximum length, is not a string,
+     *   or `maxLength` is not a usable bound
      *
      * @example
      * InputValidator.validateStringLength('hello', 'pattern', 100);  // ✓ Valid
@@ -220,11 +254,25 @@ export class InputValidator {
         if (typeof str !== 'string') {
             throw new Error(`${fieldName} must be a string`);
         }
+        // A bound that cannot bound anything is a caller bug, not a limit.
+        //
+        // `str.length > NaN` is false, as is every comparison with NaN, so
+        // a NaN maxLength silently disabled the check entirely: a
+        // million-character string was accepted by the function whose whole
+        // purpose is preventing resource exhaustion. `maxLength` itself was
+        // never validated (#491).
+        if (!Number.isFinite(maxLength) || maxLength < 0) {
+            throw new Error(`${fieldName} length check misconfigured: maxLength must be a finite ` +
+                `non-negative number, got ${String(maxLength)}`);
+        }
         if (!allowEmpty && str.trim().length === 0) {
             throw new Error(`${fieldName} cannot be empty`);
         }
+        // UTF-16 code units, which is what `.length` counts and what a
+        // resource bound should count. The message used to say "characters",
+        // so a single emoji was reported as 2 of them (#491).
         if (str.length > maxLength) {
-            throw new Error(`${fieldName} too long (max ${maxLength} characters, got ${str.length})`);
+            throw new Error(`${fieldName} too long (max ${maxLength} UTF-16 code units, got ${str.length})`);
         }
     }
     /**