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

package/dist/server/tools/transform.js

@@ -50,73 +50,131 @@ function transposePattern(pattern, semitones) {
         return noteNames[newNoteValue] + newOctave;
     });
 }
+const SESSION_ID_PROP = {
+    session_id: {
+        type: 'string',
+        description: 'Optional session ID (#108). Omit to use default session.',
+    },
+};
 export const tools = [
+    {
+        name: 'transform',
+        description: 'Apply a single transform op to the current session pattern. ' +
+            'op=transpose shifts notes by `semitones`. ' +
+            'op=reverse appends `.rev` to the pattern. ' +
+            'op=stretch slows by `factor` (>1 slower, <1 faster). ' +
+            'op=quantize snaps to the `grid` (e.g. "1/16"). ' +
+            'op=humanize adds rand-nudge timing of `amount` (0-1). ' +
+            'op=swing applies `.swing(amount)` (alias for add_swing). ' +
+            'op=scale applies a `root`/`scale` filter to notes (alias for apply_scale). ' +
+            'op=vary returns a variation of `type` (subtle/moderate/extreme/glitch/evolving — note: this is what generate_variation does today; the name is misleading because it transforms rather than generates). ' +
+            'Example: transform({ op: "transpose", semitones: 7 }). ' +
+            'For effects (add/remove) use effect; for mood/energy/refine use shape; for tempo use set_tempo.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                op: {
+                    type: 'string',
+                    enum: ['transpose', 'reverse', 'stretch', 'quantize', 'humanize', 'swing', 'scale', 'vary'],
+                    description: 'Which transform to apply',
+                },
+                semitones: { type: 'number', description: 'op=transpose: integer semitones to shift' },
+                factor: { type: 'number', description: 'op=stretch: stretch factor' },
+                grid: { type: 'string', description: 'op=quantize: grid size (e.g. "1/16")' },
+                amount: { type: 'number', description: 'op=humanize/swing: amount 0-1' },
+                root: { type: 'string', description: 'op=scale: root note (e.g. "C")' },
+                scale: { type: 'string', description: 'op=scale: scale name (e.g. "minor")' },
+                type: { type: 'string', description: 'op=vary: variation type (subtle/moderate/extreme/glitch/evolving)' },
+                ...SESSION_ID_PROP,
+            },
+            required: ['op'],
+        },
+    },
     {
         name: 'transpose',
-        description: 'Transpose notes by semitones',
+        description: '[DEPRECATED — use transform({ op: "transpose" }) instead] Transpose notes by semitones',
         inputSchema: {
             type: 'object',
-            properties: { semitones: { type: 'number', description: 'Semitones to transpose' } },
+            properties: { semitones: { type: 'number', description: 'Semitones to transpose' }, ...SESSION_ID_PROP },
             required: ['semitones'],
         },
     },
     {
         name: 'reverse',
-        description: 'Reverse pattern',
-        inputSchema: { type: 'object', properties: {} },
+        description: '[DEPRECATED — use transform({ op: "reverse" }) instead] Reverse pattern',
+        inputSchema: { type: 'object', properties: { ...SESSION_ID_PROP } },
     },
     {
         name: 'stretch',
-        description: 'Time stretch pattern',
+        description: '[DEPRECATED — use transform({ op: "stretch" }) instead] Time stretch pattern',
         inputSchema: {
             type: 'object',
-            properties: { factor: { type: 'number', description: 'Stretch factor' } },
+            properties: { factor: { type: 'number', description: 'Stretch factor' }, ...SESSION_ID_PROP },
             required: ['factor'],
         },
     },
     {
         name: 'quantize',
-        description: 'Quantize to grid',
+        description: '[DEPRECATED — use transform({ op: "quantize" }) instead] Quantize to grid',
         inputSchema: {
             type: 'object',
-            properties: { grid: { type: 'string', description: 'Grid size (e.g., "1/16")' } },
+            properties: { grid: { type: 'string', description: 'Grid size (e.g., "1/16")' }, ...SESSION_ID_PROP },
             required: ['grid'],
         },
     },
     {
         name: 'humanize',
-        description: 'Add human timing variation',
+        description: '[DEPRECATED — use transform({ op: "humanize" }) instead] Add human timing variation',
         inputSchema: {
             type: 'object',
-            properties: { amount: { type: 'number', description: 'Humanization amount (0-1)' } },
+            properties: { amount: { type: 'number', description: 'Humanization amount (0-1)' }, ...SESSION_ID_PROP },
         },
     },
     {
         name: 'generate_variation',
-        description: 'Create pattern variations',
+        description: '[DEPRECATED — use transform({ op: "vary" }) instead] Create pattern variations (mis-named today; it transforms, not generates)',
         inputSchema: {
             type: 'object',
-            properties: { type: { type: 'string', description: 'Variation type (subtle/moderate/extreme/glitch/evolving)' } },
+            properties: { type: { type: 'string', description: 'Variation type (subtle/moderate/extreme/glitch/evolving)' }, ...SESSION_ID_PROP },
+        },
+    },
+    {
+        name: 'effect',
+        description: 'Add or remove a Strudel effect on the current session pattern. ' +
+            'action=add appends `.<effect>(<params>)`. ' +
+            'action=remove strips the last `.<effect>(...)` call from the pattern. ' +
+            'Example: effect({ action: "add", effect: "lpf", params: "1000" }). ' +
+            'For higher-level effect bundles (mood/energy/refine) use shape; for raw transforms use transform.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['add', 'remove'], description: 'add or remove the effect' },
+                effect: { type: 'string', description: 'Effect name (e.g. lpf, room, delay)' },
+                params: { type: 'string', description: 'Effect parameters (action=add only)' },
+                ...SESSION_ID_PROP,
+            },
+            required: ['action', 'effect'],
         },
     },
     {
         name: 'add_effect',
-        description: 'Add effect to pattern',
+        description: '[DEPRECATED — use effect({ action: "add" }) instead] Add effect to pattern',
         inputSchema: {
             type: 'object',
             properties: {
                 effect: { type: 'string', description: 'Effect name' },
                 params: { type: 'string', description: 'Effect parameters' },
+                ...SESSION_ID_PROP,
             },
             required: ['effect'],
         },
     },
     {
         name: 'remove_effect',
-        description: 'Remove effect',
+        description: '[DEPRECATED — use effect({ action: "remove" }) instead] Remove effect',
         inputSchema: {
             type: 'object',
-            properties: { effect: { type: 'string', description: 'Effect to remove' } },
+            properties: { effect: { type: 'string', description: 'Effect to remove' }, ...SESSION_ID_PROP },
             required: ['effect'],
         },
     },
