@atomic-chat/core 0.19.1 → 0.20.6

package/dist/audio/parse.js

@@ -0,0 +1,149 @@
+/**
+ * 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 { AUDIO_MODES, AUDIO_TASKS } from '../contracts/index.js';
+import { audioError } from './errors.js';
+function invalid(field, expected) {
+    throw audioError('INVALID_REQUEST', 'The request is not valid.', `${field}: expected ${expected}`);
+}
+function fields(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        invalid(field, 'an object');
+    return value;
+}
+/** `undefined` for a field that is absent or `null`. */
+function present(source, key) {
+    const value = source[key];
+    return value === null ? undefined : value;
+}
+function string(value, field) {
+    if (typeof value !== 'string')
+        invalid(field, 'a string');
+    return value;
+}
+function nonEmpty(value, field) {
+    if (typeof value !== 'string' || value.trim() === '')
+        invalid(field, 'a non-empty string');
+    return value;
+}
+function number(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        invalid(field, 'a number');
+    return value;
+}
+function positive(value, field) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)
+        invalid(field, 'a number above zero');
+    return value;
+}
+function integer(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value))
+        invalid(field, 'a whole number');
+    return value;
+}
+function positiveInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0)
+        invalid(field, 'a whole number above zero');
+    return value;
+}
+function wholeNumber(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0)
+        invalid(field, 'a whole number, zero or more');
+    return value;
+}
+function oneOf(value, field, allowed) {
+    if (typeof value !== 'string' || !allowed.includes(value))
+        invalid(field, `one of ${allowed.join(', ')}`);
+    return value;
+}
+function options(value, field) {
+    const source = fields(value, field);
+    const out = {};
+    for (const [key, entry] of Object.entries(source)) {
+        if (typeof entry !== 'string' &&
+            typeof entry !== 'boolean' &&
+            !(typeof entry === 'number' && Number.isFinite(entry)))
+            invalid(`${field}.${key}`, 'a string, a number or true/false');
+        out[key] = entry;
+    }
+    return out;
+}
+/** Set `target[key]` from `source[key]` when it is present, through `read`. */
+function copy(target, key, source, read) {
+    const value = present(source, key);
+    if (value !== undefined)
+        target[key] = read(value, key);
+}
+export function parseAudioMode(value) {
+    return oneOf(value, 'mode', AUDIO_MODES);
+}
+function audioSource(value, field) {
+    const source = fields(value, field);
+    const path = present(source, 'path');
+    const base64 = present(source, 'base64');
+    if ((path === undefined) === (base64 === undefined))
+        invalid(field, 'either a path or base64');
+    return path !== undefined
+        ? { path: nonEmpty(path, `${field}.path`) }
+        : { base64: nonEmpty(base64, `${field}.base64`) };
+}
+export function parseAudioConfig(body) {
+    const source = fields(body, 'config');
+    const config = {};
+    if ('outputDir' in source)
+        config.outputDir = source['outputDir'] === null ? null : string(source['outputDir'], 'outputDir');
+    copy(config, 'idleUnloadSecs', source, wholeNumber);
+    return config;
+}
+export function parseLoadAudioModelRequest(body) {
+    const source = fields(body, 'request');
+    const request = {
+        modelId: nonEmpty(source['modelId'], 'modelId'),
+        displayName: string(source['displayName'], 'displayName'),
+        mode: parseAudioMode(source['mode']),
+        file: nonEmpty(source['file'], 'file'),
+        family: nonEmpty(source['family'], 'family'),
+        task: oneOf(source['task'], 'task', AUDIO_TASKS),
+    };
+    copy(request, 'loadOptions', source, options);
+    copy(request, 'sessionOptions', source, options);
+    copy(request, 'defaultRequestOptions', source, options);
+    copy(request, 'defaultVoice', source, string);
+    copy(request, 'threads', source, positiveInteger);
+    copy(request, 'startupTimeoutSecs', source, positiveInteger);
+    return request;
+}
+export function parseAudioGenerateRequest(body) {
+    const source = fields(body, 'request');
+    const request = { text: nonEmpty(source['text'], 'text') };
+    copy(request, 'voice', source, string);
+    copy(request, 'voiceRef', source, audioSource);
+    copy(request, 'referenceText', source, string);
+    copy(request, 'speed', source, positive);
+    copy(request, 'language', source, string);
+    copy(request, 'instruct', source, string);
+    copy(request, 'lyrics', source, string);
+    copy(request, 'durationSec', source, number);
+    copy(request, 'bpm', source, positive);
+    copy(request, 'seed', source, integer);
+    copy(request, 'steps', source, positiveInteger);
+    copy(request, 'negativePrompt', source, string);
+    copy(request, 'options', source, options);
+    return request;
+}
+/** `POST /audio/jobs`: `{mode, request}`. */
+export function parseAudioJobSubmission(body) {
+    const source = fields(body, 'body');
+    return { mode: parseAudioMode(source['mode']), request: parseAudioGenerateRequest(source['request']) };
+}
+export function parseAudioGalleryListOptions(body) {
+    const source = fields(body, 'options');
+    return { offset: wholeNumber(source['offset'], 'offset'), limit: wholeNumber(source['limit'], 'limit') };
+}
+/** One required string out of a body, for the routes that take nothing else (`path`, `relativePath`). */
+export function requireAudioString(body, key) {
+    return string(fields(body, 'body')[key], key);
+}
+//# sourceMappingURL=parse.js.map

