@telora/daemon 0.18.61 → 0.18.67

package/dist/host-control/sizing.js

@@ -0,0 +1,464 @@
+/**
+ * Hardware-aware context sizing for the host-control plane (Local model host
+ * control, D3).
+ *
+ * The problem this closes: `max_seq_length` (the load-time context window) was a
+ * MANUAL, hardware-blind input. Set it too SMALL and codex's turn-1 prompt does
+ * not fit -- the load silently fails turn-1 with an instant `response.failed`
+ * (live: a 4096-ctx load failed; a manual reload to >=16k fixed it). Set it too
+ * LARGE and the KV-cache (which scales with context) OOMs a near-full GPU (live:
+ * a 12GB card sat ~93% used with a model resident). The safe value is bounded
+ * BELOW by codex's ~8k turn-1 floor and ABOVE by remaining VRAM headroom.
+ *
+ * This module adds two things:
+ *   1. defensive client reads over the host's hardware + kv-cache endpoints
+ *      (`getHardware`, `getKvCacheEstimate`) -- the live JSON shapes are NOT
+ *      pinned, so the normalizers tolerate reasonable field-name variants and
+ *      are flagged for runbook reconciliation;
+ *   2. a PURE `computeSafeMaxSeqLength` (no HTTP) -- the heart: pick the largest
+ *      context that clears the codex floor without exceeding VRAM headroom,
+ *      reaching for optional KV-cache quantization when it lets a context fit.
+ *
+ * The hardware/kv-cache endpoints live under the host ROOT (NOT `/v1`), so we
+ * derive the root with `hostRootFromBaseUrl` (strips a trailing `/v1`). All
+ * errors are address-free (TEL-5): the load path treats any read failure as
+ * "no sizing data" and falls back to the fixed floor default, never breaking a
+ * swap that previously worked.
+ */
+import { hostGet, hostRootFromBaseUrl } from './client.js';
+import { DEFAULT_MAX_SEQ_LENGTH } from './load.js';
+/**
+ * The control-surface path (under the host ROOT, not `/v1`) for GPU hardware
+ * info: GPU name + total/used VRAM. Reconcile field names per the runbook.
+ */
+export const HOST_CONTROL_HARDWARE_PATH = '/api/system/hardware';
+/**
+ * The control-surface path (under the host ROOT, not `/v1`) for a KV-cache fit
+ * prediction at a candidate context. Reconcile field names per the runbook.
+ */
+export const HOST_CONTROL_KV_CACHE_PATH = '/api/models/kv-cache-estimate';
+/**
+ * Codex's turn-1 context floor. A load BELOW this silently fails the very first
+ * codex turn (instant `response.failed`) -- so we treat it as a HARD lower
+ * bound and never return a `maxSeqLength` under it, even when VRAM headroom is
+ * tight (we signal quant-required/marginal instead of silently going lower).
+ *
+ * The live datapoint: a 4096-ctx load failed turn-1; a reload to >=16384
+ * worked. The exact floor is ~8k; 8192 is the documented conservative pin.
+ */
+export const CODEX_TURN1_FLOOR = 8192;
+/**
+ * VRAM safety margin (MB) held back from raw headroom before sizing the KV
+ * cache. A near-full GPU (live: 12GB card ~93% used with a model resident)
+ * leaves little slack; this guards against the estimate being slightly optimistic,
+ * driver/allocator overhead, and fragmentation. Conservative on purpose --
+ * an OOM costs a whole swap, a slightly-smaller context costs nothing.
+ */
+export const VRAM_SAFETY_MARGIN_MB = 512;
+/**
+ * Per-token KV-cache cost heuristic (MB per 1 token of context) used as the
+ * FALLBACK growth model when the host's kv-cache-estimate endpoint is not
+ * consulted (the pure path takes only static inputs). This is intentionally a
+ * coarse upper-ish estimate for a ~7-8B class model at fp16 KV; the actual
+ * footprint is model-architecture-specific. The host's `getKvCacheEstimate`
+ * endpoint, when reachable, gives a far better per-context number and SHOULD be
+ * preferred by the orchestrator; this constant only bounds the pure computation
+ * when no live estimate is supplied.
+ *
+ * Derivation sketch (documented so the runbook can refine it): KV bytes ~=
+ * 2 (K and V) * layers * 2 (kv heads grouping varies) * head_dim * bytes/elem.
+ * For a 7B-class model at fp16 this lands on the order of ~0.12-0.20 MB/token;
+ * we pin a conservative 0.16 MB/token. Quantized KV (int8/fp8) roughly halves
+ * this -- see `KV_QUANT_FOOTPRINT_FACTOR`.
+ */
+export const KV_CACHE_MB_PER_TOKEN = 0.16;
+/**
+ * Footprint multiplier when KV-cache quantization is requested. int8/fp8 KV
+ * roughly halves the per-token cost vs fp16. Conservative 0.5 -- a real host
+ * may do better; the kv-cache-estimate endpoint, when consulted, supersedes
+ * this heuristic.
+ */
+export const KV_QUANT_FOOTPRINT_FACTOR = 0.5;
+/**
+ * The KV-cache dtype token sent as `cache_type_kv` on the load wire when the
+ * sizer elects to quantize to fit a context. The exact accepted token is
+ * host-specific; `q8_0` is the common llama.cpp-family int8 KV token. Flag for
+ * the runbook to confirm against the live host's accepted values.
+ */
+export const KV_QUANT_CACHE_TYPE = 'q8_0';
+/**
+ * Hard ceiling on the context we will ever request, independent of headroom,
+ * when no native-context bound is known. A sane upper clamp so a wildly large
+ * estimate cannot produce an absurd request. Native context (when known) clamps
+ * tighter than this.
+ */
+export const MAX_SEQ_LENGTH_CEILING = 131072;
+// ── Defensive normalizers (live shapes NOT pinned -- runbook reconciles) ──────
+/** Read the first finite, non-negative number-valued key present; null if none. */
+function firstNumberOrNull(obj, keys) {
+    for (const key of keys) {
+        const v = obj[key];
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 0)
+            return v;
+        // Some hosts stringify numbers; accept a clean numeric string defensively.
+        if (typeof v === 'string') {
+            const n = Number(v.trim());
+            if (Number.isFinite(n) && n >= 0)
+                return n;
+        }
+    }
+    return null;
+}
+/** Read the first non-blank string-valued key present, trimmed; null if none. */
+function firstStringOrNull(obj, keys) {
+    for (const key of keys) {
+        const v = obj[key];
+        if (typeof v === 'string') {
+            const trimmed = v.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    return null;
+}
+/** Candidate keys for the GPU product name on a hardware payload. */
+const HW_GPU_NAME_KEYS = ['gpu_name', 'gpuName', 'name', 'gpu', 'device_name', 'product_name'];
+/**
+ * Candidate keys for TOTAL VRAM in MB. We tolerate both MB-named and bytes-named
+ * fields; a bytes field is converted in `normalizeHardware`. The MB keys win
+ * when present (no conversion ambiguity).
+ */
+const HW_VRAM_TOTAL_MB_KEYS = ['vram_total_mb', 'vramTotalMb', 'memory_total_mb', 'total_memory_mb'];
+const HW_VRAM_TOTAL_BYTES_KEYS = ['vram_total_bytes', 'vram_total', 'memory_total', 'total_memory_bytes'];
+/** Candidate keys for USED VRAM in MB / bytes (same MB-preferred convention). */
+const HW_VRAM_USED_MB_KEYS = ['vram_used_mb', 'vramUsedMb', 'memory_used_mb', 'used_memory_mb'];
+const HW_VRAM_USED_BYTES_KEYS = ['vram_used_bytes', 'vram_used', 'memory_used', 'used_memory_bytes'];
+/** Bytes -> MB (binary MiB), rounded down so we never overstate available memory. */
+function bytesToMb(bytes) {
+    return Math.floor(bytes / (1024 * 1024));
+}
+/**
+ * Resolve a VRAM quantity in MB from a payload, preferring an MB-named field and
+ * falling back to a bytes-named field (converted). Some hosts nest VRAM under a
+ * `gpu`/`gpus[0]`/`memory` sub-object; we also probe a single nested object.
+ * Returns null when nothing usable is present.
+ */
+function vramMb(obj, mbKeys, bytesKeys) {
+    const mb = firstNumberOrNull(obj, mbKeys);
+    if (mb !== null)
+        return Math.floor(mb);
+    const bytes = firstNumberOrNull(obj, bytesKeys);
+    if (bytes !== null)
+        return bytesToMb(bytes);
+    return null;
+}
+/**
+ * Probe for a nested hardware sub-object so a payload like
+ * `{ gpu: { name, vram_total_mb, ... } }` or `{ gpus: [ {...} ] }` still yields
+ * fields. Returns the merged top-level + nested view (top-level wins).
+ */
+function flattenHardwarePayload(obj) {
+    const nestedKeys = ['gpu', 'memory', 'device'];
+    let merged = { ...obj };
+    for (const key of nestedKeys) {
+        const v = obj[key];
+        if (v && typeof v === 'object' && !Array.isArray(v)) {
+            merged = { ...v, ...merged };
+        }
+    }
+    // A `gpus: [ {...} ]` array -- take the first entry as the active device.
+    const gpus = obj['gpus'];
+    if (Array.isArray(gpus) && gpus.length > 0 && gpus[0] && typeof gpus[0] === 'object') {
+        merged = { ...gpus[0], ...merged };
+    }
+    return merged;
+}
+/**
+ * Normalize a `/api/system/hardware` payload into a typed `HostHardware`.
+ * DEFENSIVE: the live shape is NOT pinned. Tolerates MB- or bytes-named VRAM
+ * fields, a flat or a `{ gpu: {...} }` / `{ gpus: [...] }` nesting, and missing
+ * fields (-> null). Pure + exported for unit testing.
+ *
+ * Runbook flag: confirm the live `/api/system/hardware` field names + units
+ * (MB vs bytes) and tighten `HW_*_KEYS` once observed.
+ */
+export function normalizeHardware(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { gpuName: null, vramTotalMb: null, vramUsedMb: null };
+    }
+    const obj = flattenHardwarePayload(payload);
+    return {
+        gpuName: firstStringOrNull(obj, HW_GPU_NAME_KEYS),
+        vramTotalMb: vramMb(obj, HW_VRAM_TOTAL_MB_KEYS, HW_VRAM_TOTAL_BYTES_KEYS),
+        vramUsedMb: vramMb(obj, HW_VRAM_USED_MB_KEYS, HW_VRAM_USED_BYTES_KEYS),
+    };
+}
+/** Candidate keys for the predicted KV-cache footprint (MB) on an estimate payload. */
+const KV_FOOTPRINT_MB_KEYS = ['kv_cache_mb', 'kvCacheMb', 'footprint_mb', 'estimate_mb', 'mb'];
+const KV_FOOTPRINT_BYTES_KEYS = ['kv_cache_bytes', 'footprint_bytes', 'bytes'];
+/** Candidate keys for a boolean "does it fit" verdict on an estimate payload. */
+const KV_FITS_KEYS = ['fits', 'ok', 'will_fit'];
+/**
+ * Normalize a `/api/models/kv-cache-estimate` payload into a typed
+ * `KvCacheEstimate`. DEFENSIVE: footprint under MB- or bytes-named fields, an
+ * optional boolean fit verdict, both null/undefined when absent. Pure + exported.
+ *
+ * Runbook flag: confirm the live estimate field names + whether the endpoint
+ * echoes the candidate context; tighten `KV_*_KEYS` once observed.
+ */
+export function normalizeKvCacheEstimate(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return { footprintMb: null, fits: null };
+    }
+    const obj = payload;
+    let footprintMb = firstNumberOrNull(obj, KV_FOOTPRINT_MB_KEYS);
+    if (footprintMb === null) {
+        const bytes = firstNumberOrNull(obj, KV_FOOTPRINT_BYTES_KEYS);
+        if (bytes !== null)
+            footprintMb = bytesToMb(bytes);
+    }
+    let fits = null;
+    for (const key of KV_FITS_KEYS) {
+        const v = obj[key];
+        if (typeof v === 'boolean') {
+            fits = v;
+            break;
+        }
+    }
+    return { footprintMb, fits };
+}
+// ── Client reads ──────────────────────────────────────────────────────────────
+/**
+ * Read the host's GPU + VRAM info (`GET <root>/api/system/hardware`), normalized
+ * to a typed `HostHardware`. The hardware endpoint lives under the host ROOT,
+ * NOT `/v1`, so we derive the root from the stored baseUrl. Throws
+ * `HostControlError` (address-free) on any transport failure -- the caller
+ * fail-safes to the floor default.
+ */
+export async function getHardware(baseUrl, apiKey) {
+    const root = hostRootFromBaseUrl(baseUrl);
+    const payload = await hostGet(`${root}${HOST_CONTROL_HARDWARE_PATH}`, { apiKey });
+    return normalizeHardware(payload);
+}
+/**
+ * Read a KV-cache fit prediction for a candidate context
+ * (`GET <root>/api/models/kv-cache-estimate`). The candidate context (and an
+ * optional model path + kv quant) are passed as query params; the live host's
+ * exact param names are NOT pinned, so we send the common-sense set and the
+ * normalizer is defensive about the response. Throws `HostControlError` on any
+ * transport failure -- the caller treats it as "no estimate" and uses the pure
+ * heuristic instead.
+ *
+ * Runbook flag: confirm the live query-param names (`max_seq_length`,
+ * `model_path`, `cache_type_kv`) the endpoint expects.
+ */
+export async function getKvCacheEstimate(baseUrl, params, apiKey) {
+    const root = hostRootFromBaseUrl(baseUrl);
+    const qs = new URLSearchParams();
+    // snake_case ONLY at the wire boundary (query string).
+    qs.set('max_seq_length', String(params.maxSeqLength));
+    if (params.modelPath)
+        qs.set('model_path', params.modelPath);
+    if (params.cacheTypeKv)
+        qs.set('cache_type_kv', params.cacheTypeKv);
+    const payload = await hostGet(`${root}${HOST_CONTROL_KV_CACHE_PATH}?${qs.toString()}`, { apiKey });
+    return normalizeKvCacheEstimate(payload);
+}
+// ── The pure heart: computeSafeMaxSeqLength ──────────────────────────────────
+/**
+ * Round a context length down to a power-of-two-ish, clean step. Hosts size KV
+ * buffers in chunks; a clean step avoids requesting an awkward non-aligned
+ * context. We step in 1024-token units (a context is always a multiple of 1024)
+ * and never round a value below the floor up-and-over -- callers clamp the floor
+ * separately. Returns at least 0.
+ */
+function roundDownToStep(value, step = 1024) {
+    if (value <= 0)
+        return 0;
+    return Math.floor(value / step) * step;
+}
+/**
+ * The per-token KV-cache cost for the chosen quant mode (fp16 vs quantized).
+ */
+function perTokenCost(kvQuant) {
+    return kvQuant ? KV_CACHE_MB_PER_TOKEN * KV_QUANT_FOOTPRINT_FACTOR : KV_CACHE_MB_PER_TOKEN;
+}
+/**
+ * The largest context (rounded to the step) whose KV cache fits within
+ * `availableMb` at the given per-token cost, clamped to `nativeCap`. May return
+ * a value BELOW the floor -- the caller decides what to do with that.
+ */
+function largestFittingContext(availableMb, kvQuant, nativeCap) {
+    if (availableMb <= 0)
+        return 0;
+    const rawTokens = availableMb / perTokenCost(kvQuant);
+    const stepped = roundDownToStep(rawTokens);
+    return Math.min(stepped, nativeCap);
+}
+/**
+ * PURE: compute the safe `max_seq_length` (and whether to quantize the KV cache)
+ * for a load, given VRAM totals/usage, the resident model size, and the model's
+ * native context. NO HTTP -- the orchestrator gathers the inputs and (optionally)
+ * validates the result against the live kv-cache endpoint.
+ *
+ * The arithmetic, with the live constraints in mind:
+ *
+ *  - headroom = vramTotal - vramUsed - VRAM_SAFETY_MARGIN_MB. This is the VRAM
+ *    available for the KV cache AFTER the model weights are resident. (Live: a
+ *    12GB card sat ~93% used with a model loaded -- headroom is small, so the
+ *    KV cache, which scales with context, is the binding constraint.) When
+ *    `vramUsed` already accounts for the weights, `modelSizeMb` is informational;
+ *    when it does not, we subtract `modelSizeMb` too (see below).
+ *
+ *  - The KV cache grows ~linearly with context (`KV_CACHE_MB_PER_TOKEN`). We pick
+ *    the LARGEST context whose KV cache fits headroom, clamped to the model's
+ *    native context (`nativeContext`) and the global ceiling.
+ *
+ *  - HARD LOWER BOUND (codex floor): a context below `CODEX_TURN1_FLOOR` silently
+ *    fails turn-1, so we NEVER return below it. If headroom can't fit the floor
+ *    at fp16 KV, we try quantization (`cacheTypeKv`), which ~halves the footprint.
+ *    If even quantized KV can't fit the floor, we return the floor ANYWAY with
+ *    `quantRequired`/`marginal` set -- going below is not an option; better to
+ *    attempt the floor (and let the load fail loudly / the operator add VRAM)
+ *    than to silently load a too-small context that fails turn-1 with no signal.
+ *
+ *  - When inputs are missing/degenerate (no VRAM data, zero/negative headroom),
+ *    we degrade SAFELY to the floor default -- never throw, never go below floor.
+ */
+export function computeSafeMaxSeqLength(input) {
+    const floor = input.codexFloor ?? CODEX_TURN1_FLOOR;
+    // Native context bounds everything; when unknown, fall back to the global
+    // ceiling so headroom (not an unknown native cap) is the binding constraint.
+    const nativeCap = typeof input.nativeContext === 'number' && input.nativeContext >= floor
+        ? input.nativeContext
+        : MAX_SEQ_LENGTH_CEILING;
+    // Degenerate VRAM inputs -> we cannot size against headroom. Return the floor
+    // (clamped to native) and signal marginal so the orchestrator logs it. NEVER
+    // go below the floor; NEVER throw.
+    const vramTotal = input.vramTotalMb;
+    const vramUsed = input.vramUsedMb;
+    if (vramTotal === null ||
+        vramTotal === undefined ||
+        vramUsed === null ||
+        vramUsed === undefined ||
+        !Number.isFinite(vramTotal) ||
+        !Number.isFinite(vramUsed)) {
+        return { maxSeqLength: Math.min(floor, nativeCap === floor ? floor : Math.max(floor, nativeCap)), marginal: true };
+    }
+    // Headroom = total - used - safety margin. If the host's `vramUsed` does NOT
+    // already include the candidate model's weights (i.e. nothing resident yet),
+    // also subtract the model size so we size the KV cache against memory left
+    // AFTER the weights load. We can't know which the host reports, so we take the
+    // conservative interpretation: subtract modelSize only when it would not already
+    // be reflected -- i.e. when used is small relative to the model size, treat the
+    // model as not-yet-resident and reserve its weights. This keeps us safe on a
+    // cold GPU (subtract weights) and on a warm GPU (used already high -> no double
+    // subtract because we cap headroom at >= 0).
+    const modelSize = typeof input.modelSizeMb === 'number' && input.modelSizeMb > 0 ? input.modelSizeMb : 0;
+    const modelNotYetResident = modelSize > 0 && vramUsed < modelSize;
+    const reservedForWeights = modelNotYetResident ? modelSize : 0;
+    const headroom = vramTotal - vramUsed - VRAM_SAFETY_MARGIN_MB - reservedForWeights;
+    const requestedQuant = input.kvQuant === true;
+    // First try fp16 KV (no quant) unless the caller pre-requested quant.
+    const fp16Fit = largestFittingContext(headroom, false, nativeCap);
+    if (!requestedQuant && fp16Fit >= floor) {
+        // Comfortable: the largest fp16 context that fits clears the floor.
+        return { maxSeqLength: fp16Fit };
+    }
+    // fp16 can't clear the floor (or quant was requested) -> try quantized KV,
+    // which ~halves the per-token cost and so fits a larger context.
+    const quantFit = largestFittingContext(headroom, true, nativeCap);
+    if (quantFit >= floor) {
+        // Quantization buys us the floor (or more). Take the larger of the two paths
+        // that clears the floor; if fp16 already cleared it (requestedQuant case),
+        // honor the requested quant but never drop below what fp16 would have given.
+        const best = Math.max(quantFit, requestedQuant && fp16Fit >= floor ? fp16Fit : 0);
+        return { maxSeqLength: Math.min(best, nativeCap), cacheTypeKv: KV_QUANT_CACHE_TYPE };
+    }
+    // Even quantized KV can't fit the floor in the available headroom. Do NOT go
+    // below the floor (that silently fails turn-1). Return the floor clamped to
+    // native, flag quant-required + marginal so the load path logs the risk; the
+    // load may fail loudly / the operator must free VRAM. Better a loud floor
+    // attempt than a silent sub-floor failure.
+    return {
+        maxSeqLength: Math.min(floor, nativeCap),
+        cacheTypeKv: KV_QUANT_CACHE_TYPE,
+        quantRequired: true,
+        marginal: true,
+    };
+}
+/**
+ * Resolve the safe `EnsureLoadedOptions` sizing bits (`maxSeqLength` + optional
+ * `cacheTypeKv`) for a load by reading the host's hardware, running the PURE
+ * `computeSafeMaxSeqLength`, and OPTIONALLY validating the result against the
+ * live kv-cache-estimate endpoint. This is the seam the focus-executor calls in
+ * place of D2's fixed `DEFAULT_MAX_SEQ_LENGTH`.
+ *
+ * FAIL-SAFE: if the hardware endpoint is missing / unreachable / returns no VRAM
+ * totals, we DO NOT compute against headroom -- we return the fixed
+ * `DEFAULT_MAX_SEQ_LENGTH` (>= the codex floor) exactly as D2 did, and report the
+ * fallback so the caller logs it. A sizing failure must NEVER break a swap that
+ * previously worked with the fixed default.
+ *
+ * The kv-cache-estimate validation is best-effort: if it predicts the computed
+ * context will NOT fit (and we are not already quantizing), we re-run the sizer
+ * forcing quantization; if the endpoint is unreachable we keep the pure result.
+ * The estimate is never allowed to push the context BELOW the floor.
+ *
+ * Returns `{ maxSeqLength, cacheTypeKv?, source, marginal?, quantRequired? }`.
+ * `source` is `'computed'` when hardware drove the value, `'fallback'` when we
+ * fell back to the fixed default -- the caller logs which path it took.
+ */
+export async function resolveSafeLoadOptions(baseUrl, modelPath, hints = {}, apiKey) {
+    let hardware;
+    try {
+        hardware = await getHardware(baseUrl, apiKey);
+    }
+    catch {
+        // Hardware endpoint missing / unreachable -> fail-safe to the fixed default.
+        // Address-free: the rich error was already categorized inside the client; we
+        // do not surface or rethrow it -- a sizing read failure is non-fatal.
+        return { maxSeqLength: DEFAULT_MAX_SEQ_LENGTH, source: 'fallback' };
+    }
+    // No usable VRAM totals -> we cannot size against headroom. Fail-safe to the
+    // fixed default (which clears the floor), rather than guessing.
+    if (hardware.vramTotalMb === null) {
+        return { maxSeqLength: DEFAULT_MAX_SEQ_LENGTH, source: 'fallback' };
+    }
+    const computed = computeSafeMaxSeqLength({
+        vramTotalMb: hardware.vramTotalMb,
+        vramUsedMb: hardware.vramUsedMb,
+        modelSizeMb: hints.modelSizeMb ?? null,
+        nativeContext: hints.nativeContext ?? null,
+    });
+    // Best-effort validation against the live kv-cache estimate. If the host says
+    // the computed context will NOT fit and we are not already quantizing, re-run
+    // the sizer forcing quantization. A failed estimate read is ignored (keep the
+    // pure result). The estimate can never push us below the floor.
+    let result = computed;
+    if (!computed.cacheTypeKv) {
+        try {
+            const estimate = await getKvCacheEstimate(baseUrl, { maxSeqLength: computed.maxSeqLength, modelPath: modelPath ?? undefined }, apiKey);
+            if (estimate.fits === false) {
+                result = computeSafeMaxSeqLength({
+                    vramTotalMb: hardware.vramTotalMb,
+                    vramUsedMb: hardware.vramUsedMb,
+                    modelSizeMb: hints.modelSizeMb ?? null,
+                    nativeContext: hints.nativeContext ?? null,
+                    kvQuant: true,
+                });
+            }
+        }
+        catch {
+            // Estimate endpoint missing / unreachable -> keep the pure computed result.
+        }
+    }
+    return {
+        maxSeqLength: result.maxSeqLength,
+        ...(result.cacheTypeKv !== undefined ? { cacheTypeKv: result.cacheTypeKv } : {}),
+        source: 'computed',
+        ...(result.marginal !== undefined ? { marginal: result.marginal } : {}),
+        ...(result.quantRequired !== undefined ? { quantRequired: result.quantRequired } : {}),
+    };
+}
+//# sourceMappingURL=sizing.js.map