@@ -125,34 +183,62 @@ export const tools = [
         description: 'Set BPM',
         inputSchema: {
             type: 'object',
-            properties: { bpm: { type: 'number', description: 'Tempo in BPM' } },
+            properties: { bpm: { type: 'number', description: 'Tempo in BPM' }, ...SESSION_ID_PROP },
             required: ['bpm'],
         },
     },
     {
         name: 'add_swing',
-        description: 'Add swing to pattern',
+        description: '[DEPRECATED — use transform({ op: "swing" }) instead] Add swing to pattern',
         inputSchema: {
             type: 'object',
-            properties: { amount: { type: 'number', description: 'Swing amount (0-1)' } },
+            properties: { amount: { type: 'number', description: 'Swing amount (0-1)' }, ...SESSION_ID_PROP },
             required: ['amount'],
         },
     },
     {
         name: 'apply_scale',
-        description: 'Apply scale to notes',
+        description: '[DEPRECATED — use transform({ op: "scale" }) instead] Apply scale to notes',
         inputSchema: {
             type: 'object',
             properties: {
                 scale: { type: 'string', description: 'Scale name' },
                 root: { type: 'string', description: 'Root note' },
+                ...SESSION_ID_PROP,
             },
             required: ['scale', 'root'],
         },
     },
