@atomic-chat/core 0.19.1 → 0.20.6

package/dist/audio/jobs.js

@@ -0,0 +1,340 @@
+/**
+ * Jobs: validate, send to `audiocpp_server`, save, and the cancel path. One job at a time; the
+ * request is synchronous (audio.cpp has no job API), so a job moves through phases only —
+ * `queued`, `loading` while a server stopped by a cancel or a crash comes back, `generating` while
+ * the engine runs, `saving` while the clip is written — each one an `audio:job` event.
+ *
+ * Cancel: audio.cpp cannot interrupt a running request and goes on generating after a JSON client
+ * hangs up, so a cancel aborts the request and stops the process, keeping the spec; the next job
+ * respawns the server from it. A job not generating yet just ends.
+ */
+import { randomInt, randomUUID } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import { audioError, audioErrorBody, audioInternalError } from './errors.js';
+import { AudioTimeoutError } from './http.js';
+import { audioCrashError, engineErrorMessage, engineRejection } from './output.js';
+import { buildAudioRecipe } from './recipe.js';
+import { buildSpeechBody, buildTaskBody, decodeTaskAudio, extraOptions, SPEECH_PATH, TASK_PATH, } from './request.js';
+import { emitAudioError, loadFromSpec, modelNotLoadedError, stopKeepingSpec, takeDownSession, } from './session.js';
+import { isTerminalAudioJobState } from './state.js';
+import { MAX_VOICE_REF_BYTES } from './types.js';
+import { parseWav, stripAudioDataUrl } from './wav.js';
+export const DEFAULT_AUDIO_JOB_TIMINGS = {
+    generationCeilingMs: 6 * 60 * 60 * 1000,
+    exitWaitMs: 1_000,
+};
+export function drawAudioSeed() {
+    return randomInt(0, 0x8000_0000);
+}
+const cancelledError = () => audioError('CANCELLED', 'The job was cancelled.');
+/** A reference voice file, read whole once it is known to be small enough. */
+export async function readVoiceRefFile(path, maxBytes) {
+    const meta = await stat(path).catch(() => undefined);
+    if (!meta || !meta.isFile())
+        throw audioError('INVALID_REQUEST', 'The reference voice file was not found.', path);
+    if (meta.size > maxBytes)
+        throw audioError('INVALID_REQUEST', 'The reference voice is larger than 5 MiB.', `${meta.size} bytes`);
+    return readFile(path).catch((error) => {
+        throw audioError('INVALID_REQUEST', 'The reference voice file could not be read.', error instanceof Error ? error.message : String(error));
+    });
+}
+/** The reference voice as the engine takes it: a WAV of at most 5 MiB, base64. */
+export async function resolveVoiceRef(source, readSource) {
+    let bytes;
+    if ('path' in source)
+        bytes = await readSource(source.path, MAX_VOICE_REF_BYTES);
+    else {
+        const payload = stripAudioDataUrl(source.base64);
+        // Refused before it is decoded: four characters carry three bytes.
+        if (Math.floor((payload.length * 3) / 4) > MAX_VOICE_REF_BYTES + 2)
+            throw audioError('INVALID_REQUEST', 'The reference voice is larger than 5 MiB.', `${payload.length} base64 characters`);
+        bytes = Buffer.from(payload, 'base64');
+        if (bytes.length > MAX_VOICE_REF_BYTES)
+            throw audioError('INVALID_REQUEST', 'The reference voice is larger than 5 MiB.', `${bytes.length} bytes`);
+    }
+    if (!parseWav(bytes))
+        throw audioError('INVALID_REQUEST', 'The reference voice is not a WAV file.');
+    return bytes.toString('base64');
+}
+/** The request as the job record keeps it: inline audio bytes blanked, file paths kept. */
+export function withoutInlineAudio(request) {
+    const copy = structuredClone(request);
+    if (copy.voiceRef && 'base64' in copy.voiceRef)
+        copy.voiceRef = { base64: '' };
+    return copy;
+}
+const MODE_WORDS = {
+    speech: 'speech',
+    music: 'music',
+    effects: 'sound effects',
+};
+// ---------------------------------------------------------------------------
+// Job bookkeeping
+// ---------------------------------------------------------------------------
+function emitJob(deps, id) {
+    const job = deps.state.job(id);
+    if (job)
+        deps.emit('audio:job', { job });
+}
+/** Move a job to `phase` (and to `generating` with it), never out of a terminal state. */
+export function setJobPhase(deps, id, phase) {
+    let changed = false;
+    deps.state.updateJob(id, (job) => {
+        if (isTerminalAudioJobState(job.state))
+            return;
+        const now = deps.now();
+        job.progress = { phase, elapsedMs: now - job.createdAtMs };
+        if ((phase === 'generating' || phase === 'saving') && job.state === 'queued') {
+            job.state = 'generating';
+            job.startedAtMs = now;
+        }
+        changed = true;
+    });
+    if (changed)
+        emitJob(deps, id);
+}
+/** Move a job to a terminal state exactly once. Whether this call made the transition. */
+export function finishAudioJob(deps, id, result) {
+    let transitioned = false;
+    deps.state.updateJob(id, (job) => {
+        if (isTerminalAudioJobState(job.state))
+            return;
+        transitioned = true;
+        const now = deps.now();
+        job.finishedAtMs = now;
+        if (job.progress)
+            job.progress = { ...job.progress, elapsedMs: now - job.createdAtMs };
+        if (result.ok) {
+            job.state = 'completed';
+            job.output = result.item;
+            delete job.error;
+        }
+        else {
+            job.state = result.error.code === 'CANCELLED' ? 'cancelled' : 'failed';
+            job.error = result.error;
+        }
+    });
+    if (transitioned) {
+        if (deps.state.activeJobId === id)
+            deps.state.activeJobId = undefined;
+        emitJob(deps, id);
+    }
+    return transitioned;
+}
+// ---------------------------------------------------------------------------
+// Entry points
+// ---------------------------------------------------------------------------
+/** Validate, register and start a job in `mode` on the loaded model. */
+export async function startAudioJob(deps, mode, request) {
+    const { state } = deps;
+    if (state.closing)
+        throw audioError('ENGINE_CRASHED', 'The audio engine is shutting down.');
+    const spec = state.spec;
+    if (!spec)
+        throw modelNotLoadedError();
+    if (spec.mode !== mode)
+        throw audioError('UNSUPPORTED_MODE', `The loaded model makes ${MODE_WORDS[spec.mode]}, not ${MODE_WORDS[mode]}.`, `${spec.modelId}: ${spec.mode}`);
+    if (request.text.trim() === '')
+        throw audioError('INVALID_REQUEST', 'Say what to make.');
+    const busy = () => {
+        if (state.activeJobId !== undefined)
+            throw audioError('JOB_BUSY', 'Another clip is being made. Wait for it, or stop it.', state.activeJobId);
+    };
+    busy();
+    const speech = mode === 'speech';
+    if (speech && request.voiceRef === undefined && state.capabilities?.requiresVoiceRef === true)
+        throw audioError('INVALID_REQUEST', 'This voice model speaks only in a cloned voice: add a reference voice.');
+    const voiceRef = speech && request.voiceRef !== undefined
+        ? await resolveVoiceRef(request.voiceRef, deps.readSource)
+        : undefined;
+    // Reading the reference took a moment: another job may have started meanwhile.
+    busy();
+    const id = randomUUID().replaceAll('-', '');
+    state.activeJobId = id;
+    state.clearIdle();
+    const createdAtMs = deps.now();
+    const record = {
+        job: {
+            id,
+            state: 'queued',
+            mode,
+            modelId: spec.modelId,
+            request: withoutInlineAudio(request),
+            createdAtMs,
+            progress: { phase: 'queued', elapsedMs: 0 },
+            output: null,
+        },
+        cancel: { requested: false, abort: new AbortController() },
+    };
+    state.insertJob(record);
+    emitJob(deps, id);
+    const done = execute(deps, id, mode, request, voiceRef, record).then((outcome) => {
+        finishAudioJob(deps, id, { ok: true, item: outcome.item });
+        state.touchIdle();
+        const job = state.job(id);
+        return { ok: true, outcome: { job, item: outcome.item, wav: outcome.wav } };
+    }, (raw) => {
+        const error = audioErrorBody(raw);
+        finishAudioJob(deps, id, { ok: false, error });
+        state.touchIdle();
+        if (error.code !== 'CANCELLED')
+            emitAudioError(deps, id, error);
+        // The record is authoritative: a cancel that raced the runner may already have marked it.
+        return { ok: false, error: state.job(id)?.error ?? error };
+    });
+    record.done = done;
+    return { job: state.job(id), done };
+}
+/** Run one job to completion; the path a caller that awaits the clip takes. */
+export async function runAudioJob(deps, mode, request) {
+    const { done } = await startAudioJob(deps, mode, request);
+    const result = await done;
+    if (result.ok)
+        return result.outcome;
+    throw audioError(result.error.code, result.error.message, result.error.details);
+}
+/** The resident session, respawned from the kept spec when a cancel or a crash took the server down. */
+async function ensureSession(deps, id, record) {
+    const { state } = deps;
+    const view = () => {
+        const session = state.session;
+        return session && session.server.exitStatus() === undefined
+            ? { baseUrl: session.baseUrl, spec: session.spec, server: session.server }
+            : undefined;
+    };
+    const alive = view();
+    if (alive)
+        return alive;
+    if (record.cancel.requested)
+        throw cancelledError();
+    setJobPhase(deps, id, 'loading');
+    await deps.loadLock.run(async () => {
+        // Once the lock is held the job may be cancelled, the model unloaded or replaced, or the server
+        // already back: the spec is read only now.
+        if (record.cancel.requested)
+            throw cancelledError();
+        if (state.closing)
+            throw audioError('ENGINE_CRASHED', 'The audio engine is shutting down.');
+        if (view())
+            return;
+        const current = state.spec;
+        if (!current)
+            throw modelNotLoadedError();
+        await takeDownSession(deps);
+        await loadFromSpec(deps, current, 'respawn', record.cancel.abort.signal);
+    });
+    const back = view();
+    if (!back)
+        throw audioError('ENGINE_CRASHED', 'The audio engine went away right after starting.');
+    return back;
+}
+async function execute(deps, id, mode, request, voiceRef, record) {
+    const { state, timings } = deps;
+    const seed = request.seed !== undefined && request.seed >= 0 ? request.seed : deps.drawSeed();
+    const view = await ensureSession(deps, id, record);
+    if (record.cancel.requested)
+        throw cancelledError();
+    const speech = mode === 'speech';
+    const body = speech
+        ? buildSpeechBody(view.spec.modelId, request, seed, voiceRef)
+        : buildTaskBody(view.spec.modelId, request, seed);
+    setJobPhase(deps, id, 'generating');
+    const started = deps.now();
+    let response;
+    try {
+        response = await deps.http.post(`${view.baseUrl}${speech ? SPEECH_PATH : TASK_PATH}`, body, {
+            timeoutMs: timings.generationCeilingMs,
+            signal: record.cancel.abort.signal,
+        });
+    }
+    catch (error) {
+        return afterTransportError(deps, record, view, error);
+    }
+    const durationMs = deps.now() - started;
+    if (record.cancel.requested)
+        throw cancelledError();
+    if (response.status === 503)
+        throw audioError('JOB_BUSY', 'The audio engine is busy with another request.', engineErrorMessage(response.body.toString('utf8')));
+    if (response.status !== 200)
+        throw engineRejection(response.status, response.body.toString('utf8'));
+    const wav = speech ? response.body : decodeTaskAudio(response.body);
+    if (!parseWav(wav))
+        throw audioError('INVALID_OUTPUT', 'The audio engine returned something that is not a WAV.', response.contentType);
+    setJobPhase(deps, id, 'saving');
+    if (record.cancel.requested)
+        throw cancelledError();
+    const options = extraOptions(mode, request);
+    if (speech && request.instruct !== undefined)
+        options['instruct'] = request.instruct;
+    const recipe = buildAudioRecipe({
+        jobId: id,
+        request,
+        spec: view.spec,
+        seed,
+        options,
+        createdAtMs: record.job.createdAtMs,
+        durationMs,
+    });
+    const item = await deps.gallery.save(state.outputDir(), recipe, wav);
+    return { item, wav };
+}
+/**
+ * The request to the engine failed without an answer. A cancel is a cancel; past the ceiling the
+ * server is stopped; otherwise the server crashed or dropped the connection, and is stopped too —
+ * keeping the spec, so the next job brings it back.
+ */
+async function afterTransportError(deps, record, view, raw) {
+    if (record.cancel.requested)
+        throw cancelledError();
+    const reason = raw instanceof Error ? raw.message : String(raw);
+    const ours = () => deps.state.session?.server === view.server;
+    if (raw instanceof AudioTimeoutError) {
+        const error = audioInternalError(`Generation exceeded ${Math.round(deps.timings.generationCeilingMs / 3_600_000)} hours and was stopped.`, reason);
+        if (ours())
+            await stopKeepingSpec(deps, 'timeout', audioErrorBody(error));
+        throw error;
+    }
+    const exit = view.server.exitStatus() ??
+        (await Promise.race([view.server.exited, deps.sleep(deps.timings.exitWaitMs).then(() => undefined)]));
+    const error = exit
+        ? audioCrashError(exit, view.server.tail())
+        : audioError('ENGINE_CRASHED', 'The audio engine dropped the connection while generating.', reason);
+    deps.log('warn', `audio job failed: ${error.message} (${error.details ?? reason})`);
+    if (ours())
+        await stopKeepingSpec(deps, 'crashed', audioErrorBody(error));
+    throw error;
+}
+// ---------------------------------------------------------------------------
+// Cancel
+// ---------------------------------------------------------------------------
+/**
+ * Cancel a job. While the engine generates, the request is aborted and the server stopped (the spec
+ * stays, so the next job respawns it); a clip already being saved is kept. Before that the job ends
+ * here and now: its runner may be waiting for the load lock to respawn the server, and the caller may
+ * hold that lock (a load, an unload, an engine update), so nothing here waits for the runner then.
+ */
+export async function cancelAudioJob(deps, id) {
+    const { state } = deps;
+    const record = state.record(id);
+    if (!record)
+        throw audioError('JOB_NOT_FOUND', 'That job no longer exists.');
+    if (isTerminalAudioJobState(record.job.state))
+        return { cancelled: record.job.state === 'cancelled', serverStopped: false };
+    record.cancel.requested = true;
+    const generating = record.job.progress?.phase === 'generating';
+    record.cancel.abort.abort();
+    if (generating) {
+        deps.log('info', 'cancelling an audio job: stopping audiocpp_server, which cannot interrupt a request');
+        await stopKeepingSpec(deps, 'cancelled');
+        finishAudioJob(deps, id, { ok: false, error: audioErrorBody(cancelledError()) });
+        return { cancelled: true, serverStopped: true };
+    }
+    if (record.job.progress?.phase === 'saving') {
+        // The engine has answered and the clip is being written, which needs no lock.
+        await record.done;
+        return { cancelled: state.job(id)?.state === 'cancelled', serverStopped: false };
+    }
+    finishAudioJob(deps, id, { ok: false, error: audioErrorBody(cancelledError()) });
+    return { cancelled: true, serverStopped: false };
+}
+//# sourceMappingURL=jobs.js.map

