@atomic-chat/core 0.5.1 → 0.13.2

package/dist/contracts/embedding.js

@@ -0,0 +1,24 @@
+/**
+ * The embedding model (ADR 2026-10-07-embedding-models-are-their-own-core-module): one stock llama.cpp
+ * `llama-server --embedding` the app turns on for the Local API Server's `/v1/embeddings`, outside the
+ * sessions registry like the decision model. The model is a GGUF the app downloaded (its catalog is
+ * the app's, `atomic-chat-conf/models/embedding.json`), plus a projector for one that reads images or
+ * audio; the core only runs it.
+ */
+/** The pooling a model is started with (`--pooling`); empty in the settings = the GGUF's own. */
+export const EMBEDDING_POOLINGS = ['mean', 'cls', 'last'];
+export const DEFAULT_EMBEDDING_SETTINGS = {
+    enabled: false,
+    model_path: '',
+    mmproj_path: '',
+    model_id: '',
+    ctx_size: 0,
+    pooling: '',
+    image_max_tokens: 0,
+    threads: 0,
+    idle_unload_secs: 0,
+    // A first start maps the weights and, with a projector, warms the vision and audio encoders.
+    startup_timeout_secs: 120,
+    engine_path: '',
+};
+//# sourceMappingURL=embedding.js.map

package/dist/contracts/embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding.js","sourceRoot":"","sources":["../../src/contracts/embedding.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iGAAiG;AACjG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAU,CAAA;AAyClE,MAAM,CAAC,MAAM,0BAA0B,GAAsB;IAC3D,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,EAAE;IACd,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,EAAE;IACZ,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,EAAE;IACX,gBAAgB,EAAE,CAAC;IACnB,OAAO,EAAE,CAAC;IACV,gBAAgB,EAAE,CAAC;IACnB,6FAA6F;IAC7F,oBAAoB,EAAE,GAAG;IACzB,WAAW,EAAE,EAAE;CAChB,CAAA"}

package/dist/contracts/engine-builds.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Engine builds the core installs itself: stable-diffusion.cpp (`sd-server`) and MLX (`mlx-server`),
+ * from conf's `backends/sdcpp-manifest.json` and `backends/mlx-manifest.json` (openspec change
+ * `move-sdcpp-mlx-install-to-core`, spec `engine-builds`). snake_case on the wire, like `/backends`
+ * and `/environments`.
+ *
+ * The core advises and the client decides (ADR 2026-09-27): nothing here installs on a schedule.
+ * `POST /engine-builds/:engine/catalog` and `/updates` only read; `/install` acts when called.
+ */
+import type { ProxyConfig } from './backend-advisor.js';
+export declare const ENGINE_BUILD_IDS: readonly ["sd-cpp", "mlx"];
+export type EngineBuildId = (typeof ENGINE_BUILD_IDS)[number];
+/**
+ * `downloaded` — installed by the core under `<data>`, removable; `bundled` — `mlx-server` shipped in
+ * the desktop installer (`--resources-dir`), read-only, never removed by the core.
+ */
+export type EngineBuildOrigin = 'downloaded' | 'bundled';
+/** One build, by what identifies it on disk. */
+export interface EngineBuildRef {
+    tag: string;
+    backend_id: string;
+    origin: EngineBuildOrigin;
+}
+export interface InstalledEngineBuild extends EngineBuildRef {
+    /** `null` for a bundled build: the installer, not the core, put it there. */
+    installed_at_ms: number | null;
+    /** MLX: the release date the build is ordered by; `null` when unknown (oldest of all). */
+    published_at?: string | null;
+    removable: boolean;
+    /** A loaded session runs from this build right now. */
+    in_use: boolean;
+    /** The build the next model load uses. */
+    active: boolean;
+}
+/** The accepted manifest a catalog was built from. */
+export interface EngineBuildManifestInfo {
+    tag: string;
+    /** MLX only. */
+    published_at?: string;
+    /** `cache` — the network gave nothing acceptable this time; `error` says why. */
+    source: 'remote' | 'cache';
+    /** Milliseconds since the epoch. */
+    fetched_at: number;
+    error: string | null;
+}
+export interface EngineBuildCatalog {
+    engine: EngineBuildId;
+    /** `null` when there is neither a network answer nor a cached copy; `manifest_error` says why. */
+    manifest: EngineBuildManifestInfo | null;
+    manifest_error: string | null;
+    /** The build this host would install from the manifest; `null` with `host_reason` when none fits. */
+    host_backend_id: string | null;
+    host_reason: string | null;
+    installed: InstalledEngineBuild[];
+    active: InstalledEngineBuild | null;
+}
+export interface EngineBuildCatalogRequest {
+    /** Re-read the manifest from the network. */
+    force?: boolean;
+    proxy?: ProxyConfig | null;
+}
+export type EngineBuildUpdateCheckRequest = EngineBuildCatalogRequest;
+export interface EngineBuildTarget {
+    tag: string;
+    backend_id: string;
+    published_at?: string;
+    /** Every archive the install would download (the cudart companion included). */
+    download_bytes: number;
+}
+export interface EngineBuildUpdateCheck {
+    /** `true` only for a build strictly newer than the active one; never without an active build. */
+    update_needed: boolean;
+    current: EngineBuildRef | null;
+    target: EngineBuildTarget | null;
+}
+export interface EngineBuildInstallRequest {
+    /** The download task progress and cancellation run under (`POST /downloads/:task_id/cancel`). */
+    task_id: string;
+    /** Reinstall the same build. Never installs one older than the active build. */
+    force?: boolean;
+    proxy?: ProxyConfig | null;
+}
+export interface EngineBuildInstallResult {
+    /** `false` when nothing was downloaded; `reason` says why. */
+    installed: boolean;
+    reason?: 'already-installed' | 'active-is-newer';
+    build: EngineBuildRef;
+    /**
+     * Always empty since change `unify-engine-lifecycle`: an install deletes no other build, and neither
+     * does the start. Kept in the shape for the clients that already read it.
+     */
+    retired: EngineBuildRef[];
+    /** Always empty, like `retired`. */
+    kept_in_use: EngineBuildRef[];
+    /**
+     * sd.cpp: builds higher on this host's ladder that unpacked but failed their probe on the way down
+     * (design D7); they are skipped for this tag from now on.
+     */
+    failed_backend_ids?: string[];
+}
+export interface EngineBuildRemoveResult {
+    removed: boolean;
+}
+export interface EngineBuildChangedEvent {
+    engine: EngineBuildId;
+    /** `startup-cleanup` is no longer sent: the start removes no build. Kept for the vendored clients. */
+    reason: 'install' | 'uninstall' | 'startup-cleanup';
+}

