@atomic-chat/core 0.5.1 → 0.13.2

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

@@ -0,0 +1,266 @@
+/**
+ * The seam between the engine-neutral managed-text lifecycle (`lifecycle.ts`) and one containerized
+ * engine (openspec change `add-tensorrt-llm-linux`, task 2.12; the TensorRT-LLM adapter is task 2.13).
+ *
+ * An adapter is compiled into core and looked up by the `adapter_id` a pinned runtime descriptor
+ * names — never loaded from metadata. Everything engine-specific the lifecycle needs goes through
+ * this interface: the engine's argv and port, how to tell it is ready, which log lines mark its
+ * progress, how long it may take, and what its exit meant. The lifecycle itself holds no
+ * `engine_id` branch anywhere; a second engine is a second adapter, not an `if`.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+import type { ModelFamilySupport, SessionLoadStage } from '../../contracts/index.js';
+import type { EngineLaunchSpec } from './types.js';
+/** The adapter contract this core implements; a descriptor's `adapter_contract_version` must match. */
+export declare const MANAGED_TEXT_ADAPTER_CONTRACT_VERSION = 1;
+/**
+ * The load stages an engine's own log can move a load into. `stopping-previous` and `ready` belong
+ * to the lifecycle alone: the first happens before any container exists, the second only once the
+ * readiness probe answers.
+ */
+export type EngineLoadStage = Extract<SessionLoadStage, 'starting-container' | 'initializing-engine'>;
+/**
+ * A log line that tells the lifecycle the engine reached `stage`. With no markers the lifecycle moves
+ * to `initializing-engine` as soon as the container starts; with markers it stays in
+ * `starting-container` until one of them shows up in the container's log.
+ */
+export interface ManagedStageMarker {
+    stage: EngineLoadStage;
+    pattern: RegExp;
+}
+/** An HTTP GET against the engine's server root that answers `expectedStatus` once it can serve. */
+export interface ManagedReadinessProbe {
+    /** Absolute path, no query, no `..`: joined onto the internal `BackendTarget`, never a full URL. */
+    path: string;
+    /** A 2xx status. A redirect is never readiness: the probe does not follow redirects at all. */
+    expectedStatus: number;
+}
+/** What an adapter is told when it builds a launch. Container paths are fixed by the executor. */
+export interface ManagedLaunchContext<S> {
+    modelId: string;
+    settings: S;
+    /** The model directory as the container sees it, mounted read-only. */
+    modelPath: string;
+    /** The engine cache directory as the container sees it, mounted read-write and kept across loads. */
+    engineCachePath: string;
+    /**
+     * This generation's own directory as the container sees it, mounted read-only: where the launch's
+     * `files` land (beside the watchdog's heartbeat file), and gone with the generation.
+     */
+    generationFilesPath: string;
+    weightBytes: number;
+    /** The pinned descriptor's `model_families` entry for this model's architecture, or null. */
+    family: ModelFamilySupport | null;
+    /**
+     * The card has no memory of its own (GB10/DGX Spark): what an engine sees as free GPU memory is the
+     * host's free RAM, so a launch that sizes a cache as a share of it takes the operating system's
+     * memory too.
+     */
+    unifiedMemory: boolean;
+    /** The chosen card's memory in bytes (`null` on a unified-memory card or when unknown). */
+    gpuTotalVramBytes?: number | null;
+    /** The chosen card's compute capability (`"8.9"`), or `null` when unknown. */
+    gpuComputeCapability?: string | null;
+    /**
+     * What the provider's `beforeCreate` check answered right before this launch (change
+     * `add-vllm-runtime`, design D9): numbers taken from the card as it stands after the previous
+     * sessions stopped, shaped by and for one engine (vLLM's KV bytes and memory share). Absent for an
+     * engine whose provider plans nothing.
+     */
+    plan?: unknown;
+}
+export interface ManagedEngineLaunch {
+    engine: EngineLaunchSpec;
+    /** The engine's own argv. The container runs `<watchdog entrypoint> -- <argv>`. */
+    argv: string[];
+    /** Engine env vars; the watchdog's own `ATOMIC_WATCHDOG_*` vars are the lifecycle's and win. */
+    env?: Record<string, string>;
+    /**
+     * Files the lifecycle writes, before the container is created, into this generation's read-only
+     * directory (`ManagedLaunchContext.generationFilesPath` inside the container), keyed by a bare file
+     * name — e.g. an engine's option file its argv points at. Core writes them, so nothing the
+     * container runs can change them; the name `heartbeat` is the watchdog's and is refused.
+     */
+    files?: Readonly<Record<string, string>>;
+    /**
+     * `--shm-size` for this engine's container (`<n>k|m|g`, at most the executor's 16g ceiling); absent,
+     * the executor's default (2g). vLLM V1 passes tensors between its API server and engine core through
+     * shared memory (change `add-vllm-runtime`, design D8).
+     */
+    shm_size?: string;
+}
+export type ManagedExitKind = 'out-of-memory' | 'unsupported-model' | 'other';
+/** What an engine's exit meant, read from its log (the whole log before readiness) and exit code. */
+export interface ManagedExitClassification {
+    kind: ManagedExitKind;
+    /** Human wording, including whatever numbers the log gave (e.g. requested vs. free memory). */
+    message: string;
+    /** The numbers behind `message`, for a caller that wants to render them itself. */
+    numbers?: Record<string, number>;
+    /**
+     * The log lines that decided this classification. The lifecycle puts them ahead of the log tail in
+     * the error's details when they are not already in it, so a line a long traceback pushed out of the
+     * tail still reaches the user.
+     */
+    excerpt?: string;
+}
+/** What a loaded model can do through this engine (spec `tensorrt-llm-runtime`, design D9). */
+export interface ManagedTextCapabilities {
+    tools: boolean;
+    reasoning: boolean;
+    structured_output: boolean;
+    vision: boolean;
+    embeddings: boolean;
+    responses: boolean;
+}
+/**
+ * One route this engine serves through the session gateway: method and path together
+ * (findings-2.13-r3.md item 1). Path alone is not enough to declare a route — a path match with the
+ * wrong method must still be refused (`405`), not silently forwarded, or `GET /v1/chat/completions`
+ * would reach the upstream just because the *path* `/v1/chat/completions` happens to be declared for
+ * `POST`. `method` is compared to `IncomingMessage.method` exactly as Node reports it (always
+ * upper-case for a real request; a fake source in a test should match that). `HEAD` is never implied
+ * by a declared `GET` route — an adapter that wants to serve `HEAD` declares it explicitly; the
+ * default (nothing declares it) is a `405`, which is the correct, safe answer for a route that has
+ * no `HEAD` handler of its own.
+ */
+export interface ManagedRoute {
+    method: string;
+    /** Absolute path, no query, no `..`: the same shape a readiness path is held to. */
+    path: string;
+}
+/**
+ * One containerized text engine. `S` is the adapter's own validated settings shape; the lifecycle
+ * treats it as opaque and only ever hands back what `validateSettings` returned.
+ */
+export interface ManagedTextAdapter<S = unknown> {
+    /** Matches the descriptor's `adapter_id`. */
+    readonly id: string;
+    /** Matches the descriptor's `adapter_contract_version`. */
+    readonly contractVersion: number;
+    readonly readiness: ManagedReadinessProbe;
+    readonly stageMarkers: readonly ManagedStageMarker[];
+    /**
+     * Every method+path this engine serves through the session gateway. A path with no matching
+     * method gets `404` from the gateway; a path that *is* declared, but not for the method the
+     * request used, gets `405` with an `Allow` header — neither is ever forwarded upstream
+     * (findings-2.13-r2.md item 3, keyed on method+path since findings-2.13-r3.md item 1: path alone
+     * let `GET`/`PUT`/`DELETE /v1/chat/completions` and `POST`/`DELETE`/`HEAD`/`OPTIONS /v1/models`
+     * all reach the upstream). This is what closes off an engine's own undocumented or administrative
+     * routes (e.g. `trtllm-serve`'s `/update_weights`, `/release_memory`) that were never meant to be
+     * reachable from outside the container. The readiness path (`readiness.path` above) is
+     * deliberately not part of this list — the lifecycle probes it directly against the container's
+     * own port, never through the gateway a caller's traffic goes over.
+     */
+    readonly routes: readonly ManagedRoute[];
+    /**
+     * The subset of `routes` whose request body `rewriteRequestBody` may rewrite — each entry must
+     * also appear in `routes` (checked at registration). Every other declared route (and every
+     * undeclared or wrong-method one, which never gets this far) streams through byte-for-byte: no
+     * JSON parsing, no re-serialization. Absent or empty when `rewriteRequestBody` is not defined at
+     * all.
+     */
+    readonly rewritableRoutes?: readonly ManagedRoute[];
+    /** Throws `AtomicCoreError('INVALID_ARGUMENT', ...)` before any container exists. */
+    validateSettings(raw: unknown): S;
+    buildLaunch(context: ManagedLaunchContext<S>): ManagedEngineLaunch;
+    /** How long readiness may take for this much weight, with margin; a provider setting overrides it. */
+    readinessTimeoutMs(weightBytes: number, settings: S): number;
+    /**
+     * Why the engine exited. Before readiness `log` is the container's whole log (bounded by the docker
+     * exec's per-stream output cap, which keeps a longer log's start and end), so a decisive line far
+     * above the last one still counts; after a crash of a ready session it is the log tail.
+     */
+    classifyExit(log: string, exitCode: number | null): ManagedExitClassification;
+    /**
+     * Optional: why an engine that answers its readiness probe still cannot serve its own launch, read
+     * off the container's whole log right after readiness; `null` when it can. The load then fails as an
+     * exit before readiness would, with this classification, and the container is stopped with
+     * confirmation (TensorRT-LLM on an 8 GB card started with a KV cache of 224 tokens for a 4096-token
+     * context, and every request then failed mid-stream).
+     */
+    classifyReady?(log: string, settings: S): ManagedExitClassification | null;
+    /**
+     * Optional: why the engine cut a streamed answer short, read off the session's log tail right after
+     * the stream broke off; null when the log does not say. The session gateway sends it to the client
+     * as an error event in place of the missing end (`gateway.ts`, `guardedEventStream`).
+     */
+    describeStreamFailure?(logTail: string): string | null;
+    capabilities(context: {
+        settings: S;
+        family: ModelFamilySupport | null;
+    }): ManagedTextCapabilities;
+    /**
+     * Optional: rewrites a JSON POST request body before the session gateway forwards it upstream
+     * (`../managed-text/gateway.ts`'s `startManagedGateway`; see
+     * `docs/decisions/2026-09-28-tensorrt-llm-output-cap-enforced-by-the-session-gateway.md` for why
+     * this exists at all — most engines need no request-side rewriting and should leave it undefined,
+     * and `rewritableRoutes` empty/absent). `route` is the request path with no query string, decoded
+     * and already matched — method and path together — against `routes` by the gateway. The gateway
+     * calls this only for a request whose method+path is listed in `rewritableRoutes`, only with a
+     * non-empty body, under a byte cap enforced while the body streams in (over it answers `413`
+     * before this is even called, without buffering the rest), and only once the body parses as JSON
+     * (a parse failure answers `400` without calling this or reaching the upstream). This may throw to
+     * reject the request outright — e.g. a client-supplied value that is present but not usable — and
+     * must not silently substitute a different value for something invalid and forward that instead.
+     * Throw `AtomicCoreError('INVALID_ARGUMENT', message)` for that: the gateway surfaces its
+     * `message` verbatim as an OpenAI-shaped `400`, since that text was written to be read by the
+     * client whose request it rejects; a `ManagedRequestRefusal` (below) also chooses the OpenAI `code`,
+     * e.g. `unsupported_capability` for what `capabilities` — this session's own, bound by the lifecycle —
+     * says the model cannot do (findings-2.14-r1.md item 1). Any other throw (a bug in this hook itself, not a rejection of
+     * the client's input) becomes a generic `500` instead — the gateway does not assume an arbitrary
+     * thrown value's `message` is safe to show a client (findings-2.13-r3.md item 3). The response
+     * stream is never touched by this hook, on any route, streamed or not.
+     */
+    rewriteRequestBody?(route: string, body: unknown, settings: S, capabilities: ManagedTextCapabilities): unknown;
+    /**
+     * Optional (task 2.14 fix round 1, findings-2.14-r1.md item 1): the OpenAI error body a client gets
+     * for an engine's own error answer on a declared POST route, or `null` to relay the engine's answer
+     * as it is. The gateway calls this only for a non-2xx answer, reads that answer under a small cap
+     * (`MANAGED_GATEWAY_ERROR_BODY_CAP_BYTES`) to do so, and never touches a 2xx answer — streamed or
+     * not. What an engine needs here is a translation of its own error wording into the one clients
+     * already handle (`context_length_exceeded` for `trtllm-serve`'s context overflow).
+     */
+    mapErrorResponse?(route: string, status: number, body: string): object | null;
+    /**
+     * Optional: a rewrite of a 2xx answer's JSON — the whole body, or each SSE `data:` event of a
+     * stream — chosen per request from the request's own (already rewritten) body and the session's
+     * model family, or `null` to relay the answer byte for byte as before. Only for rewritable routes.
+     * Exists for one engine behaviour: a reasoning parser that assumes every reply starts inside the
+     * reasoning (`qwen3_5` on 1.3.0rc29) files a no-thinking reply under `reasoning_content`, and only
+     * the request says whether thinking was on.
+     */
+    rewriteResponseFor?(route: string, requestBody: unknown, family: ModelFamilySupport | null): ManagedResponseRewrite | null;
+    /**
+     * Optional: the part of the validated settings a running container was started with. A later load
+     * of the same model whose settings differ only outside this part joins the running session (with
+     * the new settings in force for what the gateway enforces per request) instead of restarting a
+     * container (findings-2.14-r1.md item 3). Absent, every setting counts.
+     */
+    restartKey?(settings: S): unknown;
+}
+/** Rewrites one JSON object of an engine's 2xx answer (`ManagedTextAdapter.rewriteResponseFor`). */
+export type ManagedResponseRewrite = (json: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * What a request-side hook (`rewriteRequestBody`) throws to refuse a request with a specific OpenAI
+ * error `code` — e.g. `unsupported_capability` for `tools` sent to a model with no tool-call parser.
+ * The gateway answers it as `400 {"error": {message, type: 'invalid_request_error', code}}`, the same
+ * envelope `:1337` uses, so a client sees one shape whichever port it talks to.
+ */
+export declare class ManagedRequestRefusal extends AtomicCoreError {
+    readonly openaiCode: string;
+    constructor(message: string, openaiCode: string);
+}
+/** The adapters compiled into this core, keyed by `adapter_id`. */
+export declare class ManagedTextAdapterRegistry {
+    private readonly adapters;
+    register(adapter: ManagedTextAdapter): void;
+    has(adapterId: string): boolean;
+    ids(): string[];
+    /**
+     * The adapter a pinned descriptor asks for. An id this core does not know, or a contract version
+     * it does not implement, is `MANAGED_ADAPTER_UNAVAILABLE`: the installation cannot be served by
+     * this core, whatever the descriptor says.
+     */
+    resolve(adapterId: string, contractVersion?: number): ManagedTextAdapter;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * The seam between the engine-neutral managed-text lifecycle (`lifecycle.ts`) and one containerized
+ * engine (openspec change `add-tensorrt-llm-linux`, task 2.12; the TensorRT-LLM adapter is task 2.13).
+ *
+ * An adapter is compiled into core and looked up by the `adapter_id` a pinned runtime descriptor
+ * names — never loaded from metadata. Everything engine-specific the lifecycle needs goes through
+ * this interface: the engine's argv and port, how to tell it is ready, which log lines mark its
+ * progress, how long it may take, and what its exit meant. The lifecycle itself holds no
+ * `engine_id` branch anywhere; a second engine is a second adapter, not an `if`.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+/** The adapter contract this core implements; a descriptor's `adapter_contract_version` must match. */
+export const MANAGED_TEXT_ADAPTER_CONTRACT_VERSION = 1;
+/**
+ * What a request-side hook (`rewriteRequestBody`) throws to refuse a request with a specific OpenAI
+ * error `code` — e.g. `unsupported_capability` for `tools` sent to a model with no tool-call parser.
+ * The gateway answers it as `400 {"error": {message, type: 'invalid_request_error', code}}`, the same
+ * envelope `:1337` uses, so a client sees one shape whichever port it talks to.
+ */
+export class ManagedRequestRefusal extends AtomicCoreError {
+    openaiCode;
+    constructor(message, openaiCode) {
+        super('INVALID_ARGUMENT', message);
+        this.name = 'ManagedRequestRefusal';
+        this.openaiCode = openaiCode;
+    }
+}
+const READINESS_PATH = /^\/(?!\/)[A-Za-z0-9._~/-]*$/;
+function invalid(message, detail) {
+    throw new AtomicCoreError('INVALID_ARGUMENT', message, detail);
+}
+/** Same shape a readiness path must have; a declared route is held to the same rule. */
+function assertRoutePath(path, what) {
+    if (!READINESS_PATH.test(path) || path.split('/').some((segment) => segment === '..')) {
+        invalid(`${what} is not an absolute path with no query, fragment or \`..\`.`, path);
+    }
+}
+function assertAdapterShape(adapter) {
+    if (adapter.id === '')
+        invalid('A managed text adapter needs an id.', adapter.id);
+    if (!Number.isInteger(adapter.contractVersion) || adapter.contractVersion < 1) {
+        invalid('A managed text adapter contract version is a positive integer.', String(adapter.contractVersion));
+    }
+    const { path, expectedStatus } = adapter.readiness;
+    assertRoutePath(path, 'A readiness path');
+    if (!Number.isInteger(expectedStatus) || expectedStatus < 200 || expectedStatus > 299) {
+        invalid('A readiness probe expects a 2xx status.', String(expectedStatus));
+    }
+    if (adapter.routes.length === 0) {
+        invalid('A managed text adapter needs at least one declared route.', adapter.id);
+    }
+    for (const route of adapter.routes) {
+        if (route.method === '')
+            invalid('A declared route needs a method.', route.path);
+        assertRoutePath(route.path, 'A declared route');
+    }
+    const isDeclared = (route) => adapter.routes.some((r) => r.method === route.method && r.path === route.path);
+    for (const route of adapter.rewritableRoutes ?? []) {
+        if (!isDeclared(route)) {
+            invalid('A rewritable route must also be a declared route.', `${route.method} ${route.path}`);
+        }
+    }
+}
+/** The adapters compiled into this core, keyed by `adapter_id`. */
+export class ManagedTextAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        assertAdapterShape(adapter);
+        if (this.adapters.has(adapter.id)) {
+            invalid('A managed text adapter with this id is already registered.', adapter.id);
+        }
+        this.adapters.set(adapter.id, adapter);
+    }
+    has(adapterId) {
+        return this.adapters.has(adapterId);
+    }
+    ids() {
+        return [...this.adapters.keys()];
+    }
+    /**
+     * The adapter a pinned descriptor asks for. An id this core does not know, or a contract version
+     * it does not implement, is `MANAGED_ADAPTER_UNAVAILABLE`: the installation cannot be served by
+     * this core, whatever the descriptor says.
+     */
+    resolve(adapterId, contractVersion) {
+        const adapter = this.adapters.get(adapterId);
+        if (adapter === undefined) {
+            throw new AtomicCoreError('MANAGED_ADAPTER_UNAVAILABLE', 'This core has no adapter for the engine this installation needs.', adapterId);
+        }
+        if (contractVersion !== undefined && contractVersion !== adapter.contractVersion) {
+            throw new AtomicCoreError('MANAGED_ADAPTER_UNAVAILABLE', 'The installation needs a different adapter contract version than this core implements.', `${adapterId}: wants ${contractVersion}, core implements ${adapter.contractVersion}`);
+        }
+        return adapter;
+    }
+}
+//# sourceMappingURL=adapter.js.map

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

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

