@ericdisero/aurora-shared 0.1.0 → 0.2.0

package/dist/operations/index.js

@@ -12,13 +12,15 @@ import { z } from 'zod';
 import { v4 as uuidv4 } from 'uuid';
 import { getDbPath, getProjectsDirectory, getUserDataDir } from '../paths.js';
 import { getMvsepKey, getSunoKey, getKieKey } from '../config.js';
-import { createCover, createGeneration, createSoundsGeneration, createWavConversion, downloadTo, getRemainingCredits, host, pollWavConversion, uploadAudioFile } from '../providers/suno.js';
+import { createAddInstrumental, createAddVocals, createCover, createGeneration, createSoundsGeneration, createWavConversion, downloadTo, getRemainingCredits, host, pollWavConversion, uploadAudioFile } from '../providers/suno.js';
 import { getMvsepUserInfo } from '../providers/mvsep.js';
 import { createProject, deleteProject, getProject, getProjectDirectory, listProjects, renameProject } from '../storage/projects.js';
 import { addFileAsset, deleteAsset, getAsset, insertAsset, listAssets, updateAssetPath } from '../storage/assets.js';
 import { getProjectStems, getStems } from '../storage/stems.js';
 import { advanceJob, listJobs, loadJob, newJobManifest, saveJob } from '../jobs.js';
 import { createSplitJobs, prepareSplit } from '../split.js';
+import { prepareExtract } from '../extract.js';
+import { EXTRACT_BUNDLES, EXTRACT_INDIVIDUAL_STEMS, estimateExtractCost } from '../extract-catalog.js';
 import { probeDurationSeconds, standardizeToWav, convertToMp3, pitchShift } from '../audio/ffmpeg.js';
 import { runRipMidi, runRvcUpscale } from '../sidecars.js';
 import { addLane, exportStackBundle, laneNameFromPath, loadStack, removeLane, updateLane } from '../stack.js';
@@ -313,24 +315,82 @@ const fetchWavOp = {
     }
 };
 // ── Generation (long ops — background-capable) ──────────────────
