@atomic-chat/core 0.5.1 → 0.13.6

package/dist/runtime/wsl/guest-scope.js

@@ -0,0 +1,98 @@
+/**
+ * A Windows scope's own folder in the guest (change `add-tensorrt-llm-windows`, task 2.6, design D5):
+ * `scope_key` — a random id core makes once and keeps in the scope's data
+ * (`ManagedScopePaths.guestScopeFile`), so that copying the data folder elsewhere keeps pointing at the
+ * same guest folder and its models (spec "Перенос папки данных не перемещает модели") — and the folders
+ * under it, created as the guest's root and handed to uid 1000: the account the app writes models as
+ * through `\\wsl.localhost` and the model container runs as, so the files of both belong to one user.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { guestScopeRoot } from './guest-paths.js';
+const SCOPE_KEY = /^[A-Za-z0-9-]{1,64}$/;
+/** The account in the guest that owns a scope's files (design D5). */
+export const GUEST_SCOPE_OWNER = '1000:1000';
+/** The scope's key, made on first use. A file that does not hold a valid key is an error, never replaced. */
+export async function readOrCreateGuestScopeKey(file, newKey = randomUUID) {
+    let text = null;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (text !== null) {
+        const parsed = JSON.parse(text);
+        if (parsed.schema_version !== 1 ||
+            typeof parsed.scope_key !== 'string' ||
+            !SCOPE_KEY.test(parsed.scope_key)) {
+            throw new AtomicCoreError('MANAGED_METADATA_INVALID', 'The guest scope key file is not valid.', file);
+        }
+        return parsed.scope_key;
+    }
+    const key = newKey();
+    await mkdir(dirname(file), { recursive: true });
+    const temp = `${file}.tmp`;
+    await writeFile(temp, `${JSON.stringify({ schema_version: 1, scope_key: key })}\n`, 'utf8');
+    await rename(temp, file);
+    return key;
+}
+/** One read (or creation) of the key shared by every caller: two first callers racing would each create one. */
+export function guestScopeKeyReader(file, newKey = randomUUID) {
+    let read = null;
+    return () => {
+        read ??= readOrCreateGuestScopeKey(file, newKey).catch((error) => {
+            read = null;
+            throw error;
+        });
+        return read;
+    };
+}
+/**
+ * `managed-models`, `models/tensorrt-llm`, `caches`, `heartbeats`, `watchdog` under the scope's guest root,
+ * owned by uid 1000 — and the folders directly in `managed-models` too: the store migration creates a
+ * moved model's parent (`managed-models/<org>`) as root, and a folder root owns there refuses every
+ * later download into it through `\\wsl.localhost` (`EACCES`, Windows `os error 5`).
+ */
+export async function ensureGuestScope(transport, scopeKey) {
+    const root = guestScopeRoot(scopeKey);
+    const store = `${root}/managed-models`;
+    const leaves = [
+        store,
+        `${root}/models/tensorrt-llm`,
+        `${root}/caches`,
+        `${root}/heartbeats`,
+        `${root}/watchdog`,
+    ];
+    const run = async (argv) => {
+        const output = await transport.exec(argv, { user: 'root', timeoutMs: 120_000 });
+        if (output.code !== 0) {
+            throw new AtomicCoreError('IO_ERROR', `The model folders could not be prepared in the distribution "${transport.name}".`, `${argv.join(' ')}: ${output.stderr.trim()}`);
+        }
+    };
+    await run(['mkdir', '-p', ...leaves]);
+    // Not recursive: the folders, never every file of every model under them.
+    await run(['chown', GUEST_SCOPE_OWNER, root, `${root}/models`, ...leaves]);
+    // Only folders root owns, one level down: the model folders below them already belong to uid 1000.
+    await run([
+        'find',
+        store,
+        '-mindepth',
+        '1',
+        '-maxdepth',
+        '1',
+        '-type',
+        'd',
+        '-user',
+        'root',
+        '-exec',
+        'chown',
+        GUEST_SCOPE_OWNER,
+        '{}',
+        '+',
+    ]);
+}
+//# sourceMappingURL=guest-scope.js.map

package/dist/runtime/wsl/guest-scope.js.map

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