package/dist/runtime/managed-text/backend-target.d.ts

@@ -0,0 +1,3 @@
+import type { BackendTarget } from './types.js';
+/** Pure: throws `AtomicCoreError('FORBIDDEN_HOST', ...)` rather than return an unpublishable port. */
+export declare function projectSessionPort(target: BackendTarget): number;

package/dist/runtime/managed-text/backend-target.js

@@ -0,0 +1,52 @@
+/**
+ * Reduces an internal `BackendTarget` to today's desktop `SessionInfo.port` representation.
+ *
+ * ADR T01e (`docs/decisions/2026-09-23-preserve-deployment-seams.md`): production desktop adapters
+ * publish only on exactly `127.0.0.1` over plain `http`, at an explicit, valid TCP port, with an
+ * empty or root path and no credentials, query or fragment. Projecting another loopback spelling
+ * (`localhost`, `::1`, `127.0.0.2`, ...) to just a port would point an existing caller that already
+ * assumes `127.0.0.1` — the app, the public server's forwarder — at the wrong listener. Anything
+ * that does not fit is refused here, before publication, rather than silently reduced.
+ */
+import { AtomicCoreError } from '../../contracts/index.js';
+const DESKTOP_HOST = '127.0.0.1';
+function refuse(baseUrl, why) {
+    throw new AtomicCoreError('FORBIDDEN_HOST', `Managed backend target cannot be published as a desktop session: ${why}.`, baseUrl);
+}
+/** Pure: throws `AtomicCoreError('FORBIDDEN_HOST', ...)` rather than return an unpublishable port. */
+export function projectSessionPort(target) {
+    let url;
+    try {
+        url = new URL(target.base_url);
+    }
+    catch {
+        return refuse(target.base_url, 'base_url is not a valid URL');
+    }
+    if (url.protocol !== 'http:') {
+        return refuse(target.base_url, `protocol is ${url.protocol.replace(':', '')}, not http`);
+    }
+    if (url.hostname !== DESKTOP_HOST) {
+        return refuse(target.base_url, `host is not exactly ${DESKTOP_HOST}`);
+    }
+    if (url.username !== '' || url.password !== '') {
+        return refuse(target.base_url, 'URL carries credentials');
+    }
+    if (url.search !== '') {
+        return refuse(target.base_url, 'URL carries a query string');
+    }
+    if (url.hash !== '') {
+        return refuse(target.base_url, 'URL carries a fragment');
+    }
+    if (url.pathname !== '/') {
+        return refuse(target.base_url, 'URL is not the server root');
+    }
+    if (url.port === '') {
+        return refuse(target.base_url, 'URL has no explicit port');
+    }
+    const port = Number(url.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        return refuse(target.base_url, 'port is out of range');
+    }
+    return port;
+}
+//# sourceMappingURL=backend-target.js.map

