@atomic-chat/core 0.5.1

package/dist/runtime/shared/ports.js

@@ -0,0 +1,45 @@
+/**
+ * Session port selection and the per-session API key. Port of `generate_random_port` in
+ * `src-tauri/utils/src/network.rs` and `generate_api_key` in the plugin's `commands.rs`.
+ */
+import { createHmac, randomInt } from 'node:crypto';
+import { createServer } from 'node:net';
+export const PORT_RANGE_MIN = 3000;
+export const PORT_RANGE_MAX = 4000; // exclusive
+export const PORT_MAX_ATTEMPTS = 20000;
+export const PORT_EXHAUSTED_MESSAGE = 'Failed to find an available port for the model to load';
+/** Bind-and-release probe on 127.0.0.1 (inherently racy, as in the original). */
+export function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = createServer();
+        server.once('error', () => resolve(false));
+        server.listen(port, '127.0.0.1', () => server.close(() => resolve(true)));
+    });
+}
+/** A random port in [3000, 4000) that no session uses and that binds. */
+export async function randomFreePort(usedPorts, opts = {}) {
+    const used = new Set(usedPorts);
+    const min = opts.min ?? PORT_RANGE_MIN;
+    const max = opts.max ?? PORT_RANGE_MAX;
+    const attempts = opts.attempts ?? PORT_MAX_ATTEMPTS;
+    const random = opts.random ?? ((lo, hi) => randomInt(lo, hi));
+    const isAvailable = opts.isAvailable ?? isPortAvailable;
+    for (let i = 0; i < attempts; i++) {
+        const port = random(min, max);
+        if (used.has(port))
+            continue;
+        if (await isAvailable(port))
+            return port;
+    }
+    throw new Error(PORT_EXHAUSTED_MESSAGE);
+}
+/** Secret the extension has always used for session keys (`index.ts:531`). */
+export const DEFAULT_API_SECRET = 'JustAskNow';
+/**
+ * base64(HMAC-SHA256(secret, modelId + port)) — what the process gets as `LLAMA_API_KEY`. The
+ * extension concatenates the port onto the model id before calling the Rust HMAC (`index.ts:3195`).
+ */
+export function generateApiKey(modelId, port, secret = DEFAULT_API_SECRET) {
+    return createHmac('sha256', secret).update(`${modelId}${port}`).digest('base64');
+}
+//# sourceMappingURL=ports.js.map

package/dist/runtime/shared/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/runtime/shared/ports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAClC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA,CAAC,YAAY;AAC/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAA;AACtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,wDAAwD,CAAA;AAE9F,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;QAC7B,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAA;QAC1C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3E,CAAC,CAAC,CAAA;AACJ,CAAC;AAUD,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,SAA2B,EAAE,OAAoB,EAAE;IACtF,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAA;IAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,cAAc,CAAA;IACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,cAAc,CAAA;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,iBAAiB,CAAA;IACnD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAA;IAC7D,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,eAAe,CAAA;IACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;QAC7B,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAQ;QAC5B,IAAI,MAAM,WAAW,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;IAC1C,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAA;AACzC,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAA;AAE9C;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,IAAqB,EACrB,SAAiB,kBAAkB;IAEnC,OAAO,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,GAAG,OAAO,GAAG,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;AAClF,CAAC"}

