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

package/dist/server/tools/analysis.js

@@ -6,12 +6,16 @@
  *   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.
  */
+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',
@@ -57,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: {
@@ -118,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;
@@ -198,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.';
@@ -218,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,
@@ -232,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, ` +
@@ -245,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) => ({
@@ -261,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,
@@ -273,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,
@@ -281,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}`);

package/dist/server/tools/capture.js

@@ -1,14 +1,19 @@
 /**
  * capture domain — audio recording and MIDI export.
  *
- * Owns two tools: `audio_capture(action=start|stop|sample)` and
- * `export_midi` (kept separate — MIDI is symbolic, audio is waveform).
+ * Owns three tools: `audio_capture(action=start|stop|sample)`,
+ * `export_audio` (records a window and writes a file), and `export_midi`
+ * (kept separate — MIDI is symbolic, audio is waveform).
  *
- * The AudioCaptureService is lazy-instantiated module-side: we need
- * the current Playwright page for `injectRecorder()`, and that only
- * exists after `init`. The singleton survives across tool calls.
+ * AudioCaptureService instances are lazy-created per session: we need the
+ * session's Playwright page for `injectRecorder()`, and that only exists
+ * after `init`. The server holds them in a Map keyed by session id (#180),
+ * so each instance survives across tool calls and sessions do not share
+ * a recorder.
  */
+import { categorizeError, err } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
+import { declaredBpm } from '../../utils/Tempo.js';
 // AudioCaptureService lifecycle lives on the server; we fetch a shared
 // instance via ctx.getAudioCaptureService() so tests can mock the class
 // at module boundary without the extractor caching a stale instance.
