@trillboards/edge-sdk 0.2.4 → 0.2.7

package/dist/VlmAdmissionGate.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * VlmAdmissionGate — the connector's port of the Android
+ * `VlmFrameAdmissionGate` (agent-core `inference/vlm/VlmFrameAdmissionGate.kt`).
+ *
+ * WHY THIS EXISTS. `litert-lm serve` is a SINGLE-CONVERSATION server: it
+ * processes one chat completion at a time. `CloudSensingManager` fans out one
+ * independent timer loop per feed, and those loops free-run — at 16 cameras on
+ * the 30 s cadence that is ~32 inference requests/minute arriving at a server
+ * that sustains 2–10/minute. Without a gate the surplus does not queue
+ * politely: the requests pile onto one serve instance, frames age against the
+ * provider's 120 s HTTP timeout, and every timeout burns up to 3 retry
+ * attempts (`LiteRtVlmProvider` maxAttempts). The machine spends its whole
+ * budget re-asking about frames that are already minutes stale.
+ *
+ * THE ANDROID SEMANTICS, MIRRORED (not reinvented):
+ *   - a bounded number of in-flight slots (ONE, sized to the serve's real
+ *     concurrency; `maxInFlight` exists so a genuinely concurrent backend can
+ *     be sized up, never guessed up);
+ *   - `minIntervalMs` — a global pacing floor between admissions;
+ *   - stale recovery at `maxInFlightMs` — a slot whose holder vanished (a
+ *     crashed provider, a socket that never resolved) is reclaimed rather than
+ *     wedging sensing forever on an unattended 24/7 connector;
+ *   - DROP, never queue. A stale frame is worthless: by the time a queued frame
+ *     reached the model the scene has moved on. The caller is told "no" and
+ *     tries again on its next tick.
+ *
+ * WHAT DIFFERS FROM ANDROID, AND WHY. Android has exactly one camera, so its
+ * gate is a bare boolean. The connector has N feeds sharing ONE serve, so
+ * admission must be attributable: every acquire/deny is counted per feed, which
+ * is what makes "camera 12 is being starved" observable instead of invisible.
+ * Acquire returns a TICKET rather than a bare boolean so a late release from a
+ * call whose slot was already reclaimed as stale cannot free somebody else's
+ * slot.
+ *
+ * THREADING. Node is single-threaded and `tryAcquire`/`release` never await, so
+ * the whole body is one critical section by construction — the Kotlin
+ * `@Synchronized` has no counterpart to write.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VlmAdmissionGate = void 0;
+const DEFAULT_MAX_IN_FLIGHT = 1;
+const DEFAULT_MAX_IN_FLIGHT_MS = 180000;
+class VlmAdmissionGate {
+    constructor(options = {}) {
+        this.inFlight = new Set();
+        this.nextAllowedAtMs = 0;
+        this.admitted = 0;
+        this.droppedInFlight = 0;
+        this.droppedMinInterval = 0;
+        this.staleReclaimed = 0;
+        this.lateReleases = 0;
+        this.perFeed = new Map();
+        this.maxInFlight = Math.max(1, Math.trunc(options.maxInFlight ?? DEFAULT_MAX_IN_FLIGHT));
+        this.minIntervalMs = Math.max(0, Math.trunc(options.minIntervalMs ?? 0));
+        this.maxInFlightMs = Math.max(0, Math.trunc(options.maxInFlightMs ?? DEFAULT_MAX_IN_FLIGHT_MS));
+        this.now = options.now ?? Date.now;
+    }
+    /** Slots this gate will ever hand out at once. */
+    getMaxInFlight() {
+        return this.maxInFlight;
+    }
+    /** Slots currently held (after reclaiming any stale ones). */
+    getInFlight(nowMs) {
+        this.reclaimStale(nowMs ?? this.now());
+        return this.inFlight.size;
+    }
+    /**
+     * Try to take a slot for `name`. Returns a ticket on admission, `null` on a
+     * DROP — the caller must abandon this frame, not hold it. Never blocks.
+     */
+    tryAcquire(name, nowMs) {
+        const now = nowMs ?? this.now();
+        this.reclaimStale(now);
+        const feed = this.feedStats(name);
+        if (this.inFlight.size >= this.maxInFlight) {
+            this.droppedInFlight++;
+            feed.dropped++;
+            return null;
+        }
+        if (now < this.nextAllowedAtMs) {
+            this.droppedMinInterval++;
+            feed.dropped++;
+            return null;
+        }
+        const ticket = { name, acquiredAtMs: now };
+        this.inFlight.add(ticket);
+        this.nextAllowedAtMs = now + this.minIntervalMs;
+        this.admitted++;
+        feed.admitted++;
+        feed.lastAdmittedAtMs = now;
+        return ticket;
+    }
+    /**
+     * Give a slot back. Idempotent, and a no-op for a ticket already reclaimed as
+     * stale (counted as a late release so the reclaim threshold stays auditable).
+     */
+    release(ticket) {
+        if (!ticket)
+            return;
+        if (!this.inFlight.delete(ticket)) {
+            this.lateReleases++;
+        }
+    }
+    /** Age (ms) of the oldest held slot, or null when idle. */
+    oldestInFlightAgeMs(nowMs) {
+        const now = nowMs ?? this.now();
+        let oldest = null;
+        for (const t of this.inFlight) {
+            const age = Math.max(0, now - t.acquiredAtMs);
+            if (oldest === null || age > oldest)
+                oldest = age;
+        }
+        return oldest;
+    }
+    /** Drop every slot and counter (a stop()/start() cycle starts clean). */
+    reset() {
+        this.inFlight.clear();
+        this.nextAllowedAtMs = 0;
+        this.admitted = 0;
+        this.droppedInFlight = 0;
+        this.droppedMinInterval = 0;
+        this.staleReclaimed = 0;
+        this.lateReleases = 0;
+        this.perFeed.clear();
+    }
+    getStats(nowMs) {
+        this.reclaimStale(nowMs ?? this.now());
+        return {
+            maxInFlight: this.maxInFlight,
+            inFlight: this.inFlight.size,
+            admitted: this.admitted,
+            droppedInFlight: this.droppedInFlight,
+            droppedMinInterval: this.droppedMinInterval,
+            staleReclaimed: this.staleReclaimed,
+            lateReleases: this.lateReleases,
+            perFeed: [...this.perFeed.values()].map((f) => ({ ...f })),
+        };
+    }
+    // ─── Private ────────────────────────────────────────────────────────────────
+    feedStats(name) {
+        let feed = this.perFeed.get(name);
+        if (!feed) {
+            feed = { name, admitted: 0, dropped: 0, lastAdmittedAtMs: null };
+            this.perFeed.set(name, feed);
+        }
+        return feed;
+    }
+    /**
+     * Free slots whose holder has exceeded `maxInFlightMs` — the Kotlin gate's
+     * stale branch. A wedged slot on a 24/7 unattended connector is indefinite
+     * blindness, so the gate self-heals rather than waiting for a restart.
+     */
+    reclaimStale(nowMs) {
+        if (this.maxInFlightMs <= 0 || this.inFlight.size === 0)
+            return;
+        for (const t of this.inFlight) {
+            if (nowMs - t.acquiredAtMs > this.maxInFlightMs) {
+                this.inFlight.delete(t);
+                this.staleReclaimed++;
+            }
+        }
+    }
+}
+exports.VlmAdmissionGate = VlmAdmissionGate;
+//# sourceMappingURL=VlmAdmissionGate.js.map