package/dist/contracts/engine-builds.js

@@ -0,0 +1,11 @@
+/**
+ * Engine builds the core installs itself: stable-diffusion.cpp (`sd-server`) and MLX (`mlx-server`),
+ * from conf's `backends/sdcpp-manifest.json` and `backends/mlx-manifest.json` (openspec change
+ * `move-sdcpp-mlx-install-to-core`, spec `engine-builds`). snake_case on the wire, like `/backends`
+ * and `/environments`.
+ *
+ * The core advises and the client decides (ADR 2026-09-27): nothing here installs on a schedule.
+ * `POST /engine-builds/:engine/catalog` and `/updates` only read; `/install` acts when called.
+ */
+export const ENGINE_BUILD_IDS = ['sd-cpp', 'mlx'];
+//# sourceMappingURL=engine-builds.js.map

package/dist/contracts/engine-builds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-builds.js","sourceRoot":"","sources":["../../src/contracts/engine-builds.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAU,CAAA"}

package/dist/contracts/engines.d.ts

@@ -0,0 +1,157 @@
+/**
+ * One layer over the three ways the core installs engines (openspec change `unify-engine-lifecycle`,
+ * spec `engine-lifecycle`, design D1, D2, D10): llama.cpp packs (`/backends`), sd.cpp and MLX builds
+ * (`/engine-builds`) and the managed engines' environments (`/environments`). The same four commands
+ * for every engine: what is installed and what is newer, update, make a build active, remove a build.
+ *
+ * The core still never installs on its own (ADR 2026-09-27): the versions answer only reads, and an
+ * update runs when a client calls it. snake_case on the wire, like the routes underneath.
+ *
+ * Browser-safe: types and constant lists only.
+ */
+import type { ProxyConfig } from './backend-advisor.js';
+import type { ErrorBody } from './errors.js';
+/** Every engine the layer answers for, in the order the desktop lists them. */
+export declare const ENGINE_IDS: readonly ["llamacpp-upstream", "llamacpp", "atomic-prism", "sd-cpp", "mlx", "tensorrt-llm", "vllm"];
+export type EngineId = (typeof ENGINE_IDS)[number];
+/** Which system underneath installs the engine. */
+export type EngineKind = 'llamacpp' | 'engine-build' | 'managed';
+/** The kind of every engine: what decides its update body, who picks its active build, how it applies. */
+export declare const ENGINE_KINDS: Readonly<Record<EngineId, EngineKind>>;
+/**
+ * Who picks the build the next load runs: `client` — any installed build can be made active
+ * (llama.cpp, `version_backend`); `core` — the core's own rule (sd.cpp and MLX: the newest; a
+ * managed engine: its one installation).
+ */
+export type EngineActiveChoice = 'client' | 'core';
+/**
+ * `downloaded` — the core put it there; `bundled` — it came with the desktop installer and is never
+ * removed; `managed` — a managed engine's installation.
+ */
+export type EngineOrigin = 'downloaded' | 'bundled' | 'managed';
+export declare const ENGINE_NOT_REMOVABLE_REASONS: readonly ["active", "bundled", "in-use"];
+/** A build both active and in use reports `active`. */
+export type EngineNotRemovableReason = (typeof ENGINE_NOT_REMOVABLE_REASONS)[number];
+/**
+ * What names a build in every command. `version` is the llama.cpp tag, the sd.cpp/MLX tag or the
+ * managed `descriptor_id`; `variant` is the build for the hardware (`win-cuda12-x64`), for a managed
+ * engine the image platform.
+ */
+export interface EngineBuildKey {
+    version: string;
+    variant: string;
+}
+export interface EngineBuild extends EngineBuildKey {
+    origin: EngineOrigin;
+    active: boolean;
+    /** A session, the decision model or the embedding model runs from it right now. */
+    in_use: boolean;
+    removable: boolean;
+    /** Present exactly when `removable` is `false`. */
+    not_removable_reason?: EngineNotRemovableReason;
+}
+/** A build the engine's source offers. */
+export interface EngineAvailableBuild extends EngineBuildKey {
+    /** Every archive or image layer the install would download, when the source says. */
+    download_bytes?: number;
+    published_at?: string;
+}
+export type EngineUpdateApply = 'swap' | 'reinstall';
+export declare const ENGINE_UPDATE_BLOCKED_REASONS: readonly ["family-change", "unstable", "requires-newer-app", "source-unavailable"];
+/** Why a newer build exists but is not offered; `needed` is then `false`. */
+export type EngineUpdateBlockedReason = (typeof ENGINE_UPDATE_BLOCKED_REASONS)[number];
+export interface EngineUpdateOffer {
+    /** `true` only for a `target` strictly newer than the active build; never without an active build. */
+    needed: boolean;
+    target: EngineAvailableBuild | null;
+    /** `swap` — installed beside, the engine's sessions unloaded; `reinstall` — removed and set up again. */
+    apply: EngineUpdateApply;
+    blocked_reason?: EngineUpdateBlockedReason;
+}
+/** `remote` — fetched this time; `cache` — what was accepted before; `null` — neither. */
+export type EngineVersionsSource = 'remote' | 'cache' | null;
+/** One engine of this host. */
+export interface EngineVersions {
+    engine: EngineId;
+    kind: EngineKind;
+    active_choice: EngineActiveChoice;
+    builds: EngineBuild[];
+    /** The build the next model load uses, or `null`. */
+    active: EngineBuildKey | null;
+    /** The newest build for this host by the engine's source, or `null`. */
+    latest: EngineAvailableBuild | null;
+    update: EngineUpdateOffer;
+    source: EngineVersionsSource;
+    /** Why the source was not read from the network this time (with `cache` or `null`); `null` otherwise. */
+    source_error: string | null;
+    /** Set when this engine's answer could not be built; the other engines are answered as usual. */
+    error: ErrorBody | null;
+}
+export interface EngineVersionsRequest {
+    /** Re-read every engine's source from the network. */
+    force?: boolean;
+    proxy?: ProxyConfig | null;
+    /** The client's version, for `minimum_app_version` and the TurboQuant `min_app_version` gate. */
+    app_version?: string | null;
+}
+export interface EngineVersionsResponse {
+    /** One entry per engine registered on this host; an engine this platform lacks is absent. */
+    engines: EngineVersions[];
+}
+/** llama.cpp, sd.cpp and MLX: answers once applied, which can take as long as the download. */
+export interface EngineSwapUpdateRequest {
+    /** The download task progress and cancellation run under (`POST /downloads/:task_id/cancel`). */
+    task_id: string;
+    /**
+     * llama.cpp only: the build to move to. Without `version` — the newest of that `variant` in the
+     * catalog. With a target the family check does not apply: the client chose. sd.cpp and MLX refuse it.
+     */
+    target?: {
+        version?: string;
+        variant: string;
+    };
+    force?: boolean;
+    proxy?: ProxyConfig | null;
+    app_version?: string | null;
+}
+/** A managed engine: answers `202` with the removal that starts the reinstall. */
+export interface EngineReinstallRequest {
+    /** Makes a retried call the same operation; the setup that follows runs under `<request_id>:setup`. */
+    request_id: string;
+    app_version?: string | null;
+}
+export type EngineUpdateRequest = EngineSwapUpdateRequest | EngineReinstallRequest;
+export type EngineUpdateNotAppliedReason = 'already-active' | 'no-update';
+export interface EngineUpdateResult {
+    /** `false` when nothing changed; `reason` says why. */
+    updated: boolean;
+    reason?: EngineUpdateNotAppliedReason;
+    active: EngineBuildKey | null;
+    /**
+     * Always empty: an update deletes no build, the old ones stay to switch back to or remove. Kept in
+     * the shape for the clients that already read it.
+     */
+    retired: EngineBuildKey[];
+    /** Always empty, like `retired`. */
+    kept_in_use: EngineBuildKey[];
+}
+/** `202`: a managed engine's reinstall began; follow it on `environment:operation`. */
+export interface EngineOperationStarted {
+    operation_id: string;
+}
+/** `removed: false` for a build that was not there. A managed engine answers `202` `EngineOperationStarted`. */
+export interface EngineBuildDeleteResult {
+    removed: boolean;
+}
+export interface EngineActivateResult {
+    activated: boolean;
+    reason?: 'already-active';
+    active: EngineBuildKey;
+}
+export declare const ENGINE_CHANGED_REASONS: readonly ["update", "activate", "install", "uninstall", "startup-cleanup", "reinstall"];
+export type EngineChangedReason = (typeof ENGINE_CHANGED_REASONS)[number];
+/** The set or the active build of an engine changed, by any route: re-read `POST /engines/versions`. */
+export interface EngineChangedEvent {
+    engine: EngineId;
+    reason: EngineChangedReason;
+}