package/dist/audio/parse.js.map

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

package/dist/audio/recipe.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The recipe written next to every clip as `<jobId>.json`: what was asked, with which model, engine
+ * and seed, and how long the engine took. A WAV whose recipe does not parse is not ours. Pure.
+ */
+import type { AudioGenerateRequest, AudioOptions, AudioRecipe } from '../contracts/index.js';
+import type { AudioServerSpec } from './types.js';
+export interface RecipeInput {
+    jobId: string;
+    request: AudioGenerateRequest;
+    spec: AudioServerSpec;
+    seed: number;
+    /** The options sent to the engine, named fields merged in. */
+    options: AudioOptions;
+    createdAtMs: number;
+    durationMs: number;
+}
+/** The recipe of a finished job. Speech fields are `null` for music and effects, and the other way round. */
+export declare function buildAudioRecipe(input: RecipeInput): AudioRecipe;
+/** Two-space JSON with every key, `null`s included. */
+export declare function serializeAudioRecipe(recipe: AudioRecipe): string;
+/** The recipe in a sidecar's text, or `undefined` when it is not one of ours. */
+export declare function parseAudioRecipe(text: string): AudioRecipe | undefined;

package/dist/audio/recipe.js

@@ -0,0 +1,92 @@
+/**
+ * The recipe written next to every clip as `<jobId>.json`: what was asked, with which model, engine
+ * and seed, and how long the engine took. A WAV whose recipe does not parse is not ours. Pure.
+ */
+import { AUDIO_BACKENDS, AUDIO_MODES, AUDIO_TASKS } from '../contracts/index.js';
+const basename = (path) => path.split(/[\\/]/).filter(Boolean).pop() ?? path;
+/** The recipe of a finished job. Speech fields are `null` for music and effects, and the other way round. */
+export function buildAudioRecipe(input) {
+    const { request, spec } = input;
+    const speech = spec.mode === 'speech';
+    const or = (value, applies) => applies && value !== undefined ? value : null;
+    return {
+        jobId: input.jobId,
+        mode: spec.mode,
+        text: request.text,
+        voice: or(request.voice, speech),
+        voiceRef: speech && request.voiceRef !== undefined,
+        speed: or(request.speed, speech),
+        language: or(request.language, speech),
+        instruct: or(request.instruct, speech),
+        lyrics: or(request.lyrics, !speech),
+        durationSec: or(request.durationSec, !speech),
+        bpm: or(request.bpm, !speech),
+        seed: input.seed,
+        steps: or(request.steps, !speech),
+        negativePrompt: or(request.negativePrompt, !speech),
+        options: { ...input.options },
+        model: {
+            modelId: spec.modelId,
+            family: spec.family,
+            task: spec.task,
+            displayName: spec.displayName,
+            filename: basename(spec.modelPath),
+        },
+        engine: { kind: 'audio-cpp', backend: spec.backend, tag: spec.tag },
+        createdAtMs: input.createdAtMs,
+        durationMs: input.durationMs,
+    };
+}
+/** Two-space JSON with every key, `null`s included. */
+export function serializeAudioRecipe(recipe) {
+    return `${JSON.stringify(recipe, null, 2)}\n`;
+}
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const stringOrNull = (value) => value === null || typeof value === 'string';
+const numberOrNull = (value) => value === null || (typeof value === 'number' && Number.isFinite(value));
+const isOptions = (value) => isRecord(value) &&
+    Object.values(value).every((v) => typeof v === 'string' || typeof v === 'boolean' || (typeof v === 'number' && Number.isFinite(v)));
+/** The recipe in a sidecar's text, or `undefined` when it is not one of ours. */
+export function parseAudioRecipe(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isRecord(raw))
+        return undefined;
+    const model = raw['model'];
+    const engine = raw['engine'];
+    if (typeof raw['jobId'] !== 'string' ||
+        !AUDIO_MODES.includes(raw['mode']) ||
+        typeof raw['text'] !== 'string' ||
+        !stringOrNull(raw['voice']) ||
+        typeof raw['voiceRef'] !== 'boolean' ||
+        !numberOrNull(raw['speed']) ||
+        !stringOrNull(raw['language']) ||
+        !stringOrNull(raw['instruct']) ||
+        !stringOrNull(raw['lyrics']) ||
+        !numberOrNull(raw['durationSec']) ||
+        !numberOrNull(raw['bpm']) ||
+        typeof raw['seed'] !== 'number' ||
+        !numberOrNull(raw['steps']) ||
+        !stringOrNull(raw['negativePrompt']) ||
+        !isOptions(raw['options']) ||
+        !isRecord(model) ||
+        typeof model['modelId'] !== 'string' ||
+        typeof model['family'] !== 'string' ||
+        !AUDIO_TASKS.includes(model['task']) ||
+        typeof model['displayName'] !== 'string' ||
+        typeof model['filename'] !== 'string' ||
+        !isRecord(engine) ||
+        engine['kind'] !== 'audio-cpp' ||
+        !AUDIO_BACKENDS.includes(engine['backend']) ||
+        typeof engine['tag'] !== 'string' ||
+        typeof raw['createdAtMs'] !== 'number' ||
+        typeof raw['durationMs'] !== 'number')
+        return undefined;
+    return raw;
+}
+//# sourceMappingURL=recipe.js.map