package/dist/runtime/shared/process.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Spawn a backend process and wait until it is ready. Port of the process half of
+ * `load_llama_model_impl` (`commands.rs`) and `process.rs` in the llama.cpp plugin; MLX and
+ * Foundation Models reuse it with their own ready markers and no `/health` poll.
+ *
+ * Readiness = a stdout/stderr line whose lowercase form contains one of `readyMarkers`, OR the
+ * injected `healthCheck` reporting success (polled every 200 ms). An early exit is classified by the
+ * caller-provided `classifyExit`; a timeout kills the child and raises `MODEL_LOAD_TIMED_OUT`.
+ *
+ * Two signals can stop a start, and they mean different things. `signal` is the owner shutting
+ * down: the child gets a grace period and the caller sees `CORE_NOT_RUNNING`. `cancelSignal` is the
+ * user cancelling this load: the child is killed at once, so its memory is back before the error
+ * reaches anyone, and the caller sees `MODEL_LOAD_CANCELLED`.
+ */
+import type { ChildProcess } from 'node:child_process';
+import { AtomicCoreError } from '../../contracts/index.js';
+import type { ExitInfo } from '../llamacpp/index.js';
+/** Substrings (lowercase) that mean llama-server's HTTP server is up; stable across upstream rewordings. */
+export declare const LLAMA_READY_MARKERS: string[];
+export declare function isReadyLogLine(lineLower: string, markers?: readonly string[]): boolean;
+export interface SpawnSpec {
+    exe: string;
+    args: string[];
+    env: Record<string, string>;
+    cwd?: string | undefined;
+}
+export interface ReadyOptions {
+    timeoutMs: number;
+    /** Cancel process startup (owner shutdown); the child is terminated before rejection. */
+    signal?: AbortSignal;
+    /** The user cancelled this load: kill the child immediately and raise `MODEL_LOAD_CANCELLED`. */
+    cancelSignal?: AbortSignal;
+    readyMarkers?: readonly string[];
+    /** Poll for readiness (e.g. `GET /health` → 2xx); omitted for backends without a health route. */
+    healthCheck?: () => Promise<boolean>;
+    healthIntervalMs?: number;
+    onLine?: (stream: 'stdout' | 'stderr', line: string) => void;
+    /** Turn an early exit into the error the caller wants. */
+    classifyExit: (exit: ExitInfo, stderr: string, stdout: string) => AtomicCoreError;
+    /** Details for the timeout error (`Timeout: Ns\n\nStderr:\n…` in the app). */
+    timeoutMessage?: string;
+    /** Build the timeout error yourself, for backends whose timeout has its own code (MLX, Foundation Models). */
+    timeoutError?: (stderr: string) => AtomicCoreError;
+    /** Grace before SIGKILL when the startup times out; 0 kills at once, as the MLX plugin does. */
+    timeoutGraceMs?: number;
+    /**
+     * A line that means the startup has already failed, before the process exits — Foundation Models
+     * writes its reason and only then exits. The child is terminated and this error is raised.
+     */
+    failOnLine?: (stream: 'stdout' | 'stderr', line: string) => AtomicCoreError | undefined;
+    /** Separate readiness markers per stream, when a backend says "ready" differently on each (MLX). */
+    streamReadyMarkers?: {
+        stdout: readonly string[];
+        stderr: readonly string[];
+    };
+}
+export interface ManagedProcess {
+    child: ChildProcess;
+    pid: number;
+    /** Resolves when the process exits (never rejects). */
+    exited: Promise<ExitInfo>;
+    /** SIGTERM → wait `graceMs` → SIGKILL on unix; `kill()` (TerminateProcess) on Windows. */
+    terminate: (graceMs?: number) => Promise<ExitInfo>;
+    /** Everything the process wrote so far (kept for later classification). */
+    output: () => {
+        stdout: string;
+        stderr: string;
+    };
+    /** Set when the process could not be started at all (ENOENT, EACCES, …). */
+    spawnFailure: () => Error | undefined;
+}
+export declare const DEFAULT_TERMINATE_GRACE_MS = 5000;
+/**
+ * What a caller that reads the output itself asks for
+ * (ADR 2026-09-17-spawnmanaged-reports-raw-chunks-and-can-skip-capturing-output).
+ */
+export interface SpawnHooks {
+    /**
+     * Raw bytes as they arrive, before any line splitting. For a process that redraws a line in place
+     * (`\r…ESC[K`): a reader keyed on line ends sees every redraw one step late.
+     */
+    onData?: (stream: 'stdout' | 'stderr', chunk: Buffer) => void;
+    /** `false` keeps nothing: `output()` stays empty. For a verbose process that runs for hours. */
+    captureOutput?: boolean;
+}
+/** Spawn without waiting; used by `spawnAndAwaitReady` and by probes that just want output. */
+export declare function spawnManaged(spec: SpawnSpec, onLine?: ReadyOptions['onLine'], hooks?: SpawnHooks): ManagedProcess;
+export interface SpawnReadyResult {
+    process: ManagedProcess;
+    /** Which signal reported readiness. */
+    readyVia: 'log' | 'health';
+}
+export declare function spawnAndAwaitReady(spec: SpawnSpec, opts: ReadyOptions): Promise<SpawnReadyResult>;
+/** `kill(pid, 0)` liveness probe. */
+export declare function isProcessAlive(pid: number): boolean;

package/dist/runtime/shared/process.js