+    {
+        name: 'shape',
+        description: 'Shape the current pattern along one of three high-level dimensions. ' +
+            'dimension=mood applies a mood profile (dark/euphoric/melancholic/aggressive/dreamy/peaceful/energetic) with optional intensity 0-1. ' +
+            'dimension=energy applies an energy level (integer 0-10). ' +
+            'dimension=refine applies a directional refinement: faster/slower/louder/quieter/brighter/darker/"more reverb"/drier. ' +
+            'All three auto-play by default. ' +
+            'Example: shape({ dimension: "mood", target_mood: "dark", intensity: 0.8 }). ' +
+            'For raw transform ops use transform; for explicit effects use effect.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                dimension: { type: 'string', enum: ['mood', 'energy', 'refine'], description: 'Which dimension to shape along' },
+                target_mood: {
+                    type: 'string',
+                    enum: ['dark', 'euphoric', 'melancholic', 'aggressive', 'dreamy', 'peaceful', 'energetic'],
+                    description: 'dimension=mood: target mood',
+                },
+                intensity: { type: 'number', minimum: 0, maximum: 1, description: 'dimension=mood: intensity 0-1 (default 0.5)' },
+                level: { type: 'number', description: 'dimension=energy: integer level 0-10' },
+                direction: { type: 'string', description: 'dimension=refine: faster, slower, louder, quieter, brighter, darker, "more reverb", drier' },
+                auto_play: { type: 'boolean', description: 'Start playback after shape (default true)' },
+                ...SESSION_ID_PROP,
+            },
+            required: ['dimension'],
+        },
+    },
     {
         name: 'shift_mood',
-        description: 'Transform current pattern to match a different emotional mood by adjusting tempo, effects, and note choices. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic.',
+        description: '[DEPRECATED — use shape({ dimension: "mood" }) instead] Transform current pattern to match a different emotional mood. Moods: dark, euphoric, melancholic, aggressive, dreamy, peaceful, energetic.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -163,122 +249,170 @@ export const tools = [
                 },
                 intensity: { type: 'number', minimum: 0, maximum: 1, description: 'How strongly to apply the mood transformation (0-1, default: 0.5)' },
                 auto_play: { type: 'boolean', description: 'Start playback after transformation (default: true)' },
+                ...SESSION_ID_PROP,
             },
             required: ['target_mood'],
         },
     },
     {
         name: 'set_energy',
-        description: 'Adjust the overall energy level of the current pattern on a 0-10 scale. 0: minimal/ambient, 1-2: sparse, 3-4: light/relaxed, 5-6: normal/moderate, 7-8: driving/intense, 9-10: maximum. Auto-plays after applying energy level.',
+        description: '[DEPRECATED — use shape({ dimension: "energy" }) instead] Adjust energy level 0-10. Auto-plays after applying.',
         inputSchema: {
             type: 'object',
-            properties: { level: { type: 'number', description: 'Energy level from 0 (minimal) to 10 (maximum)' } },
+            properties: { level: { type: 'number', description: 'Energy level from 0 (minimal) to 10 (maximum)' }, ...SESSION_ID_PROP },
             required: ['level'],
         },
     },
     {
         name: 'refine',
-        description: 'Incrementally refine the current pattern with simple directional commands. Supports: faster/slower (tempo), louder/quieter (gain), brighter/darker (filter cutoff), "more reverb"/drier (reverb). Auto-plays after applying refinement.',
+        description: '[DEPRECATED — use shape({ dimension: "refine" }) instead] Incrementally refine current pattern: faster/slower/louder/quieter/brighter/darker/"more reverb"/drier.',
         inputSchema: {
             type: 'object',
-            properties: { direction: { type: 'string', description: 'Refinement direction: faster, slower, louder, quieter, brighter, darker, "more reverb", or drier' } },
+            properties: { direction: { type: 'string', description: 'Refinement direction: faster, slower, louder, quieter, brighter, darker, "more reverb", or drier' }, ...SESSION_ID_PROP },
             required: ['direction'],
         },
     },
 ];
 export const toolNames = new Set(tools.map(t => t.name));