package/dist/audio/recipe.js.map

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

package/dist/audio/request.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a job sends `audiocpp_server` and how its answer is read. Pure.
+ *
+ * Speech goes to `POST /v1/audio/speech` (OpenAI's shape: `input`, `voice`, `speed`, plus audio.cpp's
+ * `seed`, `language`, `voice_ref`, `reference_text` and `options`) and answers WAV bytes. Music and
+ * effects go to `POST /v1/tasks/run` (`request.text` and `request.options`) and answer JSON with the
+ * WAV as base64 `audio` — and the same bytes again under `named_audio_outputs`, which is ignored.
+ *
+ * audio.cpp refuses an option the family does not declare ("unknown … request option"), so a named
+ * field is sent only when the request sets it; it then wins over the same key in `options`. A style
+ * instruction travels as the `instruct` option (Qwen3-TTS declares it): the top-level `instructions`
+ * becomes an `instruction` option no family declares.
+ */
+import type { AudioGenerateRequest, AudioMode, AudioOptions } from '../contracts/index.js';
+export declare const SPEECH_PATH = "/v1/audio/speech";
+export declare const TASK_PATH = "/v1/tasks/run";
+/** The request's own `options`, minus every key a named field (the seed included) of `mode` sets. */
+export declare function extraOptions(mode: AudioMode, request: AudioGenerateRequest): AudioOptions;
+/** `POST /v1/audio/speech`. `voiceRef` is the reference WAV, base64. */
+export declare function buildSpeechBody(modelId: string, request: AudioGenerateRequest, seed: number, voiceRef?: string): Record<string, unknown>;
+/** `POST /v1/tasks/run` for music and effects. */
+export declare function buildTaskBody(modelId: string, request: AudioGenerateRequest, seed: number): Record<string, unknown>;
+/** The WAV of a `/v1/tasks/run` answer; `INVALID_OUTPUT` when there is none. */
+export declare function decodeTaskAudio(body: Buffer): Buffer;