package/dist/runtime/managed-text/backend-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-target.js","sourceRoot":"","sources":["../../../src/runtime/managed-text/backend-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAG1D,MAAM,YAAY,GAAG,WAAW,CAAA;AAEhC,SAAS,MAAM,CAAC,OAAe,EAAE,GAAW;IAC1C,MAAM,IAAI,eAAe,CACvB,gBAAgB,EAChB,oEAAoE,GAAG,GAAG,EAC1E,OAAO,CACR,CAAA;AACH,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,IAAI,GAAQ,CAAA;IACZ,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,6BAA6B,CAAC,CAAA;IAC/D,CAAC;IAED,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,eAAe,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,YAAY,CAAC,CAAA;IAC1F,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,uBAAuB,YAAY,EAAE,CAAC,CAAA;IACvE,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,IAAI,GAAG,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAA;IAC3D,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,4BAA4B,CAAC,CAAA;IAC9D,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CAAA;IAC1D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,GAAG,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,4BAA4B,CAAC,CAAA;IAC9D,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,EAAE,CAAC;QACpB,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,0BAA0B,CAAC,CAAA;IAC5D,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACxD,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,sBAAsB,CAAC,CAAA;IACxD,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC"}

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

@@ -0,0 +1,14 @@
+import type { ManagedDeployment, MountSourceResolver } from './types.js';
+export interface DesktopManagedDeploymentDeps {
+    /** Host ports already claimed by other sessions, so the new publication does not collide. */
+    usedHostPorts?: () => Iterable<number>;
+    /** Injected for tests; the production default binds `randomFreePort` (`runtime/shared`) to loopback. */
+    allocateHostPort?: (usedHostPorts: Iterable<number>) => Promise<number>;
+    mountSource?: MountSourceResolver;
+}
+/**
+ * Desktop bindings for a container started on this machine: loopback publication at a random free
+ * host port, and an identity-mounted heartbeat path by default (a core running on the host and the
+ * Docker daemon it talks to share one filesystem).
+ */
+export declare function createDesktopManagedDeployment(deps?: DesktopManagedDeploymentDeps): ManagedDeployment;

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