package/dist/audio/jobs.js.map

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

package/dist/audio/model-files.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The models the client downloads into `<data>/audio/models` (the core never downloads one: ADR
+ * 2026-10-15-core-does-not-download-models): listed recursively without in-flight downloads, and
+ * deleted one file at a time by their path relative to that folder. The listing is image generation's.
+ */
+import type { AudioModelFile } from '../contracts/index.js';
+/** Regular files under the models root, recursively, with `/`-separated relative paths. */
+export declare function listAudioModelFiles(modelsRoot: string): Promise<AudioModelFile[]>;
+/** The absolute path of a file named relative to the models root; anything that leaves it is refused. */
+export declare function audioModelFilePath(modelsRoot: string, relativePath: string, platform?: NodeJS.Platform): Promise<string>;
+/** Delete one file under the models root, and the folders it leaves empty. A file already gone is not an error. */
+export declare function deleteAudioModelFile(modelsRoot: string, path: string, platform?: NodeJS.Platform): Promise<void>;

package/dist/audio/model-files.js

@@ -0,0 +1,42 @@
+/**
+ * The models the client downloads into `<data>/audio/models` (the core never downloads one: ADR
+ * 2026-10-15-core-does-not-download-models): listed recursively without in-flight downloads, and
+ * deleted one file at a time by their path relative to that folder. The listing is image generation's.
+ */
+import { readdir, rm, rmdir, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join } from 'node:path';
+import { listModelFiles, locate } from '../diffusion/index.js';
+import { audioError, audioIoError } from './errors.js';
+/** Regular files under the models root, recursively, with `/`-separated relative paths. */
+export function listAudioModelFiles(modelsRoot) {
+    return listModelFiles(modelsRoot);
+}
+/** The absolute path of a file named relative to the models root; anything that leaves it is refused. */
+export async function audioModelFilePath(modelsRoot, relativePath, platform = process.platform) {
+    const segments = relativePath.split(/[\\/]/).filter(Boolean);
+    if (relativePath.trim() === '' || isAbsolute(relativePath) || /^[A-Za-z]:/.test(relativePath))
+        throw audioError('INVALID_REQUEST', 'Name the model file relative to the audio models folder.', relativePath);
+    const path = join(modelsRoot, ...segments);
+    if ((await locate(path, modelsRoot, platform)) !== 'inside')
+        throw audioError('INVALID_REQUEST', 'That file is not in the audio models folder.', relativePath);
+    return path;
+}
+const isEmptyDir = (dir) => readdir(dir).then((names) => names.length === 0, () => false);
+/** Delete one file under the models root, and the folders it leaves empty. A file already gone is not an error. */
+export async function deleteAudioModelFile(modelsRoot, path, platform = process.platform) {
+    const meta = await stat(path).catch(() => undefined);
+    if (!meta)
+        return;
+    if (meta.isDirectory())
+        throw audioError('INVALID_REQUEST', 'That path is a folder, not a model file.', path);
+    await rm(path).catch((error) => {
+        throw audioIoError('Could not delete the model file.', error);
+    });
+    // Prune empty folders on the way up, never the root itself.
+    for (let dir = dirname(path);; dir = dirname(dir)) {
+        if ((await locate(dir, modelsRoot, platform)) !== 'inside' || !(await isEmptyDir(dir)))
+            break;
+        await rmdir(dir).catch(() => { });
+    }
+}
+//# sourceMappingURL=model-files.js.map

