@atomic-chat/core 0.19.1 → 0.20.6

package/dist/audio/server-process.js

@@ -0,0 +1,202 @@
+/**
+ * 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 { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../contracts/index.js';
+import { OutputRecords } from '../diffusion/index.js';
+import { diagnosticTail } from '../diffusion/index.js';
+import { backendOutputReporter, buildProcessEnv, discoverCudaPaths, nodeCudaProbeEnv, randomFreePort, retryOnTakenPort, spawnManaged, } from '../runtime/shared/index.js';
+import { audioChildEnv, buildAudioServerArgs } from './args.js';
+import { buildCapabilities, parseServedModels, parseVoiceList } from './capabilities.js';
+import { buildServerConfig } from './config.js';
+import { audioError, audioIoError } from './errors.js';
+import { audioServerBinaryName } from './install.js';
+import { audioEarlyExitError, describeAudioExit, exitedOnTakenAudioPort, readModelFact } from './output.js';
+export const HEALTH_PATH = '/health';
+export const MODELS_PATH = '/v1/models?include_params=true';
+export const VOICES_PATH = '/v1/audio/voices';
+export const READY_POLL_INTERVAL_MS = 300;
+export const READY_REQUEST_TIMEOUT_MS = 2_000;
+export const PROBE_TIMEOUT_MS = 10_000;
+/** SIGTERM → this long → SIGKILL. */
+export const TERMINATE_GRACE_MS = 5_000;
+/** How many output lines a server keeps for its own post-mortem. */
+export const TAIL_CAPACITY = 200;
+/** The file the core writes the server's config to, under `<data>/audio/run`. */
+export const SERVER_CONFIG_FILE = 'server.json';
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 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 async function spawnAudioServer(spec, deps) {
+    return retryOnTakenPort(() => spawnOnce(spec, deps), (error) => error instanceof AtomicCoreError &&
+        error.code === 'MODEL_LOAD_FAILED' &&
+        exitedOnTakenAudioPort(error.details), (attempt) => deps.log?.('warn', `audiocpp_server's port was taken while it started; retrying (${attempt})`));
+}
+async function spawnOnce(spec, deps) {
+    const platform = deps.platform ?? process.platform;
+    const baseEnv = deps.env ?? process.env;
+    const log = deps.log ?? (() => { });
+    const exe = join(spec.binaryDir, audioServerBinaryName(platform));
+    const isFile = await stat(exe).then((s) => s.isFile(), () => false);
+    if (!isFile)
+        throw audioError('ENGINE_MISSING', 'The audio engine is not installed.', `missing binary: ${exe}`);
+    for (const dir of [deps.runDir, deps.tmpDir])
+        await mkdir(dir, { recursive: true }).catch((error) => {
+            throw audioIoError('Could not create the audio folders.', error);
+        });
+    const port = await (deps.freePort ?? (() => randomFreePort([])))().catch((error) => {
+        throw audioError('INTERNAL', 'No free port for audiocpp_server.', error instanceof Error ? error.message : String(error));
+    });
+    const configFile = join(deps.runDir, SERVER_CONFIG_FILE);
+    await writeFile(configFile, JSON.stringify(buildServerConfig(spec, port), null, 2)).catch((error) => {
+        throw audioIoError('Could not write the audio server config.', error);
+    });
+    const args = buildAudioServerArgs(configFile, port, spec.backend, spec.threads);
+    log('info', `starting audiocpp_server: ${args.join(' ')}`);
+    log('debug', `launch tag=${spec.tag} backend=${spec.backendId} binary=${exe} model=${spec.modelPath}`);
+    const { env } = buildProcessEnv({
+        platform,
+        baseEnv,
+        exeDir: spec.binaryDir,
+        cuda: discoverCudaPaths(nodeCudaProbeEnv(platform, baseEnv)),
+        userEnv: audioChildEnv(platform, deps.tmpDir),
+    });
+    const tail = [];
+    const facts = {};
+    const records = { stdout: new OutputRecords(), stderr: new OutputRecords() };
+    const reportOutput = backendOutputReporter(deps.backendOutput, deps.log);
+    const deliver = (stream, lines) => {
+        for (const line of lines) {
+            reportOutput({ provider: 'audio-cpp', model: spec.modelId, stream, line });
+            if (tail.length >= TAIL_CAPACITY)
+                tail.shift();
+            tail.push(line);
+            readModelFact(facts, line);
+        }
+    };
+    // The build's own folder is the working directory on every platform: its runtime DLLs sit there.
+    const proc = spawnManaged({ exe, args, env, cwd: spec.binaryDir, platform }, undefined, {
+        captureOutput: false,
+        onData: (stream, chunk) => deliver(stream, records[stream].push(chunk)),
+    });
+    const flushed = proc.exited.then((exit) => {
+        for (const stream of ['stdout', 'stderr'])
+            deliver(stream, records[stream].finish());
+        return exit;
+    });
+    let exit;
+    void flushed.then((e) => (exit = e));
+    const handle = {
+        pid: proc.pid,
+        port,
+        exe,
+        capabilities: {
+            modelId: spec.modelId,
+            mode: spec.mode,
+            family: spec.family,
+            task: spec.task,
+            params: [],
+            voices: [],
+            supportsVoiceRef: false,
+            requiresVoiceRef: false,
+        },
+        tail: () => [...tail],
+        exitStatus: () => exit,
+        exited: flushed,
+        terminate: (graceMs = TERMINATE_GRACE_MS) => proc.terminate(graceMs).then(() => flushed),
+    };
+    try {
+        await deps.onSpawned?.(proc.pid, port, exe);
+    }
+    catch (error) {
+        await handle.terminate(0);
+        throw error;
+    }
+    try {
+        await awaitReady(spec, handle, proc, tail, facts, deps, exe);
+    }
+    catch (error) {
+        await deps.onGone?.(proc.pid);
+        throw error;
+    }
+    return handle;
+}
+async function awaitReady(spec, handle, proc, tail, facts, deps, exe) {
+    const log = deps.log ?? (() => { });
+    const sleep = deps.sleep ?? defaultSleep;
+    const abandon = async (graceMs, error) => {
+        await handle.terminate(graceMs);
+        throw error;
+    };
+    const url = `http://127.0.0.1:${handle.port}`;
+    const deadline = Date.now() + spec.startupTimeoutMs;
+    for (;;) {
+        if (deps.signal?.aborted)
+            await abandon(0, audioError('CANCELLED', 'The audio model load was stopped.'));
+        const spawnFailure = proc.spawnFailure();
+        if (spawnFailure)
+            throw audioError('MODEL_LOAD_FAILED', 'audiocpp_server could not be started.', `${exe}: ${spawnFailure.message}`);
+        const exit = handle.exitStatus();
+        if (exit !== undefined) {
+            // Give the pipes a moment to flush the final lines.
+            await sleep(100);
+            const error = audioEarlyExitError(exit, tail);
+            log('warn', `audiocpp_server exited early (${describeAudioExit(exit)}):\n${error.details ?? ''}`);
+            throw error;
+        }
+        if (Date.now() >= deadline)
+            await abandon(TERMINATE_GRACE_MS, audioError('MODEL_LOAD_FAILED', `The audio model did not finish loading within ${Math.round(spec.startupTimeoutMs / 1000)} seconds.`, diagnosticTail(tail)));
+        const ready = await deps.http.get(`${url}${HEALTH_PATH}`, { timeoutMs: READY_REQUEST_TIMEOUT_MS }).then((response) => response.status === 200, () => false);
+        if (ready)
+            break;
+        await sleep(deps.readyPollIntervalMs ?? READY_POLL_INTERVAL_MS);
+    }
+    const foreign = (why) => abandon(TERMINATE_GRACE_MS, audioError('MODEL_LOAD_FAILED', "Another process answered on the audio server's port.", why));
+    const listing = await deps.http
+        .get(`${url}${MODELS_PATH}`, { timeoutMs: PROBE_TIMEOUT_MS })
+        .catch((error) => foreign(`${MODELS_PATH}: ${error instanceof Error ? error.message : String(error)}`));
+    let body;
+    try {
+        body = JSON.parse(listing.body.toString('utf8'));
+    }
+    catch {
+        body = undefined;
+    }
+    if (listing.status !== 200 || body === undefined)
+        await foreign(`${MODELS_PATH} answered ${listing.status}: the listener is not audio.cpp`);
+    const served = parseServedModels(body).find((model) => model.id === spec.modelId);
+    if (!served)
+        return foreign(`${MODELS_PATH} does not list ${spec.modelId}: the listener is not our audio.cpp`);
+    if (served.family !== spec.family || served.task !== spec.task)
+        await abandon(TERMINATE_GRACE_MS, audioError('MODEL_INCOMPATIBLE', 'The audio engine serves this model as something else.', `family=${served.family} task=${served.task}; wanted family=${spec.family} task=${spec.task}`));
+    if (!served.loaded)
+        await abandon(TERMINATE_GRACE_MS, audioError('MODEL_LOAD_FAILED', 'The audio engine listed the model without loading it.', spec.modelId));
+    // A voice list beyond what `voice_id` declares: read only when the declaration has none.
+    let listedVoices = [];
+    const voiceParam = served.params.find((param) => param.name === 'voice_id');
+    if (spec.mode === 'speech' && !(voiceParam?.values && voiceParam.values.length > 0)) {
+        const voices = await deps.http
+            .get(`${url}${VOICES_PATH}?model=${encodeURIComponent(spec.modelId)}`, { timeoutMs: PROBE_TIMEOUT_MS })
+            .catch(() => undefined);
+        if (voices?.status === 200) {
+            try {
+                listedVoices = parseVoiceList(JSON.parse(voices.body.toString('utf8')));
+            }
+            catch {
+                log('warn', 'the voice list was not JSON');
+            }
+        }
+    }
+    handle.capabilities = buildCapabilities(spec, served, facts, listedVoices);
+}
+//# sourceMappingURL=server-process.js.map