@@ -0,0 +1,32 @@
+/**
+ * The desktop `ManagedDeployment` (`types.ts`): publishes an engine's `container_port` on loopback
+ * with a random host port, and resolves the heartbeat file's mount source through the given
+ * `MountSourceResolver` (identity by default; WSL's guest-path resolver replaces it, task 2.8,
+ * without touching this shape). The shared lifecycle depends only on `ManagedDeployment` — it never
+ * allocates a port, picks a socket/distro or branches on OS itself, per ADR T01e.
+ */
+import { randomFreePort } from '../shared/index.js';
+import { identityMountSourceResolver } from './mount-source.js';
+const DESKTOP_HOST = '127.0.0.1';
+/**
+ * Desktop bindings for a container started on this machine: loopback publication at a random free
+ * host port, and an identity-mounted heartbeat path by default (a core running on the host and the
+ * Docker daemon it talks to share one filesystem).
+ */
+export function createDesktopManagedDeployment(deps = {}) {
+    const usedHostPorts = deps.usedHostPorts ?? (() => []);
+    const allocateHostPort = deps.allocateHostPort ?? ((used) => randomFreePort(used));
+    const mountSource = deps.mountSource ?? identityMountSourceResolver;
+    return {
+        mountSource,
+        async prepareLaunch(spec, heartbeatCorePath) {
+            const host_port = await allocateHostPort(usedHostPorts());
+            return {
+                publication: { host: DESKTOP_HOST, host_port, container_port: spec.container_port },
+                target: { base_url: `http://${DESKTOP_HOST}:${host_port}` },
+                heartbeat: { core_path: heartbeatCorePath, mount_source: mountSource(heartbeatCorePath) },
+            };
+        },
+    };
+}
+//# sourceMappingURL=deployment.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"deployment.js","sourceRoot":"","sources":["../../../src/runtime/managed-text/deployment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAA;AAG/D,MAAM,YAAY,GAAG,WAAW,CAAA;AAUhC;;;;GAIG;AACH,MAAM,UAAU,8BAA8B,CAAC,OAAqC,EAAE;IACpF,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,GAAqB,EAAE,CAAC,EAAE,CAAC,CAAA;IACxE,MAAM,gBAAgB,GAAG,IAAI,CAAC,gBAAgB,IAAI,CAAC,CAAC,IAAsB,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAA;IACpG,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,2BAA2B,CAAA;IAEnE,OAAO;QACL,WAAW;QACX,KAAK,CAAC,aAAa,CAAC,IAAsB,EAAE,iBAAyB;YACnE,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,aAAa,EAAE,CAAC,CAAA;YACzD,OAAO;gBACL,WAAW,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE;gBACnF,MAAM,EAAE,EAAE,QAAQ,EAAE,UAAU,YAAY,IAAI,SAAS,EAAE,EAAE;gBAC3D,SAAS,EAAE,EAAE,SAAS,EAAE,iBAAiB,EAAE,YAAY,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE;aAC1F,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/runtime/managed-text/engine-cache.d.ts