package/dist/audio/model-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-files.js","sourceRoot":"","sources":["../../src/audio/model-files.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErD,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAEtD,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,OAAO,cAAc,CAAC,UAAU,CAAC,CAAA;AACnC,CAAC;AAED,yGAAyG;AACzG,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAkB,EAClB,YAAoB,EACpB,WAA4B,OAAO,CAAC,QAAQ;IAE5C,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAC5D,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC;QAC3F,MAAM,UAAU,CACd,iBAAiB,EACjB,0DAA0D,EAC1D,YAAY,CACb,CAAA;IACH,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,GAAG,QAAQ,CAAC,CAAA;IAC1C,IAAI,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,KAAK,QAAQ;QACzD,MAAM,UAAU,CAAC,iBAAiB,EAAE,8CAA8C,EAAE,YAAY,CAAC,CAAA;IACnG,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,GAAW,EAAoB,EAAE,CACnD,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CACf,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAC7B,GAAG,EAAE,CAAC,KAAK,CACZ,CAAA;AAEH,mHAAmH;AACnH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAkB,EAClB,IAAY,EACZ,WAA4B,OAAO,CAAC,QAAQ;IAE5C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACpD,IAAI,CAAC,IAAI;QAAE,OAAM;IACjB,IAAI,IAAI,CAAC,WAAW,EAAE;QACpB,MAAM,UAAU,CAAC,iBAAiB,EAAE,0CAA0C,EAAE,IAAI,CAAC,CAAA;IACvF,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACtC,MAAM,YAAY,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAA;IAC/D,CAAC,CAAC,CAAA;IACF,4DAA4D;IAC5D,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAI,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,GAAG,CAAC,CAAC;YAAE,MAAK;QAC7F,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAClC,CAAC;AACH,CAAC"}

