@slatesvideo/shared 0.5.4 → 0.5.6

package/dist/operations/index.js

@@ -120,8 +120,11 @@ export const listAvailableModels = {
         const table = models.map((m) => `${m.model} ${creditCost(m)}`).join('\n');
         return {
             text: `${models.length} COST keys (credits per generation)${input.filter ? ` matching "${input.filter}"` : ''}. ` +
-                `NOTE: these are billing keys for cost lookup ONLY — the \`model\` param on slates_generate_video takes a BASE id ` +
-                `(kling-v3.0-std | kling-v3.0-pro | kling-v3.0-omni | seedance-2 | veo-3.1-fast | veo-3.1-standard) with duration/videoResolution as separate params:\n` +
+                `NOTE: these are billing keys for cost lookup ONLY — the \`model\` param on the generate ops takes a BASE id. ` +
+                // Derived from the SSOT arrays, not restated: a hand-written list here
+                // drifts the moment a model lands (it already omitted omni-flash).
+                `slates_generate_video: ${VIDEO_MODELS.join(' | ')} (duration/videoResolution as separate params). ` +
+                `slates_generate_audio: ${AUDIO_MODELS.join(' | ')} (durationSeconds as a separate param):\n` +
                 table,
             data: { count: models.length },
         };
@@ -133,7 +136,8 @@ export const estimateGenerationCost = {
     input: z.object({
         model: z.string().describe('Base model id as passed to the generate op (e.g. "seedance-2", "kling-v3.0-std", "nano-banana-2") or an exact registry cost key ("nano-banana-2-2k", "seedance-2-1080p-8s")'),
         quantity: z.number().int().min(1).max(10).optional().describe('Number of generations (default 1)'),
-        duration: z.number().int().min(3).max(15).optional().describe('Video only — seconds. Cost scales linearly; required with a video base id.'),
+        duration: z.number().int().min(1).max(360).optional().describe('Seconds. Video 3-15 (cost scales linearly; required with a video base id). Audio: seed-audio 3-120 (⚠️ the requested duration IS the bill), eleven-sfx 1-22. Ignored by eleven-v3 (per-character) and suno (flat).'),
+        characters: z.number().int().min(1).max(5000).optional().describe('eleven-v3 only — script length in characters, billed in 100-char buckets rounded up.'),
         videoResolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe('Video only. Seedance defaults to 1080p.'),
         resolution: z.enum(['1k', '2k', '3k', '4k']).optional().describe('Image only (default 2k; 3k = gpt-image-2 1440p class).'),
         quality: z.enum(['medium', 'high']).optional().describe('gpt-image-2 only — quality tier (default medium).'),
@@ -152,6 +156,52 @@ export const estimateGenerationCost = {
             if (img)
                 key = imageCostKey(img, input.resolution ?? (img === 'nano-banana-2-lite' ? '1k' : '2k'), input.quality ?? 'medium');
         }
+        // 2a) audio base id → seconds (seed-audio, eleven-sfx), characters
+        //     (eleven-v3), or flat (suno). Runs BEFORE the video resolver: it is
+        //     forgiving by design and "seed-audio" would otherwise be mistaken for
+        //     a seedance spelling.
+        if (!key && AUDIO_MODELS.includes(input.model)) {
+            const m = input.model;
+            if ((m === 'seed-audio' || m === 'eleven-sfx') && !input.duration) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['duration'],
+                    message: m === 'seed-audio'
+                        ? 'Seed Audio cost scales with the REQUESTED duration — and that duration is what the user is billed regardless of what comes back (it has no duration parameter; the number is written into the prompt). Pass duration in seconds (3-120).'
+                        : 'Sound Effects bills per second — pass duration in seconds (1-22).',
+                });
+            }
+            if (m === 'eleven-v3' && !input.characters) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['characters'],
+                    message: 'Eleven v3 bills per 100 characters of script, rounded up — pass characters (the length of the text you intend to speak).',
+                });
+            }
+            // REFUSE an out-of-range duration rather than quoting the clamped price.
+            // audioCostKey clamps (it has to — it mirrors the desktop, which clamps),
+            // so without this an agent asking for 2s of Seed Audio would be handed a
+            // real 3s price and no hint that 2s is not a thing it can order. The
+            // generate op gates the same way; the two must agree or the quote is a
+            // promise the generation refuses to keep.
+            const audioBounds = {
+                'seed-audio': { min: SEED_AUDIO_MIN_SECONDS, max: SEED_AUDIO_MAX_SECONDS },
+                'eleven-sfx': { min: ELEVEN_SFX_MIN_SECONDS, max: ELEVEN_SFX_MAX_SECONDS },
+                suno: { min: SUNO_MIN_SECONDS, max: SUNO_MAX_SECONDS },
+            };
+            const bounds = audioBounds[m];
+            if (bounds && input.duration != null && (input.duration < bounds.min || input.duration > bounds.max)) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['duration'],
+                    message: `${m} accepts ${bounds.min}-${bounds.max} seconds — ${input.duration}s is outside that range and would be refused at generation time. ` +
+                        (m === 'suno'
+                            ? 'Suno duration is FREE and flat-priced, so any value in range costs the same.'
+                            : 'Re-ask with a duration in range.'),
+                });
+            }
+            key = audioCostKey({ model: m, durationSeconds: input.duration, characters: input.characters });
+        }
         // 2b) Kling O3 edit base id + duration (ceiled source-clip length)
         if (!key && (input.model === 'kling-v3.0-omni-edit' || input.model === 'kling-v3.0-omni-pro-edit')) {
             if (!input.duration) {
@@ -190,7 +240,7 @@ export const estimateGenerationCost = {
         }
         const perCredits = key != null ? byKey.get(key) : undefined;
         if (key == null || perCredits == null) {
-            throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | nano-banana-2 | flux-2-max | seedream-5-lite) plus duration/resolution params, or use slates_list_available_models with a filter.`);
+            throw new Error(`Unknown model: ${input.model}. Pass a base id (${VIDEO_MODELS.join(' | ')} | ${AUDIO_MODELS.join(' | ')} | nano-banana-2 | flux-2-max | seedream-5-lite) plus duration/characters/resolution params, or use slates_list_available_models with a filter.`);
         }
         const qty = input.quantity ?? 1;
         const totalCredits = perCredits * qty;
@@ -439,16 +489,16 @@ export const getAssetVideoFrames = {
 };
 export const uploadReferenceImage = {
     id: 'slates_upload_reference_image',
-    description: 'Add a reference image OR video clip to a Slates project. Pass either filePath (absolute path to a local file) or dataUrl (base64 data: URL) — exactly one. Set type:"video" on a filePath import to bring in a clip (the user\'s own footage to edit/relocate/trim); imported videos are probed on ingest, so duration + dimensions are available immediately. Default type is "image". dataUrl is image-only.',
+    description: 'Add a reference image, video clip, or audio file to a Slates project from disk. Pass either filePath (absolute path to a local file) or dataUrl (base64 data: URL) — exactly one. Set type:"video" to bring in a clip (the user\'s own footage to edit/relocate/trim) or type:"audio" for music/VO/SFX they already have; both are probed on ingest, so duration (and for video, dimensions) are available immediately, and audio gets its waveform. Default type is "image". dataUrl is image-only.',
     input: z
         .object({
         projectId: z.string().uuid(),
         filePath: z.string().optional(),
         dataUrl: z.string().optional(),
         type: z
-            .enum(['image', 'video'])
+            .enum(['image', 'video', 'audio'])
             .optional()
-            .describe('Asset kind for a filePath import — "image" (default) or "video". A dataUrl is always an image.'),
+            .describe('Asset kind for a filePath import — "image" (default), "video", or "audio". A dataUrl is always an image.'),
     })
         .refine((d) => !!d.filePath !== !!d.dataUrl, {
         message: 'Pass exactly one of filePath or dataUrl',
@@ -463,8 +513,8 @@ export const uploadReferenceImage = {
             });
             return ok(r);
         }
-        if (input.type === 'video') {
-            throw new Error('dataUrl uploads are image-only — pass a filePath to import a video clip.');
+        if (input.type === 'video' || input.type === 'audio') {
+            throw new Error(`dataUrl uploads are image-only — pass a filePath to import ${input.type === 'audio' ? 'an audio file' : 'a video clip'}.`);
         }
         const r = await desktop.post('/agent/assets/upload-base64', {
             projectId: input.projectId,
@@ -506,6 +556,82 @@ export const moveAssetsToFolder = {
         return ok(await ctx.desktop().post('/agent/folders/move-assets', input));
     },
 };
+export const moveAssetsToProject = {
+    id: 'slates_move_assets_to_project',
+    description: 'Move assets (images, videos, audio) out of one project into another. The media files move on disk into the destination project folder — this is a real re-home, not a copy. Moved assets leave whatever gallery folder they were in and are issued fresh badge codes in the destination.',
+    input: z.object({
+        sourceProjectId: z.string().uuid(),
+        // Badge codes ("IMG-A8") resolve against sourceProjectId at call time.
+        assetIds: z.array(z.string().min(1)).min(1),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        if (input.sourceProjectId === input.targetProjectId) {
+            throw new Error('sourceProjectId and targetProjectId are the same — nothing to move.');
+        }
+        const resolved = await resolveAssetRefs(ctx, input.sourceProjectId, input.assetIds);
+        const assetIds = input.assetIds.map((ref) => resolved.get(ref)?.id ?? ref);
+        const result = await ctx.desktop().post('/agent/assets/move-to-project', {
+            assetIds,
+            targetProjectId: input.targetProjectId,
+            // Sent so the route can ENFORCE it. resolveAssetRefs only validates
+            // badge codes against the source project — a raw UUID passes straight
+            // through, so without this a caller could move an asset out of a
+            // project it never named.
+            sourceProjectId: input.sourceProjectId,
+        });
+        // Timeline clips key media by PATH, so the move repointed edits in OTHER
+        // projects at files that now live inside the destination — and deleting the
+        // destination deletes those files. Say it in the TEXT, not just the data:
+        // an agent summarising this result must be able to pass the warning on.
+        const refs = result.externalClipRefs ?? [];
+        if (refs.length > 0) {
+            const clips = refs.reduce((n, r) => n + r.clipCount, 0);
+            const where = refs.map((r) => `"${r.projectName}"`).join(', ');
+            return ok(result, `${JSON.stringify(result)}\n\n⚠️ ${clips} timeline clip(s) in ${where} now reference the moved ` +
+                `file(s) inside the destination project. Deleting the destination project would break those ` +
+                `edits. Tell the user — this is the one cross-project reference Slates allows.`);
+        }
+        return ok(result);
+    },
+};
+export const copyAssetsToProject = {
+    id: 'slates_copy_assets_to_project',
+    description: 'Copy assets (images, videos, audio) from one project into another. The originals stay exactly where they are — new files, new rows, new badge codes in the destination. Use this instead of slates_move_assets_to_project when the asset is already in use where it lives: an image that is a character/environment/style identity or sits in a storyboard frame CANNOT be moved out (that would leave the other project pointing at a file it no longer owns), but it can always be copied. Lineage is not copied; the copy starts clean.',
+    input: z.object({
+        sourceProjectId: z.string().uuid(),
+        // Badge codes ("IMG-A8") resolve against sourceProjectId at call time.
+        assetIds: z.array(z.string().min(1)).min(1),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        if (input.sourceProjectId === input.targetProjectId) {
+            throw new Error('sourceProjectId and targetProjectId are the same — nothing to copy.');
+        }
+        const resolved = await resolveAssetRefs(ctx, input.sourceProjectId, input.assetIds);
+        const assetIds = input.assetIds.map((ref) => resolved.get(ref)?.id ?? ref);
+        return ok(await ctx.desktop().post('/agent/assets/copy-to-project', {
+            assetIds,
+            targetProjectId: input.targetProjectId,
+            // Enforced route-side for the same reason as the move op: resolveAssetRefs
+            // only validates badge codes, so a raw UUID would otherwise let a caller
+            // copy out of a project it never named.
+            sourceProjectId: input.sourceProjectId,
+        }));
+    },
+};
+export const moveEntityToProject = {
+    id: 'slates_move_entity_to_project',
+    description: "Move a character, environment, or style into another project, taking every image it references with it. This is the fix when slates_move_assets_to_project refuses an asset because an entity still uses it: the identity image can't leave on its own, but the whole entity can. Refuses (rather than cascading) if one of its images is ALSO used by something else — copy the images instead in that case. Storyboard frames are not movable this way; moving a frame's image out would empty the shot.",
+    input: z.object({
+        kind: z.enum(['character', 'environment', 'style']),
+        entityId: z.string().uuid(),
+        targetProjectId: z.string().uuid(),
+    }),
+    async run(input, ctx) {
+        return ok(await ctx.desktop().post('/agent/entities/move-to-project', input));
+    },
+};
 // ── Characters ──────────────────────────────────────────────────
 export const listCharacters = {
     id: 'slates_list_characters',
@@ -528,23 +654,9 @@ export const createCharacter = {
         return ok(await ctx.desktop().post('/agent/characters', input));
     },
 };
-export const setCharacterTurnaround = {
-    id: 'slates_set_character_turnaround_asset',
-    description: 'Bind an image asset to the character\'s turnaround slot (or clear with assetId=null). The user sees the character card update live.',
-    input: z.object({
-        characterId: z.string().uuid(),
-        assetId: z.string().uuid().nullable(),
-    }),
-    async run(input, ctx) {
-        return ok(await ctx.desktop().post('/agent/characters/update', {
-            id: input.characterId,
-            data: { turnaroundAssetId: input.assetId },
-        }));
-    },
-};
-export const setCharacterExpression = {
-    id: 'slates_set_character_expression_asset',
-    description: 'Bind an image asset to the character\'s expression-sheet slot (or clear with assetId=null).',
+export const setCharacterIdentity = {
+    id: 'slates_set_character_identity_asset',
+    description: 'Bind one image asset as the character identity (or clear with assetId=null). The user sees the character card update live.',
     input: z.object({
         characterId: z.string().uuid(),
         assetId: z.string().uuid().nullable(),
@@ -552,7 +664,7 @@ export const setCharacterExpression = {
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/characters/update', {
             id: input.characterId,
-            data: { expressionAssetId: input.assetId },
+            data: { identityAssetId: input.assetId, expressionAssetId: null },
         }));
     },
 };
@@ -578,17 +690,13 @@ export const createEnvironment = {
         return ok(await ctx.desktop().post('/agent/environments', input));
     },
 };
-export const generateCharacterSheets = {
-    id: 'slates_generate_character_sheets',
-    description: "Generate a character's identity reference sheet from a base portrait asset and bind it to the character. THE real character-building workflow — call right after slates_create_character. ONE sheet per character by default: a dominant three-quarter chest-up portrait (the sole face authority) plus full-body front and back panels on a deep neutral-grey plate — it binds to the turnaround slot and the expression slot stays null. That is deliberate: every bound sheet costs a reference slot on EVERY downstream shot, so one sheet per character doubles the cast you can stage against real caps (Kling 3.0 takes 4 ingredients, NB2 4 character slots, Seedance 9). Pass sheetTypes:['expression'] only when a character genuinely needs a separate expression range. baseAssetId is the source portrait (a project asset). Afterward, carry the character into a scene by passing its bound sheet asset id as characterAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image). Read slates-character-turnaround before calling. Default nano-banana-2 @ 2K — quote the price from slates_estimate_generation_cost, never from memory.",
+export const generateCharacterIdentity = {
+    id: 'slates_generate_character_identity',
+    description: "Generate one character identity sheet from a base portrait asset and bind it as the character's canonical reference. Call after slates_create_character. Read slates-character-identity before calling and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         characterId: z.string().uuid(),
         projectId: z.string().uuid(),
-        baseAssetId: z.string().uuid().describe('The base portrait asset the sheets are generated from.'),
-        sheetTypes: z
-            .array(z.enum(['turnaround', 'expression']))
-            .optional()
-            .describe("Which sheets to generate. Default ['turnaround'] — the single identity sheet. Add 'expression' only when the character needs a dedicated expression range; it costs a second reference slot on every downstream generation."),
+        baseAssetId: z.string().uuid().describe('The base portrait asset the identity is generated from.'),
         userNotes: z.string().optional().describe('Extra instruction, e.g. "use the woman on the left".'),
         model: z
             .enum(['nano-banana-2', 'nano-banana-2-lite', 'nano-banana-pro', 'gpt-image-2'])
@@ -596,11 +704,10 @@ export const generateCharacterSheets = {
             .describe('Image model for the sheet. Omit for the default (nano-banana-2). Exists so the layout-vs-face tradeoff can be tested with comparison gens — do not switch without a receipt.'),
     }),
     async run(input, ctx) {
-        return ok(await ctx.desktop().post('/agent/characters/generate-sheets', {
+        return ok(await ctx.desktop().post('/agent/characters/generate-identity', {
             characterId: input.characterId,
             projectId: input.projectId,
             baseAssetIds: [input.baseAssetId],
-            sheetTypes: input.sheetTypes,
             userNotes: input.userNotes,
             model: input.model,
         }));
@@ -608,7 +715,7 @@ export const generateCharacterSheets = {
 };
 export const generateEnvironmentPlate = {
     id: 'slates_generate_environment_plate',
-    description: "Generate an environment's single clean establishing plate (Nano Banana 2, 2K) from an optional base image, and bind it as the environment's reference. THE real environment-building workflow — call right after slates_create_environment. Afterward, pass the plate asset id as environmentAssetIds to slates_generate_video (or referenceAssetIds to slates_generate_image) so the location stays consistent across shots. Cost ~6 credits.",
+    description: "Generate one clean establishing image from an optional base image and bind it as the environment's canonical reference. Call after slates_create_environment and quote the cost from slates_estimate_generation_cost.",
     input: z.object({
         environmentId: z.string().uuid(),
         projectId: z.string().uuid(),
@@ -1298,6 +1405,90 @@ export function klingEditCostKey(model, duration) {
 export function omniFlashEditCostKey(duration) {
     return `omni-flash-edit-${duration}s`;
 }
+// ── Audio ───────────────────────────────────────────────────────
+// Exported: the exact `model` ids slates_generate_audio accepts — consumed
+// by the desktop Studio Agent system prompt (SSOT; never restate these ids
+// in prose that can drift). Mirrors VIDEO_MODELS for the third media type.
+export const AUDIO_MODELS = ['seed-audio', 'eleven-v3', 'eleven-sfx', 'suno'];
+/**
+ * Per-surface bounds and defaults.
+ *
+ * 🚨 THESE FOUR NUMBERS PER SURFACE LIVE IN THREE REPOS. A change is a
+ * three-site edit, every time:
+ *   1. HERE (`audioCostKey`, the agent's pre-flight quote)
+ *   2. `slate/src/shared/pricing.ts` → MODEL_REGISTRY `audio.durationSeconds`
+ *      (min/max/default), read by `clampAudioDuration` + `audioCreditKey`
+ *   3. `slates-api/src/lib/audio-keys.ts` → the server's fail-closed bounds
+ * `slates-api/scripts/pricing-consistency-check.mjs` §4 asserts 1 and 2 agree
+ * at EVERY value including out-of-range ones; the gate check covers 3.
+ *
+ * The MINs used to be missing here, and the clamp floor was a hardcoded 1. That
+ * made `slates_estimate_generation_cost({model:'seed-audio', duration:2})`
+ * quote a real `seed-audio-2s` price for a generation the desktop would bill as
+ * 3s and the proxy would REJECT outright. Same for an omitted duration, which
+ * quoted `seed-audio-1s` against the desktop's `seed-audio-15s`.
+ */
+export const SEED_AUDIO_MIN_SECONDS = 3;
+export const SEED_AUDIO_MAX_SECONDS = 120;
+export const SEED_AUDIO_DEFAULT_SECONDS = 15;
+export const ELEVEN_SFX_MIN_SECONDS = 1;
+export const ELEVEN_SFX_MAX_SECONDS = 22;
+export const ELEVEN_SFX_DEFAULT_SECONDS = 4;
+export const ELEVEN_V3_MAX_CHARACTERS = 5000;
+export const SUNO_MIN_SECONDS = 10;
+export const SUNO_MAX_SECONDS = 360;
+/**
+ * Byte-for-byte the desktop's `clampAudioDuration` in slate/src/shared/pricing.ts,
+ * INCLUDING the non-finite arm — that one matters: `Math.max(min, NaN)` is NaN,
+ * so without it a NaN duration produces the key `seed-audio-NaNs` here while the
+ * desktop quotes the default. Divergence at a value neither side can bill is
+ * still divergence; the checker sweeps for it.
+ */
+function clampAudioSeconds(value, min, max, fallback) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.ceil(value)));
+}
+function clampInt(value, min, max) {
+    return Math.min(max, Math.max(min, Math.ceil(value)));
+}
+// Exported for scripts/pricing-consistency-check.mjs (slates-api repo), which
+// asserts this builder byte-matches the desktop's audioCreditKey().
+//
+// Seed Audio has NO duration parameter — length is driven by the prompt text.
+// We bill the REQUESTED duration (shape B, locked 2026-07-31): the desktop
+// injects "... N seconds" into the prompt and bills seed-audio-{N}s, so
+// display == billing with no amendment to the pricing law. The server probes
+// the returned audio.duration afterwards and logs SEED AUDIO BILLING DRIFT.
+export function audioCostKey(input) {
+    if (input.model === 'seed-audio') {
+        // `?? default` before the clamp, not `?? 0` — the desktop resolves a missing
+        // duration to the registry DEFAULT, and a quote that doesn't match what the
+        // desktop would bill is the whole bug class this mirrors away.
+        const secs = clampAudioSeconds(input.durationSeconds ?? SEED_AUDIO_DEFAULT_SECONDS, SEED_AUDIO_MIN_SECONDS, SEED_AUDIO_MAX_SECONDS, SEED_AUDIO_DEFAULT_SECONDS);
+        return `seed-audio-${secs}s`;
+    }
+    if (input.model === 'eleven-v3') {
+        // 100-character buckets, always rounded UP — never under-bill a read.
+        // Mirrors ttsBuckets() in slate/src/shared/pricing.ts, non-finite arm included.
+        const chars = input.characters ?? 0;
+        const buckets = Number.isFinite(chars)
+            ? Math.min(ELEVEN_V3_MAX_CHARACTERS / 100, Math.max(1, Math.ceil(chars / 100)))
+            : 1;
+        return `eleven-v3-tts-${buckets}00c`;
+    }
+    if (input.model === 'eleven-sfx') {
+        const secs = clampAudioSeconds(input.durationSeconds ?? ELEVEN_SFX_DEFAULT_SECONDS, ELEVEN_SFX_MIN_SECONDS, ELEVEN_SFX_MAX_SECONDS, ELEVEN_SFX_DEFAULT_SECONDS);
+        return `eleven-sfx-${secs}s`;
+    }
+    if (input.model === 'suno') {
+        // Flat across every Suno model AND every duration up to 360s — measured
+        // against the live sunoapi.org balance 2026-07-31 (12 credits for a
+        // default call and for duration=240 alike). One call returns TWO songs.
+        return 'suno-generate';
+    }
+    throw new Error(`Unknown audio model: ${input.model}`);
+}
 /**
  * Forgiving model-id resolver. Agents routinely paste registry COST keys
  * ("kling-v3-standard-8s", "seedance-2-1080p-8s") into the `model` param —
@@ -1384,7 +1575,7 @@ export const generateVideo = {
         lastFrameAssetId: z.string().optional().describe('Ending frame (UUID or badge code). Veo and Seedance only. Pairs with firstFrameAssetId for guided transitions.'),
         ingredientAssetIds: z.array(z.string()).max(9).optional().describe('Visual reference / ingredient assets (UUIDs or badge codes) for Kling Omni, Seedance, or Omni Flash. Up to 9 (Seedance), 4 (Kling), or 7 (Omni Flash, combined across all ref params).'),
         characterAssetIds: z.array(z.string()).optional().describe('Character sheet assets (UUIDs or badge codes) — keeps a character consistent across the shot.'),
-        environmentAssetIds: z.array(z.string()).optional().describe('Environment grid assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
+        environmentAssetIds: z.array(z.string()).optional().describe('Environment reference assets (UUIDs or badge codes) — keeps a location/setting consistent across the shot.'),
         styleAssetIds: z.array(z.string()).optional().describe('Style reference assets (UUIDs or badge codes) — locks the visual style of the shot.'),
         videoReferenceAssetId: z.string().optional().describe('Seedance ONLY: an existing VIDEO asset (UUID or badge code) to use as a reference — edit/relocate a clip, or MOTION TRANSFER (pair with a subject in ingredientAssetIds and a prompt like "the character from image 1 performs the motion from video 1"). 2-15s. Billing switches to input+output seconds (the vref key) — pass videoReferenceSeconds so the quote is right. If the clip contains a human/AI character, pair with seedanceFace=true (the default Seedance route blocks people). Ignored by Kling/Veo.'),
         videoReferenceSeconds: z.number().optional().describe('REQUIRED with videoReferenceAssetId: the reference clip\'s duration in seconds (from the asset listing). Feeds the vref cost key — a video-reference gen bills combined input+output seconds; the server re-derives this by probing the clip, so an understated value just gets corrected upward.'),
@@ -1690,6 +1881,207 @@ export const generateVideo = {
         };
     },
 };
+// ── Generate audio ──────────────────────────────────────────────
+export const generateAudio = {
+    id: 'slates_generate_audio',
+    description: 'Generate AUDIO via Slates credits — the third media type, saved as a project asset you can drop on an audio track. Four surfaces: seed-audio (default; a whole audio SCENE — dialogue + SFX + ambience — from one plain sentence, 3-120s), eleven-v3 (verbatim text-to-speech in a named voice), eleven-sfx (ONE effect with an exact 1-22s duration, or a seamless loop), suno (full music; every call returns TWO songs for one flat price). Which surface for which job: read the slates-model-selection skill. ' +
+        '🚨 seed-audio has NO duration parameter — the length you pass is written INTO THE PROMPT and is what the user is BILLED, whatever comes back. Choose it deliberately. ' +
+        'REQUIRED before calling: read slates-cost-discipline and the matching prompting skill (slates-prompting-seed-audio | slates-prompting-elevenlabs | slates-prompting-suno). Kling\'s "SFX:" / "Ambient noise:" prompt syntax does NOT transfer to seed-audio and makes results worse. ' +
+        'projectId is REQUIRED (no headless path). Cost > 17 credits returns requires_confirm — pass confirm=true after explicit user OK. No skill files installed? Call slates_get_prompting_guide first.',
+    input: z.object({
+        projectId: z.string().uuid().describe('Slates project the audio asset lands in. Required — the renderer refreshes live.'),
+        model: z
+            .enum(AUDIO_MODELS)
+            .describe('Audio surface. seed-audio = scene/ambience/beds (default choice), eleven-v3 = exact-script voiceover, eleven-sfx = one precise effect, suno = music. Routing doctrine: slates-model-selection skill.'),
+        prompt: z
+            .string()
+            .min(1)
+            .max(5000)
+            .describe('seed-audio: ONE plain sentence describing the scene (no production jargon, no "SFX:" prefixes; name the crowd/room size). eleven-v3: the SCRIPT, spoken verbatim — never put stage directions here. eleven-sfx: the effect described by its physical CAUSE ("heavy oak door slams shut in a stone hallway"), max 450 chars. suno: a description in default mode, or the EXACT LYRICS when customMode=true and instrumental=false.'),
+        durationSeconds: z
+            .number()
+            .optional()
+            .describe('seed-audio 3-120 (default 15) — ⚠️ THIS IS THE BILL: it is appended to the prompt and charged regardless of the returned length. eleven-sfx 1-22 (default 4) — always sent explicitly so the per-second charge is deterministic. suno 10-360, FREE (a 6-minute track costs the same as a default one) but only accepted on sunoModel=V5_5 with customMode=true. Ignored by eleven-v3, which bills per 100 characters of text.'),
+        voice: z
+            .string()
+            .optional()
+            .describe('seed-audio: a preset voice id (e.g. "cedric_en_zh") — leave unset to let the scene cast itself, which is usually right for background dialogue. eleven-v3: a preset name (Rachel default; Aria, Roger, Sarah, Laura, Charlie, George, Callum, River, Liam, Charlotte, Alice, Matilda, Will, Jessica, Eric, Chris, Brian, Daniel, Lily, Bill). Pick one and keep it for the whole piece. No voice cloning on this route.'),
+        stability: z.number().min(0).max(1).optional().describe('eleven-v3 only. 0-1, default 0.5. Lower = more expressive and more variable take-to-take; higher = flatter and repeatable. Raise it for long narration.'),
+        languageCode: z.string().optional().describe('eleven-v3 only — ISO 639-1 code to force a language when the text is ambiguous or code-switched.'),
+        speed: z.number().min(0.5).max(2).optional().describe('seed-audio only — 0.5-2.0. Reach for it when dialogue races or drags against picture.'),
+        volume: z.number().min(0.5).max(2).optional().describe('seed-audio only — output gain, 0.5-2.0 (1 = unchanged). Prefer the timeline track fader for mix decisions; this is for when the model itself renders a scene too hot or too quiet.'),
+        pitch: z.number().int().min(-12).max(12).optional().describe('seed-audio only — semitones. Small moves; ±3 is already a lot.'),
+        multilingual: z.boolean().optional().describe('seed-audio only — better non-English / mixed-language handling.'),
+        loop: z.boolean().optional().describe('eleven-sfx only — produce a seamless loop (rain, engine hum, crowd murmur).'),
+        promptInfluence: z.number().min(0).max(1).optional().describe('eleven-sfx only — 0-1, default 0.3. Higher hugs your wording with less variation between takes.'),
+        audioReferenceAssetIds: z
+            .array(z.string())
+            .max(3)
+            .optional()
+            .describe('seed-audio only — up to 3 AUDIO assets (UUIDs or badge codes like "AUD-S1"), each ≤30s, referenced in the prompt as @Audio1-@Audio3 ("match the room tone of @Audio1"). MUTUALLY EXCLUSIVE with imageReferenceAssetId — the API rejects both.'),
+        imageReferenceAssetId: z
+            .string()
+            .optional()
+            .describe('seed-audio only — ONE image asset to score what is in frame. MUTUALLY EXCLUSIVE with audioReferenceAssetIds.'),
+        sunoModel: z.enum(['V4', 'V4_5', 'V4_5PLUS', 'V4_5ALL', 'V5', 'V5_5']).optional().describe('suno only — wire model id (underscored). Default V5. Cost is FLAT across every version. duration needs V5_5.'),
+        customMode: z
+            .boolean()
+            .optional()
+            .describe('suno only. false (default) = prompt is a ≤500-char DESCRIPTION and lyrics get written for you. true = style + title required, and prompt becomes the EXACT LYRICS, sung as written. Putting a description in the prompt while customMode=true wastes a full generation.'),
+        instrumental: z.boolean().optional().describe('suno only — score with no vocals. Usually right for a film bed: an unasked-for vocal fights dialogue.'),
+        style: z.string().optional().describe('suno only — genre + era + instrumentation + tempo ("90s trip-hop, dusty breakbeat, Rhodes, 85 bpm"). Required in customMode. Steer here, not by piling adjectives into the prompt.'),
+        title: z.string().optional().describe('suno only — track title. Required in customMode.'),
+        negativeTags: z.string().optional().describe('suno only — comma-separated things to keep out ("brass, EDM drop, male vocal").'),
+        vocalGender: z.enum(['m', 'f']).optional().describe('suno only — the WIRE values m/f, not "male"/"female".'),
+        styleWeight: z.number().min(0).max(1).optional().describe('suno only — 0-1, how hard the track hugs `style`. Higher = more genre-obedient and more generic; lower = more room to surprise you.'),
+        weirdnessConstraint: z.number().min(0).max(1).optional().describe('suno only — 0-1 experimentation dial. Low is safe and on-brief; high wanders. Leave unset for a film bed.'),
+        background: z.boolean().optional().describe(BACKGROUND_DESCRIBE + ' Recommended for suno (2-3 min renders).'),
+        confirm: z.boolean().optional().describe('Set true to bypass the confirm gate after explicit user OK.'),
+    }),
+    run: async (input, ctx) => {
+        // ── Per-surface clarification + constraint gates ──
+        const cfgDefaults = {
+            'seed-audio': 15,
+            'eleven-sfx': 4,
+            'eleven-v3': undefined,
+            suno: undefined,
+        };
+        const seconds = input.durationSeconds ?? cfgDefaults[input.model];
+        if (input.model === 'seed-audio') {
+            if (seconds == null || seconds < 3 || seconds > SEED_AUDIO_MAX_SECONDS) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['durationSeconds'],
+                    message: `Seed Audio needs a durationSeconds of 3-${SEED_AUDIO_MAX_SECONDS}. It has NO duration parameter — the number is written into the prompt AND is what the user is billed, so it must be a deliberate choice. Ask the user how long the bed should be (a few seconds longer than the clip it sits under, so the edit has handles).`,
+                });
+            }
+            if ((input.audioReferenceAssetIds?.length ?? 0) > 0 && input.imageReferenceAssetId) {
+                throw new Error('Seed Audio takes audio references OR one image reference, never both — the provider rejects the combination.');
+            }
+        }
+        if (input.model === 'eleven-sfx') {
+            if (seconds == null || seconds < 1 || seconds > ELEVEN_SFX_MAX_SECONDS) {
+                return ok({
+                    requires_clarification: true,
+                    missing: ['durationSeconds'],
+                    message: `Sound Effects needs a durationSeconds of 1-${ELEVEN_SFX_MAX_SECONDS}. It is billed per second and is never left for the model to pick (that would make the charge non-deterministic). Roughly: 0.5-1s for an impact, 2-4s for a whoosh, 8-22s for a loopable bed.`,
+                });
+            }
+            if (input.prompt.length > 450) {
+                throw new Error(`Sound Effects accepts up to 450 characters — this prompt is ${input.prompt.length}.`);
+            }
+        }
+        if (input.model === 'eleven-v3' && input.prompt.length > ELEVEN_V3_MAX_CHARACTERS) {
+            throw new Error(`Eleven v3 accepts up to ${ELEVEN_V3_MAX_CHARACTERS} characters — this script is ${input.prompt.length}.`);
+        }
+        if (input.model === 'suno' && input.customMode === true) {
+            if (!input.style || !input.title) {
+                return ok({
+                    requires_clarification: true,
+                    missing: [...(input.style ? [] : ['style']), ...(input.title ? [] : ['title'])],
+                    message: 'Suno custom mode requires style and title. Remember that in custom mode the prompt field is the EXACT LYRICS (unless instrumental=true, where it is ignored) — if you meant to describe a mood, use customMode=false instead.',
+                });
+            }
+        }
+        await ctx.desktop().requireCapability('audio-generation', 'audio generation');
+        // ── Resolve asset refs at CALL time (UUIDs or badge codes) ──
+        const refInputs = [];
+        for (const ref of input.audioReferenceAssetIds ?? [])
+            refInputs.push({ ref, role: 'audio reference' });
+        if (input.imageReferenceAssetId)
+            refInputs.push({ ref: input.imageReferenceAssetId, role: 'image reference' });
+        const resolvedRefs = refInputs.length > 0
+            ? await resolveAssetRefs(ctx, input.projectId, refInputs.map((r) => r.ref))
+            : new Map();
+        const rid = (v) => (v ? (resolvedRefs.get(v)?.id ?? v) : v);
+        const refEcho = refInputs.length > 0 ? describeResolvedRefs(refInputs, resolvedRefs) : '';
+        // ── Cost — from the CLOUD registry, keyed by the SAME builder the desktop
+        //    and the proxy use. Never quote a price from memory. ──
+        const cloud = ctx.cloud();
+        const registry = await cloud.get('/api/agent/models');
+        const costKey = audioCostKey({
+            model: input.model,
+            durationSeconds: seconds,
+            characters: input.prompt.length,
+        });
+        const entry = registry.models.find((m) => m.model === costKey);
+        if (!entry) {
+            throw new Error(`Audio variant not in registry: ${costKey}. Available audio models: ${AUDIO_MODELS.join(' | ')}.`);
+        }
+        const totalCents = creditCost(entry);
+        if (!input.confirm && totalCents > CONFIRM_CREDITS) {
+            return ok({
+                requires_confirm: true,
+                model: input.model,
+                variant: costKey,
+                cost_credits: totalCents,
+                cost_display: fmtCredits(totalCents),
+                message: `${input.model} audio will cost ${fmtCredits(totalCents)}. ` +
+                    (input.model === 'seed-audio'
+                        ? `You are billed for the ${seconds}s you requested regardless of the returned length. `
+                        : '') +
+                    (input.model === 'suno' ? 'This returns TWO songs for that one price. ' : '') +
+                    'Confirm with the user, then call again with confirm: true.',
+            });
+        }
+        // ── Submit through the DESKTOP so the progress card, the project save,
+        //    and recovery all behave exactly like a UI-triggered run. ──
+        const desktop = ctx.desktop();
+        if (input.background) {
+            await desktop.requireCapability('background-generation', 'background generation');
+        }
+        const result = await desktop.post('/agent/generation/audio', {
+            projectId: input.projectId,
+            model: input.model,
+            prompt: input.prompt,
+            durationSeconds: seconds,
+            voice: input.voice,
+            stability: input.stability,
+            languageCode: input.languageCode,
+            speed: input.speed,
+            volume: input.volume,
+            pitch: input.pitch,
+            multilingual: input.multilingual,
+            loop: input.loop,
+            promptInfluence: input.promptInfluence,
+            audioReferenceAssetIds: (input.audioReferenceAssetIds ?? []).map((r) => rid(r)),
+            imageReferenceAssetId: rid(input.imageReferenceAssetId),
+            sunoModel: input.sunoModel,
+            customMode: input.customMode,
+            instrumental: input.instrumental,
+            style: input.style,
+            title: input.title,
+            negativeTags: input.negativeTags,
+            vocalGender: input.vocalGender,
+            styleWeight: input.styleWeight,
+            weirdnessConstraint: input.weirdnessConstraint,
+            background: input.background,
+        });
+        if (!result.success)
+            throw new Error(result.error ?? 'Audio generation failed');
+        if (result.background) {
+            return backgroundSubmitted(`${input.model} audio generation`, [result.generationId].filter(Boolean), { model: input.model, variant: costKey, projectId: input.projectId, cost_credits: totalCents }, refEcho);
+        }
+        const siblings = result.siblingAssets ?? [];
+        return {
+            text: `Generated ${input.model} audio into project ${input.projectId} for ${fmtCredits(totalCents)}` +
+                (siblings.length > 0 ? ` (${siblings.length + 1} tracks — Suno returns two variations)` : '') +
+                `. Prompt: "${input.prompt.slice(0, 60)}${input.prompt.length > 60 ? '...' : ''}"` +
+                (refEcho ? ` ${refEcho}` : ''),
+            data: {
+                model: input.model,
+                variant: costKey,
+                projectId: input.projectId,
+                durationSeconds: seconds,
+                cost_cents: totalCents,
+                cost_credits: totalCents,
+                asset: result.asset,
+                ...(siblings.length > 0 ? { siblingAssets: siblings } : {}),
+                generationId: result.generationId,
+            },
+        };
+    },
+};
 // ── Generate lip-sync ───────────────────────────────────────────
 export const generateLipSync = {
     id: 'slates_generate_lip_sync',
@@ -2532,7 +2924,7 @@ export const setFolderCover = {
 };
 export const updateCharacter = {
     id: 'slates_update_character',
-    description: 'Update a character\'s name, description, or style. (Turnaround / expression image slots have their own dedicated set_character_* ops.)',
+    description: 'Update a character\'s name, description, or style. Use slates_set_character_identity_asset for its canonical image.',
     input: z.object({
         characterId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
@@ -2556,13 +2948,13 @@ export const deleteCharacter = {
 };
 export const updateEnvironment = {
     id: 'slates_update_environment',
-    description: 'Update an environment\'s name, description, style, or bound grid asset (gridAssetId=null clears it).',
+    description: 'Update an environment\'s name, description, style, or bound reference image (referenceAssetId=null clears it).',
     input: z.object({
         environmentId: z.string().uuid(),
         name: z.string().min(1).max(120).optional(),
         description: z.string().optional(),
         style: z.string().max(200).optional().describe("Art style. Omit to inherit the reference's style (the default). Canonical styles: photoreal, anime, painterly, 3d-render, comic. Or pass any free-text instruction, e.g. 'turn this into a real person'."),
-        gridAssetId: z.string().uuid().nullable().optional(),
+        referenceAssetId: z.string().uuid().nullable().optional(),
     }),
     async run(input, ctx) {
         return ok(await ctx.desktop().post('/agent/environments/update', {
@@ -2571,7 +2963,7 @@ export const updateEnvironment = {
                 name: input.name,
                 description: input.description,
                 style: input.style,
-                gridAssetId: input.gridAssetId,
+                referenceAssetId: input.referenceAssetId,
             },
         }));
     },
@@ -2728,6 +3120,9 @@ function resolveGuideTopic(topic) {
     const t = topic.trim().toLowerCase();
     if (SKILLS[t])
         return t;
+    if (t === 'slates-character-turnaround' || t === 'character-turnaround') {
+        return 'slates-character-identity';
+    }
     if (t === 'model-selection' ||
         t === 'model selection' ||
         t === 'which-model' ||
@@ -2754,6 +3149,16 @@ function resolveGuideTopic(topic) {
         return 'slates-prompting-kling-v3';
     if (t.startsWith('kling-v3'))
         return 'slates-prompting-kling-v3';
+    // Audio — seed-audio BEFORE the seedance check: "seed-audio" also starts
+    // with "seed", and falling through would hand the video guide to the audio
+    // model (the exact class of aliasing bug this comment block warns about).
+    if (t.startsWith('seed-audio') || t === 'seed audio' || t === 'audio')
+        return 'slates-prompting-seed-audio';
+    if (t.startsWith('eleven') || t.startsWith('elevenlabs') || t === 'tts' || t === 'sfx' || t === 'sound-effects' || t === 'sound effects' || t === 'voiceover') {
+        return 'slates-prompting-elevenlabs';
+    }
+    if (t.startsWith('suno') || t === 'music')
+        return 'slates-prompting-suno';
     if (t.startsWith('seedance'))
         return 'slates-prompting-seedance';
     if (t.startsWith('avatar-') || t.includes('lip-sync'))
@@ -2780,7 +3185,7 @@ export const getPromptingGuide = {
         topic: z
             .string()
             .min(1)
-            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-turnaround, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
+            .describe('Guide name, model id, or style name. Guides: slates-model-selection (which model for which job — read before choosing any model), slates-cost-discipline, slates-content-policy, slates-style-prompting, slates-prompting-nano-banana-2, slates-prompting-veo-3, slates-prompting-kling-v3, slates-prompting-seedance, slates-prompting-seed-audio, slates-prompting-elevenlabs, slates-prompting-suno, slates-prompting-lip-sync, slates-prompting-motion-transfer, slates-prompting-flux-2-max, slates-prompting-seedream-5-lite, slates-edit-and-iterate, slates-vision-feedback-loop, slates-character-identity, slates-storyboard-from-script, slates-direct-response-ad, slates-one-prompt-film. Style names (photoreal, anime, painterly, 3d-render) resolve to slates-style-prompting.'),
     }),
     async run(input) {
         const resolved = resolveGuideTopic(input.topic);
@@ -2812,13 +3217,15 @@ export const ALL_OPERATIONS = [
     listFolders,
     createFolder,
     moveAssetsToFolder,
+    moveAssetsToProject,
+    copyAssetsToProject,
+    moveEntityToProject,
     listCharacters,
     createCharacter,
-    setCharacterTurnaround,
-    setCharacterExpression,
+    setCharacterIdentity,
     listEnvironments,
     createEnvironment,
-    generateCharacterSheets,
+    generateCharacterIdentity,
     generateEnvironmentPlate,
     listStoryboards,
     createStoryboard,
@@ -2827,6 +3234,7 @@ export const ALL_OPERATIONS = [
     addFrame,
     generateImage,
     generateVideo,
+    generateAudio,
     generateLipSync,
     generateMotionTransfer,
     editVideo,