+// ---- per-op helpers (shared by transform({op}) and the deprecated aliases)
+async function opTranspose(args, ctx, sid) {
+    if (typeof args.semitones !== 'number' || !Number.isInteger(args.semitones)) {
+        throw new Error('Semitones must be an integer');
+    }
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(transposePattern(p, args.semitones), sid);
+    return `Transposed ${args.semitones} semitones`;
+}
+async function opReverse(ctx, sid) {
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(p + '.rev', sid);
+    return 'Pattern reversed';
+}
+async function opStretch(args, ctx, sid) {
+    InputValidator.validateGain(args.factor);
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(p + `.slow(${args.factor})`, sid);
+    return `Stretched by factor of ${args.factor}`;
+}
+async function opQuantize(args, ctx, sid) {
+    InputValidator.validateStringLength(args.grid, 'grid', 50, false);
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(p + `.struct("${args.grid}")`, sid);
+    return `Quantized to ${args.grid} grid`;
+}
+async function opHumanize(args, ctx, sid) {
+    if (args.amount !== undefined)
+        InputValidator.validateNormalizedValue(args.amount, 'amount');
+    const p = await ctx.getCurrentPatternSafe(sid);
+    const amt = args.amount || 0.01;
+    await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`, sid);
+    return 'Added human timing';
+}
+async function opVary(args, ctx, sid) {
+    const p = await ctx.getCurrentPatternSafe(sid);
+    const varied = ctx.generator.generateVariation(p, args.type || 'subtle');
+    await ctx.writePatternSafe(varied, sid);
+    return `Added ${args.type || 'subtle'} variation`;
+}
+async function opSwing(args, ctx, sid) {
+    InputValidator.validateNormalizedValue(args.amount, 'amount');
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(p + `.swing(${args.amount})`, sid);
+    return `Added swing: ${args.amount}`;
+}
+async function opScale(args, ctx, sid) {
+    InputValidator.validateStringLength(args.scale, 'scale', 50, false);
+    InputValidator.validateRootNote(args.root);
+    const p = await ctx.getCurrentPatternSafe(sid);
+    await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`, sid);
+    return `Applied ${args.root} ${args.scale} scale`;
+}
+async function opEffectAdd(args, ctx, sid) {
+    InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    if (args.params)
+        InputValidator.validateStringLength(args.params, 'params', 1000, true);
+    const p = await ctx.getCurrentPatternSafe(sid);
+    const withEffect = args.params
+        ? p + `.${args.effect}(${args.params})`
+        : p + `.${args.effect}()`;
+    await ctx.writePatternSafe(withEffect, sid);
+    return `Added ${args.effect} effect`;
+}
+async function opEffectRemove(args, ctx, sid) {
+    InputValidator.validateStringLength(args.effect, 'effect', 100, false);
+    const p = await ctx.getCurrentPatternSafe(sid);
+    const regex = new RegExp(`\\.${args.effect}\\([^)]*\\)`, 'g');
+    const stripped = p.replace(regex, '');
+    if (stripped === p)
+        return `No ${args.effect} effect found to remove`;
+    await ctx.writePatternSafe(stripped, sid);
+    return `Removed ${args.effect} effect`;
+}
 export async function execute(name, args, ctx) {
+    const sid = args?.session_id;
+    if (!sid && !ctx.isInitialized()) {
+        return 'Browser not initialized. Run init first.';
+    }
     switch (name) {
-        case 'transpose': {
-            if (typeof args.semitones !== 'number' || !Number.isInteger(args.semitones)) {
-                throw new Error('Semitones must be an integer');
+        case 'transform': {
+            const op = args?.op;
+            switch (op) {
+                case 'transpose': return await opTranspose(args, ctx, sid);
+                case 'reverse': return await opReverse(ctx, sid);
+                case 'stretch': return await opStretch(args, ctx, sid);
+                case 'quantize': return await opQuantize(args, ctx, sid);
+                case 'humanize': return await opHumanize(args, ctx, sid);
+                case 'swing': return await opSwing(args, ctx, sid);
+                case 'scale': return await opScale(args, ctx, sid);
+                case 'vary': return await opVary(args, ctx, sid);
+                default:
+                    throw new Error(`Invalid op: ${op}. Must be one of: transpose, reverse, stretch, quantize, humanize, swing, scale, vary`);
             }
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(transposePattern(p, args.semitones));
-            return `Transposed ${args.semitones} semitones`;
-        }
-        case 'reverse': {
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(p + '.rev');
-            return 'Pattern reversed';
-        }
-        case 'stretch': {
-            InputValidator.validateGain(args.factor);
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(p + `.slow(${args.factor})`);
-            return `Stretched by factor of ${args.factor}`;
-        }
-        case 'quantize': {
-            InputValidator.validateStringLength(args.grid, 'grid', 50, false);
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(p + `.struct("${args.grid}")`);
-            return `Quantized to ${args.grid} grid`;
         }
-        case 'humanize': {
-            if (args.amount !== undefined)
-                InputValidator.validateNormalizedValue(args.amount, 'amount');
-            const p = await ctx.getCurrentPatternSafe();
-            const amt = args.amount || 0.01;
-            await ctx.writePatternSafe(p + `.nudge(rand.range(-${amt}, ${amt}))`);
-            return 'Added human timing';
-        }
-        case 'generate_variation': {
-            const p = await ctx.getCurrentPatternSafe();
-            const varied = ctx.generator.generateVariation(p, args.type || 'subtle');
-            await ctx.writePatternSafe(varied);
-            return `Added ${args.type || 'subtle'} variation`;
-        }
-        case 'add_effect': {
-            InputValidator.validateStringLength(args.effect, 'effect', 100, false);
-            if (args.params)
-                InputValidator.validateStringLength(args.params, 'params', 1000, true);
-            const p = await ctx.getCurrentPatternSafe();
-            const withEffect = args.params
-                ? p + `.${args.effect}(${args.params})`
-                : p + `.${args.effect}()`;
-            await ctx.writePatternSafe(withEffect);
-            return `Added ${args.effect} effect`;
-        }
-        case 'remove_effect': {
-            InputValidator.validateStringLength(args.effect, 'effect', 100, false);
-            const p = await ctx.getCurrentPatternSafe();
-            const regex = new RegExp(`\\.${args.effect}\\([^)]*\\)`, 'g');
-            const stripped = p.replace(regex, '');
-            if (stripped === p)
-                return `No ${args.effect} effect found to remove`;
-            await ctx.writePatternSafe(stripped);
-            return `Removed ${args.effect} effect`;
+        // Deprecated aliases — forward to per-op helpers.
+        case 'transpose': return await opTranspose(args, ctx, sid);
+        case 'reverse': return await opReverse(ctx, sid);
+        case 'stretch': return await opStretch(args, ctx, sid);
+        case 'quantize': return await opQuantize(args, ctx, sid);
+        case 'humanize': return await opHumanize(args, ctx, sid);
+        case 'generate_variation': return await opVary(args, ctx, sid);
+        case 'add_swing': return await opSwing(args, ctx, sid);
+        case 'apply_scale': return await opScale(args, ctx, sid);
+        case 'effect': {
+            const a = args?.action;
+            if (a !== 'add' && a !== 'remove') {
+                throw new Error(`Invalid action: ${a}. Must be one of: add, remove`);
+            }
+            return a === 'add'
+                ? await opEffectAdd(args, ctx, sid)
+                : await opEffectRemove(args, ctx, sid);
         }
+        case 'add_effect': return await opEffectAdd(args, ctx, sid);
+        case 'remove_effect': return await opEffectRemove(args, ctx, sid);
         case 'set_tempo': {
             InputValidator.validateBPM(args.bpm);
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(`setcpm(${args.bpm})\n${p}`);
+            const p = await ctx.getCurrentPatternSafe(sid);
+            await ctx.writePatternSafe(`setcpm(${args.bpm})\n${p}`, sid);
             return `Set tempo to ${args.bpm} BPM`;
         }
-        case 'add_swing': {
-            InputValidator.validateNormalizedValue(args.amount, 'amount');
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(p + `.swing(${args.amount})`);
-            return `Added swing: ${args.amount}`;
-        }
-        case 'apply_scale': {
-            InputValidator.validateStringLength(args.scale, 'scale', 50, false);
-            InputValidator.validateRootNote(args.root);
-            const p = await ctx.getCurrentPatternSafe();
-            await ctx.writePatternSafe(p + `.scale("${args.root}:${args.scale}")`);
-            return `Applied ${args.root} ${args.scale} scale`;
+        case 'shape': {
+            const dim = args?.dimension;
+            switch (dim) {
+                case 'mood': return await shiftMood(args, ctx, sid);
+                case 'energy': return await setEnergyLevel(args.level, ctx, sid);
+                case 'refine': return await refinePattern(args.direction, ctx, sid);
+                default:
+                    throw new Error(`Invalid dimension: ${dim}. Must be one of: mood, energy, refine`);
+            }
         }
-        case 'shift_mood':
-            return await shiftMood(args, ctx);
-        case 'set_energy':
-            return await setEnergyLevel(args.level, ctx);
-        case 'refine':
-            return await refinePattern(args.direction, ctx);
+        case 'shift_mood': return await shiftMood(args, ctx, sid);
+        case 'set_energy': return await setEnergyLevel(args.level, ctx, sid);
+        case 'refine': return await refinePattern(args.direction, ctx, sid);
         default:
             throw new Error(`transform module does not handle tool: ${name}`);
     }
 }
-async function shiftMood(args, ctx) {
+async function shiftMood(args, ctx, sid) {
     const mood = args.target_mood?.toLowerCase()?.trim();
     const profile = MOOD_PROFILES[mood];
     if (!profile) {
@@ -287,7 +421,7 @@ async function shiftMood(args, ctx) {
             error: `Unknown mood: ${args.target_mood}. Valid moods: ${Object.keys(MOOD_PROFILES).join(', ')}.`,
         };
     }
-    const pattern = await ctx.getCurrentPatternSafe();
+    const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
         return { success: false, error: 'No pattern to transform. Write a pattern first.' };
     }
@@ -329,17 +463,17 @@ async function shiftMood(args, ctx) {
         result += `.gain(${g.toFixed(2)})`;
         applied.push(`gain ${profile.gainMod > 0 ? '+' : ''}${Math.round(profile.gainMod * 100 * intensity)}%`);
     }
-    await ctx.writePatternSafe(result);
-    if (args.auto_play !== false && ctx.isInitialized()) {
-        await ctx.controller.play();
+    await ctx.writePatternSafe(result, sid);
+    if (args.auto_play !== false && (sid || ctx.isInitialized())) {
+        await ctx.getController(sid).play();
     }
     return { success: true, target_mood: mood, intensity, applied_effects: applied };
 }
-async function setEnergyLevel(level, ctx) {
+async function setEnergyLevel(level, ctx, sid) {
     if (level < 0 || level > 10 || !Number.isInteger(level)) {
         return { success: false, error: 'Energy level must be an integer from 0 to 10.' };
     }
-    const pattern = await ctx.getCurrentPatternSafe();
+    const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
         return { success: false, error: 'No pattern to adjust. Write a pattern first.' };
     }
@@ -348,13 +482,13 @@ async function setEnergyLevel(level, ctx) {
     if (config.densityAdjust)
         result += config.densityAdjust;
     result += `.room(${config.roomAmount})`;
-    await ctx.writePatternSafe(result);
-    if (ctx.isInitialized())
-        await ctx.controller.play();
+    await ctx.writePatternSafe(result, sid);
+    if (sid || ctx.isInitialized())
+        await ctx.getController(sid).play();
     return { success: true, level, description: config.description };
 }
-async function refinePattern(direction, ctx) {
-    const pattern = await ctx.getCurrentPatternSafe();
+async function refinePattern(direction, ctx, sid) {
+    const pattern = await ctx.getCurrentPatternSafe(sid);
     if (!pattern || pattern.trim().length === 0) {
         return { success: false, error: 'No pattern to refine. Write a pattern first.' };
     }
@@ -391,9 +525,9 @@ async function refinePattern(direction, ctx) {
                 error: `Unknown refinement direction: ${direction}. Supported: faster, slower, louder, quieter, brighter, darker, "more reverb", drier.`,
             };
     }
-    await ctx.writePatternSafe(pattern + modification);
-    if (ctx.isInitialized())
-        await ctx.controller.play();
+    await ctx.writePatternSafe(pattern + modification, sid);
+    if (sid || ctx.isInitialized())
+        await ctx.getController(sid).play();
     return { success: true, direction: dir, applied: modification };
 }
 export const transformModule = { tools, toolNames, execute };

package/dist/server/tools/types.js

@@ -6,4 +6,69 @@
  * dispatcher. The server keeps the MCP protocol layer thin and delegates
  * to these modules.
  */
-export {};
+/** Type guard for tools and dispatchers. */
+export function isEnvelope(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'ok' in v &&
+        typeof v.ok === 'boolean');
+}
+/** Construct a success envelope. */
+export function ok(data) {
+    return { ok: true, data };
+}
+/**
+ * Construct a success envelope that represents a valid-empty result —
+ * the call worked but produced nothing (no patterns found, empty
+ * history, etc.). Distinct from `err` so agents can choose between
+ * "report nothing" and "retry/setup".
+ */
+export function empty(data) {
+    return { ok: true, data, empty: true };
+}
+/** Construct an error envelope. */
+export function err(category, message, opts) {
+    return {
+        ok: false,
+        errorCategory: category,
+        // Default retryability follows category: transient retries, others don't.
+        isRetryable: opts?.isRetryable ?? category === 'transient',
+        message,
+        ...(opts?.partialResult !== undefined ? { partialResult: opts.partialResult } : {}),
+    };
+}
+/**
+ * Best-effort error categorization for raw thrown errors. Used by the
+ * dispatcher when a tool throws without wrapping. Tools that know better
+ * should construct `err(category, message)` directly.
+ */
+export function categorizeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes('not initialized') ||
+        lower.includes("run 'init' first") ||
+        lower.includes('run init first') ||
+        lower.includes('not found') ||
+        lower.includes('already exists')) {
+        return 'business';
+    }
+    if (lower.includes('invalid') ||
+        lower.includes('must be') ||
+        lower.includes('required') ||
+        lower.includes('out of range')) {
+        return 'validation';
+    }
+    if (lower.includes('gemini') ||
+        lower.includes('api key') ||
+        lower.includes('unauthorized') ||
+        lower.includes('forbidden')) {
+        return 'permission';
+    }
+    if (lower.includes('timeout') ||
+        lower.includes('econnrefused') ||
+        lower.includes('network') ||
+        lower.includes('fetch failed')) {
+        return 'transient';
+    }
+    return 'internal';
+}

package/dist/services/AudioCaptureService.js

@@ -89,7 +89,7 @@ export class AudioCaptureService {
                                 capture.chunks.push(event.data);
                             }
                         };
-                        capture.recorder.onerror = (event) => {
+                        capture.recorder.onerror = (_event) => {
                             capture.error = 'MediaRecorder error occurred';
                             capture.isCapturing = false;
                         };
@@ -157,10 +157,11 @@ export class AudioCaptureService {
      * Starts audio capture on the page.
      *
      * @param page - Playwright page instance
-     * @param config - Optional capture configuration
+     * @param _config - Optional capture configuration (currently unused;
+     *   recorder config is fixed at injectRecorder time)
      * @throws {Error} When capture fails to start
      */
-    async startCapture(page, config) {
+    async startCapture(page, _config) {
         const result = await page.evaluate(/* istanbul ignore next */ () => {
             const capture = window.strudelAudioCapture;
             if (!capture) {

package/dist/services/GeminiService.js

@@ -549,7 +549,7 @@ Focus on:
         return prompt;
     }
     buildVariationPrompt(pattern, style) {
-        let prompt = `You are an expert in Strudel.cc live coding music.
+        const prompt = `You are an expert in Strudel.cc live coding music.
 
 Given this pattern:
 \`\`\`javascript