@@ -0,0 +1,224 @@
+/**
+ * Spawn a backend process and wait until it is ready. Port of the process half of
+ * `load_llama_model_impl` (`commands.rs`) and `process.rs` in the llama.cpp plugin; MLX and
+ * Foundation Models reuse it with their own ready markers and no `/health` poll.
+ *
+ * Readiness = a stdout/stderr line whose lowercase form contains one of `readyMarkers`, OR the
+ * injected `healthCheck` reporting success (polled every 200 ms). An early exit is classified by the
+ * caller-provided `classifyExit`; a timeout kills the child and raises `MODEL_LOAD_TIMED_OUT`.
+ *
+ * Two signals can stop a start, and they mean different things. `signal` is the owner shutting
+ * down: the child gets a grace period and the caller sees `CORE_NOT_RUNNING`. `cancelSignal` is the
+ * user cancelling this load: the child is killed at once, so its memory is back before the error
+ * reaches anyone, and the caller sees `MODEL_LOAD_CANCELLED`.
+ */
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { loadCancelledError } from './load-cancel.js';
+/** Substrings (lowercase) that mean llama-server's HTTP server is up; stable across upstream rewordings. */
+export const LLAMA_READY_MARKERS = [
+    'listening on',
+    'all slots are idle',
+    'starting the main loop',
+    'http server listening',
+];
+export function isReadyLogLine(lineLower, markers = LLAMA_READY_MARKERS) {
+    return markers.some((m) => lineLower.includes(m));
+}
+export const DEFAULT_TERMINATE_GRACE_MS = 5000;
+function exitInfo(code, signal) {
+    return { code, signal };
+}
+/** Spawn without waiting; used by `spawnAndAwaitReady` and by probes that just want output. */
+export function spawnManaged(spec, onLine, hooks = {}) {
+    const child = spawn(spec.exe, spec.args, {
+        env: spec.env,
+        cwd: spec.cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    const capture = hooks.captureOutput !== false;
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    const wire = (stream) => {
+        const src = stream === 'stdout' ? child.stdout : child.stderr;
+        if (!src)
+            return;
+        const { onData } = hooks;
+        if (onData)
+            src.on('data', (chunk) => onData(stream, chunk));
+        // Nobody wants lines: leave the pipe to `onData`, or drain it so the child never blocks on a full one.
+        if (!capture && !onLine) {
+            if (!onData)
+                src.resume();
+            return;
+        }
+        const rl = createInterface({ input: src, crlfDelay: Infinity });
+        rl.on('line', (raw) => {
+            const line = raw.replace(/\s+$/, '');
+            if (line === '')
+                return;
+            if (capture) {
+                if (stream === 'stdout')
+                    stdoutBuf += line + '\n';
+                else
+                    stderrBuf += line + '\n';
+            }
+            onLine?.(stream, line);
+        });
+    };
+    wire('stdout');
+    wire('stderr');
+    let spawnFailure;
+    const exited = new Promise((resolve) => {
+        child.once('exit', (code, signal) => resolve(exitInfo(code, signal)));
+        child.once('error', (e) => {
+            spawnFailure = e;
+            resolve(exitInfo(null, null));
+        });
+    });
+    const terminate = async (graceMs = DEFAULT_TERMINATE_GRACE_MS) => {
+        if (child.exitCode !== null || child.signalCode !== null)
+            return exited;
+        if (process.platform === 'win32') {
+            child.kill();
+            return exited;
+        }
+        if (graceMs <= 0) {
+            child.kill('SIGKILL');
+            return exited;
+        }
+        child.kill('SIGTERM');
+        const timer = new Promise((r) => setTimeout(() => r('timeout'), graceMs).unref());
+        const outcome = await Promise.race([exited, timer]);
+        if (outcome === 'timeout') {
+            child.kill('SIGKILL');
+            return exited;
+        }
+        return outcome;
+    };
+    return {
+        child,
+        pid: child.pid ?? -1,
+        exited,
+        terminate,
+        output: () => ({ stdout: stdoutBuf, stderr: stderrBuf }),
+        spawnFailure: () => spawnFailure,
+    };
+}
+export async function spawnAndAwaitReady(spec, opts) {
+    if (opts.signal?.aborted)
+        throw new AtomicCoreError('CORE_NOT_RUNNING', 'The runtime stopped before the process could start.');
+    if (opts.cancelSignal?.aborted)
+        throw loadCancelledError();
+    const markers = opts.readyMarkers ?? LLAMA_READY_MARKERS;
+    let resolveReady;
+    const ready = new Promise((r) => (resolveReady = r));
+    let resolveFailed;
+    const failed = new Promise((r) => (resolveFailed = r));
+    const proc = spawnManaged(spec, (stream, line) => {
+        opts.onLine?.(stream, line);
+        const failure = opts.failOnLine?.(stream, line);
+        if (failure)
+            resolveFailed?.(failure);
+        const streamMarkers = opts.streamReadyMarkers ? opts.streamReadyMarkers[stream] : markers;
+        if (isReadyLogLine(line.toLowerCase(), streamMarkers))
+            resolveReady?.('log');
+    });
+    let healthTimer;
+    let healthStopped = false;
+    const stopHealth = () => {
+        healthStopped = true;
+        if (healthTimer)
+            clearTimeout(healthTimer);
+    };
+    if (opts.healthCheck) {
+        const interval = opts.healthIntervalMs ?? 200;
+        const poll = async () => {
+            if (healthStopped)
+                return;
+            try {
+                if (await opts.healthCheck()) {
+                    resolveReady?.('health');
+                    return;
+                }
+            }
+            catch {
+                // not ready yet
+            }
+            if (!healthStopped)
+                healthTimer = setTimeout(poll, interval);
+        };
+        healthTimer = setTimeout(poll, interval);
+    }
+    const timeout = new Promise((r) => setTimeout(() => r('timeout'), opts.timeoutMs).unref());
+    let resolveAbort;
+    const aborted = new Promise((resolve) => {
+        resolveAbort = () => resolve('aborted');
+        opts.signal?.addEventListener('abort', resolveAbort, { once: true });
+    });
+    let resolveCancel;
+    const cancelled = new Promise((resolve) => {
+        resolveCancel = () => resolve('cancelled');
+        opts.cancelSignal?.addEventListener('abort', resolveCancel, { once: true });
+    });
+    try {
+        const outcome = await Promise.race([
+            ready.then((via) => ({ kind: 'ready', via })),
+            proc.exited.then((exit) => ({ kind: 'exit', exit })),
+            timeout.then(() => ({ kind: 'timeout' })),
+            aborted.then(() => ({ kind: 'aborted' })),
+            cancelled.then(() => ({ kind: 'cancelled' })),
+            failed.then((error) => ({ kind: 'failed', error })),
+        ]);
+        if (outcome.kind === 'ready')
+            return { process: proc, readyVia: outcome.via };
+        if (outcome.kind === 'exit') {
+            // A process that never started (ENOENT, EACCES, …) also settles `exited`.
+            const failure = proc.spawnFailure();
+            if (failure)
+                throw new AtomicCoreError('IO_ERROR', 'An input/output error occurred.', failure.message);
+            // Give the pipes a tick to flush their last lines before classifying.
+            await new Promise((r) => setTimeout(r, 10));
+            const { stdout, stderr } = proc.output();
+            if (outcome.exit.code === 0 && outcome.exit.signal === null) {
+                // Exited cleanly without ever reporting ready.
+                throw opts.classifyExit({ code: 0, signal: null }, stderr, stdout);
+            }
+            throw opts.classifyExit(outcome.exit, stderr, stdout);
+        }
+        // A cancel frees the memory now: no grace, and the error is raised only once the child is gone.
+        const graceMs = outcome.kind === 'cancelled' ? 0 : outcome.kind === 'timeout' ? (opts.timeoutGraceMs ?? 1000) : 1000;
+        await proc.terminate(graceMs);
+        if (outcome.kind === 'cancelled')
+            throw loadCancelledError();
+        if (outcome.kind === 'failed')
+            throw outcome.error;
+        if (outcome.kind === 'aborted') {
+            throw new AtomicCoreError('CORE_NOT_RUNNING', 'The runtime stopped while the process was starting.');
+        }
+        const { stderr } = proc.output();
+        if (opts.timeoutError)
+            throw opts.timeoutError(stderr);
+        throw new AtomicCoreError('MODEL_LOAD_TIMED_OUT', opts.timeoutMessage ?? 'The model took too long to load and timed out.', `Timeout: ${Math.round(opts.timeoutMs / 1000)}s\n\nStderr:\n${stderr}`);
+    }
+    finally {
+        stopHealth();
+        if (resolveAbort)
+            opts.signal?.removeEventListener('abort', resolveAbort);
+        if (resolveCancel)
+            opts.cancelSignal?.removeEventListener('abort', resolveCancel);
+    }
+}
+/** `kill(pid, 0)` liveness probe. */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+//# sourceMappingURL=process.js.map

package/dist/runtime/shared/process.js.map

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

package/dist/runtime/shared/sidecar.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The session table of a sidecar runtime — MLX and Foundation Models: engines the core starts as
+ * one process per model and does not plan arguments for beyond a handful of flags.
+ *
+ * It holds what the llama.cpp runtime guarantees, in one place, so both sidecars keep it:
+ *  - one load at a time for the provider, and a second request for a model already loading joins it
+ *    (the MLX plugin's global load mutex; Foundation Models had none and could start two servers);
+ *  - every spawned process is journalled before it can be forgotten, so a crashed owner leaves a
+ *    trail the next owner can clean up and the app's reaper spares it;
+ *  - a session exists only while its process does. Neither plugin watched its process: a crashed
+ *    server stayed in the table until a chat request found the dead port. The table removes it on
+ *    exit and emits `session:died`, which the app already listens for per provider;
+ *  - a load the user cancels stops wherever it is — waiting for its turn, waiting on an unload,
+ *    joined to another load, or about to be published — and never lets the load behind it start
+ *    while the one ahead is still running.
+ */
+import type { WriteStream } from 'node:fs';
+import type { CoreEvents, LocalProviderId, SessionInfo, UnloadResult } from '../../contracts/index.js';
+import type { ProcessJournal } from '../../lock/index.js';
+import type { ExitInfo } from '../llamacpp/index.js';
+import type { ManagedProcess } from './process.js';
+export type EmitFn = <K extends keyof CoreEvents>(name: K, payload: CoreEvents[K]) => void;
+export interface SidecarSession<Extra = unknown> {
+    info: SessionInfo;
+    process: ManagedProcess;
+    exe: string;
+    /** What the runtime needs to remember about a session (its context size, its drafter…). */
+    extra: Extra;
+    logStream?: WriteStream | undefined;
+    journalled: boolean;
+}
+export interface SidecarTableOptions {
+    provider: LocalProviderId;
+    instanceId: string;
+    journal?: ProcessJournal | undefined;
+    emit: EmitFn;
+    /** Human wording of an unexpected exit, for `session:died`. */
+    describeExit: (exit: ExitInfo, stderr: string, stdout: string) => string;
+    /** SIGTERM grace on unload (both plugins: 5 s). */
+    unloadGraceMs: number;
+    /** SIGTERM grace when the owner shuts down (both plugins' exit cleanup: 2 s). */
+    shutdownGraceMs: number;
+    /** Engine name for messages. */
+    engine: string;
+}
+export declare class SidecarTable<Extra = unknown> {
+    private readonly options;
+    private readonly sessions;
+    private readonly loading;
+    private readonly unloading;
+    private loadTail;
+    private closing;
+    private readonly shutdownController;
+    constructor(options: SidecarTableOptions);
+    /** Aborts a process that is still starting when the owner shuts down. */
+    get signal(): AbortSignal;
+    get isClosing(): boolean;
+    list(): SessionInfo[];
+    get(modelId: string): SidecarSession<Extra> | undefined;
+    findSession(modelId: string): SessionInfo | undefined;
+    getLoadedModels(): string[];
+    isLoading(modelId: string): boolean;
+    /** Ports sessions already hold, so a new load never picks one of them. */
+    usedPorts(): number[];
+    /** In-flight loads other than this model's, which an auto-unload must wait for. */
+    otherLoads(modelId: string): Promise<SessionInfo>[];
+    /**
+     * Load through the provider's single queue, or join the load already in flight for this model.
+     * An already-loaded model answers with its session without queueing. `signal` is the user's
+     * cancel: it ends the wait at once, wherever the load is waiting.
+     */
+    load(modelId: string, operation: () => Promise<SessionInfo>, signal?: AbortSignal): Promise<SessionInfo>;
+    /**
+     * Record a process that reported ready, and start watching it. Terminates it if that fails — or
+     * if the user cancelled while it was coming up: a cancel that raced the ready signal still wins,
+     * so no session is published for it.
+     */
+    adopt(session: Omit<SidecarSession<Extra>, 'journalled'>, signal?: AbortSignal): Promise<SessionInfo>;
+    private journal;
+    private watchExit;
+    /** Stop one session. Unloading something that is not loaded is not an error. */
+    unload(modelId: string, graceMs?: number): Promise<UnloadResult>;
+    private unloadAfterLoading;
+    shutdown(): Promise<void>;
+    assertRunning(): void;
+}