package/dist/audio/server-process.js.map

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

package/dist/audio/service.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The audio-generation service: one resident `audiocpp_server` for the loaded model, jobs against it,
+ * the gallery and the model files, and what the engine-builds module and GPU residency need of it.
+ * The shape of image generation's `DiffusionService`, much smaller.
+ */
+import type { AudioPaths } from '../config/index.js';
+import type { AudioCancelResult, AudioCapabilities, AudioConfig, AudioGalleryListOptions, AudioGalleryPage, AudioGenerateRequest, AudioJob, AudioMode, AudioModelFile, AudioStatus, LoadAudioModelRequest, LoadedAudioModel } from '../contracts/index.js';
+import type { EngineHost } from '../engine-builds/service.js';
+import type { AudioSpeechBackend } from '../server/index.js';
+import type { BackendOutputSink, GpuClaimHook, GpuOccupancy } from '../runtime/shared/index.js';
+import type { AudioHttpClient } from './http.js';
+import type { AudioJobOutcome, AudioJobTimings } from './jobs.js';
+import type { AudioEmitter, AudioLogger } from './session.js';
+import { AudioState } from './state.js';
+import type { AudioServerHandle, AudioServerSpec } from './types.js';
+export interface AudioServiceDeps {
+    paths: AudioPaths;
+    emit: AudioEmitter;
+    log: AudioLogger;
+    /** The child journal: written right after the spawn, cleared when the server is gone. */
+    journal?: {
+        add(pid: number, port: number, exe: string, modelId: string): Promise<void>;
+        remove(pid: number): Promise<void>;
+    };
+    http?: AudioHttpClient;
+    /** Every stdout/stderr line `audiocpp_server` prints, for the life of the session. */
+    backendOutput?: BackendOutputSink;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    timings?: Partial<AudioJobTimings>;
+    idleTickMs?: number;
+    /**
+     * Core's GPU residency: asked before every `audiocpp_server` spawn — a load, a respawn after a
+     * cancel or a crash — to free the GPU of the other engines. Absent, nothing is asked.
+     */
+    claimGpu?: GpuClaimHook;
+    /** Test seams. */
+    spawn?: (spec: AudioServerSpec, signal?: AbortSignal) => Promise<AudioServerHandle>;
+    drawSeed?: () => number;
+}
+export declare class AudioService {
+    readonly state: AudioState;
+    private readonly deps;
+    private readonly platform;
+    private readonly env;
+    private readonly idleTickMs;
+    private idle;
+    /** Stops a load still waiting for its model when the model is unloaded or the core shuts down. */
+    private loading;
+    /** GPU claims in flight, a load's or a respawn's; an unload aborts them rather than wait behind them. */
+    private readonly claims;
+    /** Unloads asked for and not finished: a GPU claim that starts meanwhile gives up at once. */
+    private unloadRequests;
+    constructor(options: AudioServiceDeps);
+    /** Arm the idle timer. */
+    start(): void;
+    /** Optional settings: the output folder (`null` restores `<data>/audios`) and the idle unload. */
+    config(config: AudioConfig): Promise<AudioStatus>;
+    status(): Promise<AudioStatus>;
+    /** The gallery folder; an empty path restores `<data>/audios`. */
+    setOutputDir(path: string): Promise<AudioStatus>;
+    /**
+     * What the engine-builds module needs of audio generation: the load lock, the build directories in
+     * use, and the activation of a new build — cancel the running job, unload a model whose build the
+     * new one replaces (`engine-updated`), report the install.
+     */
+    engineHost(): EngineHost;
+    /**
+     * The GPU the resident, stopping or starting `audiocpp_server` holds, for core's residency rule. The
+     * resident or starting one is `busy` while a job runs on it that nobody asked to cancel: residency
+     * then refuses a chat load (`GPU_BUSY`) instead of stopping the clip.
+     */
+    gpuOccupancy(): GpuOccupancy[];
+    /** What the active job is making on `spec`; none when no job is live. */
+    private working;
+    /** The session's claim hook over core's: abortable by an unload, whatever signal the caller had. */
+    private claimGpu;
+    listModelFiles(): Promise<AudioModelFile[]>;
+    /** Delete a file named relative to `<data>/audio/models`; the loaded model's own file is refused. */
+    deleteModelFile(relativePath: string): Promise<void>;
+    /** Answers once the server serves the model. One load at a time; a load replaces the resident model. */
+    loadModel(request: LoadAudioModelRequest): Promise<LoadedAudioModel>;
+    /** What a load runs: the newest installed build, the model file checked. */
+    private specFor;
+    unloadModel(): Promise<void>;
+    /** Reset the idle-unload deadline without generating. */
+    touchIdle(): void;
+    capabilities(): AudioCapabilities;
+    /** Start a job; answers it at once, its phases and outcome arrive as `audio:job` events. */
+    generate(mode: AudioMode, request: AudioGenerateRequest): Promise<AudioJob>;
+    /** Run one job to completion and answer the clip. */
+    runJob(mode: AudioMode, request: AudioGenerateRequest): Promise<AudioJobOutcome>;
+    /**
+     * What `POST /v1/audio/speech` needs: the loaded model and what it makes, and a speech job started
+     * the way `runJob` starts one — same validation, events, gallery and idle timer — but answered with
+     * its id at once, so a client that hangs up can have it cancelled.
+     */
+    speechBackend(): AudioSpeechBackend;
+    getJob(id: string): AudioJob | null;
+    cancelJob(id: string): Promise<AudioCancelResult>;
+    gallery(options: AudioGalleryListOptions): Promise<AudioGalleryPage>;
+    deleteGalleryItem(id: string): Promise<void>;
+    /** Owner exit: an `audiocpp_server` must not outlive the core. No events, a short grace. */
+    shutdown(): Promise<void>;
+}