package/dist/audio/output.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What `audiocpp_server --log` prints, read: the model facts it traces while it loads, why it died,
+ * and the engine's own error message in an HTTP answer. Pure.
+ *
+ * audio.cpp reports no progress while it generates (only family-specific `[TIMING …]` lines), so
+ * nothing here tracks a job: a job moves through phases only.
+ */
+import type { AtomicCoreError } from '../contracts/index.js';
+import type { ExitInfo } from '../runtime/llamacpp/index.js';
+/** What the loader said about the model: `runtime.model.variant` and `supports_speaker_reference`. */
+export interface AudioModelFacts {
+    /** e.g. `0b6-base` (Qwen3-TTS Base), `Kokoro 82M`, `small` (Stable Audio). */
+    variant?: string;
+    supportsSpeakerReference?: boolean;
+}
+/** Fold one output line into `facts`; lines that say nothing about the model leave it as it is. */
+export declare function readModelFact(facts: AudioModelFacts, line: string): void;
+/** Whether a server that exited while starting did so because its port was taken. */
+export declare function exitedOnTakenAudioPort(details: string | undefined): boolean;
+/** How an exit reads in a message: `code 1`, `signal SIGKILL`, or `unknown status`. */
+export declare function describeAudioExit(exit: ExitInfo): string;
+/** The error for a server that died before it listened: out of memory when ggml said so. */
+export declare function audioEarlyExitError(exit: ExitInfo, tail: readonly string[]): AtomicCoreError;
+/** The error for a server that died while it generated. */
+export declare function audioCrashError(exit: ExitInfo, tail: readonly string[]): AtomicCoreError;
+/**
+ * The engine's words in an error answer: `{"error":{"message"}}` as audio.cpp writes it, a bare
+ * `{"error":"…"}`, or the body itself when it is not JSON. At most 1000 characters.
+ */
+export declare function engineErrorMessage(body: string): string;
+/** A refusal the engine sent while it ran a job, on the closest code: out of memory, or rejected. */
+export declare function engineRejection(status: number, body: string): AtomicCoreError;

