@atomic-chat/core 0.5.1 → 0.13.2

package/README.md

@@ -25,6 +25,28 @@ atomic-chat-core shutdown
 `serve` attaches to the one persistent owner for the selected data folder. The command can exit
 without unloading the model; `shutdown` explicitly stops that owner and its sessions.
 
+## Managed runtimes (Linux + NVIDIA)
+
+On Linux with an NVIDIA GPU, the core can also run a model inside a container it manages itself —
+today `tensorrt-llm`, NVIDIA's inference engine — instead of spawning a local process the way
+llama.cpp and MLX do. It needs Docker and the NVIDIA Container Toolkit, which the core never installs
+on its own: setting one up computes a plan, asks for consent, and then runs the one privileged step
+(package install, `docker` group membership) through a helper the app or CLI runs as root — the core
+itself never gains elevated rights. A step that adds you to the `docker` group waits for your next
+sign-in before it can continue. See [`docs/contracts.md`](docs/contracts.md) for the control routes,
+the host-step file protocol and exit codes, the on-disk layout, and the `model.yml` shape a managed
+model's directory needs.
+
+Installing by hand runs the same steps the setup does: Docker Engine and the NVIDIA Container Toolkit
+from their vendors' own `apt` or `dnf` repositories, for the distributions the runtime descriptor
+qualifies (see `atomic-chat-conf/runtimes/`), then the NVIDIA runtime registered with Docker and the
+invoking user added to the `docker` group. Nothing is ever removed or upgraded on the host.
+
+Live tests that actually install this on a real Linux VM are opt-in and change the machine — see
+[`docs/live-tests.md`](docs/live-tests.md) for what they do. They run only when `ATOMIC_LIVE=1` and
+`ATOMIC_LIVE_MANAGED=1` are both set; `ATOMIC_RUNTIME_DESCRIPTOR_URL` optionally points them at a
+local descriptor.
+
 ## Releasing
 
 The desktop app pins a core version (`atomicCore.version` in its `package.json`) and downloads that

package/dist/app-daemon.js

@@ -1,72 +1,25 @@
 #!/usr/bin/env node
-/** Dedicated app-owned binary. It has no CLI command dispatcher or path override for CLI commands. */
+/**
+ * Dedicated app-owned binary. It has no CLI command dispatcher or path override for CLI commands.
+ * This entry only hands the real process, clock and core to `runAppDaemon` (`host/app-daemon.ts`);
+ * `scripts/build-binaries.mjs` and `docs/app-e2e.md` depend on this file's path.
+ */
 import { homedir } from 'node:os';
-import { parseArgs } from 'node:util';
-import { dataLayout } from './config/index.js';
 import { AtomicCore } from './core/index.js';
-import { CORE_VERSION } from './version.js';
 import { nodeCliIo } from './cli/io.js';
