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

package/dist/server/tools/history.js

@@ -1,16 +1,15 @@
 /**
  * history domain — undo/redo stacks and the pattern history browser.
  *
- * Owns (5 tools): undo, redo, list_history, restore_history,
- * compare_patterns. Post-consolidation target per the #110 audit:
- * single `history` tool with an `action` enum. For now we keep the
- * individual verbs.
+ * Owns one consolidated tool (`history(action)`) with undo/redo/list/
+ * restore/compare actions.
  *
  * The history module mutates the three state arrays (undoStack,
- * redoStack, historyStack) passed through ctx.history. The outer
- * server pushes onto these arrays on write/append/insert/replace/clear,
- * so all mutations share the same underlying storage.
+ * redoStack, historyStack) reached through ctx.getHistory(). The outer
+ * server pushes onto these arrays on every edit_pattern call, so all
+ * mutations share the same underlying storage.
  */
+import { empty, err } from './types.js';
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -45,51 +44,6 @@ export const tools = [
             required: ['action'],
         },
     },
-    {
-        name: 'undo',
-        description: '[DEPRECATED — use history({ action: "undo" }) instead] Undo last action',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'redo',
-        description: '[DEPRECATED — use history({ action: "redo" }) instead] Redo action',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'list_history',
-        description: '[DEPRECATED — use history({ action: "list" }) instead] List recent pattern history with timestamps and previews',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                limit: { type: 'number', description: 'Maximum entries to return (default: 10)' },
-            },
-        },
-    },
-    {
-        name: 'restore_history',
-        description: '[DEPRECATED — use history({ action: "restore" }) instead] Restore a previous pattern from history by ID',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id: { type: 'number', description: 'History entry ID to restore' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['id'],
-        },
-    },
-    {
-        name: 'compare_patterns',
-        description: '[DEPRECATED — use history({ action: "compare" }) instead] Compare two patterns from history showing differences',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                id1: { type: 'number', description: 'First pattern ID' },
-                id2: { type: 'number', description: 'Second pattern ID (default: current pattern)' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['id1'],
-        },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 function formatTimeAgo(date) {
@@ -143,8 +97,11 @@ async function doUndo(ctx, sid) {
     const { undoStack, redoStack, maxHistory } = ctx.getHistory(sid);
     if (!sid && !ctx.isInitialized())
         return 'Browser not initialized. Run init first.';
+    // A valid-empty, not a failure: the call worked, there was simply
+    // nothing on the stack. `empty()` lets an agent tell that apart from
+    // a rich result without parsing the prose (#288).
     if (undoStack.length === 0)
-        return 'Nothing to undo';
+        return empty('Nothing to undo');
     const controller = ctx.getController(sid);
     const current = await controller.getCurrentPattern();
     redoStack.push(current);
@@ -159,7 +116,7 @@ async function doRedo(ctx, sid) {
     if (!sid && !ctx.isInitialized())
         return 'Browser not initialized. Run init first.';
     if (redoStack.length === 0)
-        return 'Nothing to redo';
+        return empty('Nothing to redo');
     const controller = ctx.getController(sid);
     const current = await controller.getCurrentPattern();
     undoStack.push(current);
@@ -172,7 +129,14 @@ async function doRedo(ctx, sid) {
 function doList(args, ctx, sid) {
     const { historyStack } = ctx.getHistory(sid);
     if (historyStack.length === 0) {
-        return 'No pattern history yet. Make some edits to build history.';
+        // Same record shape as the populated branch below, so a caller can
+        // read `entries` unconditionally instead of branching on a string.
+        return empty({
+            count: 0,
+            showing: 0,
+            entries: [],
+            message: 'No pattern history yet. Make some edits to build history.',
+        });
     }
     const limit = args?.limit || 10;
     const recent = historyStack.slice(-limit).reverse();
@@ -195,7 +159,10 @@ async function doRestore(args, ctx, sid) {
     const controller = ctx.getController(sid);
     const entry = historyStack.find(e => e.id === args.id);
     if (!entry) {
-        return `History entry #${args.id} not found. Use history({ action: "list" }) to see available entries.`;
+        // Same bare-string false success as storage's load (#293): nothing
+        // was restored, but `ok: true` said otherwise.
+        return err('business', `History entry #${args.id} not found. ` +
+            'Use history({ action: "list" }) to see available entries.');
     }
     const current = await controller.getCurrentPattern();
     undoStack.push(current);
@@ -207,14 +174,22 @@ async function doRestore(args, ctx, sid) {
 async function doCompare(args, ctx, sid) {
     const { historyStack } = ctx.getHistory(sid);
     const first = historyStack.find(e => e.id === args.id1);
-    if (!first)
-        return `History entry #${args.id1} not found.`;
+    if (!first) {
+        // Bare strings reach the client as `{ok: true, data: "...not
+        // found."}` — the #287/#293 false success, still here twelve lines
+        // below the `doRestore` that fixed it for the identical condition
+        // (#453).
+        return err('business', `History entry #${args.id1} not found. ` +
+            'Use history({ action: "list" }) to see available entries.');
+    }
     let second;
     let label;
     if (args.id2) {
         const b = historyStack.find(e => e.id === args.id2);
-        if (!b)
-            return `History entry #${args.id2} not found.`;
+        if (!b) {
+            return err('business', `History entry #${args.id2} not found. ` +
+                'Use history({ action: "list" }) to see available entries.');
+        }
         second = b.pattern;
         label = `#${args.id2}`;
     }
@@ -244,12 +219,6 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid action: ${action}. Must be one of: undo, redo, list, restore, compare`);
             }
         }
-        // Deprecated aliases — forward to consolidated handler.
-        case 'undo': return await doUndo(ctx, sid);
-        case 'redo': return await doRedo(ctx, sid);
-        case 'list_history': return doList(args, ctx, sid);
-        case 'restore_history': return await doRestore(args, ctx, sid);
-        case 'compare_patterns': return await doCompare(args, ctx, sid);
         default:
             throw new Error(`history module does not handle tool: ${name}`);
     }

package/dist/server/tools/playback.js

@@ -1,11 +1,7 @@
 /**
  * playback domain — transport controls.
  *
- * Owns one consolidated tool (`playback(action)`) plus three deprecated
- * aliases (play, pause, stop) per #120 / #152.
- *
- * Aliases forward to `playback` and will be removed in a future release
- * per the deprecation policy.
+ * Owns one consolidated tool (`playback(action)`) with play/pause/stop.
  */
 const SESSION_ID_PROP = {
     session_id: {
@@ -18,7 +14,7 @@ export const tools = [
         name: 'playback',
         description: 'Control transport on the current session. ' +
             'action=play starts the editor pattern. ' +
-            'action=pause stops without resetting clock. ' +
+            'action=pause halts the clock where it is, so play resumes mid-cycle. ' +
             'action=stop ends playback. ' +
             'Example: playback({ action: "play" }). ' +
             'For pattern editing use edit_pattern; for tempo use set_tempo.',
@@ -35,21 +31,6 @@ export const tools = [
             required: ['action'],
         },
     },
-    {
-        name: 'play',
-        description: '[DEPRECATED — use playback({ action: "play" }) instead] Start playing pattern',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'pause',
-        description: '[DEPRECATED — use playback({ action: "pause" }) instead] Pause playback',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
-    {
-        name: 'stop',
-        description: '[DEPRECATED — use playback({ action: "stop" }) instead] Stop playback',
-        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 export async function execute(name, args, ctx) {
@@ -58,11 +39,15 @@ export async function execute(name, args, ctx) {
         return 'Browser not initialized. Run init first.';
     }
     const controller = ctx.getController(sid);
-    const action = name === 'playback' ? args?.action : name;
+    if (name !== 'playback') {
+        throw new Error(`playback module does not handle tool: ${name}`);
+    }
+    const action = args?.action;
     switch (action) {
         case 'play':
             return await controller.play();
         case 'pause':
+            return await controller.pause();
         case 'stop':
             return await controller.stop();
         default:

package/dist/server/tools/session.js

@@ -1,11 +1,11 @@
 /**
  * session domain — multi-session lifecycle management.
  *
- * Owns one consolidated tool (`session(action)`) plus four deprecated
- * aliases (create_session, destroy_session, list_sessions, switch_session)
- * per #120 / #158. `init` stays separate — it's the global bootstrap,
- * not a session operation.
+ * Owns one consolidated tool (`session(action)`) with create/destroy/
+ * list/switch actions. `init` stays separate — it's the global
+ * bootstrap, not a session operation.
  */
+import { categorizeError, empty, err, ok } from './types.js';
 import { InputValidator } from '../../utils/InputValidator.js';
 export const tools = [
     {
@@ -26,38 +26,6 @@ export const tools = [
             required: ['action'],
         },
     },
-    {
-        name: 'create_session',
-        description: '[DEPRECATED — use session({ action: "create" }) instead] Create a new isolated Strudel browser session.',
-        inputSchema: {
-            type: 'object',
-            properties: { session_id: { type: 'string', description: 'Unique identifier for the session' } },
-            required: ['session_id'],
-        },
-    },
-    {
-        name: 'destroy_session',
-        description: '[DEPRECATED — use session({ action: "destroy" }) instead] Close and destroy a Strudel session.',
-        inputSchema: {
-            type: 'object',
-            properties: { session_id: { type: 'string', description: 'Session identifier to destroy' } },
-            required: ['session_id'],
-        },
-    },
-    {
-        name: 'list_sessions',
-        description: '[DEPRECATED — use session({ action: "list" }) instead] List all active Strudel sessions.',
-        inputSchema: { type: 'object', properties: {} },
-    },
-    {
-        name: 'switch_session',
-        description: '[DEPRECATED — use session({ action: "switch" }) instead] Change the default session.',
-        inputSchema: {
-            type: 'object',
-            properties: { session_id: { type: 'string', description: 'Session identifier to set as default' } },
-            required: ['session_id'],
-        },
-    },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
 async function doCreate(args, ctx) {
@@ -74,7 +42,14 @@ async function doCreate(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 async function doDestroy(args, ctx) {
@@ -94,16 +69,33 @@ async function doDestroy(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 function doList(ctx) {
     const sm = ctx.sessionManager;
     const info = sm.getSessionsInfo();
-    return {
+    const wrap = info.length === 0 ? empty : ok;
+    return wrap({
         count: info.length,
         max_sessions: sm.getMaxSessions(),
-        default_session: sm.getDefaultSessionId(),
+        // Only when it exists. After a destroy, SessionManager resets this
+        // to the literal 'default', and reporting that named a session no
+        // caller could switch to or find in the list below (#421).
+        //
+        // Checked against `info` rather than by looking the session up:
+        // `getSession` stamps `lastActivity`, and listing sessions is not
+        // using one.
+        default_session: info.some(s => s.id === sm.getDefaultSessionId())
+            ? sm.getDefaultSessionId()
+            : null,
         sessions: info.map(s => ({
             id: s.id,
             created: s.created.toISOString(),
@@ -111,7 +103,7 @@ function doList(ctx) {
             is_playing: s.isPlaying,
             is_default: s.id === sm.getDefaultSessionId(),
         })),
-    };
+    });
 }
 function doSwitch(args, ctx) {
     const sm = ctx.sessionManager;
@@ -125,7 +117,14 @@ function doSwitch(args, ctx) {
         };
     }
     catch (error) {
-        return { success: false, error: error instanceof Error ? error.message : String(error) };
+        // `err(...)` rather than `{ success: false }`: the dispatcher turns a
+        // failure-shaped object back into a PLAIN Error before categorising
+        // it, so a typed error thrown below this point loses its category on
+        // the way out and lands in `internal` — not retryable, and wrong
+        // about whose problem it is. Cross-model review caught that the
+        // typed errors were being destroyed at this seam (#382).
+        const message = error instanceof Error ? error.message : String(error);
+        return err(categorizeError(error), message);
     }
 }
 export async function execute(name, args, ctx) {
@@ -141,11 +140,6 @@ export async function execute(name, args, ctx) {
                     throw new Error(`Invalid action: ${a}. Must be one of: create, destroy, list, switch`);
             }
         }
-        // Deprecated aliases.
-        case 'create_session': return await doCreate(args, ctx);
-        case 'destroy_session': return await doDestroy(args, ctx);
-        case 'list_sessions': return doList(ctx);
-        case 'switch_session': return doSwitch(args, ctx);
         default:
             throw new Error(`session module does not handle tool: ${name}`);
     }

package/dist/server/tools/storage.js

@@ -1,17 +1,15 @@
 /**
  * storage domain — pattern persistence.
  *
- * Owns one consolidated tool (`pattern_store`) plus three deprecated
- * aliases (`save`, `load`, `list`) per the #120 / #143 consolidation.
- *
- * The consolidation also resolves the `list` / `list_sessions` naming
- * collision from #110 — `pattern_store(action='list')` is unambiguous
- * versus `session(action='list')` after the #158 session consolidation.
- *
- * Aliases forward to `pattern_store` and will be removed in a future
- * release per the deprecation policy in #120.
+ * Owns one consolidated tool (`pattern_store`) with save/load/list actions.
  */
 import { InputValidator } from '../../utils/InputValidator.js';
+import { ok, err, categorizeError, withStashNotice } from './types.js';
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { ValidationError } from '../../utils/CategorisedError.js';
+/** Hard cap on .mid input size — protects @tonejs/midi from pathological allocations. */
+const MAX_MIDI_BYTES = 1_000_000; // 1 MB
 const SESSION_ID_PROP = {
     session_id: {
         type: 'string',
@@ -37,6 +35,12 @@ export const tools = [
                 },
                 name: { type: 'string', description: 'Pattern name (required for save/load)' },
                 tags: { type: 'array', items: { type: 'string' }, description: 'Tags to attach (save only)' },
+                overwrite: {
+                    type: 'boolean',
+                    description: 'save only: replace a pattern saved under a DIFFERENT name that maps to the '
+                        + 'same file (names are lowercased and stripped of punctuation, so "My Jam" '
+                        + 'and "my-jam" collide). Off by default; the replaced pattern is unrecoverable.',
+                },
                 tag: { type: 'string', description: 'Filter by tag (list only)' },
                 ...SESSION_ID_PROP,
             },
@@ -44,38 +48,45 @@ export const tools = [
         },
     },
     {
-        name: 'save',
-        description: '[DEPRECATED — use pattern_store({ action: "save" }) instead] Save pattern with metadata',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Pattern name' },
-                tags: { type: 'array', items: { type: 'string' } },
-                ...SESSION_ID_PROP,
-            },
-            required: ['name'],
-        },
-    },
-    {
-        name: 'load',
-        description: '[DEPRECATED — use pattern_store({ action: "load" }) instead] Load saved pattern',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                name: { type: 'string', description: 'Pattern name' },
-                ...SESSION_ID_PROP,
-            },
-            required: ['name'],
-        },
-    },
-    {
-        name: 'list',
-        description: '[DEPRECATED — use pattern_store({ action: "list" }) instead] List saved patterns',
+        name: 'import_midi',
+        description: 'Convert a .mid file into a playable Strudel pattern (Phase 1: literal transcription, #201). ' +
+            'Use source="base64" with data=<base64 string> for inline bytes, or source="path" with data=<basename> ' +
+            'to read from the patterns/midi/ directory (path traversal blocked). ' +
+            'Drum tracks (MIDI channel 10) emit one s() lane per sample so simultaneous kicks/hats do not collide. ' +
+            'Pitched tracks emit note("...").s("piano") with simultaneous notes merged into [a,b,c] chord tokens. ' +
+            'Phase 2+ (structural compression, voice separation, LLM idiomatic pass) tracked in separate issues. ' +
+            'Example: import_midi({ source: "path", data: "drumloop.mid", steps_per_cycle: 16 }). ' +
+            'For the reverse direction (Strudel → MIDI) use the export_midi tool.',
         inputSchema: {
             type: 'object',
             properties: {
-                tag: { type: 'string', description: 'Filter by tag' },
+                source: {
+                    type: 'string',
+                    enum: ['base64', 'path'],
+                    description: 'How to interpret `data` — raw base64 bytes or a filename under patterns/midi/',
+                },
+                data: {
+                    type: 'string',
+                    description: 'For source=base64: base64-encoded .mid bytes (≤1MB decoded). ' +
+                        'For source=path: basename of a .mid file under ./patterns/midi/ (path-traversal blocked).',
+                },
+                steps_per_cycle: {
+                    type: 'number',
+                    description: 'Grid resolution per bar (integer 1-64). Default 16.',
+                },
+                bars: {
+                    type: 'number',
+                    description: 'Cap on bars to emit. Default: full file.',
+                },
+                drum_map: {
+                    type: 'object',
+                    description: 'Optional override / extension to the default GM percussion map. ' +
+                        'Keys are MIDI note numbers (as strings, since JSON object keys), values are Strudel sample names. ' +
+                        'Example: { "60": "cp", "61": "rim" }. Unmapped drums fall back to rests and are surfaced in the result summary.',
+                    additionalProperties: { type: 'string' },
+                },
             },
+            required: ['source', 'data'],
         },
     },
 ];
@@ -83,27 +94,142 @@ export const toolNames = new Set(tools.map(t => t.name));
 async function doSave(args, ctx, sid) {
     InputValidator.validateStringLength(args.name, 'name', 255, false);
     const toSave = await ctx.getCurrentPatternSafe(sid);
-    if (!toSave) {
-        return 'No pattern to save';
+    // Whitespace counts as nothing. `!toSave` covered '' only, so a
+    // pattern of "  \n\t " was written to disk and reported as a real
+    // save (#293).
+    if (!toSave || toSave.trim().length === 0) {
+        // Nothing was written to disk, so this is a failure — but as a bare
+        // string it was none of the three things the dispatcher recognises
+        // (envelope, failure-shaped object, legacy 'Error: ' prefix), so it
+        // reached clients as { ok: true, data: 'No pattern to save' }. An
+        // agent branching on `ok` recorded a successful save and moved on,
+        // and the pattern was gone (#287).
+        return err('business', 'No pattern to save. Write or generate a pattern first.');
     }
-    await ctx.store.save(args.name, toSave, args.tags || []);
+    // A collision throws ValidationError, which `categorizeError` maps to
+    // the validation envelope at the dispatcher — so the caller gets a
+    // refusal naming the pattern in the way, not a success (#428).
+    await ctx.store.save(args.name, toSave, args.tags || [], {
+        overwrite: args.overwrite === true,
+    });
     return `Pattern saved as "${args.name}"`;
 }
 async function doLoad(args, ctx, sid) {
     InputValidator.validateStringLength(args.name, 'name', 255, false);
     const saved = await ctx.store.load(args.name);
     if (saved) {
-        await ctx.writePatternSafe(saved.content, sid);
-        return `Loaded pattern "${args.name}"`;
+        const written = await ctx.writePatternSafe(saved.content, sid);
+        return withStashNotice(`Loaded pattern "${args.name}"`, written);
     }
-    return `Pattern "${args.name}" not found`;
+    // Bare prose, so the dispatcher's legacy normalisation — which only
+    // recognises 'Error: ' and 'Browser not initialized' prefixes — let
+    // this through as { ok: true, data: 'Pattern "x" not found' }. Same
+    // false success as #287, twenty lines below the code that fixed it
+    // (#293).
+    return err('business', `Pattern "${args.name}" not found. ` +
+        'Use pattern_store({ action: "list" }) to see what is saved.');
 }
 async function doList(args, ctx) {
     if (args?.tag) {
         InputValidator.validateStringLength(args.tag, 'tag', 100, false);
     }
-    const patterns = await ctx.store.list(args?.tag);
-    return patterns.map(p => `• ${p.name} [${p.tags.join(', ')}] - ${p.timestamp}`).join('\n') || 'No patterns found';
+    const { patterns, skipped } = await ctx.store.listDetailed(args?.tag);
+    // A file the store could not read is not the same as a pattern that
+    // is not there, and the caller has no other way to learn the
+    // difference — the store logs it, and no MCP client reads the log
+    // (#426, same reasoning as the export warning in #335).
+    const note = skipped > 0
+        ? `\n\n(${String(skipped)} file(s) in the pattern directory could not be read and were skipped.)`
+        : '';
+    if (patterns.length === 0) {
+        return skipped > 0
+            ? `No readable patterns found.${note}`
+            : 'No patterns found';
+    }
+    return patterns.map(p => `• ${p.name} [${p.tags.join(', ')}] - ${p.timestamp}`).join('\n') + note;
+}
+/**
+ * Resolve `args.data` to a Buffer based on `args.source`. Enforces the
+ * 1 MB cap and, for path sources, blocks path traversal by clamping to
+ * `./patterns/midi/` via `path.basename` (mirrors PatternStore).
+ */
+async function loadMidiBuffer(args) {
+    const source = args?.source;
+    const data = args?.data;
+    if (typeof data !== 'string' || data.length === 0) {
+        throw new Error('Invalid data: must be a non-empty string');
+    }
+    if (source === 'base64') {
+        // Decoded length ≤ raw length × 3/4; reject before allocating.
+        if (data.length > MAX_MIDI_BYTES * 2) {
+            throw new ValidationError(`MIDI base64 input too large (>${MAX_MIDI_BYTES} bytes decoded).`);
+        }
+        const buf = Buffer.from(data, 'base64');
+        if (buf.length === 0) {
+            throw new Error('Invalid data: base64 decoded to zero bytes');
+        }
+        if (buf.length > MAX_MIDI_BYTES) {
+            throw new ValidationError(`MIDI input too large (${buf.length} > ${MAX_MIDI_BYTES} bytes).`);
+        }
+        return buf;
+    }
+    if (source === 'path') {
+        InputValidator.validateStringLength(data, 'data', 255, false);
+        const safeName = path.basename(data);
+        if (safeName !== data) {
+            throw new Error('Invalid filename: path traversal detected');
+        }
+        const fullPath = path.resolve('./patterns/midi', safeName);
+        const expectedRoot = path.resolve('./patterns/midi');
+        if (!fullPath.startsWith(expectedRoot + path.sep)) {
+            throw new Error('Invalid filename: must resolve under patterns/midi/');
+        }
+        const buf = await readFile(fullPath);
+        if (buf.length > MAX_MIDI_BYTES) {
+            throw new ValidationError(`MIDI input too large (${buf.length} > ${MAX_MIDI_BYTES} bytes).`);
+        }
+        return buf;
+    }
+    throw new Error(`Invalid source: ${source}. Must be "base64" or "path".`);
+}
+async function doImportMidi(args, ctx) {
+    let buffer;
+    try {
+        buffer = await loadMidiBuffer(args);
+    }
+    catch (e) {
+        return err('validation', e?.message ?? 'Failed to load MIDI input');
+    }
+    // Normalize drum_map keys: JSON object keys are strings, the service wants number keys.
+    let drumMapNormalized;
+    if (args?.drum_map && typeof args.drum_map === 'object') {
+        drumMapNormalized = {};
+        for (const [k, v] of Object.entries(args.drum_map)) {
+            const n = Number(k);
+            if (!Number.isInteger(n) || n < 0 || n > 127 || typeof v !== 'string' || v.length === 0) {
+                return err('validation', `Invalid drum_map entry: ${k} -> ${String(v)}`);
+            }
+            drumMapNormalized[n] = v;
+        }
+    }
+    try {
+        const result = ctx.midiImportService.convertBuffer(buffer, {
+            steps_per_cycle: args?.steps_per_cycle,
+            bars: args?.bars,
+            drum_map: drumMapNormalized,
+        });
+        return ok(result);
+    }
+    catch (e) {
+        // Use the shared categoriser rather than a second, narrower one.
+        // This local matcher knew only parse/invalid/must-be, so every cap
+        // added in #235 landed in `internal` — including "MIDI file spans too
+        // many bars (N > 512). Pass bars=<n> to import a prefix.", which is
+        // the most actionable message in the file and was being delivered as
+        // a server bug the caller could do nothing about (#280).
+        const msg = e instanceof Error ? e.message : String(e);
+        return err(categorizeError(e), msg);
+    }
 }
 export async function execute(name, args, ctx) {
     const sid = args?.session_id;
@@ -121,11 +247,8 @@ export async function execute(name, args, ctx) {
             // Unreachable due to enum check above, but TypeScript wants it.
             return undefined;
         }
-        // Aliases — forward to consolidated handler. Kept for ≥1 release per
-        // #120 migration rules; removed afterwards.
-        case 'save': return await doSave(args, ctx, sid);
-        case 'load': return await doLoad(args, ctx, sid);
-        case 'list': return await doList(args, ctx);
+        case 'import_midi':
+            return await doImportMidi(args, ctx);
         default:
             throw new Error(`storage module does not handle tool: ${name}`);
     }