@@ -23,7 +28,7 @@ function blobToBase64(arrayBuffer) {
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
-        description: 'Optional session ID (#108). Routes page reference to the named session. Note: AudioCaptureService is currently server-wide — concurrent captures across sessions will conflict.',
+        description: 'Optional session ID (#108). Routes the capture to the named session, which has its own recorder — concurrent captures across sessions are safe (#180).',
     },
 };
 export const tools = [
@@ -36,19 +41,44 @@ export const tools = [
             'Example: audio_capture({ action: "sample", duration: 3000 }). ' +
             'Audio must be playing for capture to record meaningful data. ' +
             'For MIDI export use export_midi; for runtime diagnostics use diagnostics. ' +
-            'Note: the AudioCaptureService is currently a server-wide singleton — concurrent captures across sessions will conflict.',
+            'Each session has its own recorder, so captures in different sessions do not interfere (#180).',
         inputSchema: {
             type: 'object',
             properties: {
                 action: { type: 'string', enum: ['start', 'stop', 'sample'], description: 'Capture action' },
                 format: { type: 'string', enum: ['webm', 'opus'], description: 'action=start: audio format (default webm)' },
-                maxDuration: { type: 'number', description: 'action=start: maximum capture duration ms' },
+                maxDuration: {
+                    type: 'number',
+                    description: 'action=start: stop the recorder automatically after this many ms. '
+                        + 'Defaults to 600000 (ten minutes); the recording so far is kept and '
+                        + 'returned by a later stop.',
+                },
                 duration: { type: 'number', description: 'action=sample: duration ms (100-60000, default 5000)' },
                 ...SESSION_ID_PROP,
             },
             required: ['action'],
         },
     },
+    {
+        name: 'export_audio',
+        description: 'Record a window of live Strudel audio and write it to a file. ' +
+            'Returns a path plus what was actually recorded, not a wall of base64 — ' +
+            'prefer this over audio_capture when you want the audio to exist somewhere. ' +
+            'format=wav (default) decodes to 16-bit PCM a DAW will open; format=webm writes the raw Opus recording. ' +
+            'Reports silent captures instead of writing a silent file and claiming success. ' +
+            'Audio must already be playing: call playback({ action: "play" }) first. ' +
+            'Example: export_audio({ duration: 4000, filename: "take-01" }).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                duration: { type: 'number', description: 'Window to record in ms (100-30000, default 5000)' },
+                format: { type: 'string', enum: ['wav', 'webm'], description: 'Output format (default wav)' },
+                filename: { type: 'string', description: 'Output filename; reduced to a basename and confined to the export directory' },
+                output: { type: 'string', enum: ['file', 'base64'], description: 'file (default) writes to disk and returns a path; base64 returns bytes inline' },
+                ...SESSION_ID_PROP,
+            },
+        },
+    },
     {
         name: 'export_midi',
         description: 'Export current pattern to MIDI file. Parses note(), n(), and chord() functions.',
@@ -57,7 +87,7 @@ export const tools = [
             properties: {
                 filename: { type: 'string', description: 'Output filename (optional, default: pattern.mid)' },
                 duration: { type: 'number', description: 'Export duration in bars (default: 4)' },
-                bpm: { type: 'number', description: 'Tempo in BPM (default: 120)' },
+                bpm: { type: 'number', description: "Tempo in BPM (default: the pattern's own tempo, or 120 if it declares none)" },
                 format: { type: 'string', enum: ['file', 'base64'], description: 'Output format: file or base64 (default: base64)' },
                 ...SESSION_ID_PROP,
             },
@@ -81,60 +111,98 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid action: ${a}. Must be one of: start, stop, sample`);
             }
         }
+        case 'export_audio':
+            return await exportAudio(args, ctx, sid);
         case 'export_midi':
             return await exportMidi(args?.filename, args?.duration, args?.bpm, args?.format, ctx, sid);
         default:
             throw new Error(`capture module does not handle tool: ${name}`);
     }
 }
-async function startAudioCapture(format, _maxDuration, ctx, sid) {
+async function startAudioCapture(format, maxDuration, ctx, sid) {
     try {
         const service = await ctx.getAudioCaptureService(sid);
         if (service.isCapturing()) {
-            return { success: false, message: 'Audio capture already in progress. Stop it first.' };
+            return err('business', 'Audio capture already in progress. Stop it first.');
         }
-        await service.startCapture(ctx.getController(sid).page, { format });
+        if (maxDuration !== undefined) {
+            InputValidator.validatePositiveInteger(maxDuration, 'maxDuration');
+        }
+        await service.startCapture(ctx.getController(sid).page, { format, maxDuration });
         return {
             success: true,
             message: 'Audio capture started. Use audio_capture({ action: "stop" }) to get the recorded audio.',
-            format: format || 'webm',
+            // The mime the recorder actually produces, which is what `stop`
+            // reports. Echoing the requested `format` here meant start said
+            // "opus" and the matching stop said "audio/webm;codecs=opus" for
+            // one recording (#437). MediaRecorder gives a webm container with
+            // an Opus stream either way.
+            format: service.getMimeType(),
         };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { success: false, message: `Failed to start audio capture: ${message}` };
+        return err(categorizeError(error), `Failed to start audio capture: ${message}`);
     }
 }
 async function stopAudioCapture(ctx, sid) {
     try {
         const service = await ctx.getAudioCaptureService(sid);
         if (!service.isCapturing()) {
-            return { success: false, message: 'No audio capture in progress. Start capture first.' };
+            // Distinguish "nothing is recording" from "something else is".
+            //
+            // `export_audio` drives the page-side recorder directly and never
+            // touches this service's mirror, so for the whole of an export
+            // this branch answered "No audio capture in progress" — the
+            // opposite of what was happening (#437 item 9). The export is
+            // left to finish on its own; stopping its recorder from here
+            // would leave its own stopCapture with nothing to collect.
+            const page = ctx.getController(sid).page;
+            // Optional-chained, as `server.ts` does for `isInjectedInto`.
+            if (page && (await service.isPageCapturing?.(page)) === true) {
+                return err('business', 'An audio export is recording on this page. It stops on its own when '
+                    + 'its duration elapses; audio_capture cannot end it early.');
+            }
+            return err('business', 'No audio capture in progress. Start capture first.');
         }
         const result = await service.stopCapture(ctx.getController(sid).page);
         const buf = await result.blob.arrayBuffer();
         return {
             success: true,
-            message: `Captured ${result.duration}ms of audio`,
+            // A capture that hit `maxDuration` is shorter than the caller
+            // asked for. Saying so is the whole point of the page computing
+            // it — this handler used to drop it (#464).
+            message: `Captured ${result.duration}ms of audio`
+                + (result.warning ? ` — ${result.warning}` : ''),
             audio: blobToBase64(buf),
             duration: result.duration,
             format: result.format,
+            ...(result.warning ? { warning: result.warning } : {}),
         };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { success: false, message: `Failed to stop audio capture: ${message}` };
+        return err(categorizeError(error), `Failed to stop audio capture: ${message}`);
     }
 }
 async function captureAudioSample(duration, ctx, sid) {
-    const durationMs = duration || 5000;
+    // `?? 5000`, not `|| 5000`. Zero is a number the caller passed, and
+    // `||` swallowed it into the default, so `duration: 0` recorded five
+    // seconds instead of being refused by the bound two lines down. The
+    // same shape as every other falsy-vs-absent bug in this repo (#437
+    // item 7).
+    const durationMs = duration ?? 5000;
     if (durationMs < 100 || durationMs > 60000) {
-        return { success: false, message: 'Duration must be between 100ms and 60000ms (1 minute)' };
+        // Validation, not business: the caller passed a number outside the
+        // allowed range, and no amount of setup changes that. My codemod
+        // guessed `business` from the absence of a nearby catch, which is
+        // the same guessing-by-shape this work exists to remove.
+        return err('validation', 'Duration must be between 100ms and 60000ms (1 minute)');
     }
     try {
         const service = await ctx.getAudioCaptureService(sid);
         if (service.isCapturing()) {
-            return { success: false, message: 'Audio capture already in progress. Stop it first.' };
+            return err('business', 'Audio capture already in progress. Stop it first.');
         }
         const result = await service.captureForDuration(ctx.getController(sid).page, durationMs);
         const buf = await result.blob.arrayBuffer();
@@ -148,32 +216,71 @@ async function captureAudioSample(duration, ctx, sid) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        return { success: false, message: `Failed to capture audio sample: ${message}` };
+        return err(categorizeError(error), `Failed to capture audio sample: ${message}`);
+    }
+}
+async function exportAudio(args, ctx, sid) {
+    try {
+        const service = ctx.audioExportService;
+        // Ensures the recorder is injected for this session; export needs the
+        // same GainNode interception audio_capture uses.
+        await ctx.getAudioCaptureService(sid);
+        const result = await service.exportAudio(ctx.getController(sid).page, {
+            duration: args?.duration,
+            format: args?.format,
+            filename: args?.filename,
+            output: args?.output,
+        });
+        if (!result.success) {
+            return { success: false, message: result.error ?? 'Audio export failed.' };
+        }
+        return {
+            ...result,
+            message: result.path
+                ? `Exported ${String(result.bytes)} bytes of ${result.format} to ${result.path}`
+                : `Captured ${String(result.bytes)} bytes of ${result.format}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), `Audio export failed: ${message}`);
     }
 }
 async function exportMidi(filename, bars, bpm, format, ctx, sid) {
     if (bpm !== undefined)
         InputValidator.validateBPM(bpm);
     if (bars !== undefined && (bars < 1 || bars > 128)) {
-        return { success: false, message: 'Bars must be between 1 and 128' };
+        return err('validation', 'Bars must be between 1 and 128');
     }
     const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
-        return { success: false, message: 'No pattern to export. Write a pattern first.' };
+        return err('business', 'No pattern to export. Write a pattern first.');
     }