-import { breadcrumbLogger, createCoreReporter, failFatally, installProcessHandlers, parseTelemetryFlag, } from './telemetry/index.js';
-const io = nodeCliIo();
-const args = process.argv.slice(2);
-if (args.length === 1 && args[0] === '--version') {
-    io.stdout(`${CORE_VERSION}\n`);
-}
-else {
-    const command = args.shift();
-    if (command !== 'daemon')
-        throw new Error('The app core only accepts the daemon command.');
-    const { values } = parseArgs({
-        args,
-        options: {
-            'data-folder': { type: 'string' },
-            'control-port': { type: 'string' },
-            'resources-dir': { type: 'string' },
-            'cloudflared-bin': { type: 'string' },
-            // The app's `productAnalytic` consent at launch; it updates it later over PUT /telemetry.
-            // Absent, the core decides for itself (docs/decisions/*-the-core-owns-its-error-reporting.md).
-            'telemetry': { type: 'string' },
-        },
-        strict: true,
-    });
-    const dataFolder = values['data-folder'];
-    if (!dataFolder)
-        throw new Error('The app must supply its data folder.');
-    const reporter = await createCoreReporter({
-        host: 'atomic-chat',
-        ownerScope: 'app',
-        enabled: parseTelemetryFlag(values['telemetry']),
-        dataFolder,
-        telemetryFile: dataLayout(dataFolder).core.telemetry,
-        homeDir: homedir(),
-        env: io.env,
-        platform: process.platform,
-        arch: process.arch,
-        version: CORE_VERSION,
-        warn: (message) => io.stderr(`[warn] ${message}\n`),
-    });
-    const fatal = { reporter, writeStderr: io.stderr, exit: (code) => process.exit(code) };
-    installProcessHandlers(process, fatal);
-    let core;
-    try {
-        core = await AtomicCore.create({
-            ownerScope: 'app',
-            dataFolder,
-            controlPort: Number(values['control-port'] ?? 0),
-            ...(values['resources-dir'] ? { resourcesDir: values['resources-dir'] } : {}),
-            // The app bundles the tunnel binary next to its own executable, not under its resources.
-            ...(values['cloudflared-bin'] ? { cloudflaredPath: values['cloudflared-bin'] } : {}),
-            env: io.env,
-            errorReporter: reporter,
-            logger: breadcrumbLogger(reporter, (level, message) => io.stderr(`[${level}] ${message}\n`)),
-        });
-    }
-    catch (error) {
-        await failFatally('startup', error, fatal);
-        throw error;
-    }
-    io.stdout(`${JSON.stringify(core.readyLine())}\n`);
-    await Promise.race([io.waitForShutdown(() => core.shutdown()), core.stopped]);
-    await reporter.flush();
-}
+import { runAppDaemon } from './host/app-daemon.js';
+import { createCoreReporter } from './telemetry/index.js';
+await runAppDaemon({
+    argv: process.argv.slice(2),
+    io: nodeCliIo(),
+    processEvents: process,
+    exit: (code) => process.exit(code),
+    pid: process.pid,
+    platform: process.platform,
+    arch: process.arch,
+    homeDir: homedir(),
+    now: () => new Date(),
+    createReporter: createCoreReporter,
+    createCore: (options) => AtomicCore.create(options),
+});
 //# sourceMappingURL=app-daemon.js.map

package/dist/app-daemon.js.map

