obsbot-mcp 0.3.0 → 0.4.0

package/dist/device/manager.d.ts

@@ -1,10 +1,334 @@
 import { DeviceInfo } from "../codec/types.js";
 import { HelperProcess } from "../transport/helper-process.js";
 import { ObsbotTransport } from "../transport/transport.js";
+/** Thrown by get() with no selector when more than one camera is attached. */
+export declare class AmbiguousCameraError extends Error {
+    readonly available: string[];
+    constructor(available: string[]);
+}
+/** Thrown by get(serial) when no attached, bindable camera has that serial. */
+export declare class UnknownCameraError extends Error {
+    readonly available: string[];
+    constructor(serial: string, available: string[]);
+}
+export interface CameraInfo {
+    /** Present only for cameras this process could open and identify. */
+    serial?: string;
+    /** macOS: USB locationID. A handle for correlation/display only — never identity. */
+    locationId?: number;
+    name: string;
+    status: "available" | "bound" | "busy";
+    /**
+     * Why a `busy` camera could not be identified — the underlying open or
+     * readSerial error. Absent on cameras that bound fine. "busy" covers two very
+     * different situations (another process holds the device vs. the vendor
+     * mailbox went quiet) and without this they are indistinguishable from
+     * outside.
+     */
+    reason?: string;
+}
+/**
+ * Serial-keyed multi-camera registry. Identity is the serial (read via
+ * ObsbotTransport.readSerial() on a freshly-opened device); locationId is
+ * only ever a display/correlation hint, never persisted as truth for
+ * binding.
+ *
+ * Steady state is one HelperProcess per bound camera (Map<serial, {helper,
+ * transport, locationId}>), spawned lazily — nothing is spawned until a
+ * camera is actually needed (get() or listCameras()). While scanning for a
+ * camera to bind, candidates are tried on a single scratch helper reused
+ * across attempts, mirroring the native helper's own behaviour: `doOpen`
+ * unconditionally releases whatever device it previously held before
+ * opening the next one, so re-opening a different candidate on the same
+ * helper is exactly what one physical device-swap looks like to it. A
+ * scratch helper that turns out to be the winning candidate is promoted
+ * directly into the registry (no extra spawn); one that never opens a
+ * usable camera is kept around for the next scan instead of being spawned
+ * again. Consequently DeviceManager never closes a helper it did not spawn
+ * itself for a *losing* attempt — ownership of a bound camera's helper
+ * transfers to the registry, and callers that hand in an already-started,
+ * externally-owned helper (see the .mjs scripts) keep owning its shutdown.
+ *
+ * USB open is exclusive: a camera another process holds fails `open` with
+ * an exclusive-access error. Per multi-camera spec §4.3, ANY open failure
+ * during a scan is treated as "not mine, skip" — not fatal — because the
+ * helper does not currently surface a clean, stable way to distinguish
+ * exclusive-access from other open failures at this layer.
+ *
+ * invalidate() is the escape hatch out of "once bound, stay bound": it
+ * drops a registry entry (best-effort closing its helper first) so the
+ * next get()/bind() re-scans through a fresh helper instead of handing back
+ * a transport that may be talking to a device that already re-enumerated.
+ */
 export declare class DeviceManager {
-    private helper;
-    constructor(helper: HelperProcess);
+    private makeHelper;
+    private registry;
+    /** Lazily spawned, reused across scans until promoted into the registry. */
+    private scanHelper?;
+    /**
+     * Long-lived listener. Holds no device and never scans for one — its only job
+     * is to still be alive, and still subscribed, when the cable moves.
+     */
+    private watcher?;
+    /**
+     * Reconnect tracking, folded in from the retired DeviceSession. `everBound`
+     * records every serial this manager has bound at least once — deliberately
+     * SEPARATE from the registry Map so it survives invalidate() dropping a
+     * registry entry (the registry says "bound right now", this says "bound at
+     * some point"). A promote() of a serial already in `everBound` is therefore a
+     * RE-bind — a self-heal after a mid-session disconnect — and lands the serial
+     * in `reconnectedSerials`, which the readiness gate drains via
+     * takeReconnected() to surface `reconnected: true` on the next command.
+     */
+    private everBound;
+    private reconnectedSerials;
+    /**
+     * @param makeHelper Factory for a HelperProcess, invoked whenever a fresh
+     *   scratch helper is needed (each scan, and each rebind after
+     *   invalidate()). CONTRACT: it MUST return a freshly-started,
+     *   exclusively-owned HelperProcess on every call — DeviceManager may call
+     *   it repeatedly across a session and always expects a clean handle, not
+     *   a shared one. A factory that instead returns the SAME already-started
+     *   helper on every call (as the single-camera `.mjs` scripts under
+     *   scripts/ do, to keep one native session alive for their whole run)
+     *   MUST NOT bind more than one serial through this manager: a second
+     *   scan would hand that same shared helper back and silently steal the
+     *   first bound camera's native session out from under it. No current
+     *   caller does this (all are single-camera); this is latent and not
+     *   guarded in code — the proper fix belongs to multi-camera .mjs/CLI
+     *   wiring, not to DeviceManager itself.
+     */
+    /** True while an arrival re-bind ladder is running (see handleCameraArrived). */
+    private rebinding;
+    /**
+     * Delays before each arrival re-bind attempt, in order — so four attempts
+     * spanning ~4.5s, the first immediate.
+     *
+     * Sized from hardware, 2026-07-21: for many seconds after a USB
+     * re-enumeration the Tiny 2's vendor mailbox is intermittently not-ready
+     * (the reply slot reads back with its magic byte zeroed), and readSerial's
+     * own 8 x 30ms poll is too short to ride it out. Measured 22 failures in 80
+     * attempts across the first 14s after a replug, against 0 in 120 in steady
+     * state — so a single attempt on arrival is roughly a 1-in-4 coin flip, and
+     * losing it silently leaves the camera unbound until the user's next call.
+     * Four spread attempts make a lost re-bind unlikely without retrying forever
+     * at a camera that is simply not answering.
+     */
+    private arrivalBackoffMs;
+    /**
+     * Where a failed or retried arrival re-bind is reported. STDERR by default —
+     * never stdout, which is the JSON-RPC channel.
+     *
+     * Exists because the ladder was silent: a ladder that fired and a clean first
+     * attempt looked identical from outside the process, so the retry could not
+     * be observed on hardware even once it existed. A self-heal that fails
+     * quietly is the failure mode that cost a day of debugging.
+     */
+    private log;
+    constructor(makeHelper: () => Promise<HelperProcess>, opts?: {
+        arrivalBackoffMs?: number[];
+        log?: (msg: string) => void;
+    });
     private createTransport;
+    /**
+     * Close and forget the scratch helper. Closing matters as much as forgetting:
+     * the process is alive and holding whatever it opened, so dropping only the
+     * reference leaks it and leaves the replacement unable to open the camera —
+     * the same mistake pruneDeadEntries() makes if it merely deletes an entry.
+     */
+    private discardScanHelper;
+    /**
+     * Keep one helper alive purely to receive bus events.
+     *
+     * Bus events are delivered per PROCESS (helperFactory subscribes each one it
+     * spawns), and every process that could be listening gets closed: a departure
+     * closes the registry helper, and a failed bind closes the scratch scanner.
+     * Since promote() clears `scanHelper`, the bound steady state is exactly ONE
+     * live helper — the registry's — so handleCameraDeparted() alone drops the
+     * subscriber count to zero. The arrival that follows is then delivered to
+     * nobody and the camera stays unbound until a tool call fails against it.
+     *
+     * PRIMING IS NOT OPTIONAL. A helper that has never enumerated receives
+     * nothing. Measured on hardware (darwin-arm64, Tiny 2, 2026-07-21) across one
+     * same-port replug, three processes, none of which opened the device:
+     *
+     *   enumerated while camera present -> departure YES, arrival YES
+     *   never enumerated                -> departure NO,  arrival NO
+     *   enumerated while camera absent   -> arrival YES
+     *
+     * The silent one stayed alive the whole run and answered a later enumerate
+     * correctly, so that was genuine non-delivery. Its first enumerate took 71ms
+     * against ~1ms for the primed pair — AVFoundation's discovery subsystem
+     * starting up for the first time. Registering the observers
+     * (helper.m:registerCameraNotifications) is NOT what starts delivery;
+     * touching the device list is.
+     *
+     * Windows enforces the same rule for an unrelated reason: helper.cpp drops
+     * any event whose path is missing from `g_knownPaths`, which only enumerate
+     * fills, and that cache is per-process. There the path must have been seen
+     * WHILE THE CAMERA WAS PRESENT — an enumerate during an absence cannot cache
+     * it. macOS has no such constraint: an arm primed during an absence received
+     * the arrival in the same millisecond as one primed while present.
+     *
+     * Both halves are now MEASURED, one platform each, same three-arm experiment:
+     *
+     *            primed-present   never-primed   primed-during-absence
+     *   macOS         yes              NO                 yes
+     *   Windows       yes              NO                 NO
+     *
+     * The Windows run logged its own mechanism rather than inferring it — the
+     * absent-camera enumerate recorded "Tiny 2 in its list = false", so there was
+     * no path to cache and the arrival died at helper.cpp:1022.
+     *
+     * PRIMING REPEATS ON EVERY CALL, and that is Windows insurance specifically.
+     * macOS does NOT need it — measured across two full replug cycles, a watcher
+     * primed once at startup kept delivering (arrived=2, departed=2), identical
+     * to one that re-primed after every departure. The prime is a one-time
+     * activation there, not a lease. On Windows a watcher whose predecessor DIED
+     * during an absence gets replaced while the camera is gone, never caches the
+     * path, and never self-corrects, because the guard below would otherwise
+     * early-return on a watcher that is alive and useless. Hardware-confirmed on
+     * Windows: that scenario ends `available`, never `bound`, with no arrival ever
+     * seen — where the same code on macOS recovers.
+     *
+     * So the repeat only helps at a moment the camera is PRESENT. Re-priming
+     * during an absence is a no-op on Windows; only the next successful bind can
+     * cure a deaf watcher there.
+     *
+     * Costs one idle process once a camera has been bound. It opens nothing, so
+     * it holds no exclusive USB handle and the camera stays available to Zoom,
+     * OBS and OBSBOT Center — the constraint that shaped handleCameraArrived.
+     */
+    private ensureWatcher;
+    private getScanHelper;
+    /**
+     * Compat: raw enumerate() pass-through (unfiltered, no serials). Used by
+     * obsbot_capture_snapshot's virtual/ndi source lookup, not by obsbot_devices
+     * (which reports the identified fleet via listCameras() instead).
+     */
     list(): Promise<DeviceInfo[]>;
+    /**
+     * Scan attached candidates on the scratch helper for a camera to bind.
+     *
+     * - `wantSerial` given: stop at the first candidate whose serial matches;
+     *   throws UnknownCameraError (listing every identifiable serial seen)
+     *   if the scan exhausts without a match.
+     * - `wantSerial` omitted: every candidate must be probed so the full
+     *   fleet is known — a partial scan could under-report ambiguity or
+     *   silently pick the wrong "only" camera. Binds if exactly one distinct
+     *   serial turns up; throws AmbiguousCameraError (all distinct serials)
+     *   if more than one does; throws if none do.
+     */
+    private bind;
+    /** Move the current scratch helper into the registry under `m.serial`. */
+    private promote;
+    /**
+     * Whether the camera identified by `serial` (or, with no arg, the single
+     * bound camera) was RE-bound after a prior bind — i.e. self-healed across a
+     * mid-session disconnect — clearing that flag on read. Single-camera
+     * semantics (no serial): return true if ANY serial is pending-reconnected,
+     * draining them all. Preserves the exact contract the retired
+     * DeviceSession.takeReconnected() had.
+     */
+    takeReconnected(serial?: string): boolean;
+    /**
+     * Drop bound camera(s) from the registry so the next get()/bind() spawns a
+     * fresh scratch helper and re-scans from scratch — the correct move after
+     * a device has re-enumerated (e.g. unplug/replug), since a stale cached
+     * transport talks to a helper that may no longer own a live handle.
+     * Closing each dropped helper is best-effort: a helper whose native
+     * session already died (the common case right after a disconnect) can
+     * throw on close(), and that must not stop the entry from being dropped.
+     *
+     *   serial given -> drop just that camera (no-op if it isn't bound)
+     *   no serial    -> drop every bound camera
+     */
+    invalidate(serial?: string): Promise<void>;
+    /**
+     * Drop registry entries whose helper process has died, so the next resolve
+     * re-binds instead of handing back a transport that can only ever fail.
+     *
+     * "Once bound, stay bound" is the right default, but a bound entry whose
+     * helper is GONE isn't a binding — it's a corpse. Without this, only the
+     * tools that route through ensureReady() (which calls invalidate()) could
+     * recover; every other tool resolved straight through get() and returned the
+     * same dead transport forever. Recovery then required the caller to happen to
+     * invoke a different tool — and the caller here is an LLM, which will instead
+     * retry the failing tool or report broken hardware that is actually fine.
+     *
+     * Deliberately a `dead` check and not a liveness probe: it costs a boolean,
+     * adds no round trip to the hot path, and leaves a LIVE binding untouched (a
+     * guard that re-scanned every call would spawn a helper per tool call).
+     *
+     * A wedged-but-alive helper is intentionally NOT caught here — that is the
+     * per-request timeout's job, and condemning a session for one slow op would
+     * throw away a working binding.
+     */
+    private pruneDeadEntries;
+    /**
+     * Resolve to a bound transport.
+     *   no serial + one camera attached  -> bind & return it
+     *   no serial + several attached     -> AmbiguousCameraError
+     *   serial given + match             -> bind (lazily) & return
+     *   serial given + no match          -> UnknownCameraError
+     * Already-bound cameras are returned directly from the registry without
+     * rescanning — "bind lazily" means once bound, stay bound.
+     */
+    get(serial?: string): Promise<ObsbotTransport>;
+    /**
+     * The OS reported a camera detached. Drop any binding on that path now,
+     * instead of waiting for a tool call to fail against a dead handle.
+     *
+     * Without this the registry stays authoritative until something errors, so
+     * `obsbot_devices` reports a phantom `bound` entry — serial and all — for a
+     * camera physically sitting on the desk. The prune is otherwise reactive:
+     * `deviceLost` is only set when an op fails, and listCameras() deliberately
+     * does not re-open bound entries to check.
+     *
+     * Closes the helper rather than merely forgetting it, for the same reason
+     * pruneDeadEntries() does: a helper left running still holds the device, so
+     * the replacement could never open it.
+     */
+    handleCameraDeparted(e: {
+        path: string;
+    }): Promise<void>;
+    /**
+     * The OS reported a camera attached. Re-establish a binding this process
+     * ALREADY held — a genuine self-heal after a replug — and nothing more.
+     *
+     * Deliberately does not bind a camera we never had. The Tiny 2 is a device
+     * Zoom, OBS and OBSBOT Center also want, and a server that grabbed it the
+     * moment it appeared would make it busy for them even if nobody ever used
+     * this server. `everBound` is the record of what was ours; it survives
+     * invalidate() precisely so a re-bind can be recognised as a reconnect.
+     *
+     * Never throws: the caller is a stdout line handler, and an unhandled
+     * rejection there would take down the reader and wedge every in-flight
+     * request. A failed re-bind just leaves the next tool call to bind normally.
+     */
+    handleCameraArrived(_e: {
+        path: string;
+    }): Promise<void>;
+    /**
+     * Close everything this manager is holding: registry helpers, the scratch
+     * scanner, and the watcher.
+     *
+     * Helpers already self-terminate when the parent goes away — they exit on
+     * stdin EOF — so this is not what stops them leaking on a crash. It exists
+     * because the watcher is the first helper deliberately built to outlive every
+     * operation: nothing else bounds its lifetime, so an orderly stop needs
+     * something explicit to call. Best-effort throughout; a shutdown path that can
+     * itself throw is worse than one that leaves a process for the OS to reap.
+     */
+    shutdown(): Promise<void>;
+    /** Compat shim for the single-camera API B1 retires. */
     openFirstObsbot(): Promise<ObsbotTransport>;
+    /**
+     * Per attached camera: serial (where obtainable), locationId, name, and
+     * status. A camera this process cannot open is reported `busy` WITHOUT a
+     * serial rather than omitted — it is enumerable but not identifiable.
+     * Already-bound cameras are reported from the registry without
+     * re-opening (avoids a pointless self-conflict against our own handle).
+     */
+    listCameras(): Promise<CameraInfo[]>;
 }