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

package/dist/server/tools/history.js

@@ -11,20 +11,53 @@
  * server pushes onto these arrays on write/append/insert/replace/clear,
  * so all mutations share the same underlying storage.
  */
+const SESSION_ID_PROP = {
+    session_id: {
+        type: 'string',
+        description: 'Optional session ID (#108). Omit to use default session. Note: undo/redo/history stacks are currently server-wide; only the read/write target changes.',
+    },
+};
 export const tools = [
+    {
+        name: 'history',
+        description: 'Navigate or inspect the pattern edit history. ' +
+            'action=undo reverts the last edit on the targeted session. ' +
+            'action=redo replays a previously-undone edit. ' +
+            'action=list returns recent entries with timestamps and previews (limit defaults to 10). ' +
+            'action=restore jumps the editor to a specific entry by id (current pattern goes on the undo stack). ' +
+            'action=compare diffs two entries by id (or one entry vs current pattern). ' +
+            'Example: history({ action: "list", limit: 5 }) — recent edits, newest first. ' +
+            'For on-disk saved patterns use pattern_store — history deals with the in-memory edit timeline of the current session.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['undo', 'redo', 'list', 'restore', 'compare'],
+                    description: 'Which history operation to perform',
+                },
+                limit: { type: 'number', description: 'Maximum entries (action=list, default 10)' },
+                id: { type: 'number', description: 'History entry ID (action=restore)' },
+                id1: { type: 'number', description: 'First entry ID (action=compare)' },
+                id2: { type: 'number', description: 'Second entry ID (action=compare, default: current pattern)' },
+                ...SESSION_ID_PROP,
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'undo',
-        description: 'Undo last action',
-        inputSchema: { type: 'object', properties: {} },
+        description: '[DEPRECATED — use history({ action: "undo" }) instead] Undo last action',
+        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
     {
         name: 'redo',
-        description: 'Redo action',
-        inputSchema: { type: 'object', properties: {} },
+        description: '[DEPRECATED — use history({ action: "redo" }) instead] Redo action',
+        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
     {
         name: 'list_history',
-        description: 'List recent pattern history with timestamps and previews',
+        description: '[DEPRECATED — use history({ action: "list" }) instead] List recent pattern history with timestamps and previews',
         inputSchema: {
             type: 'object',
             properties: {
@@ -34,23 +67,25 @@ export const tools = [
     },
     {
         name: 'restore_history',
-        description: 'Restore a previous pattern from history by ID',
+        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: 'Compare two patterns from history showing differences',
+        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'],
         },
@@ -104,91 +139,117 @@ function summarizeDiff(a, b) {
     }
     return { linesAdded: added, linesRemoved: removed, linesChanged: changed, charsDiff: b.length - a.length };
 }
+async function doUndo(ctx, sid) {
+    const { undoStack, redoStack, maxHistory } = ctx.getHistory(sid);
+    if (!sid && !ctx.isInitialized())
+        return 'Browser not initialized. Run init first.';
+    if (undoStack.length === 0)
+        return 'Nothing to undo';
+    const controller = ctx.getController(sid);
+    const current = await controller.getCurrentPattern();
+    redoStack.push(current);
+    if (redoStack.length > maxHistory)
+        redoStack.shift();
+    const previous = undoStack.pop();
+    await controller.writePattern(previous);
+    return 'Undone';
+}
+async function doRedo(ctx, sid) {
+    const { undoStack, redoStack, maxHistory } = ctx.getHistory(sid);
+    if (!sid && !ctx.isInitialized())
+        return 'Browser not initialized. Run init first.';
+    if (redoStack.length === 0)
+        return 'Nothing to redo';
+    const controller = ctx.getController(sid);
+    const current = await controller.getCurrentPattern();
+    undoStack.push(current);
+    if (undoStack.length > maxHistory)
+        undoStack.shift();
+    const next = redoStack.pop();
+    await controller.writePattern(next);
+    return 'Redone';
+}
+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.';
+    }
+    const limit = args?.limit || 10;
+    const recent = historyStack.slice(-limit).reverse();
+    return {
+        count: historyStack.length,
+        showing: recent.length,
+        entries: recent.map(e => ({
+            id: e.id,
+            preview: e.pattern.substring(0, 60) + (e.pattern.length > 60 ? '...' : ''),
+            chars: e.pattern.length,
+            action: e.action,
+            timestamp: formatTimeAgo(e.timestamp),
+        })),
+    };
+}
+async function doRestore(args, ctx, sid) {
+    const { undoStack, historyStack, maxHistory } = ctx.getHistory(sid);
+    if (!sid && !ctx.isInitialized())
+        return 'Browser not initialized. Run init first.';
+    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.`;
+    }
+    const current = await controller.getCurrentPattern();
+    undoStack.push(current);
+    if (undoStack.length > maxHistory)
+        undoStack.shift();
+    await controller.writePattern(entry.pattern);
+    return `Restored pattern from history #${args.id} (${formatTimeAgo(entry.timestamp)})`;
+}
+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.`;
+    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.`;
+        second = b.pattern;
+        label = `#${args.id2}`;
+    }
+    else {
+        second = await ctx.getCurrentPatternSafe(sid);
+        label = 'current';
+    }
+    return {
+        pattern1: { id: args.id1, chars: first.pattern.length },
+        pattern2: { id: label, chars: second.length },
+        diff: generateDiff(first.pattern, second),
+        summary: summarizeDiff(first.pattern, second),
+    };
+}
 export async function execute(name, args, ctx) {
-    const { undoStack, redoStack, historyStack, maxHistory } = ctx.history;
+    const sid = args?.session_id;
     switch (name) {
-        case 'undo': {
-            if (!ctx.isInitialized())
-                return 'Browser not initialized. Run init first.';
-            if (undoStack.length === 0)
-                return 'Nothing to undo';
-            const current = await ctx.controller.getCurrentPattern();
-            redoStack.push(current);
-            if (redoStack.length > maxHistory)
-                redoStack.shift();
-            const previous = undoStack.pop();
-            await ctx.controller.writePattern(previous);
-            return 'Undone';
-        }
-        case 'redo': {
-            if (!ctx.isInitialized())
-                return 'Browser not initialized. Run init first.';
-            if (redoStack.length === 0)
-                return 'Nothing to redo';
-            const current = await ctx.controller.getCurrentPattern();
-            undoStack.push(current);
-            if (undoStack.length > maxHistory)
-                undoStack.shift();
-            const next = redoStack.pop();
-            await ctx.controller.writePattern(next);
-            return 'Redone';
-        }
-        case 'list_history': {
-            if (historyStack.length === 0) {
-                return 'No pattern history yet. Make some edits to build history.';
-            }
-            const limit = args?.limit || 10;
-            const recent = historyStack.slice(-limit).reverse();
-            return {
-                count: historyStack.length,
-                showing: recent.length,
-                entries: recent.map(e => ({
-                    id: e.id,
-                    preview: e.pattern.substring(0, 60) + (e.pattern.length > 60 ? '...' : ''),
-                    chars: e.pattern.length,
-                    action: e.action,
-                    timestamp: formatTimeAgo(e.timestamp),
-                })),
-            };
-        }
-        case 'restore_history': {
-            if (!ctx.isInitialized())
-                return 'Browser not initialized. Run init first.';
-            const entry = historyStack.find(e => e.id === args.id);
-            if (!entry) {
-                return `History entry #${args.id} not found. Use list_history to see available entries.`;
-            }
-            const current = await ctx.controller.getCurrentPattern();
-            undoStack.push(current);
-            if (undoStack.length > maxHistory)
-                undoStack.shift();
-            await ctx.controller.writePattern(entry.pattern);
-            return `Restored pattern from history #${args.id} (${formatTimeAgo(entry.timestamp)})`;
-        }
-        case 'compare_patterns': {
-            const first = historyStack.find(e => e.id === args.id1);
-            if (!first)
-                return `History entry #${args.id1} not found.`;
-            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.`;
-                second = b.pattern;
-                label = `#${args.id2}`;
-            }
-            else {
-                second = await ctx.getCurrentPatternSafe();
-                label = 'current';
+        case 'history': {
+            const action = args?.action;
+            switch (action) {
+                case 'undo': return await doUndo(ctx, sid);
+                case 'redo': return await doRedo(ctx, sid);
+                case 'list': return doList(args, ctx, sid);
+                case 'restore': return await doRestore(args, ctx, sid);
+                case 'compare': return await doCompare(args, ctx, sid);
+                default:
+                    throw new Error(`Invalid action: ${action}. Must be one of: undo, redo, list, restore, compare`);
             }
-            return {
-                pattern1: { id: args.id1, chars: first.pattern.length },
-                pattern2: { id: label, chars: second.length },
-                diff: generateDiff(first.pattern, second),
-                summary: summarizeDiff(first.pattern, second),
-            };
         }
+        // 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,41 +1,72 @@
 /**
- * playback domain — transport controls (play, pause, stop).
+ * playback domain — transport controls.
  *
- * Owns (3 tools): play, pause, stop. Post-consolidation target
- * (#110 audit, #120 epic): single `playback` tool with action enum.
- * For now we keep the individual verbs and only extract them out of
- * server.ts.
+ * Owns one consolidated tool (`playback(action)`) plus three deprecated
+ * aliases (play, pause, stop) per #120 / #152.
  *
- * Initialization checks happen upstream via requiresInitialization()
- * in StrudelMCPServer — handlers here assume the browser is ready.
+ * Aliases forward to `playback` and will be removed in a future release
+ * per the deprecation policy.
  */
+const SESSION_ID_PROP = {
+    session_id: {
+        type: 'string',
+        description: 'Optional session ID (#108). Omit to use default session.',
+    },
+};
 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=stop ends playback. ' +
+            'Example: playback({ action: "play" }). ' +
+            'For pattern editing use edit_pattern; for tempo use set_tempo.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'stop'],
+                    description: 'Transport action',
+                },
+                ...SESSION_ID_PROP,
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'play',
-        description: 'Start playing pattern',
-        inputSchema: { type: 'object', properties: {} },
+        description: '[DEPRECATED — use playback({ action: "play" }) instead] Start playing pattern',
+        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
     {
         name: 'pause',
-        description: 'Pause playback',
-        inputSchema: { type: 'object', properties: {} },
+        description: '[DEPRECATED — use playback({ action: "pause" }) instead] Pause playback',
+        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
     {
         name: 'stop',
-        description: 'Stop playback',
-        inputSchema: { type: 'object', properties: {} },
+        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) {
-    switch (name) {
+export async function execute(name, args, ctx) {
+    const sid = args?.session_id;
+    if (!sid && !ctx.isInitialized()) {
+        return 'Browser not initialized. Run init first.';
+    }
+    const controller = ctx.getController(sid);
+    const action = name === 'playback' ? args?.action : name;
+    switch (action) {
         case 'play':
-            return await ctx.controller.play();
+            return await controller.play();
         case 'pause':
         case 'stop':
-            return await ctx.controller.stop();
+            return await controller.stop();
         default:
-            throw new Error(`playback module does not handle tool: ${name}`);
+            throw new Error(`Invalid action: ${action}. Must be one of: play, pause, stop`);
     }
 }
 export const playbackModule = { tools, toolNames, execute };

package/dist/server/tools/session.js

@@ -1,19 +1,34 @@
 /**
  * session domain — multi-session lifecycle management.
  *
- * Owns (4 tools): create_session, destroy_session, list_sessions,
- * switch_session. Per the #110 audit, these collapse into a single
- * `session` tool with an `action` enum post-split. `init` stays
- * separate — it's the global bootstrap, not a session operation.
- *
- * `show_browser` also stays in server.ts for now until it moves into
- * a `browser_window` module (per audit) alongside `screenshot`.
+ * 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.
  */
 import { InputValidator } from '../../utils/InputValidator.js';
 export const tools = [
+    {
+        name: 'session',
+        description: 'Manage isolated Strudel browser sessions (multi-session, #108). ' +
+            'action=create starts a new named session (sessions share one browser but isolated contexts). ' +
+            'action=destroy closes a named session and releases its resources. ' +
+            'action=list returns metadata for all active sessions (id, created, last_activity, is_playing, is_default). ' +
+            'action=switch changes the default session that subsequent tool calls route to when no session_id is passed. ' +
+            'Example: session({ action: "create", session_id: "live-set-1" }). ' +
+            'For the on-disk pattern catalog use pattern_store(action=list) — session(action=list) lists *runtime* sessions, not saved patterns.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['create', 'destroy', 'list', 'switch'], description: 'Session lifecycle action' },
+                session_id: { type: 'string', description: 'Session identifier (required for create/destroy/switch)' },
+            },
+            required: ['action'],
+        },
+    },
     {
         name: 'create_session',
-        description: 'Create a new isolated Strudel browser session. Sessions share one browser but have isolated contexts.',
+        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' } },
@@ -22,7 +37,7 @@ export const tools = [
     },
     {
         name: 'destroy_session',
-        description: 'Close and destroy a Strudel session, releasing its resources.',
+        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' } },
@@ -31,12 +46,12 @@ export const tools = [
     },
     {
         name: 'list_sessions',
-        description: 'List all active Strudel sessions with their metadata.',
+        description: '[DEPRECATED — use session({ action: "list" }) instead] List all active Strudel sessions.',
         inputSchema: { type: 'object', properties: {} },
     },
     {
         name: 'switch_session',
-        description: 'Change the default session used by other tools.',
+        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' } },
@@ -45,69 +60,92 @@ export const tools = [
     },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
-export async function execute(name, args, ctx) {
+async function doCreate(args, ctx) {
+    const sm = ctx.sessionManager;
+    InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
+    try {
+        await sm.createSession(args.session_id);
+        return {
+            success: true,
+            session_id: args.session_id,
+            message: `Session '${args.session_id}' created successfully`,
+            total_sessions: sm.getSessionCount(),
+            max_sessions: sm.getMaxSessions(),
+        };
+    }
+    catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function doDestroy(args, ctx) {
+    const sm = ctx.sessionManager;
+    InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
+    try {
+        await sm.destroySession(args.session_id);
+        // Drop the session's history bundle (#179) and audio capture service
+        // (#180) so a future session with the same id starts fresh.
+        ctx.dropHistory(args.session_id);
+        ctx.dropAudioCaptureService(args.session_id);
+        return {
+            success: true,
+            session_id: args.session_id,
+            message: `Session '${args.session_id}' destroyed`,
+            remaining_sessions: sm.getSessionCount(),
+        };
+    }
+    catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function doList(ctx) {
     const sm = ctx.sessionManager;
+    const info = sm.getSessionsInfo();
+    return {
+        count: info.length,
+        max_sessions: sm.getMaxSessions(),
+        default_session: sm.getDefaultSessionId(),
+        sessions: info.map(s => ({
+            id: s.id,
+            created: s.created.toISOString(),
+            last_activity: s.lastActivity.toISOString(),
+            is_playing: s.isPlaying,
+            is_default: s.id === sm.getDefaultSessionId(),
+        })),
+    };
+}
+function doSwitch(args, ctx) {
+    const sm = ctx.sessionManager;
+    InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
+    try {
+        sm.setDefaultSession(args.session_id);
+        return {
+            success: true,
+            default_session: args.session_id,
+            message: `Default session switched to '${args.session_id}'`,
+        };
+    }
+    catch (error) {
+        return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function execute(name, args, ctx) {
     switch (name) {
-        case 'create_session': {
-            InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
-            try {
-                await sm.createSession(args.session_id);
-                return {
-                    success: true,
-                    session_id: args.session_id,
-                    message: `Session '${args.session_id}' created successfully`,
-                    total_sessions: sm.getSessionCount(),
-                    max_sessions: sm.getMaxSessions(),
-                };
-            }
-            catch (error) {
-                return { success: false, error: error instanceof Error ? error.message : String(error) };
-            }
-        }
-        case 'destroy_session': {
-            InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
-            try {
-                await sm.destroySession(args.session_id);
-                return {
-                    success: true,
-                    session_id: args.session_id,
-                    message: `Session '${args.session_id}' destroyed`,
-                    remaining_sessions: sm.getSessionCount(),
-                };
-            }
-            catch (error) {
-                return { success: false, error: error instanceof Error ? error.message : String(error) };
-            }
-        }
-        case 'list_sessions': {
-            const info = sm.getSessionsInfo();
-            return {
-                count: info.length,
-                max_sessions: sm.getMaxSessions(),
-                default_session: sm.getDefaultSessionId(),
-                sessions: info.map(s => ({
-                    id: s.id,
-                    created: s.created.toISOString(),
-                    last_activity: s.lastActivity.toISOString(),
-                    is_playing: s.isPlaying,
-                    is_default: s.id === sm.getDefaultSessionId(),
-                })),
-            };
-        }
-        case 'switch_session': {
-            InputValidator.validateStringLength(args.session_id, 'session_id', 100, false);
-            try {
-                sm.setDefaultSession(args.session_id);
-                return {
-                    success: true,
-                    default_session: args.session_id,
-                    message: `Default session switched to '${args.session_id}'`,
-                };
-            }
-            catch (error) {
-                return { success: false, error: error instanceof Error ? error.message : String(error) };
+        case 'session': {
+            const a = args?.action;
+            switch (a) {
+                case 'create': return await doCreate(args, ctx);
+                case 'destroy': return await doDestroy(args, ctx);
+                case 'list': return doList(ctx);
+                case 'switch': return doSwitch(args, ctx);
+                default:
+                    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}`);
     }