package/dist/runtime/wsl/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * WSL from Windows (openspec change `add-tensorrt-llm-windows`): the transport every piece of the
+ * Windows managed environment reaches Atomic Chat's own distribution through — `wsl.exe` argv with no
+ * shell, its UTF-16 output decoded, deadlines, an injectable executable, and the attached process
+ * that keeps the distribution running (design D1, D8, D16).
+ *
+ * Public API of this module is exported from this file only.
+ */
+export * from './transport.js';
+export * from './guest-paths.js';
+export * from './guest-scope.js';
+export * from './keeper.js';

package/dist/runtime/wsl/index.js

@@ -0,0 +1,13 @@
+/**
+ * WSL from Windows (openspec change `add-tensorrt-llm-windows`): the transport every piece of the
+ * Windows managed environment reaches Atomic Chat's own distribution through — `wsl.exe` argv with no
+ * shell, its UTF-16 output decoded, deadlines, an injectable executable, and the attached process
+ * that keeps the distribution running (design D1, D8, D16).
+ *
+ * Public API of this module is exported from this file only.
+ */
+export * from './transport.js';
+export * from './guest-paths.js';
+export * from './guest-scope.js';
+export * from './keeper.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/wsl/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/wsl/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA"}

package/dist/runtime/wsl/keeper.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Keeping Atomic Chat's distribution running while something needs it (change
+ * `add-tensorrt-llm-windows`, task 2.7, design D8; spec "Дистрибутив удерживается, пока он нужен").
+ * WSL stops an idle distribution on its own (`instanceIdleTimeout`, 15 s by default), and systemd
+ * services do not reliably keep it up (microsoft/WSL#13416); an attached `wsl.exe -d <name> --exec sleep
+ * infinity` does. So every user of the distribution — an environment operation, a loading or loaded
+ * model, a file operation on models — takes a lease, and one such process runs while any lease is held
+ * and none when there is none, so WSL may stop the VM and give its memory back to Windows.
+ *
+ * When the holding process ends without being released — `wsl --shutdown`, the VM crashed, a
+ * distribution not there (yet) — every subscriber hears of it (a session then ends with
+ * `wsl-stopped`), and nothing is started again on its own: a new hold would boot the VM the user just
+ * stopped, and against a distribution that does not exist it would end at once and be restarted in a
+ * loop. The next `acquire` holds again.
+ */
+import type { WslDistributionTransport } from './transport.js';
+export interface DistributionLease {
+    /** Idempotent. */
+    release(): void;
+}
+export interface DistributionKeeper {
+    /** Hold the distribution until the lease is released. `reason` only names it for diagnostics. */
+    acquire(reason: string): DistributionLease;
+    /** Whether a holding process is running now. */
+    held(): boolean;
+    /** Called when the distribution stopped under a hold. Returns the unsubscribe. */
+    onStopped(listener: () => void): () => void;
+}
+export declare function createDistributionKeeper(transport: WslDistributionTransport): DistributionKeeper;

package/dist/runtime/wsl/keeper.js

@@ -0,0 +1,48 @@
+export function createDistributionKeeper(transport) {
+    const leases = new Set();
+    const listeners = new Set();
+    let hold = null;
+    const start = () => {
+        const current = transport.hold();
+        hold = current;
+        void current.exited.then((end) => {
+            if (hold === current)
+                hold = null;
+            if (end.released)
+                return;
+            for (const listener of [...listeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    // One subscriber failing must not keep the others from hearing it.
+                }
+            }
+        });
+    };
+    return {
+        acquire: () => {
+            const lease = Symbol('lease');
+            leases.add(lease);
+            if (hold === null)
+                start();
+            return {
+                release: () => {
+                    if (!leases.delete(lease))
+                        return;
+                    if (leases.size === 0 && hold !== null) {
+                        const current = hold;
+                        hold = null;
+                        current.release();
+                    }
+                },
+            };
+        },
+        held: () => hold !== null,
+        onStopped: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+//# sourceMappingURL=keeper.js.map

package/dist/runtime/wsl/keeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keeper.js","sourceRoot":"","sources":["../../../src/runtime/wsl/keeper.ts"],"names":[],"mappings":"AA+BA,MAAM,UAAU,wBAAwB,CAAC,SAAmC;IAC1E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAA;IAChC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAc,CAAA;IACvC,IAAI,IAAI,GAAmB,IAAI,CAAA;IAE/B,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,EAAE,CAAA;QAChC,IAAI,GAAG,OAAO,CAAA;QACd,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;YAC/B,IAAI,IAAI,KAAK,OAAO;gBAAE,IAAI,GAAG,IAAI,CAAA;YACjC,IAAI,GAAG,CAAC,QAAQ;gBAAE,OAAM;YACxB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;gBACtC,IAAI,CAAC;oBACH,QAAQ,EAAE,CAAA;gBACZ,CAAC;gBAAC,MAAM,CAAC;oBACP,mEAAmE;gBACrE,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,OAAO;QACL,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;YAC7B,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACjB,IAAI,IAAI,KAAK,IAAI;gBAAE,KAAK,EAAE,CAAA;YAC1B,OAAO;gBACL,OAAO,EAAE,GAAG,EAAE;oBACZ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;wBAAE,OAAM;oBACjC,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;wBACvC,MAAM,OAAO,GAAG,IAAI,CAAA;wBACpB,IAAI,GAAG,IAAI,CAAA;wBACX,OAAO,CAAC,OAAO,EAAE,CAAA;oBACnB,CAAC;gBACH,CAAC;aACF,CAAA;QACH,CAAC;QACD,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,KAAK,IAAI;QACzB,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE;YACtB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;QACzC,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/runtime/wsl/transport.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Running things inside WSL from Windows (change `add-tensorrt-llm-windows`, task 2.2, design D1):
+ * the one place `wsl.exe` is spawned. Everything the core does in Atomic Chat's own distribution —
+ * probing the guest, running the install recipe, every docker call, the Engine API pull — goes
+ * through `exec`; `wsl.exe`'s own commands (`--list`, `--import`, `--unregister`, …) through
+ * `command`; keeping the distribution running through `hold`.
+ *
+ * Four things are deliberate.
+ *
+ * There is no shell, on either side. The command and every argument reach `spawn` as array elements,
+ * and `wsl.exe --exec` hands them to the guest's `execvp` as they are — never to `/bin/sh` — so
+ * nothing in a model path, a container name or a descriptor field is ever interpreted.
+ *
+ * Text is decoded, not assumed. `wsl.exe`'s own messages are UTF-16LE (`WSL_UTF8=1`, set on every
+ * call, asks for UTF-8, which an older WSL ignores), while a guest command's output is its own bytes,
+ * UTF-8; `decodeWslBytes` tells them apart.
+ *
+ * A command that could not answer — no `wsl.exe`, a spawn failure, past its deadline, aborted — is
+ * `code: null`, never a rejection: the same contract as `hostExec` and the docker executor, so a
+ * caller always gets one shape and reads "unknown" rather than "absent".
+ *
+ * The executable is injected. Production resolves the system `wsl.exe` from `%SystemRoot%`, never
+ * `PATH`; tests pass `process.execPath` with a fake script as `executableArgs`, which runs the same on
+ * a Windows CI runner as anywhere else (design D16).
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Every command in a distribution runs through `env` with the system `PATH`. `wsl --exec` starts the
+ * program without a shell and with a `PATH` that has no `sbin`: `useradd`, `usermod` and the like
+ * were not found there (live acceptance, `execvpe(useradd) failed: No such file or directory`).
+ * Still one argv and no shell; `env` only sets `PATH` and resolves the program against it.
+ * `/usr/lib/wsl/lib` stays on it: WSL puts `nvidia-smi` and the NVIDIA user-mode libraries there and
+ * adds that directory to the `PATH` it gives a command itself (live acceptance: without it the probe
+ * could not read the library version).
+ */
+export declare const GUEST_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/wsl/lib";
+/** What one `wsl.exe` call answered. `code: null`: it never got as far as an exit code. */
+export interface WslCommandOutput {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface WslCallOptions {
+    /** Overrides the default deadline for this call only. */
+    timeoutMs?: number;
+    /** Stops the call: it answers `code: null` and its process is killed. */
+    signal?: AbortSignal;
+    /** Written to the command's stdin, which is then closed. Without it stdin is not connected. */
+    input?: string | Buffer;
+    /** Each piece of stdout as it arrives, decoded as UTF-8 (a guest command's own bytes). */
+    onStdout?: (text: string) => void;
+}
+export interface WslExecOptions extends WslCallOptions {
+    /** `-u <user>`: the guest account to run as. The guest's default user when omitted. */
+    user?: string;
+}
+/** How a hold ended: `released` when the core let go itself, otherwise the process or the VM stopped. */
+export interface WslHoldEnd {
+    code: number | null;
+    signal: string | null;
+    released: boolean;
+}
+/** An attached `wsl.exe -d <name> --exec sleep infinity`: the distribution stays up while it lives. */
+export interface WslHold {
+    /** Resolves once, when the holding process is gone — whoever ended it. */
+    readonly exited: Promise<WslHoldEnd>;
+    /** Stop holding. Idempotent; `exited` then resolves with `released: true`. */
+    release(): void;
+}
+/** One distribution, as the core reaches it. */
+export interface WslDistributionTransport {
+    readonly name: string;
+    /** `wsl.exe -d <name> [-u <user>] --exec ...argv`. */
+    exec(argv: string[], options?: WslExecOptions): Promise<WslCommandOutput>;
+    hold(): WslHold;
+}
+export interface Wsl {
+    /** `wsl.exe ...args`: its own commands, output decoded from UTF-16 when it comes that way. */
+    command(args: string[], options?: WslCallOptions): Promise<WslCommandOutput>;
+    distribution(name: string): WslDistributionTransport;
+}
+export interface WslOptions {
+    /** The `wsl.exe` to run; `defaultWslExecutable(process.env)` when omitted. */
+    executable?: string;
+    /** Arguments placed before every call's own (a test's fake script and its state folder). */
+    executableArgs?: string[];
+    /** The environment the process starts with; `process.env` when omitted. */
+    env?: NodeJS.ProcessEnv;
+    /** Ask `wsl.exe` for UTF-8 (`WSL_UTF8=1`). On by default; a test turns it off to exercise UTF-16. */
+    utf8?: boolean;
+    /** Default deadline per call. */
+    timeoutMs?: number;
+    /** Per stream; past it the start and the end are kept (`HeadAndTail`). */
+    maxOutputBytes?: number;
+    /** Tests only: stands in for `child_process.spawn`. */
+    spawnProcess?: typeof spawn;
+}
+/** The system `wsl.exe`, from `%SystemRoot%` — never whatever `PATH` finds first. */
+export declare function defaultWslExecutable(env: Record<string, string | undefined>): string;
+/**
+ * `wsl.exe`'s own text is UTF-16LE; a guest command's is UTF-8. UTF-16 is recognised by its BOM or by
+ * NUL bytes — every ASCII character, `\r\n` included, carries one, and a guest's text output has
+ * none — so a localized message (Cyrillic, CJK) decodes as well as an English one.
+ */
+export declare function decodeWslBytes(bytes: Buffer): string;
+export declare function createWsl(options?: WslOptions): Wsl;

package/dist/runtime/wsl/transport.js

@@ -0,0 +1,181 @@
+/**
+ * Running things inside WSL from Windows (change `add-tensorrt-llm-windows`, task 2.2, design D1):
+ * the one place `wsl.exe` is spawned. Everything the core does in Atomic Chat's own distribution —
+ * probing the guest, running the install recipe, every docker call, the Engine API pull — goes
+ * through `exec`; `wsl.exe`'s own commands (`--list`, `--import`, `--unregister`, …) through
+ * `command`; keeping the distribution running through `hold`.
+ *
+ * Four things are deliberate.
+ *
+ * There is no shell, on either side. The command and every argument reach `spawn` as array elements,
+ * and `wsl.exe --exec` hands them to the guest's `execvp` as they are — never to `/bin/sh` — so
+ * nothing in a model path, a container name or a descriptor field is ever interpreted.
+ *
+ * Text is decoded, not assumed. `wsl.exe`'s own messages are UTF-16LE (`WSL_UTF8=1`, set on every
+ * call, asks for UTF-8, which an older WSL ignores), while a guest command's output is its own bytes,
+ * UTF-8; `decodeWslBytes` tells them apart.
+ *
+ * A command that could not answer — no `wsl.exe`, a spawn failure, past its deadline, aborted — is
+ * `code: null`, never a rejection: the same contract as `hostExec` and the docker executor, so a
+ * caller always gets one shape and reads "unknown" rather than "absent".
+ *
+ * The executable is injected. Production resolves the system `wsl.exe` from `%SystemRoot%`, never
+ * `PATH`; tests pass `process.execPath` with a fake script as `executableArgs`, which runs the same on
+ * a Windows CI runner as anywhere else (design D16).
+ */
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+import { HeadAndTail } from '../shared/index.js';
+/**
+ * Every command in a distribution runs through `env` with the system `PATH`. `wsl --exec` starts the
+ * program without a shell and with a `PATH` that has no `sbin`: `useradd`, `usermod` and the like
+ * were not found there (live acceptance, `execvpe(useradd) failed: No such file or directory`).
+ * Still one argv and no shell; `env` only sets `PATH` and resolves the program against it.
+ * `/usr/lib/wsl/lib` stays on it: WSL puts `nvidia-smi` and the NVIDIA user-mode libraries there and
+ * adds that directory to the `PATH` it gives a command itself (live acceptance: without it the probe
+ * could not read the library version).
+ */
+export const GUEST_PATH = '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/wsl/lib';
+const GUEST_ENV_PREFIX = ['/usr/bin/env', `PATH=${GUEST_PATH}`];
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+const NUL = 0x00;
+const BOM = '\ufeff';
+/** The system `wsl.exe`, from `%SystemRoot%` — never whatever `PATH` finds first. */
+export function defaultWslExecutable(env) {
+    const root = env['SystemRoot'] ?? env['SYSTEMROOT'] ?? 'C:\\Windows';
+    return `${root.replace(/[\\/]+$/, '')}\\System32\\wsl.exe`;
+}
+/**
+ * `wsl.exe`'s own text is UTF-16LE; a guest command's is UTF-8. UTF-16 is recognised by its BOM or by
+ * NUL bytes — every ASCII character, `\r\n` included, carries one, and a guest's text output has
+ * none — so a localized message (Cyrillic, CJK) decodes as well as an English one.
+ */
+export function decodeWslBytes(bytes) {
+    if (bytes.length === 0)
+        return '';
+    const bom = bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe;
+    const text = bom || bytes.includes(NUL) ? bytes.toString('utf16le') : bytes.toString('utf8');
+    return text.startsWith(BOM) ? text.slice(1) : text;
+}
+export function createWsl(options = {}) {
+    const executable = options.executable ?? defaultWslExecutable(process.env);
+    const prefix = options.executableArgs ?? [];
+    const limit = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const doSpawn = options.spawnProcess ?? spawn;
+    const env = {
+        ...(options.env ?? process.env),
+        ...(options.utf8 === false ? {} : { WSL_UTF8: '1' }),
+    };
+    const run = (args, call = {}) => new Promise((resolve) => {
+        const timeoutMs = call.timeoutMs ?? options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        if (call.signal?.aborted === true) {
+            resolve({ code: null, stdout: '', stderr: 'aborted before it started' });
+            return;
+        }
+        let settled = false;
+        let child;
+        const stdout = new HeadAndTail(limit);
+        const stderr = new HeadAndTail(limit);
+        const streaming = call.onStdout === undefined ? null : new StringDecoder('utf8');
+        const finish = (output) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            call.signal?.removeEventListener('abort', onAbort);
+            resolve(output);
+        };
+        const stop = (why) => {
+            child?.kill('SIGKILL');
+            finish({ code: null, stdout: '', stderr: why });
+        };
+        const onAbort = () => stop('aborted');
+        // Armed before the spawn, so a spawn that throws on the spot still has a real timer to clear.
+        const timer = setTimeout(() => stop(`wsl.exe did not answer within ${timeoutMs} ms`), timeoutMs);
+        timer.unref();
+        call.signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            child = doSpawn(executable, [...prefix, ...args], {
+                shell: false,
+                windowsHide: true,
+                stdio: [call.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+                env,
+            });
+        }
+        catch (error) {
+            finish({ code: null, stdout: '', stderr: error.message });
+            return;
+        }
+        child.stdout?.on('data', (chunk) => {
+            stdout.push(chunk);
+            if (streaming !== null)
+                call.onStdout?.(streaming.write(chunk));
+        });
+        child.stderr?.on('data', (chunk) => stderr.push(chunk));
+        if (call.input !== undefined) {
+            // A command that exits without reading its stdin closes the pipe under us; that is its answer.
+            child.stdin?.on('error', () => undefined);
+            child.stdin?.end(call.input);
+        }
+        // A missing executable arrives here as ENOENT, not as an exit code.
+        child.on('error', (error) => finish({ code: null, stdout: '', stderr: error.message }));
+        child.on('close', (code) => {
+            if (streaming !== null) {
+                const rest = streaming.end();
+                if (rest !== '')
+                    call.onStdout?.(rest);
+            }
+            finish({ code, stdout: decodeWslBytes(stdout.bytes()), stderr: decodeWslBytes(stderr.bytes()) });
+        });
+    });
+    const distribution = (name) => ({
+        name,
+        exec: (argv, call = {}) => run([
+            '-d',
+            name,
+            ...(call.user === undefined ? [] : ['-u', call.user]),
+            '--exec',
+            ...GUEST_ENV_PREFIX,
+            ...argv,
+        ], call),
+        hold: () => {
+            let released = false;
+            let child;
+            const exited = new Promise((resolve) => {
+                let settled = false;
+                const end = (code, signal) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve({ code, signal, released });
+                };
+                try {
+                    child = doSpawn(executable, [...prefix, '-d', name, '--exec', 'sleep', 'infinity'], {
+                        shell: false,
+                        windowsHide: true,
+                        stdio: 'ignore',
+                        env,
+                    });
+                }
+                catch {
+                    end(null, null);
+                    return;
+                }
+                child.on('error', () => end(null, null));
+                child.on('exit', (code, signal) => end(code, signal));
+            });
+            return {
+                exited,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    child?.kill('SIGKILL');
+                },
+            };
+        },
+    });
+    return { command: run, distribution };
+}
+//# sourceMappingURL=transport.js.map

package/dist/runtime/wsl/transport.js.map

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

package/dist/server/control/index.d.ts

@@ -9,4 +9,4 @@
  */
 export { ControlServer } from './server.js';
 export { SSE_HEARTBEAT_MS } from './types.js';
-export type { BackendControl, ChatGptControl, CloudControl, ControlServerDeps, ControlSnapshot, DiffusionControl, DiskControl, ExternalSessionControl, ModelControl, PublicServerControl, RemoteAccessControl, SessionSummary, SettingsControl, } from './types.js';
+export type { BackendControl, ChatGptControl, CloudControl, ControlServerDeps, ControlSnapshot, DecisionControl, DiffusionControl, DiskControl, ExternalSessionControl, ModelControl, PublicServerControl, RemoteAccessControl, SessionSummary, SettingsControl, } from './types.js';

package/dist/server/control/router.js

@@ -8,13 +8,19 @@ import { Router } from '../http.js';
 import { registerBackendRoutes } from './routes/backends.js';
 import { registerClientRoutes } from './routes/clients.js';
 import { registerCloudRoutes } from './routes/cloud.js';
+import { registerDecisionRoutes } from './routes/decision.js';
+import { registerEmbeddingRoutes } from './routes/embedding.js';
 import { registerDiffusionRoutes } from './routes/diffusion.js';
 import { registerDiffusionVideoRoutes } from './routes/diffusion-video.js';
 import { registerDiskRoutes } from './routes/disk.js';
+import { registerEngineBuildRoutes } from './routes/engine-builds.js';
+import { registerEngineRoutes } from './routes/engines.js';
+import { registerEnvironmentRoutes } from './routes/environments.js';
 import { registerExternalSessionRoutes } from './routes/external-sessions.js';
 import { registerHardwareRoutes } from './routes/hardware.js';
 import { registerLifecycleRoutes, registerShutdownRoute } from './routes/lifecycle.js';
 import { registerModelRoutes } from './routes/models.js';
+import { registerModelSetupRoutes } from './routes/model-setups.js';
 import { registerPublicServerRoutes } from './routes/public-server.js';
 import { registerRemoteAccessRoutes } from './routes/remote-access.js';
 import { registerSettingsRoutes } from './routes/settings.js';
@@ -36,17 +42,24 @@ export function buildRouter(deps, self) {
         sessions: deps.sessions(),
         server: deps.publicServer.status(),
         clients: deps.clients.list(),
-        downloads: [],
+        downloads: deps.downloads?.() ?? [],
         optimal_backends: deps.backends.optimalSnapshot(),
+        environments: deps.environmentsSnapshot?.() ?? [],
+        environment_operations: deps.environmentOperations?.() ?? [],
+        model_setups: deps.modelSetups?.snapshot() ?? [],
     });
     const ctx = { p, now, startedAt, snapshot, self };
     const router = new Router();
     registerLifecycleRoutes(router, deps, ctx);
     registerClientRoutes(router, deps, ctx);
     registerModelRoutes(router, deps, ctx);
+    registerModelSetupRoutes(router, deps, ctx);
     registerBackendRoutes(router, deps, ctx);
+    registerEngineBuildRoutes(router, deps, ctx);
+    registerEngineRoutes(router, deps, ctx);
     registerHardwareRoutes(router, deps, ctx);
     registerDiskRoutes(router, deps, ctx);
+    registerEnvironmentRoutes(router, deps, ctx);
     registerSettingsRoutes(router, deps, ctx);
     registerExternalSessionRoutes(router, deps, ctx);
     registerCloudRoutes(router, deps, ctx);
@@ -54,6 +67,8 @@ export function buildRouter(deps, self) {
     registerRemoteAccessRoutes(router, deps, ctx);
     registerDiffusionRoutes(router, deps, ctx);
     registerDiffusionVideoRoutes(router, deps, ctx);
+    registerDecisionRoutes(router, deps, ctx);
+    registerEmbeddingRoutes(router, deps, ctx);
     registerTelemetryRoutes(router, deps, ctx);
     registerShutdownRoute(router, deps, ctx);
     return router;

package/dist/server/control/router.js.map

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

package/dist/server/control/routes/backends.js

@@ -1,5 +1,6 @@
 /** llama.cpp backend packs and the download tasks that install them. */
 import { AtomicCoreError } from '../../../contracts/index.js';
+import { isLlamacppProviderId } from '../../../backend/index.js';
 import { queryOf, readJsonBody, sendError, sendJson } from '../../http.js';
 export function registerBackendRoutes(router, deps, ctx) {
     const { p } = ctx;
@@ -35,6 +36,31 @@ export function registerBackendRoutes(router, deps, ctx) {
         const result = await deps.backends.setOptimal(params['provider'], body.optimal ?? null, body.expected_revision);
         sendJson(res, result.status === 'conflict' ? 409 : 200, result);
     });
+    // The advisor answers; the app decides when to act (ADR 2026-09-27). All three are POST because the
+    // proxy policy may carry credentials, and those never travel in a query string.
+    const llamacppProvider = (raw) => {
+        if (!isLlamacppProviderId(raw))
+            throw new AtomicCoreError('INVALID_ARGUMENT', `The backend advisor knows llamacpp-upstream, llamacpp and atomic-prism, not ${raw}`);
+        return raw;
+    };
+    router.post(p('/backends/:provider/catalog'), async (req, res, { params }) => {
+        const provider = llamacppProvider(params['provider']);
+        const body = await readJsonBody(req);
+        sendJson(res, 200, await deps.backends.catalog(provider, body));
+    });
+    router.post(p('/backends/:provider/recommendation'), async (req, res, { params }) => {
+        const provider = llamacppProvider(params['provider']);
+        const body = await readJsonBody(req);
+        if (body.mode !== 'refresh' && body.mode !== 'recheck')
+            return sendError(res, new AtomicCoreError('INVALID_ARGUMENT', 'recommendation needs mode: refresh or recheck'));
+        // `detection_failed` is an outcome the caller reads, not an error: the current backend stays.
+        sendJson(res, 200, await deps.backends.recommend(provider, body));
+    });
+    router.post(p('/backends/:provider/updates'), async (req, res, { params }) => {
+        const provider = llamacppProvider(params['provider']);
+        const body = await readJsonBody(req);
+        sendJson(res, 200, await deps.backends.checkUpdates(provider, body));
+    });
     router.post(p('/downloads/*taskId/cancel'), (_req, res, { params }) => {
         sendJson(res, 200, { cancelled: deps.backends.cancel(params['taskId']) });
     });