-    const exportOptions = { bpm: bpm || 120, bars: bars || 4 };
+    // The pattern's own tempo, unless the caller asked for a different
+    // one. This used to be a flat `bpm || 120`, so exporting a 174 BPM
+    // pattern wrote a 120 BPM file and a round trip silently rewrote the
+    // tempo — the same guarantee #336 protects for the bar (#399).
+    const exportOptions = { bpm: bpm ?? declaredBpm(pattern) ?? 120, bars: bars ?? 4 };
     const outputFormat = format || 'base64';
     if (outputFormat === 'file') {
         const result = ctx.midiExportService.exportToFile(pattern, filename, exportOptions);
         return {
             success: result.success,
+            // The warning has to reach the caller or computing it in the
+            // service is pointless: this handler builds its own response and
+            // used to drop it, so an export that skipped most of a pattern
+            // still reported "Exported 2 notes" and nothing else (#335).
             message: result.success
                 ? `Exported ${result.noteCount} notes to ${result.output}`
+                    + (result.warning ? ` — ${result.warning}` : '')
                 : result.error || 'Export failed',
             output: result.output,
             noteCount: result.noteCount,
             bars: result.bars,
             bpm: result.bpm,
+            ...(result.warning ? { warning: result.warning } : {}),
+            ...(result.unrepresented ? { unrepresented: result.unrepresented } : {}),
+            ...(result.partiallyExported ? { partiallyExported: result.partiallyExported } : {}),
             error: result.error,
         };
     }
@@ -182,11 +289,15 @@ async function exportMidi(filename, bars, bpm, format, ctx, sid) {
         success: result.success,
         message: result.success
             ? `Exported ${result.noteCount} notes as base64 MIDI data`
+                + (result.warning ? ` — ${result.warning}` : '')
             : result.error || 'Export failed',
         output: result.output,
         noteCount: result.noteCount,
         bars: result.bars,
         bpm: result.bpm,
+        ...(result.warning ? { warning: result.warning } : {}),
+        ...(result.unrepresented ? { unrepresented: result.unrepresented } : {}),
+        ...(result.partiallyExported ? { partiallyExported: result.partiallyExported } : {}),
         error: result.error,
     };
 }