package/dist/audio/output.js

@@ -0,0 +1,93 @@
+/**
+ * What `audiocpp_server --log` prints, read: the model facts it traces while it loads, why it died,
+ * and the engine's own error message in an HTTP answer. Pure.
+ *
+ * audio.cpp reports no progress while it generates (only family-specific `[TIMING …]` lines), so
+ * nothing here tracks a job: a job moves through phases only.
+ */
+import { classifyExit, diagnosticTail } from '../diffusion/index.js';
+import { audioError } from './errors.js';
+/** `[TRACE ts=…] runtime.model.<key> <value>`: the facts the loader traces about the model. */
+const MODEL_FACT = /\]\s+runtime\.model\.(variant|supports_speaker_reference)\s+(.*)$/;
+/** What `audiocpp_server` prints when its port was taken before it could bind it. */
+const PORT_TAKEN = /could not bind|address already in use|EADDRINUSE/i;
+/** Fold one output line into `facts`; lines that say nothing about the model leave it as it is. */
+export function readModelFact(facts, line) {
+    const match = MODEL_FACT.exec(line);
+    if (!match)
+        return;
+    const value = (match[2] ?? '').trim();
+    if (match[1] === 'variant')
+        facts.variant = value;
+    else
+        facts.supportsSpeakerReference = value === '1' || value.toLowerCase() === 'true';
+}
+/** Whether a server that exited while starting did so because its port was taken. */
+export function exitedOnTakenAudioPort(details) {
+    return details !== undefined && PORT_TAKEN.test(details);
+}
+/** How an exit reads in a message: `code 1`, `signal SIGKILL`, or `unknown status`. */
+export function describeAudioExit(exit) {
+    if (exit.code !== null)
+        return `code ${exit.code}`;
+    if (exit.signal !== null)
+        return `signal ${String(exit.signal)}`;
+    return 'unknown status';
+}
+/** The exit code, or `128 + signal` for a signal the classifier knows by number (SIGKILL → 137). */
+function exitCodeOf(exit) {
+    if (exit.code !== null)
+        return exit.code;
+    if (typeof exit.signal === 'number')
+        return 128 + exit.signal;
+    if (exit.signal === 'SIGKILL')
+        return 137;
+    return undefined;
+}
+/** The error for a server that died before it listened: out of memory when ggml said so. */
+export function audioEarlyExitError(exit, tail) {
+    const text = diagnosticTail(tail);
+    if (classifyExit(text, exitCodeOf(exit)) === 'OUT_OF_MEMORY')
+        return audioError('OUT_OF_MEMORY', 'The audio model ran out of memory while loading.', text);
+    return audioError('MODEL_LOAD_FAILED', `audiocpp_server exited with ${describeAudioExit(exit)} while loading.`, text);
+}
+/** The error for a server that died while it generated. */
+export function audioCrashError(exit, tail) {
+    const text = diagnosticTail(tail);
+    if (classifyExit(text, exitCodeOf(exit)) === 'OUT_OF_MEMORY')
+        return audioError('OUT_OF_MEMORY', 'The audio engine ran out of memory while generating.', text);
+    return audioError('ENGINE_CRASHED', `The audio engine stopped while generating (${describeAudioExit(exit)}).`, text);
+}
+/**
+ * The engine's words in an error answer: `{"error":{"message"}}` as audio.cpp writes it, a bare
+ * `{"error":"…"}`, or the body itself when it is not JSON. At most 1000 characters.
+ */
+export function engineErrorMessage(body) {
+    let message;
+    try {
+        const parsed = JSON.parse(body);
+        const error = parsed?.error;
+        if (typeof error === 'string')
+            message = error;
+        else if (error !== null && typeof error === 'object') {
+            const inner = error.message;
+            if (typeof inner === 'string')
+                message = inner;
+        }
+        else if (typeof parsed?.message === 'string')
+            message = parsed.message;
+    }
+    catch {
+        // Not JSON: the body is the message.
+    }
+    return [...(message ?? body).trim()].slice(0, 1000).join('');
+}
+/** A refusal the engine sent while it ran a job, on the closest code: out of memory, or rejected. */
+export function engineRejection(status, body) {
+    const message = engineErrorMessage(body);
+    const details = message === '' ? `HTTP ${status}` : message;
+    if (classifyExit(message, undefined) === 'OUT_OF_MEMORY')
+        return audioError('OUT_OF_MEMORY', 'The audio engine ran out of memory while generating.', details);
+    return audioError('REQUEST_REJECTED', 'The audio engine refused the request.', details);
+}
+//# sourceMappingURL=output.js.map

