@telora/daemon 0.18.58 → 0.18.67

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

@@ -0,0 +1,76 @@
+/**
+ * Typed JSON HTTP helpers for the host-control plane (Local model host control, D1).
+ *
+ * These mirror the security posture of `discovery-poll.ts` exactly: the host
+ * control surface is an operator-supplied LAN endpoint, so every request must
+ * (1) pass the SSRF guard before any network call (TEL-5), (2) time-box with an
+ * AbortController so an unreachable host fails fast (TEL-6), (3) cap the body
+ * read so a malicious/oversized response can't OOM the daemon (TEL-6), and
+ * (4) surface only address-free error categories -- the raw URL/system detail is
+ * logged daemon-side, never returned to a caller that may write it to an
+ * org-readable column (TEL-5, probe-oracle defense).
+ *
+ * `hostGet`/`hostPost` are deliberately generic over the decoded shape; the
+ * caller validates the `unknown` payload with a defensive normalizer (the
+ * control-surface JSON shape is host-specific and reconciled per the runbook).
+ */
+/**
+ * Time-box a single host-control fetch. Mirrors `DISCOVERY_FETCH_TIMEOUT_MS`
+ * (5000ms) so the control probe fails fast on an unreachable host exactly like
+ * the `/v1/models` probe it rides alongside. Re-exported so callers and tests
+ * reference one source of truth.
+ */
+export declare const HOST_CONTROL_FETCH_TIMEOUT_MS = 5000;
+/**
+ * Hard ceiling on a host-control response body. A model catalog is small (~25
+ * entries observed live); this cap defends against an endpoint streaming an
+ * unbounded body to OOM the daemon (TEL-6). Mirrors discovery-poll's
+ * `MAX_DISCOVERY_BYTES` (1MB) -- declared as its own literal rather than
+ * re-exported to avoid an init-order coupling with the cyclic discovery-poll
+ * import (this module is imported by discovery-poll, which it also imports from).
+ */
+export declare const HOST_CONTROL_MAX_BYTES = 1000000;
+/**
+ * Address-free error categories for the host-control client. The control plane
+ * is fail-safe -- callers turn any of these into "not controllable, fall back to
+ * the floor" rather than propagating detail -- but they are kept distinct (and
+ * address-free) so daemon-side logs can categorize without leaking the endpoint.
+ */
+export declare const HOST_CONTROL_ERROR_REJECTED_URL = "Rejected non-http(s) host URL";
+export declare const HOST_CONTROL_ERROR_STATUS = "Host returned an error status";
+export declare const HOST_CONTROL_ERROR_UNREACHABLE = "Host unreachable or timed out";
+export declare const HOST_CONTROL_ERROR_INVALID = "Host response was not valid";
+/**
+ * A host-control client error carrying a sanitized, address-free `dbMessage`
+ * alongside the rich `message` (URL/system detail) that is safe only for the
+ * daemon log. Same precedent as `discovery-poll`'s `DiscoveryError`.
+ */
+export declare class HostControlError extends Error {
+    /** Address-free category string safe to surface anywhere (TEL-5). */
+    readonly dbMessage: string;
+    constructor(message: string, 
+    /** Address-free category string safe to surface anywhere (TEL-5). */
+    dbMessage: string);
+}
+/** Options common to host-control requests. */
+export interface HostRequestOptions {
+    /** Bearer key VALUE for an authenticated host (resolved from the Telora secret). */
+    apiKey?: string | null;
+    /** Per-request timeout override; defaults to `HOST_CONTROL_FETCH_TIMEOUT_MS`. */
+    timeoutMs?: number;
+}
+/** Typed JSON GET against a host-control URL. See `hostRequest` for the posture. */
+export declare function hostGet<T>(url: string, opts?: HostRequestOptions): Promise<T>;
+/** Typed JSON POST against a host-control URL. The body is JSON-encoded. */
+export declare function hostPost<T>(url: string, body: unknown, opts?: HostRequestOptions): Promise<T>;
+/**
+ * Derive the host ROOT from a stored `baseUrl`. The registry stores the
+ * OpenAI-compatible base (e.g. `http://host:8888/v1`), but the control surface
+ * lives under `/api` at the host root, NOT under `/v1`. Strip a single trailing
+ * `/v1` segment and any trailing slashes so callers can append `/api/...`. A
+ * `baseUrl` that is already a bare root passes through unchanged.
+ *
+ * Pure + exported for unit testing.
+ */
+export declare function hostRootFromBaseUrl(baseUrl: string): string;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/host-control/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,kCAAkC,CAAC;AAC/E,eAAO,MAAM,yBAAyB,kCAAkC,CAAC;AACzE,eAAO,MAAM,8BAA8B,kCAAkC,CAAC;AAC9E,eAAO,MAAM,0BAA0B,gCAAgC,CAAC;AAExE;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAGvC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM;gBAF1B,OAAO,EAAE,MAAM;IACf,qEAAqE;IAC5D,SAAS,EAAE,MAAM;CAK7B;AAED,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0ID,oFAAoF;AACpF,wBAAsB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,CAAC,CAAC,CAEvF;AAED,4EAA4E;AAC5E,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAO3D"}