package/dist/audio/request.js

@@ -0,0 +1,86 @@
+/**
+ * What a job sends `audiocpp_server` and how its answer is read. Pure.
+ *
+ * Speech goes to `POST /v1/audio/speech` (OpenAI's shape: `input`, `voice`, `speed`, plus audio.cpp's
+ * `seed`, `language`, `voice_ref`, `reference_text` and `options`) and answers WAV bytes. Music and
+ * effects go to `POST /v1/tasks/run` (`request.text` and `request.options`) and answer JSON with the
+ * WAV as base64 `audio` — and the same bytes again under `named_audio_outputs`, which is ignored.
+ *
+ * audio.cpp refuses an option the family does not declare ("unknown … request option"), so a named
+ * field is sent only when the request sets it; it then wins over the same key in `options`. A style
+ * instruction travels as the `instruct` option (Qwen3-TTS declares it): the top-level `instructions`
+ * becomes an `instruction` option no family declares.
+ */
+import { audioError } from './errors.js';
+export const SPEECH_PATH = '/v1/audio/speech';
+export const TASK_PATH = '/v1/tasks/run';
+/** The engine option each named field of a speech request stands for. */
+const SPEECH_NAMED = [
+    ['voice', 'voice_id'],
+    ['speed', 'speed'],
+    ['language', 'language'],
+    ['instruct', 'instruct'],
+    ['referenceText', 'reference_text'],
+];
+/** The engine option each named field of a music or effects request stands for. */
+const TASK_NAMED = [
+    ['durationSec', 'duration_sec'],
+    ['lyrics', 'lyrics'],
+    ['bpm', 'bpm'],
+    ['steps', 'num_inference_steps'],
+    ['negativePrompt', 'negative_prompt'],
+];
+/** The request's own `options`, minus every key a named field (the seed included) of `mode` sets. */
+export function extraOptions(mode, request) {
+    const out = { ...(request.options ?? {}) };
+    delete out['seed'];
+    for (const [field, key] of mode === 'speech' ? SPEECH_NAMED : TASK_NAMED)
+        if (request[field] !== undefined)
+            delete out[key];
+    return out;
+}
+/** `POST /v1/audio/speech`. `voiceRef` is the reference WAV, base64. */
+export function buildSpeechBody(modelId, request, seed, voiceRef) {
+    const options = extraOptions('speech', request);
+    if (request.instruct !== undefined)
+        options['instruct'] = request.instruct;
+    const body = { model: modelId, input: request.text, seed };
+    if (request.voice !== undefined)
+        body['voice'] = request.voice;
+    if (request.speed !== undefined)
+        body['speed'] = request.speed;
+    if (request.language !== undefined)
+        body['language'] = request.language;
+    if (voiceRef !== undefined)
+        body['voice_ref'] = { type: 'base64', data: voiceRef };
+    if (request.referenceText !== undefined)
+        body['reference_text'] = request.referenceText;
+    if (Object.keys(options).length > 0)
+        body['options'] = options;
+    return body;
+}
+/** `POST /v1/tasks/run` for music and effects. */
+export function buildTaskBody(modelId, request, seed) {
+    const options = { ...extraOptions('music', request), seed };
+    for (const [field, key] of TASK_NAMED) {
+        const value = request[field];
+        if (typeof value === 'string' || typeof value === 'number')
+            options[key] = value;
+    }
+    return { model: modelId, request: { text: request.text, options } };
+}
+/** The WAV of a `/v1/tasks/run` answer; `INVALID_OUTPUT` when there is none. */
+export function decodeTaskAudio(body) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString('utf8'));
+    }
+    catch (error) {
+        throw audioError('INVALID_OUTPUT', 'The audio engine answered with something that is not JSON.', error instanceof Error ? error.message : String(error));
+    }
+    const audio = parsed?.audio;
+    if (typeof audio !== 'string' || audio === '')
+        throw audioError('INVALID_OUTPUT', 'The audio engine answered without audio.');
+    return Buffer.from(audio, 'base64');
+}
+//# sourceMappingURL=request.js.map