@@ -1 +1 @@
-{"version":3,"file":"app-daemon.js","sourceRoot":"","sources":["../src/app-daemon.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-daemon.js","sourceRoot":"","sources":["../src/app-daemon.ts"],"names":[],"mappings":";AACA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAEzD,MAAM,YAAY,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,EAAE,EAAE,SAAS,EAAE;IACf,aAAa,EAAE,OAAO;IACtB,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;IAClC,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;IAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,OAAO,EAAE,OAAO,EAAE;IAClB,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IACrB,cAAc,EAAE,kBAAkB;IAClC,UAAU,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC;CACpD,CAAC,CAAA"}

package/dist/backend/advisor/advisor.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The backend advisor: the hardware-gated catalog, the optimal-backend recommendation and the
+ * update check for one llama.cpp provider, computed in the core and served over
+ * `POST /backends/:provider/{catalog,recommendation,updates}` (2026-09-27 ADR "the core advises on
+ * backends, the app decides"). The app used to run all of this in its extensions (`configureBackends`,
+ * `detectIdealBackendType`, `recheckOptimalBackend`, `checkBackendForUpdates`); it now asks and
+ * decides when to install. The core only answers — and persists the optimal record it derives.
+ *
+ * Composition, no policy: the rules live in `policy.ts` and the pure modules it points at. This
+ * class owns the I/O seams — hardware facts, the installed scan, the remote catalogs (upstream
+ * manifest with its session cache, the fork's release index), the optimal store, the event emitter,
+ * `--list-devices` for the Windows tier probe, the Linux ROCm probe — every one injected so a test
+ * can run the canonical hosts on any OS.
+ *
+ * Never throws for a network failure: an unreachable release stream degrades to the bundled
+ * baseline / disk cache / empty catalog, and a detection that could not complete is the
+ * `detection_failed` outcome, not an error. It throws `INVALID_ARGUMENT` only for an OS/arch the
+ * provider has no build for and for a bad `mode`.
+ */
+import type { DataLayout } from '../../config/index.js';
+import type { BackendCatalogRelease, BackendCatalogRequest, BackendCatalogResponse, BackendCurrentKind, BackendRecommendationOutcome, BackendRecommendationRequest, BackendRecommendationResponse, BackendUpdateCheckRequest, BackendUpdateCheckResponse, CoreEvents, DeviceInfo, LlamacppProviderId, ProxyConfig } from '../../contracts/index.js';
+import type { HardwareFacts } from '../../hardware/index.js';
+import { ManifestSessionCache, PrismCatalogService, TurboquantCatalogService } from '../catalog/index.js';
+import type { PrismManifest, PrismOfferOptions } from '../catalog/index.js';
+import type { OptimalBackendStore } from '../optimal/index.js';
+import type { RocmHostProbe } from '../turboquant.js';
+import type { BackendRecommendation, BackendVersion, OptimalBackendCacheRecord } from '../types.js';
+/** The app's guard around detection (`withTimeout(detectIdealBackendType(), 20_000)`). */
+export declare const BACKEND_DETECTION_TIMEOUT_MS = 20000;
+export interface BackendAdvisorDeps {
+    provider: LlamacppProviderId;
+    layout: DataLayout;
+    /** The current hardware facts (`HardwareService.facts`). */
+    hardware: () => Promise<HardwareFacts>;
+    /** The provider's `version_backend` from the core settings; the request may override it. */
+    currentVersionBackend: () => string | undefined | Promise<string | undefined>;
+    optimalStore: Pick<OptimalBackendStore, 'get' | 'set'>;
+    emit: (name: 'backend:better-detected', payload: CoreEvents['backend:better-detected']) => void;
+    /** The `fetch` for a request carrying this proxy policy (`policyFetchFor` in the core). */
+    fetchFor: (proxy?: ProxyConfig | null) => typeof fetch;
+    /** Upstream: the session manifest cache shared with `BackendService.readManifest`. */
+    manifestCache?: ManifestSessionCache;
+    /** TurboQuant: the release-index service; built from `layout` + `fetchFor` when absent. */
+    turboquantCatalog?: TurboquantCatalogService;
+    /** PrismML: the conf manifest service; built from `layout` + `fetchFor` when absent. */
+    prismCatalog?: PrismCatalogService;
+    /** PrismML: the user's `allow_candidate_builds`; absent = verified builds only. */
+    allowCandidateBuilds?: () => boolean | Promise<boolean>;
+    /** PrismML: the version `min_core_version` is compared with; defaults to this core's. */
+    coreVersion?: string;
+    /** Every pack on disk; defaults to the directory scan. */
+    installed?: () => Promise<BackendVersion[]>;
+    /** Windows + upstream: `<exe> --list-devices` for an installed build; absent = tiers stay unverified. */
+    listDevices?: (installed: BackendVersion) => Promise<DeviceInfo[]>;
+    /** Linux + TurboQuant: amdkfd / HIP facts; defaults to reading sysfs and the library dirs. */
+    rocmProbe?: () => Promise<RocmHostProbe>;
+    now?: () => number;
+    platform?: NodeJS.Platform;
+    detectionTimeoutMs?: number;
+    log?: (level: 'info' | 'warn', message: string) => void;
+}
+export declare class BackendAdvisor {
+    private readonly deps;
+    readonly provider: LlamacppProviderId;
+    private readonly policy;
+    private readonly manifestCache;
+    private readonly turboquant;
+    private readonly prism;
+    private inFlightRecommend;
+    constructor(deps: BackendAdvisorDeps);
+    /**
+     * The hardware-gated catalog: what `configureBackends` computed in the app. `available` is the
+     * merged, gated, sorted list the dropdown shows; `recommended` its best entry;
+     * `recommended_installed` the best entry already on disk (the disk-recovery pick);
+     * `latest_by_type` the newest tag per type (what `find_latest_version_for_backend` answered one
+     * round trip at a time). Throws `INVALID_ARGUMENT` only for an unsupported OS/arch.
+     */
+    catalog(request?: BackendCatalogRequest): Promise<BackendCatalogResponse>;
+    private catalogFor;
+    private remoteCatalog;
+    /**
+     * Detect the ideal backend, resolve a concrete target, build the optimal record and persist it.
+     * `refresh` is the silent startup pass (never emits); `recheck` is the user asking (forces a
+     * catalog refresh, emits `backend:better-detected` on a recommendation). macOS is `mac` without
+     * detection or a write. One pass runs at a time per provider; a second caller shares its result.
+     * A `detection_failed` pass leaves the store untouched; a `no_catalog_entry` recheck writes what
+     * the provider's extension wrote (upstream: cleared; fork: the record).
+     */
+    recommend(request: BackendRecommendationRequest): Promise<BackendRecommendationResponse>;
+    private runRecommend;
+    /** Write with the store's compare-and-set; one retry against the revision a conflict reveals. */
+    private persist;
+    private probeTier;
+    /**
+     * Whether a newer build of the current backend's type exists, plus what the app needs to decide
+     * whether to offer it: `current_kind` (a missing `version_backend` is `update_needed: false`, not
+     * the throw the plugin produced; a parked `latest/<id>` sentinel resolves to its concrete target),
+     * `same_family` (a tag bump must never move anyone between backend families) and `offer`.
+     */
+    checkUpdates(request?: BackendUpdateCheckRequest): Promise<BackendUpdateCheckResponse>;
+    private checkUpdatesOf;
+    private currentVersionBackend;
+    private installed;
+    private prismManifest;
+    private prismOfferOptions;
+    private rocmFacts;
+    private rocmInput;
+    private now;
+    private log;
+}
+/** `missing` for nothing usable (`''`, `none`, no slash), `sentinel` for `latest/<id>`, else `concrete`. */
+export declare function classifyCurrent(current: string): BackendCurrentKind;
+/**
+ * The outcome vocabulary applied to a refresh record: `cpu_optimal`, `already_optimal` when the
+ * concrete target is the current build, `no_catalog_entry` when none resolved, else `recommend`
+ * (a refresh never emits; the record is what the app reads).
+ */
+export declare function refreshOutcome(record: OptimalBackendCacheRecord | null, current: string): BackendRecommendationOutcome;
+/** The event payload a `gpu` record with a concrete target other than the current build describes. */
+export declare function recommendationOf(record: OptimalBackendCacheRecord | null, provider: LlamacppProviderId): BackendRecommendation | null;
+/**
+ * The Prism releases this core can run, newest first, each with only its offered packs. A withdrawn
+ * release stays listed (flagged, no variants) so the app can explain why it is not offered.
+ */
+export declare function prismCatalogReleases(manifest: PrismManifest, offer: PrismOfferOptions): BackendCatalogRelease[];
+/**
+ * The PrismML additions to an update answer: `current_withdrawn` whenever the installed release was
+ * pulled; when it was and no newer build exists, the newest offered build of the same backend
+ * (possibly an older tag) becomes the offer; `reason` (`model_requires` when the caller's required
+ * build is reached, `withdrawn`, else `newer`), the target's notes and its download size.
+ */
+export declare function prismUpdateResponse(response: BackendUpdateCheckResponse, manifest: PrismManifest, offer: PrismOfferOptions, requiresBuild?: number): BackendUpdateCheckResponse;