@atomic-chat/core 0.5.1 → 0.13.2

package/dist/core/managed-engines.d.ts

@@ -0,0 +1,207 @@
+import type { CoreEvents } from '../contracts/index.js';
+import type { ModelCompatibility, ManagedModelDeletion, ManagedModelLocation, ManagedStoreMigration } from '../contracts/index.js';
+import type { DataLayout, ManagedScopePaths } from '../config/index.js';
+import type { ContainerUser, DockerExec, ManagedContainers, ManagedContainersHandle, ReconcileLogger } from '../runtime/container/index.js';
+import type { InstallationStore, LinuxHost, RuntimeDescriptorProvider, UnloadEngineSessions, WindowsEnvironmentRecord, WindowsHost } from '../runtime/environment/index.js';
+import { createWslManagedDeployment } from '../runtime/managed-text/index.js';
+import type { GpuClaimHook, SessionRoutePolicy } from '../runtime/shared/index.js';
+import { ManagedEngineRegistry, ManagedTextRuntime } from '../runtime/managed-engines/index.js';
+import type { ManagedEngineSettings, ManagedEngineSpec } from '../runtime/managed-engines/index.js';
+import { ManagedModelRegistry } from '../runtime/managed-models/index.js';
+import type { ModelFileOps } from '../runtime/managed-models/index.js';
+import { type DistributionKeeper, type GuestMount, type Wsl, type WslDistributionTransport } from '../runtime/wsl/index.js';
+import type { AtomicCore } from './atomic-core.js';
+import type { ResidencyOccupant } from './gpu/index.js';
+import type { CoreLogger } from './types.js';
+/**
+ * The managed engines this core can run, in priority order: every one is wired, checked and removed
+ * the same way. Registration checks the registry's invariants (`engine_id` is the provider id).
+ */
+export declare function managedEngineRegistry(): ManagedEngineRegistry;
+/** A managed provider's route policy for a session it did not start (one the app registered). */
+export declare function managedExternalRoutePolicy(provider: string): SessionRoutePolicy | undefined;
+/**
+ * What the Windows wiring of a managed engine reaches Atomic Chat's WSL distribution through (change
+ * `add-tensorrt-llm-windows`, task 2.8), built by the managed environment on Windows: the environment
+ * record (which distribution, if any yet), the WSL transport, the one keeper per distribution, this
+ * scope's `scope_key`, and the Windows machine (its `.wslconfig`, its volumes).
+ */
+export interface WindowsManagedContext {
+    records: {
+        read(): Promise<WindowsEnvironmentRecord | null>;
+    };
+    wsl: Wsl;
+    keeper: (distribution: string) => DistributionKeeper;
+    scopeKey: () => Promise<string>;
+    host: WindowsHost;
+    /** How core reaches the guest's files; `\\wsl.localhost` unless the managed test hook says otherwise. */
+    mount?: GuestMount;
+}
+export declare function windowsStoreMigration(context: WindowsManagedContext): Promise<ManagedStoreMigration | null>;
+/**
+ * The move of TensorRT-LLM's models into the managed model store, as `create.ts` runs it (change
+ * `add-vllm-runtime`, design D5): on Linux (and any data folder off Windows) at startup, before the
+ * environment and the engines are wired, under the core's lock on its data folder; on Windows it
+ * watches the move the guest runs on the first look at the store. What it did is logged
+ * and kept for the environment diagnostics (`current`); a failure is a warning, never a failed start.
+ */
+export declare function createStoreMigration(log: CoreLogger): {
+    current: () => ManagedStoreMigration | null;
+    onLinux: (layout: DataLayout) => Promise<void>;
+    onWindows: (context: WindowsManagedContext) => void;
+};
+export interface WireManagedEngineOptions {
+    /** Injected, never `process.platform` read here; the managed environment's (the test host is Linux). */
+    platform: NodeJS.Platform;
+    /** `process.arch`: which of the descriptor's images this host runs. */
+    arch: string;
+    layout: DataLayout;
+    instanceId: string;
+    scope: string;
+    descriptors: Pick<RuntimeDescriptorProvider, 'forInstallation'>;
+    /** The setup operation's installation records, under the shared per-user root. */
+    installations: Pick<InstallationStore, 'list'>;
+    /** The one Docker executor of this core (`wireManagedEnvironment`'s handle). */
+    containers: Pick<ManagedContainersHandle, 'resolve'>;
+    /** The machine the managed environment probes: `nvidia-smi` runs through it. */
+    host: Pick<LinuxHost, 'probeDeps'>;
+    /** The public server's live trusted hosts: the same array, so a restart reaches every gateway. */
+    trustedHosts: string[];
+    settings: () => Record<string, unknown>;
+    emit: <K extends keyof CoreEvents>(name: K, payload: CoreEvents[K]) => void;
+    log: CoreLogger;
+    /** Core's GPU residency (spec `gpu-residency`): the provider's `stopping-previous` stage. */
+    claimGpu?: GpuClaimHook;
+    /** One store model, one managed provider (`managedModelExclusivity`, design D11). */
+    releaseModelElsewhere?: (modelId: string, signal: AbortSignal) => Promise<void>;
+    /**
+     * The uid:gid this core runs as (`process.getuid`/`getgid`, read by `create.ts`, never here): every
+     * model container runs as it, so the engine cache stays removable (final review I-1). Null where the
+     * platform has no numeric user, which leaves the image's own user.
+     */
+    containerUser: ContainerUser | null;
+    /** Windows (change `add-tensorrt-llm-windows`): the WSL context; without it Windows offers nothing. */
+    windows?: WindowsManagedContext;
+}
+/**
+ * One managed engine's provider, or null where it is not offered: everywhere but Linux and Windows
+ * (x64, arm64). `options.settings` is that provider's stored settings.
+ */
+export declare function wireManagedEngine<S extends ManagedEngineSettings>(engine: ManagedEngineSpec<S>, options: WireManagedEngineOptions): ManagedTextRuntime<S> | null;
+/**
+ * The WSL deployment of one guest (task 2.7): its mounts through the context's mount, the engine probed
+ * inside the guest as root, and the forwarding error built from `.wslconfig` as it reads at that moment.
+ */
+export declare function windowsDeployment(context: Pick<WindowsManagedContext, 'host' | 'mount'>, guest: {
+    record: WindowsEnvironmentRecord;
+    transport: WslDistributionTransport;
+}, exec: DockerExec): ReturnType<typeof createWslManagedDeployment>;
+/** The retried reconcile's executor where the wired one already is the guest's (Windows). */
+export declare const wiredExec: (wired: {
+    exec: DockerExec;
+}) => DockerExec;
+/**
+ * `GET /managed-models/location` (spec `managed-model-store`): `<data>/managed-models` on Linux; the
+ * scope's store in the WSL guest on Windows (`MANAGED_ADAPTER_UNAVAILABLE` before the import).
+ */
+export declare function managedModelLocation(platform: NodeJS.Platform, layout: DataLayout, windows?: WindowsManagedContext): () => Promise<ManagedModelLocation>;
+/** The managed model store's registry: the data folder's root on Linux, the guest root (once it exists) on Windows. */
+export declare function managedModelRegistry(platform: NodeJS.Platform, layout: DataLayout, windows?: WindowsManagedContext): ManagedModelRegistry;
+/** `windowsModelFiles` bound to one context and layout: the deleter's `windowsFiles` on Windows. */
+export declare function windowsModelFilesFor(windows: WindowsManagedContext, layout: DataLayout): () => Promise<{
+    paths: ManagedScopePaths;
+    files: ModelFileOps;
+}>;
+/** Windows: where a model's files and caches are, and how to size and remove them (in the guest). */
+export declare function windowsModelFiles(windows: WindowsManagedContext, layout: DataLayout): Promise<{
+    paths: ManagedScopePaths;
+    files: ModelFileOps;
+}>;
+export interface WireManagedModelCheckOptions {
+    descriptors: Pick<RuntimeDescriptorProvider, 'forInstallation' | 'cachedForNewSetup'>;
+    /** The setup operation's installation records, under the shared per-user root. */
+    installations: Pick<InstallationStore, 'list'>;
+    /** The machine `nvidia-smi`/`/proc/meminfo` are read through; never asked about Docker. */
+    host: Pick<LinuxHost, 'probeDeps'>;
+    settings: () => Record<string, unknown>;
+    /** Windows x64 (change `add-tensorrt-llm-windows`): the cards and the VM's memory are read in the guest. */
+    windows?: WindowsManagedContext;
+    /** `process.arch`; x64 unless told. */
+    arch?: string;
+}
+/**
+ * `POST /models/<engine>/check`: `null` where the provider is not offered at all. Available even when
+ * the engine is not installed yet — the check falls back to that engine's latest cached descriptor
+ * itself (`managed-models/check.ts`) — and never asks Docker anything, unlike `wireManagedEngine`'s
+ * own `hostFacts` above.
+ */
+export declare function wireManagedModelCheck<S extends ManagedEngineSettings>(platform: NodeJS.Platform, engine: ManagedEngineSpec<S>, options: WireManagedModelCheckOptions): ((body: unknown) => Promise<ModelCompatibility>) | null;
+/**
+ * What GPU residency must see of the containers a previous core left (task 2.15; carry-forward from
+ * 2.12/2.14): startup reconcile could not confirm them stopped — the stop went unconfirmed, a docker
+ * call failed, or its time budget ran out — so they may still be running and holding a GPU. Which one
+ * is not recorded, so each holds every card, as `stop-unconfirmed`, under its engine id and container
+ * id, with the remedy a refusal names. Evicting one runs the reconcile again, bounded like the startup
+ * one (a short deadline per docker call, a short `--time`, a total budget), over this scope's journal
+ * only — this instance's own records are never touched — and it is released only once Docker confirms
+ * it gone.
+ */
+export declare function leftoverContainers(options: {
+    containers: Pick<ManagedContainersHandle, 'current'>;
+    instanceId: string;
+    log: ReconcileLogger;
+    /** The core's own empty `DOCKER_CONFIG` (`layout.managed.dockerConfigDir`), as every docker call uses. */
+    dockerConfigDir: string;
+    /** Test seams: the executor of a retried reconcile (default: the startup deadline per call) and its budget. */
+    exec?: (wired: ManagedContainers) => DockerExec;
+    budgetMs?: number;
+}): () => ResidencyOccupant[];
+/**
+ * The managed environment's `unloadEngineSessions` (spec "Удаление при загруженной модели"): before
+ * a removal touches an engine's image, loads of that engine's provider are held off (`holdOffLoads`)
+ * and every model holding a card is unloaded with its container's stop confirmed — through the
+ * facade's own `unload`, as a client's unload or GPU residency would, so each model's cross-process
+ * claim is released and a load still pending is cancelled rather than queued behind (final review
+ * M-1). The provider is looked up by the engine id among the managed runtimes (`engine_id` is the
+ * provider id, design D3), never by its class. The hold lasts until the removal calls `release`. An
+ * unconfirmed stop rejects with `MANAGED_STOP_UNCONFIRMED`, which fails the removal with nothing
+ * removed, and lifts the hold at once. `runtimes` and `sessions` are read at removal time: the
+ * providers are registered after the environment is wired, and the facade after both.
+ */
+export declare function managedSessionUnloader(runtimes: () => ReadonlyMap<string, ManagedTextRuntime>, sessions: () => Pick<AtomicCore, 'cancelLoad' | 'unload'>): UnloadEngineSessions;
+/**
+ * One store model, one managed provider (change `add-vllm-runtime`, design D11; spec
+ * `managed-model-store`, "Одна модель хранилища загружена не более чем в одном managed-провайдере"):
+ * for each `provider`, its runtime's `releaseModelElsewhere` — before it loads `modelId`, every other managed provider that has it loaded or loading lets it
+ * go — a load cancelled, a session unloaded through the facade with its container's stop confirmed,
+ * so its cross-process claim is released as with any client's unload. A stop Docker will not confirm
+ * rejects with `MANAGED_STOP_UNCONFIRMED`, and the new load does not start: two live sessions of one
+ * id would make `:1337`'s routing by id ambiguous and hold the weights twice.
+ */
+export declare function managedModelExclusivity(runtimes: () => ReadonlyMap<string, ManagedTextRuntime>, sessions: () => Pick<AtomicCore, 'cancelLoad' | 'unload'>): (provider: string) => (modelId: string) => Promise<void>;
+export interface ManagedModelDeleterOptions {
+    /** Read at deletion time, like `managedSessionUnloader`'s: the providers are registered late. */
+    runtimes: () => ReadonlyMap<string, ManagedTextRuntime>;
+    sessions: () => Pick<AtomicCore, 'cancelLoad' | 'unload'>;
+    registry: Pick<ManagedModelRegistry, 'list'>;
+    /** This scope's managed paths: where the model's engine caches live. */
+    paths: ManagedScopePaths;
+    /**
+     * Windows (change `add-tensorrt-llm-windows`, task 2.8): the guest's paths and its file commands,
+     * read at deletion time — the model and its caches are sized and removed in the guest.
+     */
+    windowsFiles?: () => Promise<{
+        paths: ManagedScopePaths;
+        files: ModelFileOps;
+    }>;
+}
+/**
+ * Deleting a downloaded model (design D12a of change `add-tensorrt-llm-linux`; change
+ * `add-vllm-runtime`, D4). The id must be one the registry lists — exactly, never percent-decoded or
+ * resolved as a path — else `MODEL_NOT_FOUND`: a client's wrong id is an error, not a success. Loads
+ * of that model are held off in every managed provider for the whole deletion; a load in flight is
+ * cancelled and the model unloaded, in whichever provider holds it, through the facade as a client's
+ * unload would be, so its cross-process claim is released. Only once Docker confirmed every stop are
+ * the files touched; an unconfirmed stop rejects with `MANAGED_STOP_UNCONFIRMED` and removes nothing.
+ */
+export declare function managedModelDeleter(options: ManagedModelDeleterOptions): (modelId: string) => Promise<ManagedModelDeletion>;