@atomic-chat/core 0.5.1 → 0.13.2

package/dist/runtime/managed-text/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A containerised text session: launched through an injectable `ManagedDeployment` and published
+ * as a desktop `SessionInfo` through a pure projection of its internal `BackendTarget`. Task 2.7
+ * (openspec change `add-tensorrt-llm-linux`, ADR `docs/decisions/2026-09-23-preserve-deployment-
+ * seams.md`, task T01e) owns the types, the desktop deployment binding, and the projection; the
+ * Docker calls that produce a real `EngineLaunchSpec` and `BackendTarget` (task 2.8, `PreparedLaunch`
+ * carries the `BackendTarget` the executor resolves — see `docs/decisions/2026-09-28-pull-the-model-
+ * image-over-the-docker-engine-api.md`) and the session gateway (task 2.11) build on this module, and
+ * task 2.12 adds the `ManagedTextAdapter` registry (`adapter.ts`) and the engine-neutral load
+ * lifecycle (`lifecycle.ts`, with its pure decisions in `load-policy.ts`, the readiness probe in
+ * `readiness.ts` and the engine cache in `engine-cache.ts`) that a provider (task 2.14) runs on.
+ *
+ * Public API of this module is exported from this file only.
+ */
+export * from './types.js';
+export * from './backend-target.js';
+export * from './mount-source.js';
+export * from './deployment.js';
+export * from './gateway.js';
+export * from './adapter.js';
+export * from './load-policy.js';
+export * from './readiness.js';
+export * from './engine-cache.js';
+export * from './lifecycle.js';
+export * from './wsl-deployment.js';
+export * from './request-rules.js';

package/dist/runtime/managed-text/index.js

@@ -0,0 +1,27 @@
+/**
+ * A containerised text session: launched through an injectable `ManagedDeployment` and published
+ * as a desktop `SessionInfo` through a pure projection of its internal `BackendTarget`. Task 2.7
+ * (openspec change `add-tensorrt-llm-linux`, ADR `docs/decisions/2026-09-23-preserve-deployment-
+ * seams.md`, task T01e) owns the types, the desktop deployment binding, and the projection; the
+ * Docker calls that produce a real `EngineLaunchSpec` and `BackendTarget` (task 2.8, `PreparedLaunch`
+ * carries the `BackendTarget` the executor resolves — see `docs/decisions/2026-09-28-pull-the-model-
+ * image-over-the-docker-engine-api.md`) and the session gateway (task 2.11) build on this module, and
+ * task 2.12 adds the `ManagedTextAdapter` registry (`adapter.ts`) and the engine-neutral load
+ * lifecycle (`lifecycle.ts`, with its pure decisions in `load-policy.ts`, the readiness probe in
+ * `readiness.ts` and the engine cache in `engine-cache.ts`) that a provider (task 2.14) runs on.
+ *
+ * Public API of this module is exported from this file only.
+ */
+export * from './types.js';
+export * from './backend-target.js';
+export * from './mount-source.js';
+export * from './deployment.js';
+export * from './gateway.js';
+export * from './adapter.js';
+export * from './load-policy.js';
+export * from './readiness.js';
+export * from './engine-cache.js';
+export * from './lifecycle.js';
+export * from './wsl-deployment.js';
+export * from './request-rules.js';
+//# sourceMappingURL=index.js.map

package/dist/runtime/managed-text/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runtime/managed-text/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,cAAc,YAAY,CAAA;AAC1B,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAA;AACjC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,cAAc,CAAA;AAC5B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,qBAAqB,CAAA;AACnC,cAAc,oBAAoB,CAAA"}

package/dist/runtime/managed-text/lifecycle.d.ts