package/dist/host-control/sizing.js.map

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

package/dist/host-control/types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Shared types for the host-control plane (Local model host control, D1).
+ *
+ * The host-control plane sits ABOVE the OpenAI-compatible `/v1/models` floor: a
+ * controllable model host (e.g. Unsloth Studio) exposes its FULL downloaded
+ * catalog -- including models that are downloaded-but-not-loaded -- under a
+ * control surface (`/api/models/local`). Detection is per-endpoint and
+ * fail-safe: a plain OpenAI-compatible endpoint that lacks the control surface
+ * degrades cleanly to the load-then-discover (`/v1/models`) behavior.
+ *
+ * Delivery 1 covers detection + catalog read. Later deliveries (`load.ts`,
+ * `sizing.ts`) add load/unload + sizing on top of these types; keep this module
+ * additive-friendly.
+ */
+/**
+ * One loadable model from a controllable host's catalog. `id` is the served
+ * model identifier (the value the picklist offers); `modelPath` is the host's
+ * own load path (`model_path`) captured so a later delivery can resolve
+ * id -> path to load the model. Optional richer fields (size, family) are added
+ * by later deliveries -- keep this interface open to extension.
+ */
+export interface LoadableModel {
+    /** Served model id -- the value offered in the add-model picklist. */
+    id: string;
+    /**
+     * The host's load path for this model (`model_path` on the wire). Null when
+     * the catalog entry did not carry one (a degraded/floor entry, or a host that
+     * omits the field). Delivery 2 consumes id -> modelPath to load.
+     */
+    modelPath: string | null;
+}
+/**
+ * The result of reading an endpoint's loadable-model catalog. `controllable`
+ * records whether the host-control surface answered (true) or we fell back to
+ * the `/v1/models` floor (false). `ids` is the flat string[] for the picklist;
+ * `models` carries the richer entries for downstream load resolution. On the
+ * floor path `models` mirrors `ids` with `modelPath: null`.
+ */
+export interface LoadableCatalog {
+    /** True when the controllable host catalog answered; false on the floor path. */
+    controllable: boolean;
+    /** De-duplicated served model ids -- the picklist payload. */
+    ids: string[];
+    /** Richer per-model entries (id + modelPath) for downstream load resolution. */
+    models: LoadableModel[];
+}
+/**
+ * The outcome of a cheap, fail-safe capability probe against an endpoint's host
+ * root. `controllable: true` means the control surface answered a well-formed
+ * catalog; anything else (error / non-2xx / parse failure / timeout) yields
+ * `false` so the caller falls back to the `/v1/models` floor.
+ */
+export interface HostCapability {
+    controllable: boolean;
+}
+/**
+ * Normalized `/v1/status` snapshot (Local model host control, D2). The host's
+ * live status shape is NOT pinned, so the normalizer is defensive; this is the
+ * typed result it yields. `loadedModelId` is the currently-resident served id
+ * (null when nothing is loaded); `ready` is whether that model is up + serving.
+ */
+export interface HostStatus {
+    /** Currently-loaded served model id, or null when nothing is resident. */
+    loadedModelId: string | null;
+    /** True when the loaded model is up and ready to serve. */
+    ready: boolean;
+}
+/**
+ * Parameters for a `POST /v1/load` (Local model host control, D2). camelCase app
+ * types here; the load client maps them to the host's snake_case wire field
+ * names (`model_path`, `max_seq_length`, `cache_type_kv`, `gpu_ids`) at the
+ * boundary. `maxSeqLength` is REQUIRED + injected so Delivery 3 can pass a
+ * computed safe value rather than the fixed `DEFAULT_MAX_SEQ_LENGTH` floor.
+ */
+export interface LoadModelParams {
+    /** The host's load path for the target model (`model_path` on the wire). */
+    modelPath: string;
+    /** Context window to load with (`max_seq_length` on the wire). */
+    maxSeqLength: number;
+    /** Optional KV cache dtype (`cache_type_kv` on the wire). */
+    cacheTypeKv?: string;
+    /** Optional GPU id selection (`gpu_ids` on the wire). */
+    gpuIds?: number[];
+}
+/**
+ * The action a single-GPU swap must take to make a target model resident, given
+ * the current resident model (Local model host control, D2). One model fits the
+ * GPU at a time, so a different resident must be evicted before the load.
+ */
+export type SwapAction = 'noop' | 'load' | 'evict_then_load';
+/** The pure swap decision -- the action `ensureLoaded` will perform. */
+export interface SwapDecision {
+    action: SwapAction;
+}
+/**
+ * Normalized `/api/system/hardware` snapshot (Local model host control, D3). The
+ * host's live shape is NOT pinned, so the normalizer is defensive; this is the
+ * typed result it yields. VRAM is carried in MB (the normalizer converts a
+ * bytes-named source). Any field the host omits is null -- the sizer degrades
+ * safely to the floor default when VRAM totals are unavailable.
+ */
+export interface HostHardware {
+    /** GPU product name (e.g. "NVIDIA GeForce RTX 3060"), or null when absent. */
+    gpuName: string | null;
+    /** Total VRAM in MB, or null when the host did not report it. */
+    vramTotalMb: number | null;
+    /** Currently-used VRAM in MB, or null when the host did not report it. */
+    vramUsedMb: number | null;
+}
+/**
+ * Query params for a `GET /api/models/kv-cache-estimate` (Local model host
+ * control, D3). camelCase here; the client maps them to the host's snake_case
+ * query-string field names (`max_seq_length`, `model_path`, `cache_type_kv`) at
+ * the boundary. The candidate context is required; model path + kv quant are
+ * optional refiners.
+ */
+export interface KvCacheEstimateParams {
+    /** Candidate context to estimate the KV-cache footprint for. */
+    maxSeqLength: number;
+    /** Optional model path so the host can size against the specific model. */
+    modelPath?: string;
+    /** Optional KV-cache dtype (e.g. quantized) to estimate the smaller footprint. */
+    cacheTypeKv?: string;
+}
+/**
+ * Normalized `/api/models/kv-cache-estimate` result (Local model host control,
+ * D3). DEFENSIVE: the live shape is NOT pinned. `footprintMb` is the predicted
+ * KV-cache memory (MB) for the candidate context (null when not reported);
+ * `fits` is an optional host verdict on whether it fits available VRAM.
+ */
+export interface KvCacheEstimate {
+    /** Predicted KV-cache footprint in MB for the candidate context, or null. */
+    footprintMb: number | null;
+    /** Optional host verdict on whether the candidate context fits, or null. */
+    fits: boolean | null;
+}
+/**
+ * Input to the PURE `computeSafeMaxSeqLength` (Local model host control, D3). All
+ * static -- gathered by the orchestrator from the hardware endpoint + catalog so
+ * the core sizing arithmetic is unit-testable with NO HTTP. Unknown numeric
+ * inputs (null/undefined) degrade safely to the floor default.
+ */
+export interface SafeMaxSeqInput {
+    /** Total VRAM in MB (null/undefined -> degrade to floor). */
+    vramTotalMb: number | null | undefined;
+    /** Currently-used VRAM in MB (null/undefined -> degrade to floor). */
+    vramUsedMb: number | null | undefined;
+    /** The candidate model's on-disk/weights size in MB, when known. */
+    modelSizeMb?: number | null;
+    /** The model's native context window (clamps the result), when known. */
+    nativeContext?: number | null;
+    /** Pre-request KV quantization (forces the quantized footprint path). */
+    kvQuant?: boolean;
+    /** Override the codex turn-1 floor (defaults to `CODEX_TURN1_FLOOR`). */
+    codexFloor?: number;
+}
+/**
+ * Output of `computeSafeMaxSeqLength` (Local model host control, D3). The chosen
+ * context (never below the codex floor) and, when quantization was elected to
+ * fit a context, the `cacheTypeKv` to pass on the load. `quantRequired` +
+ * `marginal` are advisory signals for the load path to log -- they do NOT change
+ * the returned `maxSeqLength`, which is always at least the floor.
+ */
+export interface SafeMaxSeqResult {
+    /** The safe context to load with (always >= the codex floor, <= native cap). */
+    maxSeqLength: number;
+    /** KV-cache dtype to quantize with, set only when quantization was elected. */
+    cacheTypeKv?: string;
+    /** True when even quantized KV could not fit the floor -- a tight, risky load. */
+    quantRequired?: boolean;
+    /** True when the result rests at the floor under tight/unknown headroom. */
+    marginal?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/host-control/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/host-control/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX;;;;OAIG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,YAAY,EAAE,OAAO,CAAC;IACtB,8DAA8D;IAC9D,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,gFAAgF;IAChF,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE7D,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iEAAiE;IACjE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,4EAA4E;IAC5E,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACvC,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACtC,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}