package/dist/VlmAdmissionGate.js.map

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

package/dist/autoSense.d.ts

@@ -0,0 +1,266 @@
+import { type EdgeAgentConfig } from './config';
+import { type SensingManager } from './sensingRunMode';
+import { type GemmaModelOtaHandle } from './gemmaModelOta';
+/** The outcome of a LiteRT-LM health probe (consumed by the mode selector). */
+export interface LiteRtHealthResult {
+    /** True iff litert-lm answered the readiness check with a usable response. */
+    ok: boolean;
+    /** Human-readable reason (logged so support can diagnose a fallback). */
+    reason: string;
+    /** Round-trip latency of the probe in ms (best-effort; present on success). */
+    latencyMs?: number;
+    /** HTTP status the probe observed, when it got a response at all. */
+    statusCode?: number;
+}
+/** Minimal injectable HTTP GET — lets tests stub litert-lm entirely (no network). */
+export interface HttpGetter {
+    (url: string, options: {
+        timeoutMs: number;
+    }): Promise<{
+        statusCode: number;
+        body: string;
+    }>;
+}
+/**
+ * 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.
+ */
+export declare function probeLiteRtLmHealth(baseUrl?: string, opts?: {
+    timeoutMs?: number;
+    httpGetter?: HttpGetter;
+    expectedModel?: string;
+}): Promise<LiteRtHealthResult>;
+/** A timer handle the supervisor sets for its re-probe loop (injectable in tests). */
+export type AutoSenseTimerHandle = ReturnType<typeof setTimeout>;
+/** Which sensing path the supervisor is currently running. */
+export type SensingMode = 'local' | 'cloud';
+export type AutoSenseState = SensingMode | 'waiting';
+/**
+ * Everything the AutoSenseSupervisor needs, all injectable so the supervisor can
+ * be unit-tested with a fake probe + fake managers. `runAutoSense` builds this
+ * from config + the real probe/managers/timers.
+ */
+export interface AutoSenseSupervisorDeps {
+    /** Probe litert-lm, already bound to the resolved base URL / timeout / model. */
+    probe: () => Promise<LiteRtHealthResult>;
+    /** Build (NOT start) the local-sensing manager. `null` ⇒ no feeds (fatal). */
+    buildLocalManager: () => SensingManager | null;
+    /** Build (NOT start) the cloud-sensing manager. `null` ⇒ no feeds (fatal). */
+    buildCloudManager: () => SensingManager | null;
+    /** Log sink (tests capture it). */
+    log: (msg: string) => void;
+    /** Sleep between startup re-probes (tests inject a no-op). */
+    sleep: (ms: number) => Promise<void>;
+    /** Arm the steady-state re-probe timer (tests inject a controllable fake). */
+    setTimer: (cb: () => void, ms: number) => AutoSenseTimerHandle;
+    /** Clear the re-probe timer (tests assert this on shutdown). */
+    clearTimer: (handle: AutoSenseTimerHandle) => void;
+    /** Called when the chosen mode has NO feeds (fatal config error; default exits 1). */
+    onNoFeeds: () => void;
+    /** Called after LOCAL sensing starts. Used to defer model OTA until initial provisioning is complete. */
+    onLocalActivated?: () => void;
+    /** Bounded startup re-probe attempts before committing to the initial mode. */
+    startupAttempts: number;
+    /** Delay (ms) between startup re-probes. */
+    startupBackoffMs: number;
+    /** Steady-state re-probe interval (ms), already floored. */
+    recheckIntervalMs: number;
+    /** Consecutive unhealthy re-probes required before a LOCAL→CLOUD fallback. */
+    unhealthyChecksBeforeFallback: number;
+    /** Cloud inference is opt-in because continuous CCTV cloud load is expensive. */
+    allowCloudFallback: boolean;
+    /** For the initial "probing…" log line. */
+    litertLmBaseUrl: string;
+    expectedModel: string;
+    probeTimeoutMs: number;
+}
+/**
+ * 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.
+ */
+export declare class AutoSenseSupervisor {
+    private readonly deps;
+    private mode;
+    private active;
+    private localManager;
+    private cloudManager;
+    private consecutiveUnhealthy;
+    /**
+     * 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.
+     */
+    private analysesAtLastRecheck;
+    private timer;
+    private switching;
+    private stopped;
+    constructor(deps: AutoSenseSupervisorDeps);
+    /** The active mode (null until startInitial). For tests/observability. */
+    get currentMode(): AutoSenseState | null;
+    private getManager;
+    /**
+     * 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.
+     */
+    startInitial(): Promise<boolean>;
+    /** Build + start a mode's manager and make it active. False ⇒ no feeds. */
+    private activate;
+    /** Start the steady-state background re-probe loop. */
+    beginRechecks(): void;
+    private scheduleNextRecheck;
+    /**
+     * 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.
+     */
+    private localInferencesCompleted;
+    /**
+     * 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.
+     */
+    recheck(): Promise<void>;
+    /** Stop the active manager, start the target — old.stop() BEFORE new.start(). */
+    private switchTo;
+    /** SIGINT/SIGTERM: stop the active manager + clear the re-probe timer. Idempotent. */
+    shutdown(): Promise<void>;
+}
+/** Injection points for runAutoSense (default to the real probe/managers/timers). */
+export interface AutoSenseDeps {
+    /**
+     * Probe used to decide local-vs-cloud. Defaults to probeLiteRtLmHealth.
+     * Receives the resolved base URL, per-probe timeout, and the model the local
+     * path will run (so the probe can require it before declaring local usable).
+     */
+    probe?: (baseUrl: string, timeoutMs: number, expectedModel: string) => Promise<LiteRtHealthResult>;
+    /** Loads the connector config. Defaults to loadConfig. */
+    loadConfig?: (configPath: string) => EdgeAgentConfig;
+    /** Build (NOT start) the local manager. Defaults to buildLocalSensingManager(config). */
+    buildLocalManager?: () => SensingManager | null;
+    /** Build (NOT start) the cloud manager. Defaults to buildCloudSensingManager(config). */
+    buildCloudManager?: () => SensingManager | null;
+    /** Log sink (tests capture it). Defaults to console.log. */
+    log?: (msg: string) => void;
+    /** Sleep between startup re-probes (tests inject a no-op). Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Arm the re-probe timer. Defaults to setTimeout. */
+    setTimer?: (cb: () => void, ms: number) => AutoSenseTimerHandle;
+    /** Clear the re-probe timer. Defaults to clearTimeout. */
+    clearTimer?: (handle: AutoSenseTimerHandle) => void;
+    /** Fatal no-feeds handler. Defaults to process.exit(1). */
+    onNoFeeds?: () => void;
+    /** Register the shutdown handler. Defaults to SIGINT/SIGTERM listeners. */
+    registerShutdown?: (handler: () => void | Promise<void>) => void;
+    /** Block until shutdown (production never resolves; tests inject a resolved waiter). */
+    waitForShutdown?: () => Promise<void>;
+    /**
+     * Start the on-device VLM (Gemma) OTA watcher. Defaults to startGemmaModelOta.
+     * Returns a handle whose stop() runs on shutdown (or null when disabled). It
+     * starts only after LOCAL sensing activates, so first-time provisioning owns
+     * the initial model download and OTA cannot race it.
+     */
+    startModelOta?: (config: EdgeAgentConfig) => GemmaModelOtaHandle | null;
+}
+/**
+ * `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.
+ */
+export declare function runAutoSense(args: string[], deps?: AutoSenseDeps): Promise<void>;
+/**
+ * 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.
+ */
+export declare const defaultHttpGetter: HttpGetter;
+//# sourceMappingURL=autoSense.d.ts.map

package/dist/autoSense.d.ts.map

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