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

package/dist/server/tools/analysis.js

@@ -1,22 +1,21 @@
 /**
  * analysis domain — audio analysis + pattern validation (browser + local).
  *
- * Owns (10 tools):
- *   browser-required: analyze, analyze_spectrum, analyze_rhythm,
- *                     detect_tempo, detect_key, validate_pattern_runtime
+ * Owns (6 tools):
+ *   browser-required: analyze (include[] filter), validate_pattern_runtime
  *   browser-free:     validate_pattern_local, analyze_pattern_local,
  *                     query_pattern_events, transpile_pattern
  *
- * The browser-free set runs against the in-process StrudelEngine and
+ * The browser-free set runs against the local engine — since #307, a
+ * forked child with a heap cap and a deadline, not this process — and
  * pairs naturally with validate_pattern_runtime (which monitors the
  * actual Strudel console). They were orphan handlers — implementations
  * present but not registered in tools/list — until #124.
- *
- * Post-consolidation (per #110 audit): a single `analyze` tool with
- * an `include[]` filter absorbs the 4 audio detection tools.
- * Local-engine tools stay distinct — different subsystem.
  */
+import { empty, err, ok } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { IsolatedRunnerError } from '../../services/IsolatedEngineRunner.js';
+import { ValidationError } from '../../utils/CategorisedError.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -47,26 +46,6 @@ export const tools = [
             },
         },
     },