package/dist/audio/request.js.map

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

package/dist/audio/server-process.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Spawning and supervising `audiocpp_server` for one model.
+ *
+ * Readiness is real: with `lazy_load: false` audio.cpp loads the model before it binds the port, so a
+ * 200 from `GET /health` means the model is loaded, and a load failure exits the process before it
+ * listens (`audiocpp_server failed: …`). `/health` is a route other servers answer too, so the model
+ * listing is read next: it must name our model with the family and task the load asked for, loaded —
+ * otherwise the port belongs to someone else, or the engine serves something else.
+ */
+import type { BackendOutputSink } from '../runtime/shared/index.js';
+import type { AudioHttpClient } from './http.js';
+import type { AudioServerHandle, AudioServerSpec } from './types.js';
+export declare const HEALTH_PATH = "/health";
+export declare const MODELS_PATH = "/v1/models?include_params=true";
+export declare const VOICES_PATH = "/v1/audio/voices";
+export declare const READY_POLL_INTERVAL_MS = 300;
+export declare const READY_REQUEST_TIMEOUT_MS = 2000;
+export declare const PROBE_TIMEOUT_MS = 10000;
+/** SIGTERM → this long → SIGKILL. */
+export declare const TERMINATE_GRACE_MS = 5000;
+/** How many output lines a server keeps for its own post-mortem. */
+export declare const TAIL_CAPACITY = 200;
+/** The file the core writes the server's config to, under `<data>/audio/run`. */
+export declare const SERVER_CONFIG_FILE = "server.json";
+export interface SpawnAudioServerDeps {
+    http: AudioHttpClient;
+    /** `<data>/audio/run`: where `server.json` is written. */
+    runDir: string;
+    /** `<data>/audio/tmp`: the child's `TMPDIR`. */
+    tmpDir: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    log?: (level: 'info' | 'warn' | 'debug', msg: string) => void;
+    /** Every stdout/stderr line the server prints, for the life of the session. */
+    backendOutput?: BackendOutputSink;
+    /** Called with the child right after it started, before readiness: the journal entry goes here. */
+    onSpawned?: (pid: number, port: number, exe: string) => Promise<void>;
+    /** Called when a child that `onSpawned` saw is dead and will never become a session. */
+    onGone?: (pid: number) => Promise<void>;
+    /** Stops a load still waiting for the model (an unload or a shutdown); the child is killed. */
+    signal?: AbortSignal;
+    freePort?: () => Promise<number>;
+    readyPollIntervalMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Spawn `audiocpp_server` for `spec`, wait until it serves the model, and read what it declares. On
+ * any failure the child is dead when this rejects. A start that died because its port was taken
+ * before the engine could bind it goes again on another port.
+ */
+export declare function spawnAudioServer(spec: AudioServerSpec, deps: SpawnAudioServerDeps): Promise<AudioServerHandle>;