+// Shared knob schemas — the schema IS the agent's manual (param-table contract:
+// docs/suno-param-surface.md, verified vs live docs 2026-06-10).
+const styleWeightSchema = z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('0..1 — how hard the output follows the style text. ~0.55-0.75 for layering work');
+const weirdnessSchema = z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('0..1 — creative deviation/novelty. Low (0.2-0.4) = predictable takes, high = surprises');
+const audioWeightSchema = z
+    .number()
+    .min(0)
+    .max(1)
+    .optional()
+    .describe('0..1 — input-audio influence on audio-conditioned ops. 0.7-0.85 locks tempo/harmony to the upload');
+const personaIdSchema = z
+    .string()
+    .optional()
+    .describe('Persona id or Suno Voice voiceId — keeps a consistent vocal character across generations (custom mode only)');
+const personaModelSchema = z
+    .enum(['style_persona', 'voice_persona'])
+    .optional()
+    .describe('style_persona (default) | voice_persona (set when personaId is a Suno Voice voiceId, V5/V5_5 only)');
 const generateOp = {
     id: 'aurora_generate',
     description: 'Generate a full music track via Suno (2 variations land as project assets, MP3 + WAV-upgradeable). ' +
-        'Takes 1-3 minutes. PAID (Suno credits) — check aurora_get_credits first. ' +
+        'ULTRA-CUSTOM by default: in custom mode (style + title set) the prompt is the EXACT sung lyrics — ' +
+        'write real lyrics with section metatags like [Verse]/[Chorus]/[Choir]. Takes 1-3 minutes. ' +
+        'PAID (Suno credits) — check aurora_get_credits first. ' +
         BACKGROUND_DESCRIBE,
     input: z.object({
-        prompt: z.string().describe('Lyrics in custom mode (style/title set), else a track description'),
-        style: z.string().optional().describe('Music style (implies custom mode)'),
-        title: z.string().optional().describe('Track title (implies custom mode)'),
+        prompt: z
+            .string()
+            .describe('Custom mode: the EXACT lyrics sung verbatim (≤5000 chars on V4_5+; supports [Verse]/[Chorus]/[Choir]/[Instrumental] metatags; ignored when instrumental). ' +
+            'Non-custom mode: a ≤500-char track description — Suno writes its own lyrics'),
+        customMode: z
+            .boolean()
+            .optional()
+            .describe('true = full control (style + title REQUIRED, prompt = literal lyrics). false = description-only mode. ' +
+            'Default: true when style or title is set. Prefer custom mode — it is the whole point of this surface'),
+        style: z
+            .string()
+            .optional()
+            .describe('Music style text (≤1000 chars on V4_5+). Required in custom mode'),
+        title: z.string().optional().describe('Track title (≤100 chars). Required in custom mode'),
         instrumental: z.boolean().optional().describe('Generate without vocals (default false)'),
-        model: z.string().optional().describe(`Suno model id (default ${DEFAULT_GEN_MODEL})`),
+        model: z
+            .string()
+            .optional()
+            .describe(`V4 | V4_5 | V4_5PLUS | V4_5ALL | V5 | V5_5 (default ${DEFAULT_GEN_MODEL}; dots normalized)`),
         vocalGender: z.enum(['male', 'female']).optional(),
-        negativeTags: z.string().optional().describe('Styles to exclude, ONE comma-separated string'),
+        negativeTags: z
+            .string()
+            .optional()
+            .describe('Styles/instruments to exclude, ONE comma-separated string, e.g. "drums, percussion, orchestra". More reliable than "no X" in the style text'),
+        styleWeight: styleWeightSchema,
+        weirdnessConstraint: weirdnessSchema,
+        audioWeight: audioWeightSchema,
+        personaId: personaIdSchema,
+        personaModel: personaModelSchema,
         projectId: z.string().optional().describe('Target project (auto-created from the title/prompt when omitted)'),
         background: z.boolean().optional().describe('Return a jobId immediately instead of waiting')
     }),
     async run(input) {
-        const customMode = Boolean(input.style || input.title);
+        const customMode = input.customMode ?? Boolean(input.style || input.title);
+        if (customMode && (!input.style || !input.title)) {
+            throw new Error('Custom mode requires BOTH style and title (lyrics go in prompt).');
+        }
+        if (!customMode && input.prompt.length > 500) {
+            throw new Error('Non-custom prompts cap at 500 chars (it is a description, not lyrics). For literal lyrics set customMode true + style + title.');
+        }
         const model = (input.model ?? DEFAULT_GEN_MODEL).replace(/\./g, '_');
         const baseName = input.title?.trim() || input.prompt.slice(0, 60).trim() || 'Generated track';
         const projectId = await resolveProjectOrCreate(input.projectId, baseName);
@@ -342,16 +402,27 @@ const generateOp = {
             customMode,
             model,
             vocalGender: input.vocalGender,
-            negativeTags: input.negativeTags
+            negativeTags: input.negativeTags,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            personaId: input.personaId,
+            personaModel: input.personaModel
         });
         const manifest = newJobManifest('generate', `gen-${uuidv4().slice(0, 8)}`, projectId, baseName, {
             prompt: input.prompt,
+            customMode,
             style: input.style,
             title: input.title,
             instrumental: input.instrumental ?? false,
             model,
             vocalGender: input.vocalGender ?? null,
-            negativeTags: input.negativeTags
+            negativeTags: input.negativeTags,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            personaId: input.personaId,
+            personaModel: input.personaModel
         }, { taskId });
         await saveJob(manifest);
         if (input.background) {
@@ -368,9 +439,10 @@ const soundsOp = {
         BACKGROUND_DESCRIBE,
     input: z.object({
         prompt: z.string().max(500).describe('Sound description, e.g. "huge cinematic braam, dark low brass"'),
-        soundKey: z.string().optional().describe('Pitch lock, e.g. C, Cm, F#, F#m (default Any)'),
+        soundKey: z.string().optional().describe('Pitch lock: C..B major or Cm..Bm minor, sharps as C# (default Any)'),
         tempo: z.number().int().min(1).max(300).optional().describe('BPM lock; omit for auto'),
         loop: z.boolean().optional().describe('Generate as a loopable sound'),
+        grabLyrics: z.boolean().optional().describe('Also capture lyric subtitles when the sound has vocals'),
         projectId: z.string().optional(),
         background: z.boolean().optional()
     }),
@@ -381,7 +453,8 @@ const soundsOp = {
             prompt: input.prompt,
             soundKey: input.soundKey,
             soundTempo: input.tempo,
-            soundLoop: input.loop
+            soundLoop: input.loop,
+            grabLyrics: input.grabLyrics
         });
         const manifest = newJobManifest('sounds', `snd-${uuidv4().slice(0, 8)}`, projectId, baseName, {
             prompt: input.prompt,
@@ -389,7 +462,8 @@ const soundsOp = {
             model: 'V5',
             soundKey: input.soundKey,
             soundTempo: input.tempo,
-            soundLoop: input.loop ?? false
+            soundLoop: input.loop ?? false,
+            grabLyrics: input.grabLyrics ?? false
         }, { taskId });
         await saveJob(manifest);
         if (input.background) {
@@ -399,23 +473,73 @@ const soundsOp = {
         return ok(jobSummary(finished), jobText(finished));
     }
 };
+/** AIFF/FLAC → standardized WAV for upload (undocumented containers), then the
+ *  provider File Upload API. The temp file is disposable the moment the upload
+ *  returns — cleaned on every path (the leak here was a fresh-eyes review
+ *  finding). Shared by cover / add-vocals / add-instrumental. */
+async function uploadSourceAudio(sourcePath) {
+    let tempUpload = null;
+    try {
+        let uploadSource = sourcePath;
+        const ext = extname(sourcePath).toLowerCase();
+        if (ext !== '.wav' && ext !== '.mp3') {
+            const { tmpdir } = await import('node:os');
+            tempUpload = join(tmpdir(), `aurora-upload-${Date.now()}.wav`);
+            await standardizeToWav(sourcePath, tempUpload);
+            uploadSource = tempUpload;
+        }
+        return await uploadAudioFile(uploadSource);
+    }
+    finally {
+        if (tempUpload) {
+            const { rm } = await import('node:fs/promises');
+            await rm(tempUpload, { force: true }).catch(() => { });
+        }
+    }
+}
+/** Resolve a layering-op source to a local file path (asset or external). */
+function resolveSourcePath(input) {
+    const sourceAsset = input.sourceAssetId ? getAsset(input.sourceAssetId) : null;
+    if (input.sourceAssetId && !sourceAsset)
+        throw new Error(`Asset not found: ${input.sourceAssetId}`);
+    const sourcePath = sourceAsset?.path ?? input.sourcePath;
+    if (!sourcePath || !existsSync(sourcePath)) {
+        throw new Error('Source not found — pass sourceAssetId (a project asset) or sourcePath (a file).');
+    }
+    return { sourcePath, sourceAsset };
+}
 const coverOp = {
     id: 'aurora_cover',
     description: 'Cover a track (Suno upload-and-cover style transform): same musical content, new style. Source is a ' +
-        'project asset or an external file (max 8 minutes). 2 variations land as cover assets linked to the ' +
-        'source. PAID (~12 Suno credits + ~0.4/WAV) — check aurora_get_credits first. ' +
+        'project asset or an external file (max 8 minutes). COVERS RE-RENDER EVERYTHING in the reference — to ' +
+        'generate one complementary layer (e.g. a choir part), feed a stripped stem or bare melody render of ONLY ' +
+        'the line to perform, NOT the full mix (full mix in = a choir performing your drums). Layering settings ' +
+        'that lock structure while swapping timbre: audioWeight 0.7-0.85, styleWeight 0.55-0.75, ' +
+        'weirdnessConstraint 0.2-0.4. 2 variations land as cover assets linked to the source. ' +
+        'PAID (~12 Suno credits + ~0.4/WAV) — check aurora_get_credits first. ' +
         BACKGROUND_DESCRIBE,
     input: z.object({
         sourceAssetId: z.string().optional().describe('Project asset to transform'),
         sourcePath: z.string().optional().describe('OR an external audio file path'),
-        prompt: z.string().describe('What the cover should sound like'),
-        style: z.string().optional().describe('Target style (custom mode needs BOTH style and title)'),
+        prompt: z.string().describe('Custom mode: exact lyrics. Non-custom: what the cover should sound like (≤500 chars)'),
+        customMode: z
+            .boolean()
+            .optional()
+            .describe('true = style + title required, prompt = literal lyrics. Default: true when style or title is set'),
+        style: z.string().optional().describe('Target style (custom mode needs BOTH style and title; ≤1000 chars on V4_5+)'),
         title: z.string().optional(),
         instrumental: z.boolean().optional(),
-        model: z.string().optional().describe(`Suno model id (default ${DEFAULT_GEN_MODEL})`),
+        model: z
+            .string()
+            .optional()
+            .describe(`V4 | V4_5 | V4_5PLUS | V4_5ALL | V5 | V5_5 (default ${DEFAULT_GEN_MODEL}; V4_5ALL caps input at 1 min)`),
         vocalGender: z.enum(['male', 'female']).optional(),
-        negativeTags: z.string().optional().describe('Styles to exclude, ONE comma-separated string'),
-        audioWeight: z.number().min(0).max(1).optional().describe('0..1 — 0 = new style dominates, 1 = stay close to the source'),
+        negativeTags: z.string().optional().describe('Styles/instruments to exclude, ONE comma-separated string'),
+        audioWeight: z.number().min(0).max(1).optional().describe('0..1 — 0 = new style dominates, 1 = stay close to the source. 0.7-0.85 = structure locked, timbre swapped'),
+        styleWeight: styleWeightSchema,
+        weirdnessConstraint: weirdnessSchema,
+        personaId: personaIdSchema,
+        personaModel: personaModelSchema,
         projectId: z.string().optional(),
         background: z.boolean().optional(),
         fetchWav: z
@@ -431,7 +555,7 @@ const coverOp = {
         if (!sourcePath || !existsSync(sourcePath)) {
             throw new Error('Cover source not found — pass sourceAssetId (a project asset) or sourcePath (a file).');
         }
-        const customMode = Boolean(input.style || input.title);
+        const customMode = input.customMode ?? Boolean(input.style || input.title);
         if (customMode && (!input.style || !input.title)) {
             throw new Error('Custom mode needs BOTH a style and a title (you set only one).');
         }
@@ -448,28 +572,7 @@ const coverOp = {
                     throw new Error(`Project not found: ${input.projectId}`);
                 })())
             : (sourceAsset?.projectId ?? (await createProject(baseName)).id);
-        // AIFF/FLAC → standardized WAV for upload (undocumented containers). The
-        // temp file is disposable the moment the upload returns — clean it on every
-        // path (the leak here was a fresh-eyes review finding).
-        let uploadUrl;
-        let tempUpload = null;
-        try {
-            let uploadSource = sourcePath;
-            const ext = extname(sourcePath).toLowerCase();
-            if (ext !== '.wav' && ext !== '.mp3') {
-                const { tmpdir } = await import('node:os');
-                tempUpload = join(tmpdir(), `aurora-cover-upload-${Date.now()}.wav`);
-                await standardizeToWav(sourcePath, tempUpload);
-                uploadSource = tempUpload;
-            }
-            uploadUrl = await uploadAudioFile(uploadSource);
-        }
-        finally {
-            if (tempUpload) {
-                const { rm } = await import('node:fs/promises');
-                await rm(tempUpload, { force: true }).catch(() => { });
-            }
-        }
+        const uploadUrl = await uploadSourceAudio(sourcePath);
         const taskId = await createCover({
             uploadUrl,
             prompt: input.prompt,
@@ -480,17 +583,26 @@ const coverOp = {
             model,
             vocalGender: input.vocalGender,
             negativeTags: input.negativeTags,
-            audioWeight: input.audioWeight
+            audioWeight: input.audioWeight,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            personaId: input.personaId,
+            personaModel: input.personaModel
         });
         const manifest = newJobManifest('cover', `cov-${uuidv4().slice(0, 8)}`, projectId, baseName, {
             prompt: input.prompt,
+            customMode,
             style: input.style,
             title: input.title,
             instrumental: input.instrumental ?? false,
             model,
             vocalGender: input.vocalGender ?? null,
             negativeTags: input.negativeTags,
-            audioWeight: input.audioWeight
+            audioWeight: input.audioWeight,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            personaId: input.personaId,
+            personaModel: input.personaModel
         }, { taskId, sourceAssetId: sourceAsset?.id ?? null });
         await saveJob(manifest);
         if (input.background) {
@@ -516,6 +628,178 @@ const coverOp = {
         return ok(summary, `${jobText(finished)}${wavNotes.length > 0 ? ` WAV stage: ${wavNotes.join('; ')}` : ''}`);
     }
 };
+const addVocalsOp = {
+    id: 'aurora_add_vocals',
+    description: 'Layer AI vocals ON TOP of an instrumental (Suno add-vocals): upload a track, get vocals performed ' +
+        'against its tempo/key/changes. THE op for adding a choir or vocal part to an existing production: ' +
+        'feed a SIMPLIFIED bounce (harmonic skeleton + the melody to relate to — strip drums/dense ornament), ' +
+        'audioWeight 0.7-0.85, choir-steering style + negativeTags, then aurora_split the result and keep ONLY ' +
+        'the vocals stem to lay over the real production. Output is a full mix; the vocal stem is the deliverable. ' +
+        'PAID (Suno credits) — check aurora_get_credits first. ' +
+        BACKGROUND_DESCRIBE,
+    input: z.object({
+        sourceAssetId: z.string().optional().describe('Project asset to sing over'),
+        sourcePath: z.string().optional().describe('OR an external audio file path'),
+        prompt: z
+            .string()
+            .describe('Vocal content + direction — lyrics or syllables (e.g. Latin chant for choir) with [Choir]/[Harmony] metatags'),
+        style: z
+            .string()
+            .describe('Vocal approach, e.g. "epic film choir, massed choral harmonies, latin chant" (this is what steers choir vs lead singer)'),
+        title: z.string().max(100).describe('Track title (≤100 chars)'),
+        negativeTags: z
+            .string()
+            .describe('Vocal styles to exclude, ONE comma-separated string, e.g. "lead singer, pop vocal, rap, spoken word, autotune"'),
+        vocalGender: z.enum(['male', 'female']).optional(),
+        styleWeight: styleWeightSchema,
+        weirdnessConstraint: weirdnessSchema,
+        audioWeight: audioWeightSchema,
+        model: z.string().optional().describe('V4_5PLUS (default) | V5 | V5_5 — this endpoint supports only these'),
+        projectId: z.string().optional(),
+        background: z.boolean().optional(),
+        fetchWav: z.boolean().optional().describe('Blocking mode only: also fetch the provider WAV per variation (default true)')
+    }),
+    async run(input) {
+        const { sourcePath, sourceAsset } = resolveSourcePath(input);
+        const baseName = input.title.trim() || `${basename(sourcePath, extname(sourcePath))} vocals`;
+        const projectId = input.projectId
+            ? (getProject(input.projectId)?.id ??
+                (() => {
+                    throw new Error(`Project not found: ${input.projectId}`);
+                })())
+            : (sourceAsset?.projectId ?? (await createProject(baseName)).id);
+        const uploadUrl = await uploadSourceAudio(sourcePath);
+        const taskId = await createAddVocals({
+            uploadUrl,
+            prompt: input.prompt,
+            style: input.style,
+            title: input.title,
+            negativeTags: input.negativeTags,
+            vocalGender: input.vocalGender,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            model: (input.model ?? 'V4_5PLUS').replace(/\./g, '_')
+        });
+        const manifest = newJobManifest('add_vocals', `avo-${uuidv4().slice(0, 8)}`, projectId, baseName, {
+            op: 'add_vocals',
+            prompt: input.prompt,
+            style: input.style,
+            title: input.title,
+            negativeTags: input.negativeTags,
+            vocalGender: input.vocalGender ?? null,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            model: (input.model ?? 'V4_5PLUS').replace(/\./g, '_'),
+            instrumental: false
+        }, { taskId, sourceAssetId: sourceAsset?.id ?? null });
+        await saveJob(manifest);
+        if (input.background) {
+            return ok(jobSummary(manifest), jobText(manifest));
+        }
+        const finished = await awaitJob(manifest);
+        const wavNotes = [];
+        if (finished.status === 'done' && (input.fetchWav ?? true)) {
+            for (const assetId of finished.assetIds) {
+                try {
+                    await fetchWavOp.run({ assetId });
+                    wavNotes.push(`${assetId}: WAV fetched`);
+                }
+                catch (err) {
+                    wavNotes.push(`${assetId}: WAV failed (${err instanceof Error ? err.message : err}) — MP3 kept; retry with aurora_fetch_wav`);
+                }
+            }
+        }
+        const summary = jobSummary(finished);
+        if (wavNotes.length > 0)
+            summary.wavStage = wavNotes;
+        return ok(summary, `${jobText(finished)}${wavNotes.length > 0 ? ` WAV stage: ${wavNotes.join('; ')}` : ''}` +
+            (finished.status === 'done'
+                ? ' Next for layering: aurora_split the result and keep the vocals stem.'
+                : ''));
+    }
+};
+const addInstrumentalOp = {
+    id: 'aurora_add_instrumental',
+    description: 'Generate backing instrumentation complementary to an uploaded audio (Suno add-instrumental — the ' +
+        'inverse of aurora_add_vocals; input is usually a vocal or a melodic stem). Output is a full mix ' +
+        'conditioned on the upload; split it to extract the new layers. PAID (Suno credits) — check ' +
+        'aurora_get_credits first. ' +
+        BACKGROUND_DESCRIBE,
+    input: z.object({
+        sourceAssetId: z.string().optional().describe('Project asset to build instrumentation around'),
+        sourcePath: z.string().optional().describe('OR an external audio file path'),
+        title: z.string().max(100).describe('Track title (≤100 chars)'),
+        tags: z
+            .string()
+            .describe('Desired instrumental style/mood/instruments (this endpoint names the field tags, comma-separated)'),
+        negativeTags: z.string().describe('Styles/instruments to exclude, ONE comma-separated string'),
+        vocalGender: z.enum(['male', 'female']).optional(),
+        styleWeight: styleWeightSchema,
+        weirdnessConstraint: weirdnessSchema,
+        audioWeight: audioWeightSchema,
+        model: z.string().optional().describe('V4_5PLUS (default) | V5 | V5_5 — this endpoint supports only these'),
+        projectId: z.string().optional(),
+        background: z.boolean().optional(),
+        fetchWav: z.boolean().optional().describe('Blocking mode only: also fetch the provider WAV per variation (default true)')
+    }),
+    async run(input) {
+        const { sourcePath, sourceAsset } = resolveSourcePath(input);
+        const baseName = input.title.trim() || `${basename(sourcePath, extname(sourcePath))} instrumental`;
+        const projectId = input.projectId
+            ? (getProject(input.projectId)?.id ??
+                (() => {
+                    throw new Error(`Project not found: ${input.projectId}`);
+                })())
+            : (sourceAsset?.projectId ?? (await createProject(baseName)).id);
+        const uploadUrl = await uploadSourceAudio(sourcePath);
+        const taskId = await createAddInstrumental({
+            uploadUrl,
+            title: input.title,
+            tags: input.tags,
+            negativeTags: input.negativeTags,
+            vocalGender: input.vocalGender,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            model: (input.model ?? 'V4_5PLUS').replace(/\./g, '_')
+        });
+        const manifest = newJobManifest('add_instrumental', `ain-${uuidv4().slice(0, 8)}`, projectId, baseName, {
+            op: 'add_instrumental',
+            title: input.title,
+            tags: input.tags,
+            negativeTags: input.negativeTags,
+            vocalGender: input.vocalGender ?? null,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            audioWeight: input.audioWeight,
+            model: (input.model ?? 'V4_5PLUS').replace(/\./g, '_'),
+            instrumental: true
+        }, { taskId, sourceAssetId: sourceAsset?.id ?? null });
+        await saveJob(manifest);
+        if (input.background) {
+            return ok(jobSummary(manifest), jobText(manifest));
+        }
+        const finished = await awaitJob(manifest);
+        const wavNotes = [];
+        if (finished.status === 'done' && (input.fetchWav ?? true)) {
+            for (const assetId of finished.assetIds) {
+                try {
+                    await fetchWavOp.run({ assetId });
+                    wavNotes.push(`${assetId}: WAV fetched`);
+                }
+                catch (err) {
+                    wavNotes.push(`${assetId}: WAV failed (${err instanceof Error ? err.message : err}) — MP3 kept; retry with aurora_fetch_wav`);
+                }
+            }
+        }
+        const summary = jobSummary(finished);
+        if (wavNotes.length > 0)
+            summary.wavStage = wavNotes;
+        return ok(summary, `${jobText(finished)}${wavNotes.length > 0 ? ` WAV stage: ${wavNotes.join('; ')}` : ''}`);
+    }
+};
 const splitOp = {
     id: 'aurora_split',
     description: 'Split ANY project asset into 7 stems (vocals, kick, snare, toms, hats, bass, everything-else) via ' +
@@ -545,6 +829,96 @@ const splitOp = {
         return ok(jobSummary(finished), jobText(finished));
     }
 };
+const VOCAL_MODE_DESCRIBE = "lead_back = lead + backing vocals; male_female = male + female voices. Vocal stems come from the mode, never from the stems array";
+const extractOp = {
+    id: 'aurora_extract',
+    description: 'The Sample Extractor: pull SPECIFIC instruments out of ANY asset via the per-instrument MVSEP ' +
+        'catalog (~35 instruments + bundles). Everything Else is ALWAYS included free (local phase-cancel), ' +
+        'so the parts sum back to the original. VARIABLE PAID COST: one MVSEP call per individual stem, but ' +
+        'bundles count ONCE however many members you pick (drum kit = 6 stems for 1 call; lead+rhythm guitar ' +
+        '= 1 call; vocal modes = 1 call; dereverb = 1 call). Call with estimateOnly=true FIRST to see the ' +
+        'exact call plan before spending. 12-minute input cap. Results land in <project>/extracts/ + the ' +
+        'extraction_stems table; detected musical key rides every row. Takes minutes per call (sequential). ' +
+        BACKGROUND_DESCRIBE,
+    input: z.object({
+        assetId: z.string().describe('The asset to extract from (any kind)'),
+        stems: z
+            .array(z.string())
+            .optional()
+            .describe('Non-vocal catalog stem ids. Bundles: drum_kick/drum_snare/drum_toms/drum_hihats/' +
+            'drum_cymbals_crash/drum_cymbals_ride (one call), guitar_lead/guitar_rhythm (one call). ' +
+            'Individuals: piano, digital_piano, organ, accordion, harpsichord, saxophone, flute, trumpet, ' +
+            'trombone, french_horn, tuba, clarinet, oboe, bassoon, harmonica, guitar_acoustic, ' +
+            'guitar_electric, mandolin, banjo, ukulele, harp, sitar, dobro, violin, viola, cello, ' +
+            'double_bass, bells, congas, tambourine, marimba, glockenspiel, timpani, triangle, ' +
+            'wind_chimes, bass, synth'),
+        vocalMode: z.enum(['lead_back', 'male_female']).optional().describe(VOCAL_MODE_DESCRIBE),
+        includeReverb: z
+            .boolean()
+            .optional()
+            .describe('Dereverb the vocal first: adds a reverb-tail stem; with a vocalMode the bundle runs on the DRY ' +
+            'vocal; alone it delivers dry vocal + reverb tail'),
+        estimateOnly: z
+            .boolean()
+            .optional()
+            .describe('Return the call plan + cost estimate WITHOUT spending anything'),
+        background: z.boolean().optional().describe('Strongly recommended — sequential calls take minutes each')
+    }),
+    async run(input) {
+        const selection = {
+            stems: input.stems ?? [],
+            vocalSeparationType: input.vocalMode ?? null,
+            includeReverb: input.includeReverb ?? false
+        };
+        // Validate selection ids early (clear error beats a silent no-op call plan).
+        const known = new Set([
+            ...Object.keys(EXTRACT_INDIVIDUAL_STEMS),
+            ...EXTRACT_BUNDLES.drumsep.stems,
+            ...EXTRACT_BUNDLES.lead_rhythm_guitar.stems
+        ]);
+        const unknown = selection.stems.filter((s) => !known.has(s));
+        if (unknown.length > 0) {
+            throw new Error(`Unknown stem id(s): ${unknown.join(', ')}. See the stems param description for the catalog.`);
+        }
+        const asset = getAsset(input.assetId);
+        if (!asset)
+            throw new Error(`Asset not found: ${input.assetId}`);
+        const duration = await probeDurationSeconds(asset.path);
+        const estimate = estimateExtractCost(selection, duration ?? 60);
+        if (input.estimateOnly) {
+            return ok({
+                estimate,
+                durationSeconds: duration,
+                note: 'Nothing spent. Re-run without estimateOnly to fire the plan.'
+            }, `Plan: ${estimate.totalCalls} MVSEP call(s) on a ~${estimate.minuteMultiplier}-minute track. ` +
+                `Bundles: ${estimate.breakdown.bundles.map((b) => b.bundleId).join(', ') || 'none'}. ` +
+                `Individual: ${estimate.breakdown.individualStems.join(', ') || 'none'}. EE included free. Nothing spent.`);
+        }
+        const { asset: prepared, state } = await prepareExtract(input.assetId, selection);
+        const manifest = newJobManifest('extract', `ext-${uuidv4().slice(0, 8)}`, prepared.projectId, prepared.name, {
+            assetId: input.assetId,
+            stems: selection.stems,
+            vocalMode: selection.vocalSeparationType,
+            includeReverb: selection.includeReverb,
+            plannedCalls: estimate.totalCalls
+        }, { assetId: input.assetId, extract: state });
+        manifest.stage = `planned ${state.calls.length} MVSEP call(s)`;
+        await saveJob(manifest);
+        if (input.background) {
+            const summary = jobSummary(manifest);
+            summary.estimate = estimate;
+            return ok(summary, `${jobText(manifest)} Plan: ${estimate.totalCalls} MVSEP call(s).`);
+        }
+        const finished = await awaitJob(manifest);
+        const summary = jobSummary(finished);
+        summary.estimate = estimate;
+        if (finished.status === 'done' && finished.provider.extract?.detectedKey) {
+            ;
+            summary.detectedKey = finished.provider.extract.detectedKey;
+        }
+        return ok(summary, jobText(finished));
+    }
+};
 const getJobStatusOp = {
     id: 'aurora_get_job_status',
     description: 'Poll a background job (generate / sounds / cover / split). Advances the job: downloads and ' +
@@ -831,7 +1205,10 @@ export const ALL_OPERATIONS = [
     generateOp,
     soundsOp,
     coverOp,
+    addVocalsOp,
+    addInstrumentalOp,
     splitOp,
+    extractOp,
     getJobStatusOp,
     listJobsOp,
     pitchShiftOp,