@trillboards/edge-sdk 0.2.4 → 0.2.7

package/dist/autoSense.js

@@ -0,0 +1,606 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultHttpGetter = exports.AutoSenseSupervisor = void 0;
+exports.probeLiteRtLmHealth = probeLiteRtLmHealth;
+exports.runAutoSense = runAutoSense;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+const url_1 = require("url");
+const config_1 = require("./config");
+const sensingRunMode_1 = require("./sensingRunMode");
+const gemmaModelOta_1 = require("./gemmaModelOta");
+/**
+ * `auto-sense` — the ONE dispatching entrypoint for the BYO-CCTV connector that
+ * prefers ON-DEVICE local sensing (LiteRT-LM serving Gemma). Cloud inference is
+ * available only when the operator explicitly enables it.
+ *
+ * A fresh install may start before its model download finishes, so this probes
+ * `litert-lm serve` health with a SHORT timeout and:
+ *   - healthy  → runs the EXISTING local-sense path (no Vertex cost)
+ *   - unhealthy/unreachable → waits and keeps probing without uploading frames
+ *   - unhealthy + allowCloudFallback=true → runs the cloud-sense path
+ *
+ * It introduces NO new providers and NO duplicated sensing logic — the local
+ * and cloud run modes are reused verbatim. This module only owns the SELECTION.
+ */
+const DEFAULT_LITERT_LM_BASE_URL = 'http://localhost:9379';
+/** Default model the local-sense path runs (must match config.localSensing.model). */
+const DEFAULT_LITERT_LM_MODEL = 'gemma-4-E2B-it.litertlm';
+/**
+ * Probe timeout. SHORT on purpose: on a box with no litert-lm the connect
+ * either refuses fast (ECONNREFUSED) or hangs, and readiness checks should not
+ * stall the connector behind a long wait.
+ */
+const DEFAULT_PROBE_TIMEOUT_MS = 2000;
+/**
+ * Startup re-probe budget. A fresh install races litert-lm warmup/model-download
+ * (e.g. Windows `setup-litertlm.ps1` runs detached while the scheduled task can
+ * start right after pairing). A single probe at boot would pick cloud and never
+ * re-probe, stranding the box on cloud until a manual restart. So at startup we
+ * re-probe a few times before entering the steady waiting state. Default 4
+ * attempts.
+ */
+const DEFAULT_STARTUP_PROBE_ATTEMPTS = 4;
+/** Delay between startup re-probes (ms). Default 5s → ~15s warmup window. */
+const DEFAULT_STARTUP_PROBE_BACKOFF_MS = 5000;
+/**
+ * Steady-state background re-probe interval (ms). AFTER auto-sense picks a mode it
+ * keeps probing on this cadence so it can start local inference once a fresh
+ * install's litert-lm finishes warming up. Explicit cloud-fallback installs also
+ * use it to upgrade cloud→local and recover local→cloud. Default 60s.
+ */
+const DEFAULT_HEALTH_RECHECK_INTERVAL_MS = 60000;
+/** Floor for the re-probe interval (ms) so a mis-set tiny value can't hammer the serve. */
+const MIN_HEALTH_RECHECK_INTERVAL_MS = 15000;
+/**
+ * Anti-thrash: consecutive UNHEALTHY background re-probes required before a
+ * LOCAL→CLOUD fallback (a single flapping bad probe must not toggle the active
+ * manager). The reverse cloud→local upgrade is immediate. Default 2.
+ */
+const DEFAULT_LOCAL_UNHEALTHY_CHECKS_BEFORE_FALLBACK = 2;
+/**
+ * Probe `litert-lm serve` for reachability + readiness via `GET {base}/v1/models`
+ * (the OpenAI-compatible model list — cheap, present on a healthy serve, and a
+ * de-facto health endpoint). A 2xx with a parseable model list THAT INCLUDES THE
+ * MODEL the local-sense path will actually use is "healthy"; anything else
+ * (connection refused, timeout, non-2xx, empty/garbage body, OR a serve hosting
+ * a DIFFERENT model than configured) is "unhealthy" so the caller degrades to
+ * cloud.
+ *
+ * Why match the model (not just "non-empty list"): the local path posts inference
+ * to `config.localSensing.model` (default gemma-4-E2B-it.litertlm). A serve that
+ * is up but hosting a DIFFERENT model id would make auto-sense pick local and
+ * then fail EVERY frame — exactly the hard-fail this entrypoint exists to avoid.
+ * So we require the expected model to be present. (`expectedModel` omitted → fall
+ * back to "any non-empty list", e.g. for a pure reachability check.)
+ *
+ * Built-in http/https only (no extra dependency → survives bundling into the
+ * self-contained connector; trivially mockable in tests). Never throws.
+ */
+async function probeLiteRtLmHealth(baseUrl = DEFAULT_LITERT_LM_BASE_URL, opts = {}) {
+    const base = (baseUrl || DEFAULT_LITERT_LM_BASE_URL).replace(/\/+$/, '');
+    const url = `${base}/v1/models`;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const getter = opts.httpGetter ?? exports.defaultHttpGetter;
+    const expectedModel = opts.expectedModel?.trim() || undefined;
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await getter(url, { timeoutMs });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `litert-lm unreachable at ${url} (${err.message})`,
+        };
+    }
+    const latencyMs = Date.now() - startedAt;
+    if (result.statusCode < 200 || result.statusCode >= 300) {
+        return {
+            ok: false,
+            reason: `litert-lm at ${url} returned HTTP ${result.statusCode}`,
+            latencyMs,
+            statusCode: result.statusCode,
+        };
+    }
+    // A healthy serve answers /v1/models with `{ data: [ { id, ... } ] }`. Collect
+    // the model ids so we can require BOTH a non-empty list AND (when asked) the
+    // specific model the local path will use.
+    let modelIds = null;
+    try {
+        const parsed = JSON.parse(result.body);
+        if (Array.isArray(parsed?.data)) {
+            modelIds = parsed.data
+                .map((m) => (m && typeof m.id === 'string' ? m.id : null))
+                .filter((id) => id !== null);
+        }
+    }
+    catch {
+        modelIds = null;
+    }
+    if (modelIds === null) {
+        return {
+            ok: false,
+            reason: `litert-lm at ${url} returned an unparseable model list`,
+            latencyMs,
+            statusCode: result.statusCode,
+        };
+    }
+    if (modelIds.length === 0) {
+        return {
+            ok: false,
+            reason: `litert-lm at ${url} is up but has no model imported`,
+            latencyMs,
+            statusCode: result.statusCode,
+        };
+    }
+    // The serve is up with model(s), but if it isn't hosting the one we'll infer
+    // against, local would fail every frame — so treat that as unhealthy → cloud.
+    if (expectedModel && !modelIds.includes(expectedModel)) {
+        return {
+            ok: false,
+            reason: `litert-lm at ${url} is up but does not host model "${expectedModel}" ` +
+                `(has: ${modelIds.join(', ')})`,
+            latencyMs,
+            statusCode: result.statusCode,
+        };
+    }
+    return {
+        ok: true,
+        reason: `litert-lm healthy at ${url} (` +
+            (expectedModel ? `model "${expectedModel}" present, ` : `${modelIds.length} model(s), `) +
+            `${latencyMs}ms)`,
+        latencyMs,
+        statusCode: result.statusCode,
+    };
+}
+/**
+ * The `auto-sense` SUPERVISOR. Instead of probing once and then blocking forever
+ * on a single manager (the old behavior — mode FIXED for the whole process run,
+ * "restart to re-probe"), it OWNS the sensing lifecycle so the connector always
+ * prefers on-device Gemma and switches automatically with NO restart:
+ *
+ *  - startInitial(): bounded startup re-probe → start the chosen path's REAL
+ *    manager directly when litert-lm is healthy; otherwise wait locally unless
+ *    cloud fallback was explicitly enabled.
+ *  - beginRechecks(): a steady-state background re-probe loop on recheckIntervalMs.
+ *  - recheck(): one tick — AUTO-UPGRADE cloud→local the instant local is ready
+ *    (fixes the fresh-install race with zero restart). Explicit cloud-fallback
+ *    installs may also recover local→cloud after K unhealthy probes.
+ *  - shutdown(): stop the active manager + clear the timer (SIGINT/SIGTERM).
+ *
+ * At most ONE switch per tick; a re-entrancy guard + the K-debounce mean a
+ * flapping health signal can never rapidly toggle managers.
+ */
+class AutoSenseSupervisor {
+    constructor(deps) {
+        this.deps = deps;
+        this.mode = null;
+        this.active = null;
+        // Build each mode's manager once and reuse the instance across switches (a
+        // stop()→start() cycle re-runs the SAME real manager). `undefined` = not built
+        // yet; `null` = built but no feeds (fatal — cached so we don't rebuild).
+        this.localManager = undefined;
+        this.cloudManager = undefined;
+        this.consecutiveUnhealthy = 0;
+        /**
+         * Completed local analyses as of the previous re-probe. `null` = no baseline
+         * yet (not on local, or the manager cannot report it), which reads as "no
+         * positive evidence" and leaves the pre-existing behaviour in place.
+         */
+        this.analysesAtLastRecheck = null;
+        this.timer = null;
+        this.switching = false;
+        this.stopped = false;
+    }
+    /** The active mode (null until startInitial). For tests/observability. */
+    get currentMode() {
+        return this.mode;
+    }
+    getManager(mode) {
+        if (mode === 'local') {
+            if (this.localManager === undefined)
+                this.localManager = this.deps.buildLocalManager();
+            return this.localManager;
+        }
+        if (this.cloudManager === undefined)
+            this.cloudManager = this.deps.buildCloudManager();
+        return this.cloudManager;
+    }
+    /**
+     * Initial probe (bounded startup re-probe loop for the fresh-install warmup
+     * race) → start the chosen path's manager directly. Returns false (after
+     * onNoFeeds) when the chosen mode has no feeds configured.
+     */
+    async startInitial() {
+        this.deps.log(`[auto-sense] probing on-device LiteRT-LM at ${this.deps.litertLmBaseUrl} for model ` +
+            `"${this.deps.expectedModel}" (timeout ${this.deps.probeTimeoutMs}ms, up to ` +
+            `${this.deps.startupAttempts} attempt(s))…`);
+        let health = { ok: false, reason: 'no probe attempt made' };
+        for (let attempt = 1; attempt <= this.deps.startupAttempts; attempt += 1) {
+            health = await this.deps.probe();
+            if (health.ok)
+                break;
+            if (attempt < this.deps.startupAttempts) {
+                this.deps.log(`[auto-sense] LiteRT-LM not ready (attempt ${attempt}/${this.deps.startupAttempts}): ` +
+                    `${health.reason} — retrying in ${this.deps.startupBackoffMs}ms`);
+                if (this.deps.startupBackoffMs > 0)
+                    await this.deps.sleep(this.deps.startupBackoffMs);
+            }
+        }
+        if (health.ok) {
+            this.deps.log(`[auto-sense] LOCAL on-device sensing selected — ${health.reason}`);
+            return this.activate('local');
+        }
+        if (this.deps.allowCloudFallback) {
+            this.deps.log(`[auto-sense] CLOUD sensing selected by explicit fallback policy (local VLM not usable after ` +
+                `${this.deps.startupAttempts} attempt(s)) — ${health.reason}. Will AUTO-UPGRADE to LOCAL ` +
+                `with no restart once LiteRT-LM is ready (re-probing every ${this.deps.recheckIntervalMs}ms).`);
+            return this.activate('cloud');
+        }
+        // Validate feeds before entering the wait loop so a bad/empty config still
+        // fails immediately instead of looking like a model download in progress.
+        if (!this.getManager('local')) {
+            this.deps.onNoFeeds();
+            return false;
+        }
+        this.mode = 'waiting';
+        this.deps.log(`[auto-sense] LOCAL AI is not ready yet — ${health.reason}. Cloud inference is disabled by ` +
+            `default; waiting for LiteRT-LM and re-probing every ${this.deps.recheckIntervalMs}ms.`);
+        return true;
+    }
+    /** Build + start a mode's manager and make it active. False ⇒ no feeds. */
+    async activate(mode) {
+        const manager = this.getManager(mode);
+        if (!manager) {
+            this.deps.onNoFeeds();
+            return false;
+        }
+        await manager.start();
+        this.active = manager;
+        this.mode = mode;
+        this.consecutiveUnhealthy = 0;
+        // `start()` resets the manager's per-run analysis counter, so the baseline
+        // has to be re-taken here or the first re-probe would compare against a
+        // count from a previous run.
+        this.analysesAtLastRecheck = mode === 'local' ? this.localInferencesCompleted() : null;
+        if (mode === 'local')
+            this.deps.onLocalActivated?.();
+        return true;
+    }
+    /** Start the steady-state background re-probe loop. */
+    beginRechecks() {
+        this.scheduleNextRecheck();
+    }
+    scheduleNextRecheck() {
+        if (this.stopped)
+            return;
+        // Re-arming timeout (schedule the NEXT tick only after this one settles) so
+        // a slow probe/switch can never overlap the next re-probe.
+        this.timer = this.deps.setTimer(() => {
+            this.recheck()
+                .catch((err) => this.deps.log(`[auto-sense] re-probe tick failed: ${err instanceof Error ? err.message : err}`))
+                .finally(() => this.scheduleNextRecheck());
+        }, this.deps.recheckIntervalMs);
+    }
+    /**
+     * How many ON-DEVICE inferences have completed this run. `null` when the
+     * manager cannot report it (a test fake, a not-yet-built manager) — which
+     * reads as "no positive evidence", i.e. today's behaviour.
+     */
+    localInferencesCompleted() {
+        const manager = this.localManager;
+        if (!manager || typeof manager.getSensingHealth !== 'function')
+            return null;
+        try {
+            const n = manager.getSensingHealth().localInferences;
+            return Number.isFinite(n) ? n : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * One background re-probe tick.
+     *  - While WAITING: a healthy probe starts local sensing immediately.
+     *  - On CLOUD: any healthy probe → AUTO-UPGRADE to local immediately (running
+     *    on cloud while local is ready is pure waste; the K-debounce on the return
+     *    path bounds any toggling, so this is safe on the first healthy probe).
+     *  - On LOCAL: a healthy probe resets the debounce; an unhealthy probe
+     *    increments it, and only after K CONSECUTIVE unhealthy probes do we
+     *    AUTO-RECOVER to cloud only when explicit fallback is enabled.
+     * At most one switch per tick; re-entrancy guarded.
+     *
+     * ── Why an unanswered probe is not, by itself, a verdict ───────────────────
+     *
+     * `litert-lm serve` builds on `http.server.HTTPServer` — the SERIAL one, not
+     * `ThreadingHTTPServer`. One request is handled at a time, so for the whole
+     * duration of a generation the accept loop is blocked and `GET /v1/models`
+     * cannot be answered by anybody. The readiness probe therefore competes with
+     * the very work whose viability it is meant to certify: measured against the
+     * real serve, 4 of 5 probes issued during ONE 11.8 s inference timed out at
+     * the shipped 2 000 ms, while an idle serve answered the same request in
+     * 2.6 ms.
+     *
+     * A 16-camera connector keeps that single slot busy essentially all the time,
+     * so an UNANSWERED probe was near-certain and two consecutive ones demoted the
+     * whole install: measured 3 mode switches in the first 6 minutes of a
+     * 16-camera run, each one stopping and restarting all 16 loops and moving
+     * every feed onto the metered cloud path. The connector's own success at
+     * local inference was the thing that made local inference look dead.
+     *
+     * The evidence that settles it is not the ping, it is the WORK: an ON-DEVICE
+     * inference that COMPLETED since the previous re-probe proves the runtime is
+     * alive, and proves it more directly than any side-channel could. So an
+     * unanswered probe is inconclusive only while local inferences are still
+     * landing; the moment they stop landing the same probe counts, and K of them
+     * demote exactly as before.
+     *
+     * It has to be `localInferences` and not the total analysis count. With
+     * `cloudFallbackOnError` on, a frame the local provider THREW on is answered
+     * by the cloud and still lands as an analysis — so a dead runtime would keep
+     * advancing the total forever and this rule would mask it permanently, which
+     * is strictly worse than the defect it replaces.
+     *
+     * Deliberately NOT keyed on "we have a request in flight": a serve that
+     * ACCEPTS and never answers holds our permit for the provider's whole timeout,
+     * so in-flight work is compatible with a runtime that is doing nothing. Only
+     * completion is proof. An ANSWERED probe stays conclusive either way — a
+     * non-2xx or a wrong model list is a real verdict, and a serve that answers
+     * has an opinion.
+     */
+    async recheck() {
+        if (this.stopped || this.switching)
+            return;
+        const analysesBefore = this.analysesAtLastRecheck;
+        const health = await this.deps.probe();
+        if (this.stopped)
+            return;
+        const analysesNow = this.localInferencesCompleted();
+        // Positive proof of life: the ON-DEVICE runtime finished work in this window.
+        const provedAliveByWork = analysesNow !== null && analysesBefore !== null && analysesNow > analysesBefore;
+        this.analysesAtLastRecheck = analysesNow;
+        if (this.mode === 'waiting') {
+            if (health.ok) {
+                this.deps.log('[auto-sense] LOCAL AI is ready — starting on-device sensing');
+                await this.switchTo('local');
+            }
+            return;
+        }
+        if (this.mode === 'cloud') {
+            if (health.ok) {
+                this.deps.log('[auto-sense] upgrading CLOUD->LOCAL (LiteRT-LM now ready)');
+                await this.switchTo('local');
+            }
+            return;
+        }
+        if (this.mode === 'local') {
+            if (health.ok) {
+                this.consecutiveUnhealthy = 0;
+                return;
+            }
+            // Unanswered (no statusCode) while local analyses are still COMPLETING:
+            // inconclusive. Neither counted nor cleared — ask again next interval.
+            if (health.statusCode === undefined && provedAliveByWork) {
+                this.deps.log(`[auto-sense] health probe inconclusive — the single litert-lm slot cannot answer ` +
+                    `/v1/models while it generates (${health.reason}), and this connector completed ` +
+                    `${(analysesNow ?? 0) - (analysesBefore ?? 0)} on-device inference(s) since the last ` +
+                    'check. Not counting it against the fallback debounce.');
+                return;
+            }
+            this.consecutiveUnhealthy += 1;
+            if (this.consecutiveUnhealthy >= this.deps.unhealthyChecksBeforeFallback) {
+                if (this.deps.allowCloudFallback) {
+                    // Name the reason. The no-fallback branch below always has; this one
+                    // did not, so the operator whose bill just moved onto the metered
+                    // cloud path saw a demotion with no cause attached to it.
+                    this.deps.log(`[auto-sense] falling back LOCAL->CLOUD (explicit policy; LiteRT-LM unhealthy after ` +
+                        `${this.consecutiveUnhealthy} consecutive checks) — ${health.reason}`);
+                    await this.switchTo('cloud');
+                }
+                else {
+                    this.deps.log(`[auto-sense] LOCAL AI health check failed — ${health.reason}. ` +
+                        'Cloud inference remains disabled; local sensing will recover in place.');
+                    this.consecutiveUnhealthy = 0;
+                }
+            }
+        }
+    }
+    /** Stop the active manager, start the target — old.stop() BEFORE new.start(). */
+    async switchTo(mode) {
+        if (this.mode === mode || this.switching)
+            return;
+        const next = this.getManager(mode);
+        if (!next) {
+            // Can't happen mid-run (both modes resolve the SAME static feeds), but
+            // never tear down the working manager for one we can't start.
+            this.deps.log(`[auto-sense] cannot switch to ${mode} sensing (no camera feeds) — staying on ${this.mode}`);
+            return;
+        }
+        this.switching = true;
+        try {
+            if (this.active)
+                await this.active.stop();
+            await next.start();
+            this.active = next;
+            this.mode = mode;
+            this.consecutiveUnhealthy = 0;
+            // Same reason as in activate(): start() zeroes the per-run analysis count.
+            this.analysesAtLastRecheck = mode === 'local' ? this.localInferencesCompleted() : null;
+            if (mode === 'local')
+                this.deps.onLocalActivated?.();
+        }
+        finally {
+            this.switching = false;
+        }
+    }
+    /** SIGINT/SIGTERM: stop the active manager + clear the re-probe timer. Idempotent. */
+    async shutdown() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        if (this.timer != null) {
+            this.deps.clearTimer(this.timer);
+            this.timer = null;
+        }
+        if (this.active) {
+            try {
+                await this.active.stop();
+            }
+            catch {
+                // best-effort
+            }
+        }
+    }
+}
+exports.AutoSenseSupervisor = AutoSenseSupervisor;
+function defaultRegisterShutdown(handler) {
+    process.on('SIGINT', handler);
+    process.on('SIGTERM', handler);
+}
+/** Never resolves — keeps the connector process alive until SIGINT/SIGTERM. */
+function blockForever() {
+    return new Promise(() => { });
+}
+/**
+ * `auto-sense` entrypoint: resolve probe + manager inputs from config, then run
+ * the AutoSenseSupervisor (probe → start the chosen REAL manager → keep
+ * re-probing → auto-upgrade/auto-recover with NO restart). Blocks until
+ * SIGINT/SIGTERM (the supervisor's re-probe timer keeps the event loop alive).
+ *
+ * The probe target is the operator's configured `localSensing.litertLmBaseUrl`
+ * (default http://localhost:9379) so a non-standard serve host is honored, and
+ * the probe requires the configured `localSensing.model` to be present so we
+ * never pick local against a serve hosting the wrong model.
+ *
+ * Config is REQUIRED to build the sensing managers, so it's loaded up front and a
+ * genuine config error propagates to main() (prints + exits 1) — the same net
+ * result as before, where the chosen run mode re-loaded the config and reported it.
+ *
+ * The explicit `local-sense` / `cloud-sense` entrypoints stay non-switching; only
+ * `auto-sense` is supervised.
+ */
+async function runAutoSense(args, deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const load = deps.loadConfig ?? config_1.loadConfig;
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const configIdx = args.indexOf('--config');
+    const configPath = configIdx >= 0 && args[configIdx + 1] ? args[configIdx + 1] : 'trillboards.config.json';
+    const config = load(configPath);
+    const litertLmBaseUrl = config.localSensing?.litertLmBaseUrl || DEFAULT_LITERT_LM_BASE_URL;
+    const probeTimeoutMs = config.localSensing?.healthProbeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    const expectedModel = config.localSensing?.model || DEFAULT_LITERT_LM_MODEL;
+    const startupAttempts = Math.max(1, config.localSensing?.healthProbeStartupAttempts ?? DEFAULT_STARTUP_PROBE_ATTEMPTS);
+    const startupBackoffMs = config.localSensing?.healthProbeStartupBackoffMs ?? DEFAULT_STARTUP_PROBE_BACKOFF_MS;
+    const recheckIntervalMs = Math.max(MIN_HEALTH_RECHECK_INTERVAL_MS, config.localSensing?.healthRecheckIntervalMs ?? DEFAULT_HEALTH_RECHECK_INTERVAL_MS);
+    const unhealthyChecksBeforeFallback = Math.max(1, config.localSensing?.localUnhealthyChecksBeforeFallback ??
+        DEFAULT_LOCAL_UNHEALTHY_CHECKS_BEFORE_FALLBACK);
+    const allowCloudFallback = config.localSensing?.allowCloudFallback === true;
+    const probe = deps.probe
+        ? () => deps.probe(litertLmBaseUrl, probeTimeoutMs, expectedModel)
+        : () => probeLiteRtLmHealth(litertLmBaseUrl, { timeoutMs: probeTimeoutMs, expectedModel });
+    let gemmaOta = null;
+    let gemmaOtaStarted = false;
+    const startModelOtaOnce = () => {
+        if (gemmaOtaStarted)
+            return;
+        gemmaOtaStarted = true;
+        gemmaOta = (deps.startModelOta ?? gemmaModelOta_1.startGemmaModelOta)(config);
+    };
+    const supervisor = new AutoSenseSupervisor({
+        probe,
+        buildLocalManager: deps.buildLocalManager ?? (() => (0, sensingRunMode_1.buildLocalSensingManager)(config, undefined, { configPath })),
+        buildCloudManager: deps.buildCloudManager ?? (() => (0, sensingRunMode_1.buildCloudSensingManager)(config, undefined, { configPath })),
+        log,
+        sleep,
+        setTimer: deps.setTimer ?? ((cb, ms) => setTimeout(cb, ms)),
+        clearTimer: deps.clearTimer ?? ((h) => clearTimeout(h)),
+        onNoFeeds: deps.onNoFeeds ?? (() => process.exit(1)),
+        onLocalActivated: startModelOtaOnce,
+        startupAttempts,
+        startupBackoffMs,
+        recheckIntervalMs,
+        unhealthyChecksBeforeFallback,
+        allowCloudFallback,
+        litertLmBaseUrl,
+        expectedModel,
+        probeTimeoutMs,
+    });
+    // Clean shutdown: stop the OTA watcher, the active manager, + the re-probe timer.
+    const register = deps.registerShutdown ?? defaultRegisterShutdown;
+    register(async () => {
+        gemmaOta?.stop();
+        await supervisor.shutdown();
+        process.exit(0);
+    });
+    const started = await supervisor.startInitial();
+    if (!started)
+        return; // onNoFeeds already fired (default: process.exit(1))
+    supervisor.beginRechecks();
+    // Keep the process running until SIGINT/SIGTERM (tests inject a resolved waiter).
+    await (deps.waitForShutdown ?? blockForever)();
+}
+/**
+ * Default transport using Node's built-in http/https. No third-party deps so it
+ * survives bundling into the self-contained connector. Mirrors the framing
+ * tolerance of LiteRtVlmProvider's poster: litert-lm serve emits non-strict HTTP
+ * framing (bare LF on the status line) that Node's strict parser rejects, and
+ * the connector talks to a LOCAL, trusted serve, so we tolerate it here too —
+ * otherwise a healthy serve would look "unreachable" and we'd wrongly pick cloud.
+ */
+const defaultHttpGetter = (url, options) => {
+    return new Promise((resolve, reject) => {
+        let parsed;
+        try {
+            parsed = new url_1.URL(url);
+        }
+        catch (err) {
+            reject(new Error(`Invalid LiteRT-LM URL: ${err.message}`));
+            return;
+        }
+        const mod = parsed.protocol === 'https:' ? https : http;
+        const req = mod.request(url, { method: 'GET', timeout: options.timeoutMs, insecureHTTPParser: true }, (res) => {
+            const chunks = [];
+            res.on('data', (chunk) => chunks.push(chunk));
+            res.on('end', () => resolve({ statusCode: res.statusCode || 0, body: Buffer.concat(chunks).toString('utf-8') }));
+        });
+        req.on('error', (err) => reject(err));
+        req.on('timeout', () => req.destroy(new Error(`probe timed out after ${options.timeoutMs}ms`)));
+        req.end();
+    });
+};
+exports.defaultHttpGetter = defaultHttpGetter;
+//# sourceMappingURL=autoSense.js.map

package/dist/autoSense.js.map

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

package/dist/cli.d.ts

@@ -1,3 +1,29 @@
 #!/usr/bin/env node
-export {};
+/**
+ * True if a filesystem error is a PERMISSION failure (EACCES/EPERM), or its
+ * message says so. This is the signature of the paired-config write failing
+ * because ~/Library/Application Support/Trillboards is owned by another account
+ * — which happens when the `.pkg` was installed with admin rights and its
+ * postinstall ran as root, creating that dir ROOT-OWNED. It is NOT a bad or
+ * expired claim code, so it must never be reported as one.
+ */
+export declare function isPermissionError(err: unknown): boolean;
+/**
+ * The operator-facing remediation when the paired config can't be written
+ * because its directory is owned by another account. Names the REAL cause and
+ * the exact one-line fix — deliberately NOT "double-check the code" (pairing
+ * already SUCCEEDED; only the local save failed). Mirrors the guidance in
+ * deploy/macos/pair.command so the GUI and headless paths say the same thing.
+ */
+export declare function configWritePermissionMessage(resolvedConfigPath: string): string;
+/**
+ * Persist the paired config, translating a PERMISSION failure into the clear
+ * remediation above (and exiting non-zero) instead of letting a raw EACCES
+ * bubble up as an opaque "Fatal error" that the GUI then mislabels "check the
+ * code". Any OTHER write error is re-thrown unchanged (surfaced as "Fatal
+ * error: …"). The writer is injectable for tests (mirrors PairClient's poster).
+ */
+export declare function writePairedConfig(resolvedConfigPath: string, serialized: string, writeFile?: (p: string, data: string, opts: {
+    mode: number;
+}) => void): void;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2WA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,CAW/E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,kBAAkB,EAAE,MAAM,EAC1B,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,KAAK,IAC/B,GAChC,IAAI,CAWN"}