-    {
-        name: 'analyze_spectrum',
-        description: '[DEPRECATED — use analyze({ include: ["spectrum"] }) instead] FFT spectrum analysis',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'analyze_rhythm',
-        description: '[DEPRECATED — use analyze({ include: ["rhythm"] }) instead] Rhythm analysis',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'detect_tempo',
-        description: '[DEPRECATED — use analyze({ include: ["tempo"] }) instead] BPM detection',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'detect_key',
-        description: '[DEPRECATED — use analyze({ include: ["key"] }) instead] Key detection',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
     {
         name: 'validate_pattern_runtime',
         description: 'Validate pattern with runtime error checking (monitors Strudel console for errors)',
@@ -82,7 +61,7 @@ export const tools = [
     },
     {
         name: 'validate_pattern_local',
-        description: 'Validate pattern syntax against the in-process StrudelEngine (no browser required)',
+        description: 'Validate pattern syntax against the local StrudelEngine, which runs in a sandboxed child process (no browser required)',
         inputSchema: {
             type: 'object',
             properties: {
@@ -143,57 +122,80 @@ async function getRhythm(controller) {
     return await controller.analyzeRhythm();
 }
 async function getTempo(controller) {
-    try {
-        const tempoAnalysis = await controller.detectTempo();
-        if (!tempoAnalysis || tempoAnalysis.bpm === 0) {
-            return {
-                bpm: 0,
-                confidence: 0,
-                message: 'No tempo detected. Ensure audio is playing and has a clear rhythmic pattern.',
-            };
-        }
+    const tempoAnalysis = await controller.detectTempo();
+    if (!tempoAnalysis || tempoAnalysis.bpm === 0) {
+        // The measurement ran and detected nothing. `bpm: 0` read as a
+        // measured value — zero beats per minute — so null plus an
+        // explicit flag (#288). No envelope here: getTempo is a sub-result
+        // composed into analyze's object, and an envelope nested inside a
+        // data payload is not the contract.
+        //
+        // Two different states arrive here. A reading that is merely
+        // settling has a candidate already and needs another poll; telling
+        // its caller to check whether audio is playing, while audio IS
+        // playing, sends it to fix the wrong thing (#374).
         return {
-            bpm: tempoAnalysis.bpm,
-            confidence: Math.round(tempoAnalysis.confidence * 100) / 100,
-            method: tempoAnalysis.method,
-            message: `Detected ${tempoAnalysis.bpm} BPM with ${Math.round(tempoAnalysis.confidence * 100)}% confidence`,
+            bpm: null,
+            detected: false,
+            confidence: 0,
+            message: tempoAnalysis?.settling === true
+                ? 'Tempo is still settling — a reading was taken but not yet confirmed by a second '
+                    + 'window. Call again in a second or two.'
+                : 'No tempo detected. Ensure audio is playing and has a clear rhythmic pattern.',
         };
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { bpm: 0, confidence: 0, error: message || 'Tempo detection failed' };
-    }
+    return {
+        bpm: tempoAnalysis.bpm,
+        confidence: Math.round(tempoAnalysis.confidence * 100) / 100,
+        method: tempoAnalysis.method,
+        message: `Detected ${tempoAnalysis.bpm} BPM with ${Math.round(tempoAnalysis.confidence * 100)}% confidence`,
+    };
+    // No catch here on purpose.
+    //
+    // It used to return `{bpm: null, detected: false, error: message}`,
+    // which analyze nests under the `tempo` key — where `isFailureShaped`
+    // cannot see it, since that inspects only the top level. So a dead
+    // browser reached the client as:
+    //
+    //   include:['tempo'] -> {ok:true, data:{tempo:{bpm:null,
+    //                          error:'Target page ... has been closed'}}}
+    //   include:['all']   -> a failure envelope
+    //
+    // One tool, one fault, opposite verdicts (#453). Letting it propagate
+    // makes both agree, and keeps the ORIGINAL error so `categorizeError`
+    // reads its type rather than a rebuilt message (#382).
+    //
+    // The no-detection branch above is untouched: that is a measurement
+    // that ran and found nothing, which is data, not a failure (#288).
 }
 async function getKey(controller) {
-    try {
-        const keyAnalysis = await controller.detectKey();
-        if (!keyAnalysis || keyAnalysis.confidence < 0.1) {
-            return {
-                key: 'Unknown',
-                scale: 'unknown',
-                confidence: 0,
-                message: 'No clear key detected. Ensure audio is playing and has tonal content.',
-            };
-        }
-        const result = {
-            key: keyAnalysis.key,
-            scale: keyAnalysis.scale,
-            confidence: Math.round(keyAnalysis.confidence * 100) / 100,
-            message: `Detected ${keyAnalysis.key} ${keyAnalysis.scale} with ${Math.round(keyAnalysis.confidence * 100)}% confidence`,
+    // No try/catch, for the reason given on getTempo: an error nested
+    // inside a data payload is invisible to `isFailureShaped` and reached
+    // the client as ok:true (#453).
+    const keyAnalysis = await controller.detectKey();
+    if (!keyAnalysis || keyAnalysis.confidence < 0.1) {
+        return {
+            key: null,
+            scale: null,
+            detected: false,
+            confidence: 0,
+            message: 'No clear key detected. Ensure audio is playing and has tonal content.',
         };
-        if (keyAnalysis.alternatives && keyAnalysis.alternatives.length > 0) {
-            result.alternatives = keyAnalysis.alternatives.map((alt) => ({
-                key: alt.key,
-                scale: alt.scale,
-                confidence: Math.round(alt.confidence * 100) / 100,
-            }));
-        }
-        return result;
     }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { key: 'Unknown', scale: 'unknown', confidence: 0, error: message || 'Key detection failed' };
+    const result = {
+        key: keyAnalysis.key,
+        scale: keyAnalysis.scale,
+        confidence: Math.round(keyAnalysis.confidence * 100) / 100,
+        message: `Detected ${keyAnalysis.key} ${keyAnalysis.scale} with ${Math.round(keyAnalysis.confidence * 100)}% confidence`,
+    };
+    if (keyAnalysis.alternatives && keyAnalysis.alternatives.length > 0) {
+        result.alternatives = keyAnalysis.alternatives.map((alt) => ({
+            key: alt.key,
+            scale: alt.scale,
+            confidence: Math.round(alt.confidence * 100) / 100,
+        }));
     }
+    return result;
 }
 async function doAnalyze(args, controller) {
     const includeRaw = args?.include;
@@ -223,7 +225,44 @@ async function doAnalyze(args, controller) {
     const entries = await Promise.all(Object.entries(tasks).map(async ([k, p]) => [k, await p]));
     return Object.fromEntries(entries);
 }
+/**
+ * Turns a death of the isolated engine child into an envelope (#307).
+ *
+ * All four local-engine tools funnel through here, which is the point:
+ * one isolation path, one place that decides what a caller is told.
+ *
+ * The distinction the categories carry is whether retrying could possibly
+ * help. It cannot for an OOM — `new Array(5e7).fill(7)` will exhaust the
+ * cap every time it is sent — so that is the caller's input to fix, not a
+ * transient condition to wait out. A hang or an unexplained crash might
+ * well be transient. Recording this because the vote on #307 said "one
+ * retryable envelope" for all of them, and a blanket `isRetryable: true`
+ * would invite an agent into a loop it cannot win.
+ */
+function isolationFailure(error) {
+    // Not retryable, and for two different reasons. An OOM is the caller's
+    // input: `s("[bd*99999]*99999")` exhausts the cap every time it is
+    // sent. A spawn failure is the deployment: a missing or unbuilt child
+    // is missing on the next attempt too. Both would put an agent in a loop
+    // it cannot win, which is why the vote's "one retryable envelope for
+    // everything" is not what shipped.
+    if (error.kind === 'oom')
+        return err('validation', error.message);
+    if (error.kind === 'spawn')
+        return err('internal', error.message);
+    return err('transient', error.message, { isRetryable: true });
+}
 export async function execute(name, args, ctx) {
+    try {
+        return await run(name, args, ctx);
+    }
+    catch (error) {
+        if (error instanceof IsolatedRunnerError)
+            return isolationFailure(error);
+        throw error;
+    }
+}
+async function run(name, args, ctx) {
     const sid = args?.session_id;
     if (!LOCAL_ENGINE_TOOLS.has(name) && !sid && !ctx.isInitialized()) {
         return 'Browser not initialized. Run init first.';
@@ -232,11 +271,6 @@ export async function execute(name, args, ctx) {
     switch (name) {
         case 'analyze':
             return await doAnalyze(args, controller);
-        // Deprecated aliases — forward to consolidated handler.
-        case 'analyze_spectrum': return await getSpectrum(controller);
-        case 'analyze_rhythm': return await getRhythm(controller);
-        case 'detect_tempo': return await getTempo(controller);
-        case 'detect_key': return await getKey(controller);
         case 'validate_pattern_runtime': {
             InputValidator.validateStringLength(args.pattern, 'pattern', 10000, false);
             const validation = await controller.validatePatternRuntime(args.pattern, args.waitMs || 500);
@@ -248,7 +282,7 @@ export async function execute(name, args, ctx) {
         }
         case 'validate_pattern_local': {
             InputValidator.validateStringLength(args.pattern, 'pattern', 10000, false);
-            const localValidation = ctx.strudelEngine.validate(args.pattern);
+            const localValidation = await ctx.strudelEngine.validate(args.pattern);
             return {
                 valid: localValidation.valid,
                 errors: localValidation.errors,
@@ -262,7 +296,29 @@ export async function execute(name, args, ctx) {
         }
         case 'analyze_pattern_local': {
             InputValidator.validateStringLength(args.pattern, 'pattern', 10000, false);
-            const patternMetadata = ctx.strudelEngine.analyzePattern(args.pattern);
+            const patternMetadata = await ctx.strudelEngine.analyzePattern(args.pattern);
+            // Do not report event counts the engine never measured. When
+            // evaluation failed, `eventsPerCycle: 0` is a default, not a
+            // finding — and it is indistinguishable from a genuinely silent
+            // pattern, so an agent was told working code produced nothing
+            // (#276). Say what happened instead.
+            if (!patternMetadata.evaluated) {
+                // Build explicitly rather than destructuring the unwanted fields
+                // out: naming them only to discard them trips no-unused-vars, and
+                // listing what IS reported is clearer about the contract anyway.
+                return {
+                    usesSound: patternMetadata.usesSound,
+                    usesNote: patternMetadata.usesNote,
+                    isStack: patternMetadata.isStack,
+                    functionsUsed: patternMetadata.functionsUsed,
+                    complexity: patternMetadata.complexity,
+                    ...(patternMetadata.bpm !== undefined ? { bpm: patternMetadata.bpm } : {}),
+                    evaluated: false,
+                    message: 'Pattern could not be evaluated, so event counts are unavailable. ' +
+                        'The static analysis below is still valid. ' +
+                        (patternMetadata.evaluationError ?? ''),
+                };
+            }
             return {
                 ...patternMetadata,
                 message: `Pattern analysis: ${patternMetadata.eventsPerCycle} events/cycle, ` +
@@ -275,14 +331,22 @@ export async function execute(name, args, ctx) {
             const startCycle = args.start ?? 0;
             const endCycle = args.end ?? 1;
             if (startCycle >= endCycle) {
-                return { error: 'Start must be less than end' };
+                // Categorised explicitly rather than by whether the message
+                // happens to contain "must be" — which is the only reason this
+                // one landed in `validation` while the range check below landed
+                // in `internal` (#453).
+                return err('validation', 'Start must be less than end');
             }
             if (endCycle - startCycle > 16) {
-                return { error: 'Maximum range is 16 cycles to prevent excessive output' };
+                return err('validation', 'Maximum range is 16 cycles to prevent excessive output');
             }
             try {
-                const events = ctx.strudelEngine.queryEvents(args.pattern, startCycle, endCycle);
-                return {
+                const events = await ctx.strudelEngine.queryEvents(args.pattern, startCycle, endCycle);
+                // A silent pattern is a valid-empty query, not a failed one —
+                // and not the same as a pattern with events, which is what a
+                // plain ok() made it look like (#288).
+                const wrap = events.length === 0 ? empty : ok;
+                return wrap({
                     count: events.length,
                     range: { start: startCycle, end: endCycle },
                     events: events.map((e) => ({
@@ -291,9 +355,22 @@ export async function execute(name, args, ctx) {
                         end: e.end,
                         duration: e.end - e.start,
                     })),
-                };
+                });
             }
             catch (error) {
+                // The engine dying is not a syntax problem, and telling the
+                // caller to go run the validator would send them to a tool that
+                // will die the same way. Let it reach isolationFailure (#307).
+                if (error instanceof IsolatedRunnerError)
+                    throw error;
+                // A refusal that already knows it is the caller's input keeps
+                // that verdict. Flattening it into this shape sent it through
+                // the dispatcher as a bare message, which categorised "Pattern
+                // produces roughly 2e10 events, above the 50000 cap" as
+                // `internal` — found by the protocol route check, after two
+                // rounds of fixing this exact class of bug (#382).
+                if (error instanceof ValidationError)
+                    return err('validation', error.message);
                 const message = error instanceof Error ? error.message : String(error);
                 return {
                     error: message,
@@ -303,7 +380,7 @@ export async function execute(name, args, ctx) {
         }
         case 'transpile_pattern': {
             InputValidator.validateStringLength(args.pattern, 'pattern', 10000, false);
-            const transpileResult = ctx.strudelEngine.transpile(args.pattern);
+            const transpileResult = await ctx.strudelEngine.transpile(args.pattern);
             if (transpileResult.success) {
                 return {
                     success: true,
@@ -311,12 +388,14 @@ export async function execute(name, args, ctx) {
                     message: 'Pattern transpiled successfully',
                 };
             }
-            return {
-                success: false,
-                error: transpileResult.error,
-                errorLocation: transpileResult.errorLocation,
-                message: 'Transpilation failed',
-            };
+            // A syntax error in the caller's pattern is the caller's input,
+            // not an internal fault — and `Unexpected token (1:6)` matches
+            // nothing the string matcher looks for (#453). The location is
+            // kept in the message, since an envelope carries no extra fields.
+            return err('validation', `Transpilation failed: ${String(transpileResult.error)}`
+                + (transpileResult.errorLocation !== undefined
+                    ? ` (at ${String(transpileResult.errorLocation)})`
+                    : ''));
         }
         default:
             throw new Error(`analysis module does not handle tool: ${name}`);