package/dist/host-control/client.js

@@ -0,0 +1,203 @@
+/**
+ * Typed JSON HTTP helpers for the host-control plane (Local model host control, D1).
+ *
+ * These mirror the security posture of `discovery-poll.ts` exactly: the host
+ * control surface is an operator-supplied LAN endpoint, so every request must
+ * (1) pass the SSRF guard before any network call (TEL-5), (2) time-box with an
+ * AbortController so an unreachable host fails fast (TEL-6), (3) cap the body
+ * read so a malicious/oversized response can't OOM the daemon (TEL-6), and
+ * (4) surface only address-free error categories -- the raw URL/system detail is
+ * logged daemon-side, never returned to a caller that may write it to an
+ * org-readable column (TEL-5, probe-oracle defense).
+ *
+ * `hostGet`/`hostPost` are deliberately generic over the decoded shape; the
+ * caller validates the `unknown` payload with a defensive normalizer (the
+ * control-surface JSON shape is host-specific and reconciled per the runbook).
+ */
+import { isAllowedDiscoveryUrl } from '../discovery-poll.js';
+/**
+ * Time-box a single host-control fetch. Mirrors `DISCOVERY_FETCH_TIMEOUT_MS`
+ * (5000ms) so the control probe fails fast on an unreachable host exactly like
+ * the `/v1/models` probe it rides alongside. Re-exported so callers and tests
+ * reference one source of truth.
+ */
+export const HOST_CONTROL_FETCH_TIMEOUT_MS = 5000;
+/**
+ * Hard ceiling on a host-control response body. A model catalog is small (~25
+ * entries observed live); this cap defends against an endpoint streaming an
+ * unbounded body to OOM the daemon (TEL-6). Mirrors discovery-poll's
+ * `MAX_DISCOVERY_BYTES` (1MB) -- declared as its own literal rather than
+ * re-exported to avoid an init-order coupling with the cyclic discovery-poll
+ * import (this module is imported by discovery-poll, which it also imports from).
+ */
+export const HOST_CONTROL_MAX_BYTES = 1_000_000;
+/**
+ * Address-free error categories for the host-control client. The control plane
+ * is fail-safe -- callers turn any of these into "not controllable, fall back to
+ * the floor" rather than propagating detail -- but they are kept distinct (and
+ * address-free) so daemon-side logs can categorize without leaking the endpoint.
+ */
+export const HOST_CONTROL_ERROR_REJECTED_URL = 'Rejected non-http(s) host URL';
+export const HOST_CONTROL_ERROR_STATUS = 'Host returned an error status';
+export const HOST_CONTROL_ERROR_UNREACHABLE = 'Host unreachable or timed out';
+export const HOST_CONTROL_ERROR_INVALID = 'Host response was not valid';
+/**
+ * A host-control client error carrying a sanitized, address-free `dbMessage`
+ * alongside the rich `message` (URL/system detail) that is safe only for the
+ * daemon log. Same precedent as `discovery-poll`'s `DiscoveryError`.
+ */
+export class HostControlError extends Error {
+    dbMessage;
+    constructor(message, 
+    /** Address-free category string safe to surface anywhere (TEL-5). */
+    dbMessage) {
+        super(message);
+        this.dbMessage = dbMessage;
+        this.name = 'HostControlError';
+    }
+}
+/**
+ * Build request headers for a host-control call. When a bearer key VALUE is
+ * provided an `Authorization: Bearer <value>` header is added; a blank/absent
+ * value yields no auth header (unauthenticated probe). The value is never
+ * logged or persisted by this module. Mirrors `buildDiscoveryHeaders`.
+ */
+function buildHostHeaders(apiKey, extra) {
+    const headers = { accept: 'application/json', ...extra };
+    const value = typeof apiKey === 'string' ? apiKey.trim() : '';
+    if (value)
+        headers.Authorization = `Bearer ${value}`;
+    return headers;
+}
+/**
+ * Read a fetch response body with a hard byte ceiling, aborting once the cap is
+ * exceeded so a lying Content-Length (or a chunked body with none) can't OOM the
+ * daemon (TEL-6). Returns the decoded text. Throws a `HostControlError` past the
+ * ceiling. Mirrors `discovery-poll`'s `readBodyCapped`.
+ */
+async function readBodyCapped(res) {
+    const body = res.body;
+    if (!body) {
+        // No stream available -- fall back to arrayBuffer but still cap by byteLength.
+        const buf = await res.arrayBuffer();
+        if (buf.byteLength > HOST_CONTROL_MAX_BYTES) {
+            throw new HostControlError('Response body exceeded byte ceiling', HOST_CONTROL_ERROR_INVALID);
+        }
+        return new TextDecoder().decode(buf);
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value) {
+                total += value.byteLength;
+                if (total > HOST_CONTROL_MAX_BYTES) {
+                    throw new HostControlError('Response body exceeded byte ceiling', HOST_CONTROL_ERROR_INVALID);
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        // Stop the underlying transfer; ignore cancel errors.
+        await reader.cancel().catch(() => { });
+    }
+    const merged = new Uint8Array(total);
+    let offset = 0;
+    for (const c of chunks) {
+        merged.set(c, offset);
+        offset += c.byteLength;
+    }
+    return new TextDecoder().decode(merged);
+}
+/**
+ * Map a non-2xx status to an address-free category. 401/403 surface as a status
+ * error here (the host-control plane is optional, so an auth wall just means we
+ * fall back to the floor) -- unlike discovery, we don't disclose an auth-specific
+ * message, because a control-surface 401 is not independently actionable.
+ */
+function statusDbMessage(_status) {
+    return HOST_CONTROL_ERROR_STATUS;
+}
+/**
+ * Issue a host-control request and decode the JSON body, enforcing the full
+ * security posture (SSRF guard, timeout, byte cap, address-free errors). Shared
+ * core of `hostGet`/`hostPost`. Throws a `HostControlError` on any failure.
+ */
+async function hostRequest(url, init, opts) {
+    // TEL-5: validate the operator-supplied URL before any network call -- reject
+    // anything that isn't a parseable http/https URL (no file:, ftp:, etc).
+    if (!isAllowedDiscoveryUrl(url)) {
+        throw new HostControlError(`Rejected non-http(s) host-control URL: ${url}`, HOST_CONTROL_ERROR_REJECTED_URL);
+    }
+    const timeoutMs = opts.timeoutMs ?? HOST_CONTROL_FETCH_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const extra = init.method === 'POST' && init.contentType ? { 'content-type': init.contentType } : undefined;
+        const res = await fetch(url, {
+            method: init.method,
+            signal: controller.signal,
+            headers: buildHostHeaders(opts.apiKey, extra),
+            ...(init.body !== undefined ? { body: init.body } : {}),
+        });
+        if (!res.ok) {
+            throw new HostControlError(`Host returned HTTP ${res.status}`, statusDbMessage(res.status));
+        }
+        // TEL-6: reject a too-large declared body up front, then defensively cap the
+        // actual stream in case the header lied / is absent.
+        const declared = Number(res.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > HOST_CONTROL_MAX_BYTES) {
+            throw new HostControlError(`Declared Content-Length ${declared} exceeds cap`, HOST_CONTROL_ERROR_INVALID);
+        }
+        const text = await readBodyCapped(res);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new HostControlError('Response body was not valid JSON', HOST_CONTROL_ERROR_INVALID);
+        }
+    }
+    catch (err) {
+        if (err instanceof HostControlError)
+            throw err;
+        if (err.name === 'AbortError') {
+            throw new HostControlError(`Timed out after ${timeoutMs}ms reaching ${url}`, HOST_CONTROL_ERROR_UNREACHABLE);
+        }
+        // Network-level failure (DNS, connection refused, TLS): generic to callers.
+        throw new HostControlError(err.message || `Failed to reach ${url}`, HOST_CONTROL_ERROR_UNREACHABLE);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Typed JSON GET against a host-control URL. See `hostRequest` for the posture. */
+export async function hostGet(url, opts = {}) {
+    return hostRequest(url, { method: 'GET' }, opts);
+}
+/** Typed JSON POST against a host-control URL. The body is JSON-encoded. */
+export async function hostPost(url, body, opts = {}) {
+    return hostRequest(url, { method: 'POST', body: JSON.stringify(body ?? {}), contentType: 'application/json' }, opts);
+}
+/**
+ * Derive the host ROOT from a stored `baseUrl`. The registry stores the
+ * OpenAI-compatible base (e.g. `http://host:8888/v1`), but the control surface
+ * lives under `/api` at the host root, NOT under `/v1`. Strip a single trailing
+ * `/v1` segment and any trailing slashes so callers can append `/api/...`. A
+ * `baseUrl` that is already a bare root passes through unchanged.
+ *
+ * Pure + exported for unit testing.
+ */
+export function hostRootFromBaseUrl(baseUrl) {
+    // Trim trailing slashes first so a trailing-slash `/v1/` still matches.
+    const trimmed = baseUrl.replace(/\/+$/, '');
+    // Strip exactly one trailing `/v1` segment (case-sensitive, the API convention).
+    const root = trimmed.replace(/\/v1$/, '');
+    // A `/v1` with its own trailing slash (`/v1/`) leaves a dangling slash; clean it.
+    return root.replace(/\/+$/, '');
+}
+//# sourceMappingURL=client.js.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * Host-control plane barrel (Local model host control, D1).
+ *
+ * The spine for detecting and reading a controllable model host ABOVE the
+ * OpenAI-compatible `/v1/models` floor. Delivery 1 ships the client, capability
+ * detection, and catalog read; later deliveries add `load.ts` (id -> model_path
+ * load/unload) and `sizing.ts` -- export those from here when they land.
+ */
+export type { HostCapability, LoadableCatalog, LoadableModel, HostStatus, LoadModelParams, SwapAction, SwapDecision, HostHardware, KvCacheEstimate, KvCacheEstimateParams, SafeMaxSeqInput, SafeMaxSeqResult, } from './types.js';
+export { hostGet, hostPost, hostRootFromBaseUrl, HostControlError, HOST_CONTROL_FETCH_TIMEOUT_MS, HOST_CONTROL_MAX_BYTES, HOST_CONTROL_ERROR_REJECTED_URL, HOST_CONTROL_ERROR_STATUS, HOST_CONTROL_ERROR_UNREACHABLE, HOST_CONTROL_ERROR_INVALID, } from './client.js';
+export type { HostRequestOptions } from './client.js';
+export { detectHostCapability, isControllableCatalogPayload } from './capability.js';
+export { readLoadableCatalog, normalizeLocalCatalog, HOST_CONTROL_CATALOG_PATH, } from './catalog.js';
+export { loadModel, unloadModel, getStatus, resolveModelPath, decideSwap, ensureLoaded, normalizeStatus, DEFAULT_MAX_SEQ_LENGTH, HOST_CONTROL_LOAD_PATH, HOST_CONTROL_UNLOAD_PATH, HOST_CONTROL_STATUS_PATH, HOST_CONTROL_LOAD_READY_TIMEOUT_MS, HOST_CONTROL_LOAD_POLL_INTERVAL_MS, HOST_CONTROL_ERROR_LOAD_TIMEOUT, } from './load.js';
+export type { EnsureLoadedOptions } from './load.js';
+export { getHardware, getKvCacheEstimate, normalizeHardware, normalizeKvCacheEstimate, computeSafeMaxSeqLength, resolveSafeLoadOptions, CODEX_TURN1_FLOOR, VRAM_SAFETY_MARGIN_MB, KV_CACHE_MB_PER_TOKEN, KV_QUANT_FOOTPRINT_FACTOR, KV_QUANT_CACHE_TYPE, MAX_SEQ_LENGTH_CEILING, HOST_CONTROL_HARDWARE_PATH, HOST_CONTROL_KV_CACHE_PATH, } from './sizing.js';
+export type { SafeLoadSizingHints } from './sizing.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/host-control/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACb,UAAU,EACV,eAAe,EACf,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,sBAAsB,EACtB,+BAA+B,EAC/B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,kCAAkC,EAClC,kCAAkC,EAClC,+BAA+B,GAChC,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/host-control/index.js

@@ -0,0 +1,14 @@
+/**
+ * Host-control plane barrel (Local model host control, D1).
+ *
+ * The spine for detecting and reading a controllable model host ABOVE the
+ * OpenAI-compatible `/v1/models` floor. Delivery 1 ships the client, capability
+ * detection, and catalog read; later deliveries add `load.ts` (id -> model_path
+ * load/unload) and `sizing.ts` -- export those from here when they land.
+ */
+export { hostGet, hostPost, hostRootFromBaseUrl, HostControlError, HOST_CONTROL_FETCH_TIMEOUT_MS, HOST_CONTROL_MAX_BYTES, HOST_CONTROL_ERROR_REJECTED_URL, HOST_CONTROL_ERROR_STATUS, HOST_CONTROL_ERROR_UNREACHABLE, HOST_CONTROL_ERROR_INVALID, } from './client.js';
+export { detectHostCapability, isControllableCatalogPayload } from './capability.js';
+export { readLoadableCatalog, normalizeLocalCatalog, HOST_CONTROL_CATALOG_PATH, } from './catalog.js';
+export { loadModel, unloadModel, getStatus, resolveModelPath, decideSwap, ensureLoaded, normalizeStatus, DEFAULT_MAX_SEQ_LENGTH, HOST_CONTROL_LOAD_PATH, HOST_CONTROL_UNLOAD_PATH, HOST_CONTROL_STATUS_PATH, HOST_CONTROL_LOAD_READY_TIMEOUT_MS, HOST_CONTROL_LOAD_POLL_INTERVAL_MS, HOST_CONTROL_ERROR_LOAD_TIMEOUT, } from './load.js';
+export { getHardware, getKvCacheEstimate, normalizeHardware, normalizeKvCacheEstimate, computeSafeMaxSeqLength, resolveSafeLoadOptions, CODEX_TURN1_FLOOR, VRAM_SAFETY_MARGIN_MB, KV_CACHE_MB_PER_TOKEN, KV_QUANT_FOOTPRINT_FACTOR, KV_QUANT_CACHE_TYPE, MAX_SEQ_LENGTH_CEILING, HOST_CONTROL_HARDWARE_PATH, HOST_CONTROL_KV_CACHE_PATH, } from './sizing.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/host-control/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH,OAAO,EACL,OAAO,EACP,QAAQ,EACR,mBAAmB,EACnB,gBAAgB,EAChB,6BAA6B,EAC7B,sBAAsB,EACtB,+BAA+B,EAC/B,yBAAyB,EACzB,8BAA8B,EAC9B,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,SAAS,EACT,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,UAAU,EACV,YAAY,EACZ,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,EACxB,kCAAkC,EAClC,kCAAkC,EAClC,+BAA+B,GAChC,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,mBAAmB,EACnB,sBAAsB,EACtB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,aAAa,CAAC"}

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

@@ -0,0 +1,136 @@
+/**
+ * Load / unload orchestration for the host-control plane (Local model host
+ * control, D2).
+ *
+ * Per-pass model selection (D1) records which local model a coding vs review
+ * pass wants, but the daemon had no LOAD path -- so the selection could not
+ * drive an actual model switch. This module closes that gap: it loads / unloads
+ * the chosen per-pass model around each pass as a SEQUENTIAL swap on a single
+ * GPU (one model resident at a time -- loading evicts the prior), so a distinct
+ * coding-vs-review model can run end-to-end with NO manual swap in the studio.
+ *
+ * The control endpoints live under `/v1` (reachable from the stored baseUrl
+ * directly, which already ends in `/v1`): `POST /v1/load`, `POST /v1/unload`,
+ * `GET /v1/status`. Live JSON shapes are host-specific; `/v1/status` in
+ * particular is NOT pinned, so `normalizeStatus` is DEFENSIVE (tolerant of
+ * reasonable field names) and must be reconciled per the runbook.
+ *
+ * The maxSeqLength a load uses is an INJECTED input (an option, never hardcoded
+ * inside `ensureLoaded`) so Delivery 3 can replace the fixed `DEFAULT_MAX_SEQ_LENGTH`
+ * floor with a computed safe value without re-architecting this module.
+ */
+import type { HostStatus, LoadModelParams, SwapDecision } from './types.js';
+/**
+ * The control surface lives under `/v1` -- the SAME segment the stored baseUrl
+ * already ends in. We append these to the baseUrl directly (NOT the host root):
+ * a baseUrl of `http://host:8888/v1` yields `http://host:8888/v1/load`. A
+ * baseUrl without a trailing `/v1` still composes a sane path.
+ */
+export declare const HOST_CONTROL_LOAD_PATH = "/load";
+export declare const HOST_CONTROL_UNLOAD_PATH = "/unload";
+export declare const HOST_CONTROL_STATUS_PATH = "/status";
+/**
+ * Default max sequence length for a load. Sized at the live-proven 16384, which
+ * clears codex's ~8k turn-1 context floor with headroom. NOTE: Delivery 3 will
+ * REPLACE this fixed value with a computed safe value derived from the model +
+ * available VRAM; `loadModel`/`ensureLoaded` take maxSeqLength as an INJECTED
+ * input so D3 can pass a computed value without touching this module's shape.
+ */
+export declare const DEFAULT_MAX_SEQ_LENGTH = 16384;
+/**
+ * How long `ensureLoaded` will poll `/v1/status` for the target to become ready
+ * after issuing a load before giving up with a typed timeout. A cold load on a
+ * 12GB GPU has real latency; this is the bounded ceiling, not the expected wait.
+ */
+export declare const HOST_CONTROL_LOAD_READY_TIMEOUT_MS = 180000;
+/** Interval between `/v1/status` readiness polls while waiting for a load. */
+export declare const HOST_CONTROL_LOAD_POLL_INTERVAL_MS = 2000;
+/** Address-free category for a load that never reached ready within the budget. */
+export declare const HOST_CONTROL_ERROR_LOAD_TIMEOUT = "Host load did not reach ready in time";
+/**
+ * Normalize a `/v1/status` payload into a typed `HostStatus`. DEFENSIVE: the
+ * live shape is NOT pinned, so we tolerate the loaded-model id under any of
+ * `model`/`id`/`loaded_model`/... and readiness under `status`/`state`/`ready`
+ * (string token OR boolean). A payload that proves nothing loaded yields
+ * `{ loadedModelId: null, ready: false }`. Pure + exported for unit testing.
+ *
+ * Runbook flag: confirm the live `/v1/status` field names + readiness vocabulary
+ * and tighten `STATUS_*_KEYS` / `READY_TOKENS` once observed.
+ */
+export declare function normalizeStatus(payload: unknown): HostStatus;
+/**
+ * Issue a model load (`POST /v1/load`). Maps camelCase app params to the host's
+ * snake_case wire field names (`model_path`, `max_seq_length`, `cache_type_kv`,
+ * `gpu_ids`) at THIS boundary only. `maxSeqLength` is a required INJECTED input
+ * so D3 can pass a computed value. Throws `HostControlError` on any failure.
+ */
+export declare function loadModel(baseUrl: string, params: LoadModelParams, apiKey?: string | null): Promise<void>;
+/** Issue an unload (`POST /v1/unload`) -- evicts whatever is currently resident. */
+export declare function unloadModel(baseUrl: string, apiKey?: string | null): Promise<void>;
+/** Read current host status (`GET /v1/status`), normalized to a typed shape. */
+export declare function getStatus(baseUrl: string, apiKey?: string | null): Promise<HostStatus>;
+/**
+ * Resolve a chosen local_models `model` id to the host's `model_path` by reading
+ * the loadable catalog (D1) and matching by id. Returns null when the host is
+ * not controllable, the id is not in the catalog, or the matching entry carries
+ * no modelPath (a floor entry). The caller treats null as "cannot load" and
+ * skips the swap.
+ */
+export declare function resolveModelPath(baseUrl: string, modelId: string, apiKey?: string | null): Promise<string | null>;
+/**
+ * PURE swap decision over the current vs target resident model. Extracted from
+ * `ensureLoaded` so the core single-GPU swap logic is unit-testable with NO HTTP:
+ *
+ *   - target already resident + ready -> 'noop'
+ *   - a DIFFERENT model resident       -> 'evict_then_load' (single GPU -- evict first)
+ *   - nothing resident                 -> 'load'
+ *
+ * `current.modelId` is the currently-loaded id (null = nothing resident);
+ * `current.ready` gates the noop (a resident-but-not-ready target still needs a
+ * poll, but no reload -- treated as 'load' here so `ensureLoaded` re-issues +
+ * polls; the host treats a load of the resident model as a fast no-op/confirm).
+ */
+export declare function decideSwap(input: {
+    current: {
+        modelId: string | null;
+        ready: boolean;
+    };
+    target: string;
+}): SwapDecision;
+/** Options for `ensureLoaded`. `maxSeqLength` is injected (D3 computes it). */
+export interface EnsureLoadedOptions {
+    /** Context window to load with. Defaults to `DEFAULT_MAX_SEQ_LENGTH`. */
+    maxSeqLength?: number;
+    /** Optional KV cache dtype passed through to the load. */
+    cacheTypeKv?: string;
+    /** Optional GPU id selection passed through to the load. */
+    gpuIds?: number[];
+    /** Override the ready-poll budget (ms). Defaults to the module constant. */
+    readyTimeoutMs?: number;
+    /** Override the ready-poll interval (ms). Defaults to the module constant. */
+    pollIntervalMs?: number;
+    /**
+     * Injectable sleep, so the timeout/poll path is fast + deterministic in tests.
+     * Defaults to a real `setTimeout` wait.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable clock for the bounded-poll deadline (defaults to `Date.now`). */
+    now?: () => number;
+}
+/**
+ * Orchestrate the SEQUENTIAL single-GPU swap so the target model is resident +
+ * ready before the caller spawns against it:
+ *
+ *   1. read status; if the target is already resident + ready -> no-op return.
+ *   2. else: if a DIFFERENT model is resident, unload it first (single GPU --
+ *      one resident at a time). Resolve the target id -> model_path, then load
+ *      with the injected maxSeqLength.
+ *   3. poll `/v1/status` until the target is ready, or throw a typed timeout
+ *      (`HOST_CONTROL_ERROR_LOAD_TIMEOUT`) once the bounded budget elapses.
+ *
+ * Throws `HostControlError` on an unresolvable path, a load/unload failure, or
+ * the ready timeout. The caller (focus-executor) turns any throw into "skip the
+ * spawn this tick" -- it must NOT spawn against a not-yet-loaded model.
+ */
+export declare function ensureLoaded(baseUrl: string, modelId: string, opts?: EnsureLoadedOptions, apiKey?: string | null): Promise<void>;
+//# sourceMappingURL=load.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/host-control/load.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAc,YAAY,EAAE,MAAM,YAAY,CAAC;AAExF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAC9C,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAClD,eAAO,MAAM,wBAAwB,YAAY,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAE5C;;;;GAIG;AACH,eAAO,MAAM,kCAAkC,SAAU,CAAC;AAE1D,8EAA8E;AAC9E,eAAO,MAAM,kCAAkC,OAAQ,CAAC;AAExD,mFAAmF;AACnF,eAAO,MAAM,+BAA+B,0CAA0C,CAAC;AAoCvF;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CA4B5D;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,oFAAoF;AACpF,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAExF;AAED,gFAAgF;AAChF,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAG5F;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAIxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAChC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IACpD,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,YAAY,CAWf;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,mBAAwB,EAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,IAAI,CAAC,CAqDf"}