package/dist/contracts/engines.js

@@ -0,0 +1,50 @@
+/**
+ * One layer over the three ways the core installs engines (openspec change `unify-engine-lifecycle`,
+ * spec `engine-lifecycle`, design D1, D2, D10): llama.cpp packs (`/backends`), sd.cpp and MLX builds
+ * (`/engine-builds`) and the managed engines' environments (`/environments`). The same four commands
+ * for every engine: what is installed and what is newer, update, make a build active, remove a build.
+ *
+ * The core still never installs on its own (ADR 2026-09-27): the versions answer only reads, and an
+ * update runs when a client calls it. snake_case on the wire, like the routes underneath.
+ *
+ * Browser-safe: types and constant lists only.
+ */
+/** Every engine the layer answers for, in the order the desktop lists them. */
+export const ENGINE_IDS = [
+    'llamacpp-upstream',
+    'llamacpp',
+    'atomic-prism',
+    'sd-cpp',
+    'mlx',
+    'tensorrt-llm',
+    'vllm',
+];
+/** The kind of every engine: what decides its update body, who picks its active build, how it applies. */
+export const ENGINE_KINDS = {
+    'llamacpp-upstream': 'llamacpp',
+    'llamacpp': 'llamacpp',
+    'atomic-prism': 'llamacpp',
+    'sd-cpp': 'engine-build',
+    'mlx': 'engine-build',
+    'tensorrt-llm': 'managed',
+    'vllm': 'managed',
+};
+export const ENGINE_NOT_REMOVABLE_REASONS = ['active', 'bundled', 'in-use'];
+export const ENGINE_UPDATE_BLOCKED_REASONS = [
+    'family-change',
+    'unstable',
+    'requires-newer-app',
+    'source-unavailable',
+];
+// ---------------------------------------------------------------------------------------------
+// The event
+// ---------------------------------------------------------------------------------------------
+export const ENGINE_CHANGED_REASONS = [
+    'update',
+    'activate',
+    'install',
+    'uninstall',
+    'startup-cleanup',
+    'reinstall',
+];
+//# sourceMappingURL=engines.js.map

package/dist/contracts/engines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engines.js","sourceRoot":"","sources":["../../src/contracts/engines.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mBAAmB;IACnB,UAAU;IACV,cAAc;IACd,QAAQ;IACR,KAAK;IACL,cAAc;IACd,MAAM;CACE,CAAA;AAMV,0GAA0G;AAC1G,MAAM,CAAC,MAAM,YAAY,GAA2C;IAClE,mBAAmB,EAAE,UAAU;IAC/B,UAAU,EAAE,UAAU;IACtB,cAAc,EAAE,UAAU;IAC1B,QAAQ,EAAE,cAAc;IACxB,KAAK,EAAE,cAAc;IACrB,cAAc,EAAE,SAAS;IACzB,MAAM,EAAE,SAAS;CAClB,CAAA;AAeD,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAA;AAiCpF,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe;IACf,UAAU;IACV,oBAAoB;IACpB,oBAAoB;CACZ,CAAA;AAsHV,gGAAgG;AAChG,YAAY;AACZ,gGAAgG;AAEhG,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,QAAQ;IACR,UAAU;IACV,SAAS;IACT,WAAW;IACX,iBAAiB;IACjB,WAAW;CACH,CAAA"}