package/dist/audio/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/audio/output.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,+FAA+F;AAC/F,MAAM,UAAU,GAAG,mEAAmE,CAAA;AACtF,qFAAqF;AACrF,MAAM,UAAU,GAAG,mDAAmD,CAAA;AAStE,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,KAAsB,EAAE,IAAY;IAChE,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnC,IAAI,CAAC,KAAK;QAAE,OAAM;IAClB,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAA;IACrC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAA;;QAC5C,KAAK,CAAC,wBAAwB,GAAG,KAAK,KAAK,GAAG,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,MAAM,CAAA;AACvF,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,sBAAsB,CAAC,OAA2B;IAChE,OAAO,OAAO,KAAK,SAAS,IAAI,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AAC1D,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAA;IAClD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,UAAU,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;IAChE,OAAO,gBAAgB,CAAA;AACzB,CAAC;AAED,oGAAoG;AACpG,SAAS,UAAU,CAAC,IAAc;IAChC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,IAAI,CAAA;IACxC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,GAAG,GAAG,IAAI,CAAC,MAAM,CAAA;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,GAAG,CAAA;IACzC,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,IAAc,EAAE,IAAuB;IACzE,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,eAAe;QAC1D,OAAO,UAAU,CAAC,eAAe,EAAE,kDAAkD,EAAE,IAAI,CAAC,CAAA;IAC9F,OAAO,UAAU,CACf,mBAAmB,EACnB,+BAA+B,iBAAiB,CAAC,IAAI,CAAC,iBAAiB,EACvE,IAAI,CACL,CAAA;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,IAAuB;IACrE,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACjC,IAAI,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,eAAe;QAC1D,OAAO,UAAU,CAAC,eAAe,EAAE,sDAAsD,EAAE,IAAI,CAAC,CAAA;IAClG,OAAO,UAAU,CACf,gBAAgB,EAChB,8CAA8C,iBAAiB,CAAC,IAAI,CAAC,IAAI,EACzE,IAAI,CACL,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,OAA2B,CAAA;IAC/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA2C,CAAA;QACzE,MAAM,KAAK,GAAG,MAAM,EAAE,KAAK,CAAA;QAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,GAAG,KAAK,CAAA;aACzC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrD,MAAM,KAAK,GAAI,KAA+B,CAAC,OAAO,CAAA;YACtD,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,GAAG,KAAK,CAAA;QAChD,CAAC;aAAM,IAAI,OAAO,MAAM,EAAE,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAC1E,CAAC;IAAC,MAAM,CAAC;QACP,qCAAqC;IACvC,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AAC9D,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,IAAY;IAC1D,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;IACxC,MAAM,OAAO,GAAG,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,MAAM,EAAE,CAAC,CAAC,CAAC,OAAO,CAAA;IAC3D,IAAI,YAAY,CAAC,OAAO,EAAE,SAAS,CAAC,KAAK,eAAe;QACtD,OAAO,UAAU,CAAC,eAAe,EAAE,sDAAsD,EAAE,OAAO,CAAC,CAAA;IACrG,OAAO,UAAU,CAAC,kBAAkB,EAAE,uCAAuC,EAAE,OAAO,CAAC,CAAA;AACzF,CAAC"}

package/dist/audio/parse.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Request bodies of the audio routes, read strictly: closed enums, finite numbers, `null` taken as
+ * absent for anything optional, unknown fields ignored. A body that does not fit is `INVALID_REQUEST`,
+ * and nothing downstream has to doubt a type again (as image generation's `parse.ts`).
+ */
+import type { AudioConfig, AudioGalleryListOptions, AudioGenerateRequest, AudioJobSubmission, AudioMode, LoadAudioModelRequest } from '../contracts/index.js';
+export declare function parseAudioMode(value: unknown): AudioMode;
+export declare function parseAudioConfig(body: unknown): AudioConfig;
+export declare function parseLoadAudioModelRequest(body: unknown): LoadAudioModelRequest;
+export declare function parseAudioGenerateRequest(body: unknown): AudioGenerateRequest;
+/** `POST /audio/jobs`: `{mode, request}`. */
+export declare function parseAudioJobSubmission(body: unknown): AudioJobSubmission;
+export declare function parseAudioGalleryListOptions(body: unknown): AudioGalleryListOptions;
+/** One required string out of a body, for the routes that take nothing else (`path`, `relativePath`). */
+export declare function requireAudioString(body: unknown, key: string): string;