@@ -0,0 +1,276 @@
+import { AtomicCoreError } from '../../contracts/index.js';
+import type { ErrorCode, LocalProviderId, ModelFamilySupport, SessionInfo } from '../../contracts/index.js';
+import type { ManagedScopePaths } from '../../config/index.js';
+import type { ContainerUser, CreateContainerDeps, DockerExec, ExecutionJournal, HeartbeatTicker, HeartbeatTickerOptions, ImageRef } from '../container/index.js';
+import type { EmitFn } from '../shared/index.js';
+import type { ManagedExitClassification, ManagedTextAdapterRegistry } from './adapter.js';
+import type { EngineCacheSelector } from './engine-cache.js';
+import type { ManagedGateway, ManagedGatewayOptions } from './gateway.js';
+import type { ManagedDeployment } from './types.js';
+/** The heartbeat file's name inside its generation's directory (and inside the container). */
+export declare const HEARTBEAT_FILE = "heartbeat";
+/**
+ * Knobs a test shortens and task 2.19's live measurements may tune. Kept together so nothing else in
+ * this file carries a bare number of milliseconds.
+ */
+export interface ManagedLifecycleTimings {
+    /** Between two readiness/exit polls while loading; also how often progress is re-emitted. */
+    pollIntervalMs: number;
+    /** One readiness probe's own deadline. */
+    probeTimeoutMs: number;
+    /** How long the first heartbeat write may take before the load gives up (it never settles on its own if writes keep failing). */
+    heartbeatReadyTimeoutMs: number;
+    /** `docker stop --time`. */
+    stopTimeoutSecs: number;
+    /** How many log lines a failure keeps, and a classifier reads. */
+    logTailLines: number;
+    /** How many host ports a load tries when the one core picked keeps getting taken. */
+    portAttempts: number;
+    /** Between two liveness checks of a ready container. */
+    monitorIntervalMs: number;
+    /**
+     * WSL (change `add-tensorrt-llm-windows`, design D7): how many polls in a row the engine must answer
+     * inside the guest while Windows cannot reach it before that counts as a forwarding failure.
+     */
+    forwardingConfirmPolls: number;
+    /**
+     * WSL: the guest is asked once every this many polls (each ask is a `wsl.exe`), then every poll
+     * while it answers, until `forwardingConfirmPolls` confirm it.
+     */
+    guestProbeEveryPolls: number;
+    /** WSL: how many times a load publishes the port again when another program holds it on Windows. */
+    republishAttempts: number;
+}
+export declare const DEFAULT_MANAGED_LIFECYCLE_TIMINGS: ManagedLifecycleTimings;
+export type ManagedLifecycleLogger = (level: 'info' | 'warn' | 'error', message: string) => void;
+export interface ManagedTextLifecycleDeps {
+    /** The provider id every event carries (task 2.14 passes its own). */
+    provider: LocalProviderId;
+    adapters: ManagedTextAdapterRegistry;
+    exec: DockerExec;
+    deployment: ManagedDeployment;
+    journal: ExecutionJournal;
+    /** This scope's managed paths: heartbeats, engine caches, the watchdog script. */
+    paths: ManagedScopePaths;
+    instanceId: string;
+    scope: string;
+    /** The public server's LIVE trusted-hosts array — the same reference, so a later change reaches every gateway. */
+    allowedHosts: string[];
+    /**
+     * The one directory `:z` relabels may stay within under SELinux: this scope's data folder, since a
+     * model's directory lives under `<data>/<provider>/models/`, beside `<data>/atomic-core/`.
+     */
+    selinuxDataRoot: string;
+    emit: EmitFn;
+    log?: ManagedLifecycleLogger;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** Rejects when `signal` aborts. Tests inject a fake clock through this and `now`. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    newGeneration?: () => string;
+    timings?: Partial<ManagedLifecycleTimings>;
+    startHeartbeat?: (options: HeartbeatTickerOptions) => HeartbeatTicker;
+    startGateway?: (options: ManagedGatewayOptions) => Promise<ManagedGateway>;
+    createContainerDeps?: CreateContainerDeps;
+    /**
+     * The uid:gid every container runs as — the core's own (final review I-1): the engine then writes
+     * its cache as the user who can remove it again. Absent, the image's own user. With a user, the
+     * container also gets a home, a cache home and a login name inside the engine cache
+     * (`containerUserEnv`), since the image has no passwd entry for it.
+     */
+    containerUser?: ContainerUser;
+    /**
+     * Windows (change `add-tensorrt-llm-windows`, design D8): what keeps Atomic Chat's WSL distribution
+     * running while a model loads or is loaded, and says when it stopped under one. Absent on Linux.
+     */
+    keeper?: SessionKeeper;
+}
+/** The slice of `DistributionKeeper` (`runtime/wsl`) a lifecycle uses. */
+export interface SessionKeeper {
+    acquire(reason: string): {
+        release(): void;
+    };
+    onStopped(listener: () => void): () => void;
+}
+/** The login name a container user without a passwd entry is given (`USER`/`LOGNAME`). */
+export declare const CONTAINER_USER_NAME = "atomic";
+/** The pinned installation a load runs: which descriptor, image and adapter. */
+export interface ManagedInstallationRef {
+    descriptor_id: string;
+    engine_id: string;
+    adapter_id: string;
+    adapter_contract_version: number;
+    /** The descriptor's image for this host's platform. */
+    image: ImageRef;
+}
+export interface ManagedLoadRequest {
+    modelId: string;
+    /** The model directory as core sees it; mounted read-only. */
+    modelPath: string;
+    weightBytes: number;
+    installation: ManagedInstallationRef;
+    /** The descriptor's `model_families` entry for this model's architecture, or null. */
+    family: ModelFamilySupport | null;
+    gpuUuid: string;
+    /** `gpuUuid` names a unified-memory card (`ManagedLaunchContext.unifiedMemory`); absent, a discrete one. */
+    unifiedMemory?: boolean;
+    /** The chosen card's memory and compute capability, for launch defaults that depend on the card. */
+    gpuTotalVramBytes?: number | null;
+    gpuComputeCapability?: string | null;
+    /** Whether Docker runs with SELinux (probe snapshot): mounts then get the shared `:z` label. */
+    selinux: boolean;
+    /** Raw provider settings; the adapter validates them. */
+    settings: unknown;
+    /** The provider's readiness-timeout setting; overrides what the adapter computes. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /**
+     * Frees the card first (GPU residency, task 2.15). Runs before any container of this load exists,
+     * with the load's own signal — aborted when the load is cancelled or unloaded, so a callback still
+     * waiting for its turn gives up rather than stopping sessions for a load that is gone — and the
+     * generation this load's reservation carries.
+     */
+    stopPrevious?: (signal: AbortSignal, generation: string) => Promise<void>;
+    /**
+     * Runs once, after `stopPrevious` has resolved and right before the first `docker create` attempt
+     * (task 2.16w round 1, finding 1 (Critical)): a provider's own re-check that only makes sense once
+     * whatever `stopPrevious` freed is actually free — free VRAM on the chosen card, for
+     * `tensorrt-llm`, re-probed fresh rather than trusted from a snapshot taken before eviction.
+     * Throwing refuses the load with no container ever created, the same as `stopPrevious` throwing.
+     * What it answers is the engine's launch plan (`ManagedLaunchContext.plan`, change
+     * `add-vllm-runtime`): numbers a launch takes from the card as it stands right then, such as vLLM's
+     * KV cache in bytes and its share of the card's memory.
+     */
+    beforeCreate?: () => Promise<unknown>;
+    /** The saved card was gone, so `gpuUuid` is a replacement: every progress event of this load says so. */
+    gpuSubstituted?: {
+        requested_gpu_id: string;
+        gpu_id: string;
+    };
+}
+/**
+ * `stopping`: a teardown is in flight (unload, failed load or crash). `stop-unconfirmed`: Docker would
+ * not confirm the stop, so the GPU stays reserved until an unload retries it.
+ */
+export type ManagedSessionState = 'loading' | 'ready' | 'stopping' | 'stop-unconfirmed';
+/** A model holding (or about to hold) its GPU: what residency (task 2.15) must see, including unconfirmed stops. */
+export interface ManagedReservation {
+    model_id: string;
+    generation: string;
+    gpu_uuid: string;
+    container_id: string | null;
+    state: ManagedSessionState;
+}
+/** The logs of a model's last attempt that did not end in a clean unload, kept until its next load. */
+export interface ManagedLastAttempt {
+    model_id: string;
+    generation: string;
+    log_tail: string;
+    error: {
+        code: ErrorCode;
+        message: string;
+    };
+    at: number;
+}
+/** A load that ended because the engine exited, or never got ready: carries the classification and log tail. */
+export declare class ManagedLoadError extends AtomicCoreError {
+    readonly classification: ManagedExitClassification | undefined;
+    readonly exitCode: number | null;
+    constructor(code: ErrorCode, message: string, logTail: string, classification?: ManagedExitClassification, exitCode?: number | null);
+}
+export declare class ManagedTextLifecycle {
+    private readonly deps;
+    private readonly entries;
+    /** Set by `shutdown()`: from then on no load may start a container. */
+    private closed;
+    private readonly lastAttempts;
+    private readonly timings;
+    private readonly log;
+    private readonly fetchFn;
+    private readonly now;
+    private readonly sleep;
+    private readonly newGeneration;
+    private readonly startHeartbeat;
+    private readonly startGateway;
+    constructor(deps: ManagedTextLifecycleDeps);
+    /** Ready sessions only: a loading or stop-unconfirmed model has none to offer. */
+    list(): SessionInfo[];
+    findSession(modelId: string): SessionInfo | undefined;
+    isLoading(modelId: string): boolean;
+    /** Every model holding its GPU, including one whose stop Docker would not confirm. */
+    reservations(): ManagedReservation[];
+    lastAttempt(modelId: string): ManagedLastAttempt | undefined;
+    /** The loaded model's live log tail, or its last attempt's kept tail, or undefined. */
+    logs(modelId: string): Promise<string | undefined>;
+    /** Removes engine caches, refusing one a container of this core still mounts. */
+    removeEngineCaches(selector: EngineCacheSelector): Promise<string[]>;
+    load(request: ManagedLoadRequest): Promise<SessionInfo>;
+    /**
+     * Ends the model's session with a Docker-confirmed stop. Unloading a model still loading cancels
+     * that load. An unconfirmed stop throws `MANAGED_STOP_UNCONFIRMED` and leaves the model reserved.
+     */
+    unload(modelId: string): Promise<void>;
+    /** Unloads everything; failures are logged, never thrown, so one stuck container cannot block shutdown. */
+    shutdown(): Promise<void>;
+    private assertOpen;
+    /**
+     * Ends a session that is not loading with a Docker-confirmed stop. A teardown already in flight (a
+     * second unload, a crash, a failed load) is joined, not repeated, and only the first caller reports
+     * `session:unloaded`.
+     */
+    private unloadEntry;
+    private runLoad;
+    private checkAborted;
+    /** The watchdog must see a live heartbeat from its first poll; `ready` never settles on its own if writes keep failing. */
+    private firstHeartbeat;
+    private createSpec;
+    /**
+     * `docker create` + journal + `docker start`. Core picked the host port, so another process can
+     * bind it before Docker does; that one failure is retried with a new port (bounded), everything
+     * else fails the load. (`beforeCreate` ran once before the launch was built.)
+     */
+    private createAndStart;
+    private waitReady;
+    private exitFailure;
+    /** The adapter's `classifyReady` verdict on a container that just got ready, as the load's error; null when fit. */
+    private readyRefusal;
+    private tail;
+    /** Every line the container logged, bounded only by the docker exec's per-stream output cap (a
+     *  longer log keeps its start and its end). */
+    private wholeLog;
+    private failLoad;
+    private stopUnconfirmed;
+    /**
+     * The one way an entry is stopped: `stopping` while the teardown runs, then gone (confirmed, or no
+     * container at all) or `stop-unconfirmed`. Concurrent callers share the same promise. A teardown
+     * that throws counts as unconfirmed — nothing proved the container stopped. The entry leaves the
+     * table only if it is still the one there, never a newer load's.
+     *
+     * `beforeStop` runs once the session is withdrawn but before the container is stopped and removed:
+     * a crash reads its log tail there, while the entry is already `stopping`, so no load in the
+     * meantime can be handed the dead session.
+     */
+    private end;
+    /**
+     * Gateway closed, heartbeat stopped, container stopped (confirmed) and removed, journal record
+     * dropped. `null` when there was no container to stop. An unconfirmed stop leaves the entry in
+     * `stop-unconfirmed` with its container id, for a later retry and for residency to see.
+     *
+     * The heartbeat stops either way: if Docker merely lost track of an engine that is still running,
+     * the watchdog inside then ends it within its stale limit.
+     */
+    private teardown;
+    /** A started container this load gives up on before it was ready (a republication): stopped, removed, unjournalled. */
+    private discardContainer;
+    /**
+     * The WSL distribution stopped under this core (design D8): every session and load ends at once,
+     * without a docker call, and a ready session is reported dead with `wsl-stopped`.
+     */
+    private onDistributionStopped;
+    private startMonitor;
+    /**
+     * The entry turns `stopping` synchronously, before its log tail is read: a load arriving while the
+     * tail is still being fetched waits for this teardown instead of being handed the dead session.
+     */
+    private onCrash;
+}