@telora/daemon 0.18.58 → 0.18.67

package/dist/git-fetch.js

@@ -0,0 +1,164 @@
+/**
+ * Off-event-loop git fetch + circuit breaker for the per-cycle origin fetch.
+ *
+ * The poll loop's git-state detection fetches from origin every cycle. When the
+ * remote is unreachable that fetch used to run SYNCHRONOUSLY (`execFileSync`) on
+ * the daemon's single Node event loop, blocking it for the full timeout (30s)
+ * and tripping the event-loop-lag watchdog while starving unrelated
+ * fire-and-forget work (local-model discovery, telemetry). This module isolates
+ * that failure into three composable pieces:
+ *
+ *  1. `gitFetchOrigin` runs the fetch OFF the hot path via async `execFile` with
+ *     an `AbortSignal` abort path, so a slow/hung fetch never blocks the loop --
+ *     the `await` yields to the event loop while the child process runs.
+ *  2. The default timeout (`GIT_FETCH_DEFAULT_TIMEOUT_MS`) is bounded well below
+ *     the watchdog threshold (`WATCHDOG_LAG_THRESHOLD_MS`) so a hung remote costs
+ *     a few seconds per attempt, not a full 30s lag window.
+ *  3. `GitFetchCircuit` is a failure-count -> open -> backoff -> half-open ->
+ *     recover state machine: after N consecutive failures it backs off instead
+ *     of retrying every cycle, emitting ONE degraded-mode signal (`justOpened`)
+ *     rather than a per-cycle storm, and recovering once the remote is reachable.
+ */
+import { execFile } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Timeout bounds
+// ---------------------------------------------------------------------------
+/**
+ * The heartbeat watchdog's event-loop-lag threshold
+ * (`EVENT_LOOP_LAG_WARNING_MS` in heartbeat.ts). The fetch timeout must stay
+ * well below this: a fetch that could run for the full threshold is exactly the
+ * window that, on the old synchronous path, tripped the watchdog. Even off-loop
+ * (where a long fetch no longer lags the loop) this caps cost-per-attempt.
+ */
+export const WATCHDOG_LAG_THRESHOLD_MS = 30_000;
+/**
+ * Default origin-fetch timeout: a few seconds, well below
+ * {@link WATCHDOG_LAG_THRESHOLD_MS}. Mirrors the `TELORA_GIT_FETCH_TIMEOUT_MS`
+ * env default in `@telora/daemon-core` (operators override via that env var for
+ * high-latency remotes); used directly as the fallback when no timeout is passed.
+ */
+export const GIT_FETCH_DEFAULT_TIMEOUT_MS = 5_000;
+/** Max bytes of stdout/stderr to buffer from the child (10 MiB). */
+const MAX_FETCH_BUFFER_BYTES = 10 * 1024 * 1024;
+/**
+ * Default async runner: `execFile('git', ...)` -- a child process whose work
+ * runs off the event loop. The `timeout` option kills the child on overrun and
+ * the optional `signal` provides an explicit abort path; either resolves to a
+ * non-fatal failure result rather than throwing.
+ */
+export const defaultAsyncGitRunner = (args, cwd, opts) => new Promise((resolve) => {
+    execFile('git', args, {
+        cwd,
+        encoding: 'utf-8',
+        timeout: opts.timeoutMs,
+        signal: opts.signal,
+        maxBuffer: MAX_FETCH_BUFFER_BYTES,
+    }, (err, stdout, stderr) => {
+        if (!err) {
+            resolve({ success: true, output: (stdout ?? '').trim(), error: '' });
+            return;
+        }
+        const execErr = err;
+        // Timeout (Node kills the child -> killed/SIGTERM) or explicit abort.
+        if (execErr.killed ||
+            execErr.signal === 'SIGTERM' ||
+            execErr.code === 'ABORT_ERR' ||
+            execErr.name === 'AbortError') {
+            resolve({
+                success: false,
+                output: (stdout ?? '').toString(),
+                error: `Git operation timed out after ${opts.timeoutMs}ms: git ${args.join(' ')}`,
+            });
+            return;
+        }
+        resolve({
+            success: false,
+            output: (stdout ?? '').toString(),
+            error: (stderr ?? '').toString() || execErr.message || 'Unknown git error',
+        });
+    });
+});
+/**
+ * Fetch refs from origin OFF the event-loop hot path.
+ *
+ * Equivalent to the old synchronous `runGitSync(['fetch', '--quiet', 'origin'])`
+ * but non-blocking: the returned promise resolves when the child process exits,
+ * leaving the loop free to service discovery/telemetry/timers meanwhile.
+ */
+export async function gitFetchOrigin(repoPath, opts = {}, runner = defaultAsyncGitRunner) {
+    const timeoutMs = opts.timeoutMs ?? GIT_FETCH_DEFAULT_TIMEOUT_MS;
+    return runner(['fetch', '--quiet', 'origin'], repoPath, {
+        timeoutMs,
+        signal: opts.signal,
+    });
+}
+/** Consecutive failures before the circuit opens and backs off. */
+export const GIT_FETCH_FAILURE_THRESHOLD = 3;
+/** How long the circuit stays open before a half-open probe (5 minutes). */
+export const GIT_FETCH_BACKOFF_MS = 5 * 60 * 1000;
+/**
+ * Failure-count -> open -> backoff -> half-open -> recover state machine around
+ * the origin fetch. Pure and clock-injectable; holds no I/O. The caller gates
+ * each cycle's fetch on {@link shouldAttempt} and feeds the outcome back via
+ * {@link recordSuccess} / {@link recordFailure}.
+ */
+export class GitFetchCircuit {
+    state = 'closed';
+    consecutiveFailures = 0;
+    openedAt = 0;
+    threshold;
+    backoffMs;
+    now;
+    constructor(opts = {}) {
+        this.threshold = opts.failureThreshold ?? GIT_FETCH_FAILURE_THRESHOLD;
+        this.backoffMs = opts.backoffMs ?? GIT_FETCH_BACKOFF_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    getState() {
+        return this.state;
+    }
+    getConsecutiveFailures() {
+        return this.consecutiveFailures;
+    }
+    /**
+     * Whether a fetch should run this cycle. When open, returns false until the
+     * backoff window elapses, at which point it transitions to half-open and
+     * allows a single probe. Closed and half-open always attempt.
+     */
+    shouldAttempt() {
+        if (this.state === 'open') {
+            if (this.now() - this.openedAt >= this.backoffMs) {
+                this.state = 'half_open';
+                return true;
+            }
+            return false;
+        }
+        return true; // closed or half_open
+    }
+    /** Record a successful fetch -> closes the circuit; signals recovery once. */
+    recordSuccess() {
+        const recovered = this.state !== 'closed' || this.consecutiveFailures > 0;
+        this.state = 'closed';
+        this.consecutiveFailures = 0;
+        this.openedAt = 0;
+        return { state: this.state, recovered };
+    }
+    /** Record a failed fetch -> may open the circuit (once) and start backoff. */
+    recordFailure() {
+        this.consecutiveFailures += 1;
+        // A failed half-open probe drops straight back to open (restart backoff)
+        // without re-emitting the degraded signal.
+        if (this.state === 'half_open') {
+            this.state = 'open';
+            this.openedAt = this.now();
+            return { state: this.state, justOpened: false };
+        }
+        if (this.state === 'closed' && this.consecutiveFailures >= this.threshold) {
+            this.state = 'open';
+            this.openedAt = this.now();
+            return { state: this.state, justOpened: true };
+        }
+        return { state: this.state, justOpened: false };
+    }
+}
+//# sourceMappingURL=git-fetch.js.map

package/dist/git-fetch.js.map

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

package/dist/git-state-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-state-detector.d.ts","sourceRoot":"","sources":["../src/git-state-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,YAAY,CAAC;AAqDzD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAgHzE"}
+{"version":3,"file":"git-state-detector.d.ts","sourceRoot":"","sources":["../src/git-state-detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,YAAY,CAAC;AAmFzD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA0HzE"}

package/dist/git-state-detector.js

@@ -13,17 +13,41 @@ import { getDefaultBranch, repoHasCommits } from './git-branch.js';
 import { getActiveFocuses } from './queries/deliveries.js';
 import { getFocusDeliveries } from './queries/focuses.js';
 import { reportGitState } from './queries/deliveries.js';
-import { healthEvents } from '@telora/daemon-core';
-/** Short timeout for containment checks to avoid blocking the poll loop. */
+import { healthEvents, loadEnvConfig } from '@telora/daemon-core';
+import { gitFetchOrigin, GitFetchCircuit, GIT_FETCH_BACKOFF_MS, } from './git-fetch.js';
+/** Short timeout for local branch-containment checks to avoid blocking the poll loop. */
 const CONTAINMENT_CHECK_TIMEOUT_MS = 5_000;
+/**
+ * Timeout for the network fetch from origin. The fetch now runs OFF the event
+ * loop (gitFetchOrigin), but the timeout is still bounded a few seconds -- well
+ * below the watchdog's event-loop-lag threshold -- so a hung remote costs
+ * seconds per attempt, not a 30s window. Configurable via
+ * TELORA_GIT_FETCH_TIMEOUT_MS (default 5s) for high-latency remotes.
+ */
+function getFetchTimeoutMs() {
+    return loadEnvConfig(process.env).TELORA_GIT_FETCH_TIMEOUT_MS;
+}
 /** Track whether origin remote exists to avoid repeated fetch failures. */
 let originChecked = false;
 let originExists = false;
 let lastOriginCheckAt = 0;
 /** Re-check origin existence every 10 minutes (remote could be added/removed). */
 const ORIGIN_CHECK_TTL_MS = 10 * 60 * 1000;
-/** Track whether the last fetch failed to avoid spamming identical health events. */
-let lastFetchFailed = false;
+/**
+ * Per-repo fetch circuit breakers. A persistently-unreachable remote opens its
+ * circuit after N consecutive failures and backs off instead of retry-storming
+ * every poll cycle; keyed by repoPath so multi-product daemons don't conflate
+ * remotes.
+ */
+const fetchCircuits = new Map();
+function circuitFor(repoPath) {
+    let circuit = fetchCircuits.get(repoPath);
+    if (!circuit) {
+        circuit = new GitFetchCircuit();
+        fetchCircuits.set(repoPath, circuit);
+    }
+    return circuit;
+}
 /**
  * Priority ordering for git states. Higher number = more advanced.
  * Only update a delivery's state forward, never backward.
@@ -83,30 +107,43 @@ export async function detectGitStates(config) {
             console.log('[git-state-detector] Origin remote removed -- skipping fetch');
         }
     }
-    // Fetch refs once before iterating (ensures consistent state)
+    // Fetch refs once before iterating (ensures consistent state). The fetch runs
+    // OFF the event loop (async child process) and is gated by a per-repo circuit
+    // breaker so a persistently-unreachable remote backs off instead of blocking
+    // and retry-storming every cycle.
     if (originExists) {
-        const fetchResult = runGitSync(['fetch', '--quiet', 'origin'], repoPath, { timeoutMs: CONTAINMENT_CHECK_TIMEOUT_MS });
-        if (!fetchResult.success) {
-            console.debug('[git-state-detector] fetch failed (non-fatal):', fetchResult.error);
-            if (!lastFetchFailed) {
-                healthEvents.emit({
-                    severity: 'warn',
-                    source: 'git-state-detector',
-                    code: 'git.fetch_failed',
-                    message: `Git fetch failed: ${fetchResult.error}`,
-                });
-                lastFetchFailed = true;
+        const circuit = circuitFor(repoPath);
+        if (circuit.shouldAttempt()) {
+            const fetchResult = await gitFetchOrigin(repoPath, { timeoutMs: getFetchTimeoutMs() });
+            if (!fetchResult.success) {
+                console.debug('[git-state-detector] fetch failed (non-fatal):', fetchResult.error);
+                const { justOpened } = circuit.recordFailure();
+                if (justOpened) {
+                    // Single degraded-mode signal on the closed -> open transition --
+                    // not a per-cycle storm. The circuit then suppresses fetches for the
+                    // backoff window.
+                    const backoffMin = Math.round(GIT_FETCH_BACKOFF_MS / 60_000);
+                    healthEvents.emit({
+                        severity: 'warn',
+                        source: 'git-state-detector',
+                        code: 'git.fetch_failed',
+                        message: `Git fetch to origin failed ${circuit.getConsecutiveFailures()} times in a row; ` +
+                            `backing off ~${backoffMin}m before retrying. Last error: ${fetchResult.error}`,
+                    });
+                }
+            }
+            else {
+                const { recovered } = circuit.recordSuccess();
+                if (recovered) {
+                    healthEvents.emit({
+                        severity: 'info',
+                        source: 'git-state-detector',
+                        code: 'git.fetch_recovered',
+                        message: 'Git fetch to origin recovered',
+                    });
+                    healthEvents.resolveByCode('git.fetch_failed');
+                }
             }
-        }
-        else if (lastFetchFailed) {
-            healthEvents.emit({
-                severity: 'info',
-                source: 'git-state-detector',
-                code: 'git.fetch_recovered',
-                message: 'Git fetch recovered',
-            });
-            healthEvents.resolveByCode('git.fetch_failed');
-            lastFetchFailed = false;
         }
     }
     const defaultBranch = getDefaultBranch(repoPath);

package/dist/git-state-detector.js.map

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

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

@@ -0,0 +1,31 @@
+/**
+ * Per-endpoint host-control capability detection (Local model host control, D1).
+ *
+ * The control plane is an OPTIONAL capability detected per-endpoint, never
+ * assumed. `detectHostCapability` runs a CHEAP, FAIL-SAFE probe against the host
+ * root's control surface: a 2xx with a well-formed (non-empty, usable) catalog
+ * means controllable; ANY other outcome -- error, non-2xx, parse failure,
+ * timeout, or an empty/unusable payload -- means NOT controllable, so the caller
+ * falls back to the `/v1/models` floor. This guarantees a plain
+ * OpenAI-compatible endpoint is never broken by the probe.
+ */
+import type { HostCapability } from './types.js';
+/**
+ * Pure decision: does a control-surface payload prove the host is controllable?
+ * True only when the payload normalizes to at least one usable loadable-model
+ * entry. A malformed, empty, or non-catalog payload yields false. Exported for
+ * unit testing the interpret-a-payload -> controllable? boundary in isolation.
+ */
+export declare function isControllableCatalogPayload(payload: unknown): boolean;
+/**
+ * Probe an endpoint's host root for the optional control capability. Cheap (a
+ * single GET, time-boxed by the client) and FAIL-SAFE: every failure mode --
+ * SSRF rejection, network error, non-2xx, invalid JSON, timeout, or an
+ * empty/unusable catalog -- resolves to `{ controllable: false }` rather than
+ * throwing, so the caller can unconditionally proceed to the floor.
+ *
+ * `apiKey` is the bearer VALUE (resolved from the Telora secret) authorizing the
+ * probe against an auth-protected host.
+ */
+export declare function detectHostCapability(baseUrl: string, apiKey?: string | null): Promise<HostCapability>;
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/host-control/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,cAAc,CAAC,CAezB"}

package/dist/host-control/capability.js

@@ -0,0 +1,50 @@
+/**
+ * Per-endpoint host-control capability detection (Local model host control, D1).
+ *
+ * The control plane is an OPTIONAL capability detected per-endpoint, never
+ * assumed. `detectHostCapability` runs a CHEAP, FAIL-SAFE probe against the host
+ * root's control surface: a 2xx with a well-formed (non-empty, usable) catalog
+ * means controllable; ANY other outcome -- error, non-2xx, parse failure,
+ * timeout, or an empty/unusable payload -- means NOT controllable, so the caller
+ * falls back to the `/v1/models` floor. This guarantees a plain
+ * OpenAI-compatible endpoint is never broken by the probe.
+ */
+import { hostGet, hostRootFromBaseUrl, HOST_CONTROL_FETCH_TIMEOUT_MS } from './client.js';
+import { HOST_CONTROL_CATALOG_PATH, normalizeLocalCatalog } from './catalog.js';
+/**
+ * Pure decision: does a control-surface payload prove the host is controllable?
+ * True only when the payload normalizes to at least one usable loadable-model
+ * entry. A malformed, empty, or non-catalog payload yields false. Exported for
+ * unit testing the interpret-a-payload -> controllable? boundary in isolation.
+ */
+export function isControllableCatalogPayload(payload) {
+    return normalizeLocalCatalog(payload).length > 0;
+}
+/**
+ * Probe an endpoint's host root for the optional control capability. Cheap (a
+ * single GET, time-boxed by the client) and FAIL-SAFE: every failure mode --
+ * SSRF rejection, network error, non-2xx, invalid JSON, timeout, or an
+ * empty/unusable catalog -- resolves to `{ controllable: false }` rather than
+ * throwing, so the caller can unconditionally proceed to the floor.
+ *
+ * `apiKey` is the bearer VALUE (resolved from the Telora secret) authorizing the
+ * probe against an auth-protected host.
+ */
+export async function detectHostCapability(baseUrl, apiKey) {
+    const root = hostRootFromBaseUrl(baseUrl);
+    const catalogUrl = `${root}${HOST_CONTROL_CATALOG_PATH}`;
+    try {
+        const payload = await hostGet(catalogUrl, {
+            apiKey,
+            timeoutMs: HOST_CONTROL_FETCH_TIMEOUT_MS,
+        });
+        return { controllable: isControllableCatalogPayload(payload) };
+    }
+    catch {
+        // Fail-safe: any error => not controllable. Detail is intentionally swallowed
+        // here (the catalog reader logs on its own fall-through); the probe must never
+        // surface a probe-oracle or break the floor path.
+        return { controllable: false };
+    }
+}
+//# sourceMappingURL=capability.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../src/host-control/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,OAAO,EAAE,mBAAmB,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGhF;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,OAAgB;IAC3D,OAAO,qBAAqB,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,OAAe,EACf,MAAsB;IAEtB,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,GAAG,IAAI,GAAG,yBAAyB,EAAE,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAU,UAAU,EAAE;YACjD,MAAM;YACN,SAAS,EAAE,6BAA6B;SACzC,CAAC,CAAC;QACH,OAAO,EAAE,YAAY,EAAE,4BAA4B,CAAC,OAAO,CAAC,EAAE,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,8EAA8E;QAC9E,+EAA+E;QAC/E,kDAAkD;QAClD,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACjC,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,48 @@
+/**
+ * Loadable-model catalog reader for the host-control plane (Local model host
+ * control, D1).
+ *
+ * A controllable host (e.g. Unsloth Studio @ :8888) exposes its FULL
+ * downloaded-but-unloaded catalog under the control surface
+ * `<root>/api/models/local`, returning every loadable model -- not just the one
+ * currently loaded that `/v1/models` reports. This module reads that catalog and
+ * degrades CLEANLY to the `/v1/models` floor (via discovery-poll's
+ * `fetchModels`) when the host is not controllable or the catalog read fails for
+ * any reason. The floor path is byte-identical to today's behavior, so a plain
+ * OpenAI-compatible endpoint is never broken.
+ *
+ * The live catalog JSON shape is host-specific (observed: 25 entries under
+ * `/api/models/local`, each carrying a load path). We do NOT have the exact live
+ * shape pinned, so `normalizeLocalCatalog` is DEFENSIVE: it tolerates a range of
+ * reasonable container and field names and is easy to extend per the runbook's
+ * live-shape reconciliation.
+ */
+import type { LoadableCatalog, LoadableModel } from './types.js';
+/** The control-surface path (under the host ROOT, not `/v1`) for the full catalog. */
+export declare const HOST_CONTROL_CATALOG_PATH = "/api/models/local";
+/**
+ * Normalize a control-surface catalog payload into clean `LoadableModel`
+ * entries. Pure + DEFENSIVE: tolerates a bare array or a wrapped container,
+ * non-object items, missing/blank ids (dropped), and a missing model_path
+ * (captured as null). De-duplicates by id (first entry with a model_path wins
+ * its path). Exported for unit testing.
+ */
+export declare function normalizeLocalCatalog(payload: unknown): LoadableModel[];
+/**
+ * Read an endpoint's loadable-model catalog, preferring the controllable host
+ * catalog and degrading cleanly to the `/v1/models` floor.
+ *
+ * Control path: GET `<root>/api/models/local`, normalize, and if it yields at
+ * least one usable entry return the full loadable list (`controllable: true`).
+ *
+ * Floor path: on ANY control-surface failure (unreachable, non-2xx, invalid
+ * JSON, timeout, or an empty/unusable catalog) fall back to `fetchModels`
+ * (`/v1/models`) so behavior is exactly today's load-then-discover. The floor
+ * fetch's own failure propagates to the caller (same contract as the existing
+ * discovery path).
+ *
+ * `apiKey` is the bearer VALUE (resolved from the Telora secret); it authorizes
+ * both the control probe and the floor fetch.
+ */
+export declare function readLoadableCatalog(baseUrl: string, apiKey?: string | null): Promise<LoadableCatalog>;
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../src/host-control/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEjE,sFAAsF;AACtF,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAgD7D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,aAAa,EAAE,CAkBvE;AAYD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,GACrB,OAAO,CAAC,eAAe,CAAC,CAwB1B"}

package/dist/host-control/catalog.js

@@ -0,0 +1,149 @@
+/**
+ * Loadable-model catalog reader for the host-control plane (Local model host
+ * control, D1).
+ *
+ * A controllable host (e.g. Unsloth Studio @ :8888) exposes its FULL
+ * downloaded-but-unloaded catalog under the control surface
+ * `<root>/api/models/local`, returning every loadable model -- not just the one
+ * currently loaded that `/v1/models` reports. This module reads that catalog and
+ * degrades CLEANLY to the `/v1/models` floor (via discovery-poll's
+ * `fetchModels`) when the host is not controllable or the catalog read fails for
+ * any reason. The floor path is byte-identical to today's behavior, so a plain
+ * OpenAI-compatible endpoint is never broken.
+ *
+ * The live catalog JSON shape is host-specific (observed: 25 entries under
+ * `/api/models/local`, each carrying a load path). We do NOT have the exact live
+ * shape pinned, so `normalizeLocalCatalog` is DEFENSIVE: it tolerates a range of
+ * reasonable container and field names and is easy to extend per the runbook's
+ * live-shape reconciliation.
+ */
+import { fetchModels } from '../discovery-poll.js';
+import { hostGet, hostRootFromBaseUrl, HOST_CONTROL_FETCH_TIMEOUT_MS, HostControlError, } from './client.js';
+/** The control-surface path (under the host ROOT, not `/v1`) for the full catalog. */
+export const HOST_CONTROL_CATALOG_PATH = '/api/models/local';
+/**
+ * Candidate keys that may carry the array of catalog entries. The live host
+ * (Unsloth Studio) returned a bare array under `/api/models/local`; other hosts
+ * may wrap it. Defensive: we accept a top-level array OR any of these container
+ * keys. Easy to extend per the runbook.
+ */
+const CATALOG_ARRAY_KEYS = ['models', 'data', 'local', 'items'];
+/**
+ * Candidate keys for a catalog entry's served model id. `id` is canonical;
+ * `model`/`name` are common alternates on local-model hosts.
+ */
+const ID_KEYS = ['id', 'model', 'name'];
+/**
+ * Candidate keys for a catalog entry's host load path. `model_path` is the
+ * observed convention; the rest are reasonable alternates. Captured verbatim so
+ * Delivery 2 can resolve id -> path to load the model.
+ */
+const MODEL_PATH_KEYS = ['model_path', 'modelPath', 'path', 'file', 'gguf_path'];
+/** Read the first string-valued key present on an object, trimmed; '' if none. */
+function firstString(obj, keys) {
+    for (const key of keys) {
+        const v = obj[key];
+        if (typeof v === 'string') {
+            const trimmed = v.trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    return '';
+}
+/** Extract the catalog-entry array from a payload that is either a bare array or
+ *  a single-keyed container. Returns [] when no array is found (defensive). */
+function extractEntryArray(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    if (!payload || typeof payload !== 'object')
+        return [];
+    const obj = payload;
+    for (const key of CATALOG_ARRAY_KEYS) {
+        const v = obj[key];
+        if (Array.isArray(v))
+            return v;
+    }
+    return [];
+}
+/**
+ * Normalize a control-surface catalog payload into clean `LoadableModel`
+ * entries. Pure + DEFENSIVE: tolerates a bare array or a wrapped container,
+ * non-object items, missing/blank ids (dropped), and a missing model_path
+ * (captured as null). De-duplicates by id (first entry with a model_path wins
+ * its path). Exported for unit testing.
+ */
+export function normalizeLocalCatalog(payload) {
+    const entries = extractEntryArray(payload);
+    const byId = new Map();
+    for (const item of entries) {
+        if (!item || typeof item !== 'object')
+            continue;
+        const obj = item;
+        const id = firstString(obj, ID_KEYS);
+        if (!id)
+            continue; // an entry with no usable id is unselectable -- drop it.
+        const modelPath = firstString(obj, MODEL_PATH_KEYS) || null;
+        const existing = byId.get(id);
+        if (!existing) {
+            byId.set(id, { id, modelPath });
+        }
+        else if (existing.modelPath === null && modelPath !== null) {
+            // Prefer the duplicate that carries a load path over a path-less twin.
+            byId.set(id, { id, modelPath });
+        }
+    }
+    return [...byId.values()];
+}
+/** Build the floor-path catalog from a `/v1/models` id list. `modelPath` is null
+ *  on the floor -- the floor knows only the loaded id, never a load path. */
+function floorCatalog(ids) {
+    return {
+        controllable: false,
+        ids,
+        models: ids.map((id) => ({ id, modelPath: null })),
+    };
+}
+/**
+ * Read an endpoint's loadable-model catalog, preferring the controllable host
+ * catalog and degrading cleanly to the `/v1/models` floor.
+ *
+ * Control path: GET `<root>/api/models/local`, normalize, and if it yields at
+ * least one usable entry return the full loadable list (`controllable: true`).
+ *
+ * Floor path: on ANY control-surface failure (unreachable, non-2xx, invalid
+ * JSON, timeout, or an empty/unusable catalog) fall back to `fetchModels`
+ * (`/v1/models`) so behavior is exactly today's load-then-discover. The floor
+ * fetch's own failure propagates to the caller (same contract as the existing
+ * discovery path).
+ *
+ * `apiKey` is the bearer VALUE (resolved from the Telora secret); it authorizes
+ * both the control probe and the floor fetch.
+ */
+export async function readLoadableCatalog(baseUrl, apiKey) {
+    const root = hostRootFromBaseUrl(baseUrl);
+    const catalogUrl = `${root}${HOST_CONTROL_CATALOG_PATH}`;
+    try {
+        const payload = await hostGet(catalogUrl, {
+            apiKey,
+            timeoutMs: HOST_CONTROL_FETCH_TIMEOUT_MS,
+        });
+        const models = normalizeLocalCatalog(payload);
+        if (models.length > 0) {
+            return { controllable: true, ids: models.map((m) => m.id), models };
+        }
+        // Well-formed but empty (or no usable ids): not a usable control catalog --
+        // fall through to the floor so the picklist still offers the loaded model.
+    }
+    catch (err) {
+        // Fail-safe: any control-surface error means "not controllable here". Log the
+        // rich detail daemon-side (address-free dbMessage available for categorizing)
+        // and fall through to the floor. Never break a plain endpoint.
+        const detail = err instanceof HostControlError ? err.message : err.message;
+        console.log(`[host-control] catalog read fell back to /v1/models floor: ${detail}`);
+    }
+    // Floor: the OpenAI-compatible `/v1/models` listing (today's behavior).
+    const ids = await fetchModels(baseUrl, apiKey);
+    return floorCatalog(ids);
+}
+//# sourceMappingURL=catalog.js.map

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

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