threenative-asset-mcp 0.9.1 → 0.9.2

package/README.md

@@ -35,6 +35,11 @@ dependency relationships with pagination and resolution/format filters.
 - A local environment capable of running Playwright Chromium when Fab requests
   browser verification
 - No Epic or Fab login is required or automated
+- **FFmpeg and FFprobe on `PATH`** for `audio_inspect_asset` and
+  `audio_generate_sound`. Without them nothing is decoded, and the tools report
+  that they could not check rather than reporting a pass.
+- An **ElevenLabs API key of your own** for `audio_generate_sound` only. Every
+  other tool, including local audio inspection, works without one.
 
 ## Install
 
@@ -192,6 +197,83 @@ Game audio:
   `acceptLicense: true`. It uses an HTTPS host allowlist, validates every
   redirect, streams with a byte cap, writes atomically without overwrite, and
   returns the local path, byte size, and SHA-256.
+- `audio_inspect_asset` — measures one local WAV, Ogg, MP3, or FLAC with the
+  pinned `@threenative/playtest` inspector: decode integrity, silence floor,
+  peak ceiling, DC offset, a five-band spectrum, the loop seam of a **declared**
+  loop, and the requested duration, plus a spectrogram PNG. Needs no ElevenLabs
+  key and never modifies or repairs the file. Optionally compares prompt and
+  emotional tone when local CLAP is provisioned.
+- `audio_generate_sound` — **spends ElevenLabs credits.** Generates one sound
+  effect or ambience from a prompt using *your own* `ELEVENLABS_API_KEY`, saves
+  the original response plus a PCM16 WAV, and runs the same inspection
+  automatically. Reusing a `requestId` returns the saved result instead of
+  charging again.
+
+### Generating a sound
+
+The loop is **generate once → inspect → revise the one property that failed →
+explicitly generate again.** There is no best-of-N retry: every generation is a
+separate billable invocation you ask for on purpose.
+
+Describe source, action, material, distance, and timing. A useful brief:
+
+> One short metal latch closing, close microphone, dry recording, single event
+> with natural decay, no speech or music.
+
+These are prompting conventions absorbed from ElevenLabs' own
+[sound-effects skill](https://github.com/elevenlabs/skills/blob/9edcbd4b80ed57b8e07a3f86ea520333969fbc3c/sound-effects/SKILL.md)
+(MIT, reviewed at commit `9edcbd4b`), which is linked and attributed rather than
+installed. They are conventions, not guaranteed exclusion controls.
+
+`audio_generate_sound` requires `ELEVENLABS_API_KEY` in the server environment.
+It is never bundled, defaulted, or logged: without your own key the tool fails
+with `AUDIO_GENERATE_NO_CREDENTIALS` and an instruction to set one, while the
+catalog and inspection tools keep working normally.
+
+What the inspection does and does not tell you:
+
+| It answers | It does not answer |
+| --- | --- |
+| Is it broken, silent, clipped, DC-offset, or the wrong duration? | Is it a *good* sound? |
+| Does a declared loop click at the wrap? | Does it suit this scene? |
+| Is the frequency content inside bounds *you* supplied? | Is the mix right? |
+
+`artisticQuality` is always `"unverified"`. There is no `soundsGood` flag and no
+single quality score. `recommendation: "audition"` means the technical checks
+passed and every requested check completed — it means *go listen to it*, not
+*ship it*. A definite technical failure recommends `"reject"`; a warning, a
+possible mismatch, or an incomplete requested check recommends `"review"`.
+
+If asset compilation rewrites the bytes, inspect the compiled output before
+describing that output as checked.
+
+### Optional local CLAP setup
+
+Prompt fit and emotion fit are **off by default** (`semantic: "off"`) and add no
+dependency to `npm install`. To enable them:
+
+```sh
+python3 -m venv ~/.venvs/clap
+~/.venvs/clap/bin/pip install "laion-clap==1.1.6" "torch==2.4.1" \
+    "torchaudio==2.4.1" "librosa==0.10.2.post1" "numpy<2"
+# Download 630k-audioset-best.pt from the LAION-AI/CLAP releases and check its hash.
+export AUDIO_CLAP_CHECKPOINT=/path/to/630k-audioset-best.pt
+export AUDIO_CLAP_PYTHON=~/.venvs/clap/bin/python
+```
+
+Nothing is downloaded implicitly and no GPU is required. With `semantic: "clap"`
+and no provisioned model, you get the technical result plus an explicit
+unavailable semantic result and this instruction — never a semantic pass. A
+generation that requests `semantic: "clap"` is refused in preflight, before
+spending, when the model is missing.
+
+Scores are cosine similarities used as **supporting evidence**, never
+probabilities or quality grades. The emotion check builds otherwise identical
+hypotheses — `The sound of {sourceDescription}, with a {mood} emotional tone.` —
+so only the mood clause differs, and **this use of CLAP is a proposed heuristic,
+not a demonstrated emotion-recognition capability**: mood status stays
+`unverified` until the held-out emotion calibration qualifies your domain. Check
+the CLAP code and checkpoint licensing separately before redistributing either.
 
 Curated itch.io packs:
 
@@ -399,6 +481,11 @@ glTF's standard punctual-light extension has no area-light type.
 | `AUDIO_DOWNLOAD_DIR`            | `~/Downloads/threenative-asset-mcp/audio`          | Dedicated directory for curated audio downloads.         |
 | `AUDIO_MAX_DOWNLOAD_BYTES`      | `10737418240`                                      | Maximum accepted bytes per audio archive (10 GiB).       |
 | `AUDIO_DOWNLOAD_TIMEOUT_MS`     | `1800000`                                          | Total timeout for one audio download (30 minutes).       |
+| `ELEVENLABS_API_KEY`            | unset                                              | **Your own** key; required only by `audio_generate_sound`. Never bundled or logged. |
+| `AUDIO_INSPECT_ROOTS`           | the audio dir plus the launch directory            | Extra `:`-separated roots `audio_inspect_asset` may read. |
+| `AUDIO_CLAP_PYTHON`             | unset                                              | Interpreter with LAION-CLAP installed; enables `semantic: "clap"`. |
+| `AUDIO_CLAP_CHECKPOINT`         | unset                                              | Path to the `630k-audioset-best.pt` checkpoint.          |
+| `AUDIO_CLAP_CHECKPOINT_SHA256`  | unset                                              | Optional pin; a mismatched checkpoint is refused.        |
 | `ASSET_DOWNLOAD_DIR`            | `~/Downloads/threenative-asset-mcp/assets`         | Dedicated directory for direct provider downloads.       |
 | `ASSET_MAX_DOWNLOAD_BYTES`      | `10737418240`                                      | Maximum accepted bytes per provider file (10 GiB).       |
 | `ASSET_DOWNLOAD_TIMEOUT_MS`     | `1800000`                                          | Total timeout for one provider download (30 minutes).    |

package/dist/audio/fsutil.d.ts

@@ -0,0 +1,7 @@
+/** True when `path` is `parent` itself or lies beneath it. Both must already be real paths. */
+export declare function isInside(path: string, parent: string): boolean;
+export declare function sha256File(path: string): Promise<string>;
+export declare function sha256Bytes(value: Uint8Array): string;
+/** Stable hash of a plain JSON value: object key order must not change the digest. */
+export declare function sha256Json(value: unknown): string;
+//# sourceMappingURL=fsutil.d.ts.map

package/dist/audio/fsutil.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsutil.d.ts","sourceRoot":"","sources":["../../src/audio/fsutil.ts"],"names":[],"mappings":"AAIA,+FAA+F;AAC/F,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAG9D;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAS9D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAErD;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD"}

package/dist/audio/fsutil.js

@@ -0,0 +1,37 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+/** True when `path` is `parent` itself or lies beneath it. Both must already be real paths. */
+export function isInside(path, parent) {
+    const child = relative(parent, path);
+    return child === "" || (!child.startsWith("..") && !isAbsolute(child));
+}
+export async function sha256File(path) {
+    const hash = createHash("sha256");
+    await new Promise((done, fail) => {
+        const stream = createReadStream(path);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("error", fail);
+        stream.on("end", done);
+    });
+    return hash.digest("hex");
+}
+export function sha256Bytes(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+/** Stable hash of a plain JSON value: object key order must not change the digest. */
+export function sha256Json(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const entries = Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+    return `{${entries.join(",")}}`;
+}
+//# sourceMappingURL=fsutil.js.map

package/dist/audio/fsutil.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fsutil.js","sourceRoot":"","sources":["../../src/audio/fsutil.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD,+FAA+F;AAC/F,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,MAAc;IACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACrC,OAAO,KAAK,KAAK,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,IAAY;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,IAAI,OAAO,CAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACzB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACxF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;SAC7D,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC;SACxC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClC,CAAC"}

package/dist/audio/generate.d.ts

@@ -0,0 +1,95 @@
+import { type AudioInspectRequest, type AudioInspectResult, type AudioInspectorOptions } from "./inspect.js";
+/**
+ * One billed ElevenLabs sound-effect generation, saved and then inspected.
+ *
+ * The whole design here is about never charging twice. A `requestId` reserves a directory and a
+ * normalized-request hash *before* the POST, every durable step is written down as it completes, and
+ * a replay resumes from whichever verified bytes already exist. A submission whose outcome we never
+ * learned stays `outcome_unknown` forever: repeating that id never resubmits, because the provider
+ * may well have billed for it.
+ */
+export type AudioGenerateErrorCode = "AUDIO_GENERATE_NO_CREDENTIALS" | "AUDIO_GENERATE_INVALID_INPUT" | "AUDIO_GENERATE_REQUEST_CONFLICT" | "AUDIO_GENERATE_OUTCOME_UNKNOWN" | "AUDIO_GENERATE_PREREQUISITE_MISSING" | "AUDIO_GENERATE_AUTH_FAILED" | "AUDIO_GENERATE_RATE_LIMITED" | "AUDIO_GENERATE_REJECTED" | "AUDIO_GENERATE_UPSTREAM" | "AUDIO_GENERATE_TIMEOUT" | "AUDIO_GENERATE_TOO_LARGE" | "AUDIO_GENERATE_UNSAFE_REDIRECT" | "AUDIO_GENERATE_STORAGE" | "AUDIO_GENERATE_CONVERT_FAILED" | "AUDIO_GENERATE_HASH_MISMATCH";
+export declare class AudioGenerateError extends Error {
+    readonly code: AudioGenerateErrorCode;
+    readonly retryable: boolean;
+    constructor(code: AudioGenerateErrorCode, message: string, retryable?: boolean);
+}
+export declare const GENERATE_LIMITS: {
+    /** Our policy cap, not a claimed provider maximum. */
+    readonly maxPromptChars: 2000;
+    readonly minDurationSeconds: 0.5;
+    readonly maxDurationSeconds: 30;
+    readonly maxResponseBytes: number;
+    readonly timeoutMs: 120000;
+};
+export interface AudioGenerateRequest {
+    requestId: string;
+    prompt: string;
+    durationSeconds?: number | undefined;
+    loop?: boolean | undefined;
+    promptInfluence?: number | undefined;
+    inspection?: Omit<AudioInspectRequest, "path" | "loop" | "expectedDurationSeconds" | "expectedPrompt"> | undefined;
+}
+interface NormalizedRequest {
+    text: string;
+    duration_seconds: number;
+    loop: boolean;
+    prompt_influence: number;
+    model_id: string;
+    output_format: string;
+}
+export interface AudioGenerateResult {
+    requestId: string;
+    provider: "elevenlabs";
+    model: string;
+    normalizedRequest: NormalizedRequest;
+    generatedAt: string;
+    generation: "saved";
+    sourcePath: string;
+    sourceSha256: string;
+    sourceSizeBytes: number;
+    wavPath: string;
+    wavSha256: string;
+    wavSizeBytes: number;
+    providerRequestId?: string;
+    billingUnits?: string;
+    commercialUse: "unverified";
+    providerTermsUrl: string;
+    receiptPath: string;
+    replayed: boolean;
+    inspection: AudioInspectResult;
+}
+export interface AudioGeneratorOptions extends AudioInspectorOptions {
+    fetch?: typeof globalThis.fetch;
+    apiKey?: string;
+    ffmpegPath?: string;
+}
+export declare class AudioGenerator {
+    private readonly fetch;
+    private readonly audioDir;
+    private readonly apiKeyOverride;
+    private readonly ffmpegPath;
+    private readonly inspector;
+    constructor(options?: AudioGeneratorOptions);
+    /**
+     * The key is the operator's, read from their environment at call time. It is never defaulted,
+     * never written to a receipt, never logged and never returned — a missing one is an error the
+     * agent is expected to relay to the person running the server.
+     */
+    private apiKey;
+    generate(request: AudioGenerateRequest): Promise<AudioGenerateResult>;
+    /** Local-only completion: convert, inspect, finish. Never reaches the provider, never charges. */
+    private resume;
+    private preflight;
+    /** Exclusive reservation: two concurrent duplicates cannot both get past this. */
+    private reserve;
+    private submit;
+    /**
+     * Decode to PCM16 WAV with no resampling, no downmix, no normalization and no trimming. Turning
+     * MP3 into WAV does not restore what the encoder threw away, and pretending otherwise by
+     * "cleaning up" here would hide the defect the inspection exists to find.
+     */
+    private toWav;
+}
+export {};
+//# sourceMappingURL=generate.d.ts.map

package/dist/audio/generate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/audio/generate.ts"],"names":[],"mappings":"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"}

package/dist/audio/generate.js

@@ -0,0 +1,405 @@
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { sha256Bytes, sha256File, sha256Json } from "./fsutil.js";
+import { AudioInspector, } from "./inspect.js";
+import { semanticAvailable } from "./semantic.js";
+export class AudioGenerateError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "AudioGenerateError";
+    }
+}
+const ENDPOINT = "https://api.elevenlabs.io/v1/sound-generation";
+const MODEL_ID = "eleven_text_to_sound_v2";
+const OUTPUT_FORMAT = "mp3_44100_128";
+const PROVIDER_TERMS_URL = "https://help.elevenlabs.io/hc/en-us/articles/13313564601361-Can-I-publish-the-content-I-generate-on-the-platform";
+export const GENERATE_LIMITS = {
+    /** Our policy cap, not a claimed provider maximum. */
+    maxPromptChars: 2_000,
+    minDurationSeconds: 0.5,
+    maxDurationSeconds: 30,
+    maxResponseBytes: 32 * 1024 * 1024,
+    timeoutMs: 120_000,
+};
+export class AudioGenerator {
+    fetch;
+    audioDir;
+    apiKeyOverride;
+    ffmpegPath;
+    inspector;
+    constructor(options = {}) {
+        this.fetch = options.fetch ?? globalThis.fetch;
+        this.audioDir = resolve(options.audioDir ??
+            process.env.AUDIO_DOWNLOAD_DIR ??
+            join(homedir(), "Downloads", "threenative-asset-mcp", "audio"));
+        this.apiKeyOverride = options.apiKey;
+        this.ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+        this.inspector = new AudioInspector({ ...options, audioDir: this.audioDir });
+    }
+    /**
+     * The key is the operator's, read from their environment at call time. It is never defaulted,
+     * never written to a receipt, never logged and never returned — a missing one is an error the
+     * agent is expected to relay to the person running the server.
+     */
+    apiKey() {
+        const key = this.apiKeyOverride ?? process.env.ELEVENLABS_API_KEY;
+        if (!key || key.trim().length === 0) {
+            throw new AudioGenerateError("AUDIO_GENERATE_NO_CREDENTIALS", "ELEVENLABS_API_KEY is not set, so no audio can be generated and nothing was charged. " +
+                "Ask the user to set their own ElevenLabs API key in the MCP server's environment; " +
+                "the catalog and local inspection tools keep working without it.");
+        }
+        return key.trim();
+    }
+    async generate(request) {
+        const normalized = normalize(request);
+        const normalizedHash = sha256Json(normalized);
+        const dir = join(this.audioDir, "generated", request.requestId);
+        const receiptPath = join(dir, "receipt.json");
+        // Preflight: everything that could fail locally fails before a paid request is made.
+        this.apiKey();
+        await this.preflight(dir, request);
+        const existing = await readReceipt(receiptPath);
+        if (existing) {
+            if (existing.normalizedHash !== normalizedHash) {
+                throw new AudioGenerateError("AUDIO_GENERATE_REQUEST_CONFLICT", "That requestId was already used with different options. Use a new requestId for a new attempt.");
+            }
+            if (existing.state === "outcome_unknown") {
+                throw new AudioGenerateError("AUDIO_GENERATE_OUTCOME_UNKNOWN", "A previous submission of this requestId never reported its outcome; it may already have been " +
+                    "billed, so this id will never be resubmitted. Use a new requestId to deliberately try again.");
+            }
+            // Everything from here is local work on bytes already paid for.
+            return await this.resume(existing, dir, receiptPath, request);
+        }
+        await this.reserve(dir, receiptPath, {
+            requestId: request.requestId,
+            state: "submitted",
+            normalizedHash,
+            normalized,
+            provider: "elevenlabs",
+            model: MODEL_ID,
+            commercialUse: "unverified",
+            providerTermsUrl: PROVIDER_TERMS_URL,
+        });
+        const response = await this.submit(normalized, receiptPath);
+        const receipt = {
+            requestId: request.requestId,
+            state: "source_saved",
+            normalizedHash,
+            normalized,
+            provider: "elevenlabs",
+            model: MODEL_ID,
+            generatedAt: new Date().toISOString(),
+            ...(response.providerRequestId === undefined
+                ? {}
+                : { providerRequestId: response.providerRequestId }),
+            ...(response.billingUnits === undefined ? {} : { billingUnits: response.billingUnits }),
+            commercialUse: "unverified",
+            providerTermsUrl: PROVIDER_TERMS_URL,
+        };
+        const sourcePath = join(dir, "source.mp3");
+        await writeExclusive(sourcePath, response.body);
+        receipt.source = {
+            path: sourcePath,
+            sha256: sha256Bytes(response.body),
+            sizeBytes: response.body.byteLength,
+        };
+        await writeReceipt(receiptPath, receipt);
+        return await this.resume(receipt, dir, receiptPath, request);
+    }
+    /** Local-only completion: convert, inspect, finish. Never reaches the provider, never charges. */
+    async resume(receipt, dir, receiptPath, request) {
+        if (!receipt.source) {
+            // `submitted` with nothing saved yet means another caller is mid-flight with this id. That is
+            // a conflict to wait on, not an unknown outcome to condemn the id for.
+            throw receipt.state === "submitted"
+                ? new AudioGenerateError("AUDIO_GENERATE_REQUEST_CONFLICT", "That requestId is already in flight. Wait for it, or use a new requestId.")
+                : new AudioGenerateError("AUDIO_GENERATE_OUTCOME_UNKNOWN", "This request has no durable source audio, so it cannot be completed locally.");
+        }
+        // Recorded before this call finishes it: a replay is one that arrived already complete.
+        const replayed = receipt.state === "complete";
+        // A saved file that no longer matches its recorded hash fails; it is never re-fetched.
+        if ((await sha256File(receipt.source.path)) !== receipt.source.sha256) {
+            throw new AudioGenerateError("AUDIO_GENERATE_HASH_MISMATCH", "The saved source audio no longer matches the hash recorded when it was written.");
+        }
+        const wavPath = join(dir, "sound.wav");
+        if (!receipt.wav || !(await exists(wavPath))) {
+            await this.toWav(receipt.source.path, wavPath);
+            receipt.wav = {
+                path: wavPath,
+                sha256: await sha256File(wavPath),
+                sizeBytes: (await stat(wavPath)).size,
+            };
+            receipt.state = "wav_saved";
+            await writeReceipt(receiptPath, receipt);
+        }
+        else if ((await sha256File(wavPath)) !== receipt.wav.sha256) {
+            throw new AudioGenerateError("AUDIO_GENERATE_HASH_MISMATCH", "The saved WAV no longer matches the hash recorded when it was written.");
+        }
+        const inspection = await this.inspector.inspect({
+            ...(request.inspection ?? {}),
+            path: wavPath,
+            loop: receipt.normalized.loop,
+            expectedDurationSeconds: receipt.normalized.duration_seconds,
+            expectedPrompt: receipt.normalized.text,
+        });
+        receipt.state = "complete";
+        receipt.inspectionCacheKey = inspection.cacheKey;
+        await writeReceipt(receiptPath, receipt);
+        return {
+            requestId: receipt.requestId,
+            provider: "elevenlabs",
+            model: receipt.model,
+            normalizedRequest: receipt.normalized,
+            generatedAt: receipt.generatedAt ?? new Date().toISOString(),
+            generation: "saved",
+            sourcePath: receipt.source.path,
+            sourceSha256: receipt.source.sha256,
+            sourceSizeBytes: receipt.source.sizeBytes,
+            wavPath: receipt.wav.path,
+            wavSha256: receipt.wav.sha256,
+            wavSizeBytes: receipt.wav.sizeBytes,
+            ...(receipt.providerRequestId === undefined
+                ? {}
+                : { providerRequestId: receipt.providerRequestId }),
+            ...(receipt.billingUnits === undefined ? {} : { billingUnits: receipt.billingUnits }),
+            commercialUse: "unverified",
+            providerTermsUrl: PROVIDER_TERMS_URL,
+            receiptPath,
+            replayed,
+            inspection,
+        };
+    }
+    async preflight(dir, request) {
+        try {
+            await mkdir(dir, { recursive: true, mode: 0o700 });
+        }
+        catch {
+            throw new AudioGenerateError("AUDIO_GENERATE_STORAGE", "The audio output directory could not be created, so nothing was requested.");
+        }
+        await new Promise((done, fail) => {
+            execFile(this.ffmpegPath, ["-hide_banner", "-version"], { timeout: 20_000 }, (error) => error
+                ? fail(new AudioGenerateError("AUDIO_GENERATE_PREREQUISITE_MISSING", "FFmpeg is not available, so the response could not be decoded. Nothing was requested."))
+                : done());
+        });
+        this.inspector.resolveInspectorBin();
+        // An explicitly requested semantic model that is not provisioned is refused before spending.
+        if (request.inspection?.semantic === "clap" && !(await semanticAvailable())) {
+            throw new AudioGenerateError("AUDIO_GENERATE_PREREQUISITE_MISSING", "Semantic inspection was requested but local CLAP is not provisioned. Nothing was requested or charged.");
+        }
+    }
+    /** Exclusive reservation: two concurrent duplicates cannot both get past this. */
+    async reserve(dir, receiptPath, receipt) {
+        let handle;
+        try {
+            handle = await open(receiptPath, "wx", 0o600);
+        }
+        catch {
+            throw new AudioGenerateError("AUDIO_GENERATE_REQUEST_CONFLICT", "That requestId is already in flight. Wait for it, or use a new requestId.");
+        }
+        try {
+            await handle.writeFile(JSON.stringify(receipt, null, 2));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        void dir;
+    }
+    async submit(normalized, receiptPath) {
+        const url = new URL(ENDPOINT);
+        url.searchParams.set("output_format", normalized.output_format);
+        let response;
+        try {
+            response = await this.fetch(url, {
+                method: "POST",
+                // An authenticated request must never be replayed against a redirect target.
+                redirect: "error",
+                signal: AbortSignal.timeout(GENERATE_LIMITS.timeoutMs),
+                headers: {
+                    "xi-api-key": this.apiKey(),
+                    "content-type": "application/json",
+                    accept: "audio/mpeg",
+                    "user-agent": "threenative-asset-mcp",
+                },
+                body: JSON.stringify({
+                    text: normalized.text,
+                    duration_seconds: normalized.duration_seconds,
+                    loop: normalized.loop,
+                    prompt_influence: normalized.prompt_influence,
+                    model_id: normalized.model_id,
+                }),
+            });
+        }
+        catch (error) {
+            // We asked and never learned the answer, so we must assume it may have been billed.
+            await markUnknown(receiptPath);
+            throw new AudioGenerateError(isTimeout(error) ? "AUDIO_GENERATE_TIMEOUT" : "AUDIO_GENERATE_UPSTREAM", "The generation request did not complete and its outcome is unknown; this requestId will not be retried.");
+        }
+        if (!response.ok) {
+            // A refusal is a definite non-charge answer, so the reservation can simply be cleared.
+            await rm(receiptPath, { force: true });
+            throw sanitizedUpstream(response.status);
+        }
+        const providerRequestId = response.headers.get("request-id") ?? undefined;
+        const billingUnits = response.headers.get("character-cost") ?? undefined;
+        let body;
+        try {
+            body = await readCapped(response, GENERATE_LIMITS.maxResponseBytes);
+        }
+        catch (error) {
+            if (error instanceof AudioGenerateError) {
+                await rm(receiptPath, { force: true });
+                throw error;
+            }
+            await markUnknown(receiptPath);
+            throw new AudioGenerateError("AUDIO_GENERATE_UPSTREAM", "The generated audio could not be read completely and its outcome is unknown.");
+        }
+        if (body.byteLength === 0) {
+            await markUnknown(receiptPath);
+            throw new AudioGenerateError("AUDIO_GENERATE_UPSTREAM", "The provider returned no audio; the outcome of this request is unknown.");
+        }
+        return {
+            body,
+            ...(providerRequestId === undefined ? {} : { providerRequestId }),
+            ...(billingUnits === undefined ? {} : { billingUnits }),
+        };
+    }
+    /**
+     * Decode to PCM16 WAV with no resampling, no downmix, no normalization and no trimming. Turning
+     * MP3 into WAV does not restore what the encoder threw away, and pretending otherwise by
+     * "cleaning up" here would hide the defect the inspection exists to find.
+     */
+    async toWav(sourcePath, wavPath) {
+        const temporary = `${wavPath}.partial`;
+        await new Promise((done, fail) => {
+            execFile(this.ffmpegPath, ["-v", "error", "-y", "-i", sourcePath, "-c:a", "pcm_s16le", "-f", "wav", temporary], { timeout: GENERATE_LIMITS.timeoutMs, maxBuffer: 1024 * 1024 }, (error) => error
+                ? fail(new AudioGenerateError("AUDIO_GENERATE_CONVERT_FAILED", "The saved audio could not be decoded to WAV. The original response is kept.", true))
+                : done());
+        });
+        await rename(temporary, wavPath);
+    }
+}
+function normalize(request) {
+    const text = typeof request.prompt === "string" ? request.prompt.trim() : "";
+    if (text.length === 0 || text.length > GENERATE_LIMITS.maxPromptChars) {
+        throw new AudioGenerateError("AUDIO_GENERATE_INVALID_INPUT", `The prompt must be between 1 and ${String(GENERATE_LIMITS.maxPromptChars)} characters.`);
+    }
+    const duration = request.durationSeconds ?? 5;
+    if (!Number.isFinite(duration) ||
+        duration < GENERATE_LIMITS.minDurationSeconds ||
+        duration > GENERATE_LIMITS.maxDurationSeconds) {
+        throw new AudioGenerateError("AUDIO_GENERATE_INVALID_INPUT", `durationSeconds must be between ${String(GENERATE_LIMITS.minDurationSeconds)} and ${String(GENERATE_LIMITS.maxDurationSeconds)}.`);
+    }
+    const influence = request.promptInfluence ?? 0.3;
+    if (!Number.isFinite(influence) || influence < 0 || influence > 1) {
+        throw new AudioGenerateError("AUDIO_GENERATE_INVALID_INPUT", "promptInfluence must be between 0 and 1.");
+    }
+    // Generation owns these three; a caller who also sets them in `inspection` is contradicting itself.
+    const conflicting = request.inspection;
+    for (const key of ["loop", "expectedDurationSeconds", "expectedPrompt", "path"]) {
+        if (conflicting && key in conflicting) {
+            throw new AudioGenerateError("AUDIO_GENERATE_INVALID_INPUT", `inspection.${key} is supplied by generation itself and must not be set.`);
+        }
+    }
+    return {
+        text,
+        duration_seconds: duration,
+        loop: request.loop ?? false,
+        prompt_influence: influence,
+        model_id: MODEL_ID,
+        output_format: OUTPUT_FORMAT,
+    };
+}
+/** Provider error bodies and headers never reach the caller; only a category does. */
+function sanitizedUpstream(status) {
+    if (status === 401 || status === 403) {
+        return new AudioGenerateError("AUDIO_GENERATE_AUTH_FAILED", "ElevenLabs rejected the API key. Ask the user to check their own ELEVENLABS_API_KEY; nothing was saved.");
+    }
+    if (status === 429) {
+        return new AudioGenerateError("AUDIO_GENERATE_RATE_LIMITED", "ElevenLabs rate-limited or refused the request for quota reasons; nothing was saved.", true);
+    }
+    if (status === 422 || status === 400) {
+        return new AudioGenerateError("AUDIO_GENERATE_REJECTED", "ElevenLabs rejected the request parameters; nothing was saved.");
+    }
+    return new AudioGenerateError("AUDIO_GENERATE_UPSTREAM", `ElevenLabs returned an error (HTTP ${String(status)}); nothing was saved.`, status >= 500);
+}
+async function readCapped(response, cap) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > cap) {
+        throw new AudioGenerateError("AUDIO_GENERATE_TOO_LARGE", "The provider's audio response exceeds the size cap; nothing was saved.");
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return new Uint8Array(await response.arrayBuffer());
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value) {
+            total += value.byteLength;
+            if (total > cap) {
+                // Stop pulling bytes we have already decided to refuse.
+                await reader.cancel();
+                throw new AudioGenerateError("AUDIO_GENERATE_TOO_LARGE", "The provider's audio response exceeds the size cap; nothing was saved.");
+            }
+            chunks.push(value);
+        }
+    }
+    const body = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return body;
+}
+function isTimeout(error) {
+    return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+async function markUnknown(receiptPath) {
+    const receipt = await readReceipt(receiptPath);
+    if (!receipt)
+        return;
+    await writeReceipt(receiptPath, { ...receipt, state: "outcome_unknown" });
+}
+async function readReceipt(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeReceipt(path, receipt) {
+    const temporary = `${path}.partial`;
+    await writeFile(temporary, JSON.stringify(receipt, null, 2), { mode: 0o600 });
+    await rename(temporary, path);
+}
+async function writeExclusive(path, bytes) {
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=generate.js.map