@@ -0,0 +1,15 @@
+import { type ManagedScopePaths } from '../../config/index.js';
+/** Creates (if missing) and returns the cache directory for one model under one pinned descriptor. */
+export declare function ensureEngineCacheDir(paths: ManagedScopePaths, descriptorId: string, modelId: string): Promise<string>;
+/** Which caches to remove: one model everywhere, one descriptor entirely, or exactly one of each. */
+export interface EngineCacheSelector {
+    descriptorId?: string;
+    modelId?: string;
+}
+/** Every existing cache folder of one model, one per descriptor it was loaded with (task 2.24). */
+export declare function engineCacheDirsOf(paths: ManagedScopePaths, modelId: string): Promise<string[]>;
+/**
+ * Removes the selected caches and returns the directories it removed. Selecting nothing is refused
+ * rather than read as "everything": wiping every cache is never what removing one thing means.
+ */
+export declare function removeEngineCaches(paths: ManagedScopePaths, selector: EngineCacheSelector): Promise<string[]>;

package/dist/runtime/managed-text/engine-cache.js

@@ -0,0 +1,64 @@
+/**
+ * The engine cache of a managed text model (spec `tensorrt-llm-runtime`, "Кэш движка ускоряет
+ * повторный старт"; design D8): `<data>/atomic-core/managed-runtimes/caches/<descriptor_id>/<model>`,
+ * mounted read-write into that model's container and kept between loads, so a second start does not
+ * redo the engine's preparation. Keying by `descriptor_id` means a new engine release never reads a
+ * cache an older one wrote; removing a model or an installation removes its caches with it.
+ *
+ * Paths come from `config/paths.ts` (`ManagedScopePaths`), which percent-encodes both ids into one
+ * path segment each, so no id can climb out of the cache root.
+ */
+import { mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { encodeManagedId } from '../../config/index.js';
+/** Creates (if missing) and returns the cache directory for one model under one pinned descriptor. */
+export async function ensureEngineCacheDir(paths, descriptorId, modelId) {
+    const dir = paths.engineCacheDir(descriptorId, modelId);
+    await mkdir(dir, { recursive: true });
+    return dir;
+}
+async function descriptorDirs(cachesDir) {
+    const entries = await readdir(cachesDir, { withFileTypes: true }).catch((error) => {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => join(cachesDir, entry.name));
+}
+/** Every existing cache folder of one model, one per descriptor it was loaded with (task 2.24). */
+export async function engineCacheDirsOf(paths, modelId) {
+    const candidates = (await descriptorDirs(paths.cachesDir)).map((dir) => join(dir, encodeManagedId(modelId)));
+    const present = await Promise.all(candidates.map((dir) => readdir(dir).then(() => true, () => false)));
+    return candidates.filter((_, i) => present[i]);
+}
+async function removeIfPresent(path) {
+    const existed = await readdir(path).then(() => true, () => false);
+    if (existed)
+        await rm(path, { recursive: true, force: true });
+    return existed;
+}
+/**
+ * Removes the selected caches and returns the directories it removed. Selecting nothing is refused
+ * rather than read as "everything": wiping every cache is never what removing one thing means.
+ */
+export async function removeEngineCaches(paths, selector) {
+    const { descriptorId, modelId } = selector;
+    if (descriptorId === undefined && modelId === undefined) {
+        throw new AtomicCoreError('INVALID_ARGUMENT', 'Say which engine caches to remove: a model, a descriptor, or both.');
+    }
+    const targets = descriptorId === undefined
+        ? (await descriptorDirs(paths.cachesDir)).map((dir) => join(dir, encodeManagedId(modelId)))
+        : [
+            modelId === undefined
+                ? paths.descriptorCachesDir(descriptorId)
+                : paths.engineCacheDir(descriptorId, modelId),
+        ];
+    const removed = [];
+    for (const target of targets) {
+        if (await removeIfPresent(target))
+            removed.push(target);
+    }
+    return removed;
+}
+//# sourceMappingURL=engine-cache.js.map

package/dist/runtime/managed-text/engine-cache.js.map

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