obsbot-mcp 0.6.3 → 0.8.0

package/dist/tail2/mdns.js

@@ -0,0 +1,216 @@
+import dgram from "node:dgram";
+import { networkInterfaces } from "node:os";
+const GROUP = "224.0.0.251";
+const MDNS_PORT = 5353;
+const MAC_RE = /^[0-9a-f]{2}(:[0-9a-f]{2}){5}$/;
+const isUsefulHost = (h) => h !== "" && h !== "0.0.0.0" && h !== "255.255.255.255";
+// ---------------------------------------------------------------------------
+// DNS packet parsing — just enough for mDNS response packets: questions are
+// skipped, answer names are decoded (compression pointers included), and TXT
+// records are unpacked into their length-prefixed strings. SRV/A/AAAA are
+// tolerated structurally but only TXT carries the Tail 2 digest.
+// ---------------------------------------------------------------------------
+/** Decode a (possibly compressed) DNS name. Returns the name and the offset
+ *  just past it in the ORIGINAL section — after a compression pointer the
+ *  record's fixed fields continue right after the pointer itself. */
+function readName(buf, off) {
+    const labels = [];
+    let jumped = false;
+    let end = off;
+    let pos = off;
+    let jumps = 0;
+    while (true) {
+        if (pos >= buf.length)
+            return { name: "", end: buf.length };
+        const len = buf[pos];
+        if (len === 0) {
+            if (!jumped)
+                end = pos + 1;
+            break;
+        }
+        if ((len & 0xc0) === 0xc0) {
+            if (pos + 1 >= buf.length)
+                return { name: "", end: buf.length };
+            const ptr = ((len & 0x3f) << 8) | buf[pos + 1];
+            if (!jumped)
+                end = pos + 2;
+            if (++jumps > 32)
+                return { name: "", end: buf.length }; // pointer loop
+            pos = ptr;
+            jumped = true;
+            continue;
+        }
+        if (pos + 1 + len > buf.length)
+            return { name: "", end: buf.length };
+        labels.push(buf.subarray(pos + 1, pos + 1 + len).toString("latin1"));
+        pos += 1 + len;
+    }
+    return { name: labels.join("."), end };
+}
+/** Unpack one packet's TXT strings; other record types are skipped by RDLENGTH. */
+function txtStringsOf(buf) {
+    const strings = [];
+    if (buf.length < 12)
+        return strings;
+    const qd = buf.readUInt16BE(4);
+    const an = buf.readUInt16BE(6);
+    let pos = 12;
+    for (let i = 0; i < qd; i++) {
+        const { end } = readName(buf, pos);
+        pos = end + 4; // QTYPE + QCLASS
+        if (pos > buf.length)
+            return strings;
+    }
+    for (let i = 0; i < an; i++) {
+        const { end } = readName(buf, pos);
+        pos = end;
+        if (pos + 10 > buf.length)
+            return strings;
+        const type = buf.readUInt16BE(pos);
+        const rdLength = buf.readUInt16BE(pos + 8);
+        const rdata = buf.subarray(pos + 10, pos + 10 + rdLength);
+        pos += 10 + rdLength;
+        if (type === 16) {
+            // TXT RDATA: a sequence of <1-byte length><bytes> strings.
+            let p = 0;
+            while (p < rdata.length) {
+                const l = rdata[p];
+                if (p + 1 + l > rdata.length)
+                    break;
+                strings.push(rdata.subarray(p + 1, p + 1 + l).toString("utf8"));
+                p += 1 + l;
+            }
+        }
+    }
+    return strings;
+}
+/**
+ * Extract a Tail 2 announcement from one mDNS packet, or null for anything
+ * else on the wire. Detection is by the digest's own shape — TXT strings that
+ * JSON-parse into an object carrying a `ble_mac` (the registry's identity
+ * MAC) plus a reachable IP — so other devices' mDNS traffic parses to nothing
+ * and registers nothing. `srcIp` is where the packet came from; it becomes a
+ * host of last resort and a live-reachability hint.
+ */
+export function parseTail2Announcement(buf, srcIp) {
+    const merged = {};
+    for (const s of txtStringsOf(buf)) {
+        if (!s.startsWith("{"))
+            continue;
+        try {
+            const v = JSON.parse(s);
+            if (v && typeof v === "object" && !Array.isArray(v)) {
+                Object.assign(merged, v);
+            }
+        }
+        catch {
+            // Someone else's TXT string that merely looks like JSON — ignore.
+        }
+    }
+    const mac = typeof merged.ble_mac === "string" ? merged.ble_mac.toLowerCase() : "";
+    if (!MAC_RE.test(mac))
+        return null;
+    const hosts = [];
+    for (const h of [merged.wired_ip, merged.wireless_ip]) {
+        if (typeof h === "string" && isUsefulHost(h) && !hosts.includes(h))
+            hosts.push(h);
+    }
+    if (srcIp && isUsefulHost(srcIp) && !hosts.includes(srcIp))
+        hosts.push(srcIp);
+    if (hosts.length === 0)
+        return null;
+    let name = mac;
+    if (typeof merged.device_name === "string" && /^[0-9a-f]+$/i.test(merged.device_name)) {
+        const decoded = Buffer.from(merged.device_name, "hex").toString("utf8");
+        if (decoded !== "")
+            name = decoded;
+    }
+    return { mac, name, hosts };
+}
+/** Accumulates announcements across packets, keyed by MAC. Testable without
+ *  sockets: push() buffers, results() the deduplicated list. */
+export function createAnnouncementCollector() {
+    const byMac = new Map();
+    return {
+        push(buf, srcIp) {
+            const a = parseTail2Announcement(buf, srcIp);
+            if (!a)
+                return;
+            const existing = byMac.get(a.mac);
+            if (existing) {
+                for (const h of a.hosts)
+                    if (!existing.hosts.includes(h))
+                        existing.hosts.push(h);
+            }
+            else {
+                byMac.set(a.mac, a);
+            }
+        },
+        results() {
+            return [...byMac.values()];
+        },
+    };
+}
+/**
+ * Listen for Tail 2 announcements for `ms` milliseconds (the camera repeats
+ * every few seconds, so 5s is ample) and return what was heard. Never throws:
+ * a bind failure or a network without multicast yields an empty list, and the
+ * caller falls back to the HTTP sweep.
+ */
+export function listenForTail2Announcements(ms = 5000) {
+    return new Promise((resolve) => {
+        const collector = createAnnouncementCollector();
+        let socket = null;
+        let finished = false;
+        const finish = () => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            if (socket) {
+                socket.removeAllListeners();
+                try {
+                    socket.dropMembership(GROUP);
+                }
+                catch {
+                    // Already gone.
+                }
+                socket.close();
+            }
+            resolve(collector.results());
+        };
+        const timer = setTimeout(finish, ms);
+        try {
+            socket = dgram.createSocket({ type: "udp4", reuseAddr: true });
+            socket.on("message", (buf, rinfo) => {
+                collector.push(buf, rinfo.address);
+            });
+            socket.on("error", finish);
+            socket.bind(MDNS_PORT, () => {
+                const s = socket;
+                try {
+                    s.addMembership(GROUP);
+                }
+                catch {
+                    // Default-interface join failed; explicit per-interface joins below.
+                }
+                for (const addrs of Object.values(networkInterfaces())) {
+                    for (const a of addrs ?? []) {
+                        if (a.family !== "IPv4" || a.internal)
+                            continue;
+                        try {
+                            s.addMembership(GROUP, a.address);
+                        }
+                        catch {
+                            // One unusable interface must not cost the others.
+                        }
+                    }
+                }
+            });
+        }
+        catch {
+            finish();
+        }
+    });
+}
+//# sourceMappingURL=mdns.js.map

package/dist/tail2/mdns.js.map

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

package/dist/tail2/registry.d.ts

@@ -0,0 +1,100 @@
+import { Tail2Api } from "./api.js";
+import { type Tail2Announcement } from "./mdns.js";
+/**
+ * MAC-keyed registry of attached OBSBOT Tail 2 cameras.
+ *
+ * The Tiny 2's DeviceManager discovers cameras over USB and identifies them
+ * by serial; the Tail 2 reports no USB serial number in either of its USB-C
+ * modes (MTP or UVC — TAIL2-PROTOCOL.md §1, §11), so a Tail
+ * 2's identity is its MAC, exactly as OBSBOT Center treats it. Entries are
+ * created by probing a host with the discovery handshake (GET device_info,
+ * then WS hello — this module only needs the first half) and can be added
+ * four ways:
+ *
+ *   - the OBSBOT_TAIL2_HOSTS environment variable (comma-separated hosts),
+ *     for a stable, known network;
+ *   - the obsbot_tail2_scan tool, which listens for the camera's mDNS
+ *     announcements (~5s) and falls back to sweeping the local /24(s);
+ *   - the camera's own periodic mDNS announcement, which names its MAC, its
+ *     name and both its IPs — no probe needed, the camera just said so;
+ *   - resolve()/get() with an explicit host, which registers on first use.
+ *
+ * "Registered" does NOT mean "verified reachable right now" — entries persist
+ * across a camera going offline, and the next operation against its API fails
+ * with the actionable unreachable error rather than a mystery. Re-registration
+ * by MAC is idempotent and merges new candidate hosts into the entry.
+ */
+export interface Tail2Entry {
+    mac: string;
+    name: string;
+    /** Every host this camera has answered on (wired and wireless IPs). */
+    hosts: string[];
+    api: Tail2Api;
+}
+/** Mirrors DeviceManager's contract: same shapes, same caller expectations. */
+export declare class AmbiguousTail2Error extends Error {
+    readonly available: string[];
+    constructor(available: string[]);
+}
+export declare class Tail2Registry {
+    private readonly byMac;
+    private readonly probeTimeoutMs;
+    private readonly makeApi;
+    constructor(opts?: {
+        probeTimeoutMs?: number;
+        makeApi?: (host: string) => Tail2Api;
+    });
+    /**
+     * Seed from `OBSBOT_TAIL2_HOSTS` (comma-separated; blank entries ignored).
+     * The opts passthrough exists for tests; production calls it bare.
+     */
+    static fromEnv(env?: Record<string, string | undefined>, opts?: {
+        probeTimeoutMs?: number;
+        makeApi?: (host: string) => Tail2Api;
+    }): Tail2Registry;
+    /**
+     * Probe one host; register it if it answers as a Tail 2. Returns the entry,
+     * or null when nothing Tail-2-shaped answers there (wrong device, plain
+     * HTTP server, or silence) — a scan probes hundreds of addresses and
+     * "not here" is the normal outcome, not an error.
+     */
+    addHost(host: string): Promise<Tail2Entry | null>;
+    /** Resolve the `camera` selector: MAC, device_name, or host — case-insensitive. */
+    resolve(camera?: string): Promise<Tail2Entry>;
+    list(): Tail2Entry[];
+    /**
+     * Register straight from the camera's own mDNS announcement — no probe.
+     * The digest carries the MAC, the name and both IPs, and the packet arrived
+     * seconds ago, so it is better evidence than a probe that has not run. The
+     * API binds to the wired IP first (the wireless IP is often the camera's
+     * own AP subnet, 192.168.55.x, unroutable from here).
+     */
+    addAnnouncement(a: Tail2Announcement): Tail2Entry;
+    /**
+     * Discovery: listen for the camera's mDNS announcements (its own control
+     * channel — it multicasts a device digest every few seconds), and fall back
+     * to the HTTP subnet sweep only when nothing was heard, for networks where
+     * multicast is filtered. `OBSBOT_TAIL2_MDNS=0` skips the listen.
+     */
+    scan(opts?: {
+        mdnsMs?: number;
+        listen?: (ms: number) => Promise<Tail2Announcement[]>;
+        sweep?: boolean;
+        subnets?: string[];
+        concurrency?: number;
+    }): Promise<Tail2Entry[]>;
+    /**
+     * Sweep every IPv4 /24 this machine belongs to (excluding loopback) for
+     * Tail 2 cameras, registering what answers. The mDNS listen in scan()
+     * covers every network the camera's announcements can reach; this sweep is
+     * the fallback for the rest — an HTTP GET of /camera/sdk/device_info per
+     * candidate address, the same probe OBSBOT Center's discovery uses, so the
+     * traffic pattern is one the camera expects to see. Bounded concurrency
+     * keeps the sweep from socket-bombing the host; per-address timeouts keep
+     * one slow device from stretching the scan.
+     */
+    scanSubnet(opts?: {
+        concurrency?: number;
+        subnets?: string[];
+    }): Promise<Tail2Entry[]>;
+}

package/dist/tail2/registry.js

@@ -0,0 +1,200 @@
+import { networkInterfaces } from "node:os";
+import { Tail2Api } from "./api.js";
+import { listenForTail2Announcements } from "./mdns.js";
+/** Mirrors DeviceManager's contract: same shapes, same caller expectations. */
+export class AmbiguousTail2Error extends Error {
+    available;
+    constructor(available) {
+        super(`multiple Tail 2 cameras registered; specify one of: ${available.join(", ")}`);
+        this.name = "AmbiguousTail2Error";
+        this.available = available;
+    }
+}
+const NO_CAMERA_HINT = `no Tail 2 camera is registered. Add one via the obsbot_tail2_scan tool (sweeps the ` +
+    `local network), or set OBSBOT_TAIL2_HOSTS to its address(es), or pass its host as the ` +
+    `camera parameter on any Tail 2 tool`;
+export class Tail2Registry {
+    byMac = new Map();
+    probeTimeoutMs;
+    makeApi;
+    constructor(opts = {}) {
+        this.probeTimeoutMs = opts.probeTimeoutMs ?? 2500;
+        this.makeApi =
+            opts.makeApi ?? ((host) => new Tail2Api({ baseUrl: host, timeoutMs: this.probeTimeoutMs }));
+    }
+    /**
+     * Seed from `OBSBOT_TAIL2_HOSTS` (comma-separated; blank entries ignored).
+     * The opts passthrough exists for tests; production calls it bare.
+     */
+    static fromEnv(env = process.env, opts = {}) {
+        const reg = new Tail2Registry(opts);
+        const hosts = (env.OBSBOT_TAIL2_HOSTS ?? "")
+            .split(",")
+            .map((h) => h.trim())
+            .filter((h) => h !== "");
+        for (const h of hosts)
+            void reg.addHost(h);
+        // addHost is async; seeding is best-effort and races first use harmlessly
+        // (resolve() re-probes nothing, but a tool call coming in before the probe
+        // finishes simply doesn't see the entry yet and reports "not registered").
+        return reg;
+    }
+    /**
+     * Probe one host; register it if it answers as a Tail 2. Returns the entry,
+     * or null when nothing Tail-2-shaped answers there (wrong device, plain
+     * HTTP server, or silence) — a scan probes hundreds of addresses and
+     * "not here" is the normal outcome, not an error.
+     */
+    async addHost(host) {
+        const api = this.makeApi(host);
+        let info;
+        try {
+            info = await api.info();
+        }
+        catch {
+            return null;
+        }
+        if (typeof info.mac !== "string" || info.mac === "" || !info.device_name)
+            return null;
+        const mac = info.mac.toLowerCase();
+        const existing = this.byMac.get(mac);
+        if (existing) {
+            // Same camera reachable at another address (wired + wireless): keep both.
+            if (!existing.hosts.includes(host))
+                existing.hosts.push(host);
+            return existing;
+        }
+        const entry = { mac, name: info.device_name, hosts: [host], api };
+        this.byMac.set(mac, entry);
+        return entry;
+    }
+    /** Resolve the `camera` selector: MAC, device_name, or host — case-insensitive. */
+    async resolve(camera) {
+        if (camera === undefined || camera === "") {
+            const all = [...this.byMac.values()];
+            if (all.length === 1)
+                return all[0];
+            if (all.length > 1)
+                throw new AmbiguousTail2Error(all.map((e) => e.mac));
+            throw new Error(NO_CAMERA_HINT);
+        }
+        const want = camera.toLowerCase();
+        for (const e of this.byMac.values()) {
+            if (e.mac === want || e.name.toLowerCase() === want)
+                return e;
+            if (e.hosts.some((h) => h.toLowerCase() === want))
+                return e;
+        }
+        // Not registered — but if the selector IS a reachable host, register it.
+        // This makes "camera: 192.168.0.132" work on a cold server with no env
+        // config and no scan, which is the fastest path from install to control.
+        const byHost = await this.addHost(camera);
+        if (byHost)
+            return byHost;
+        const available = [...this.byMac.values()].map((e) => e.mac);
+        throw new Error(`unknown Tail 2 camera "${camera}"; available: ` +
+            (available.length ? available.join(", ") : "(none registered — run obsbot_tail2_scan)") +
+            `. If "${camera}" is a host, nothing Tail 2 answered there.`);
+    }
+    list() {
+        return [...this.byMac.values()];
+    }
+    /**
+     * Register straight from the camera's own mDNS announcement — no probe.
+     * The digest carries the MAC, the name and both IPs, and the packet arrived
+     * seconds ago, so it is better evidence than a probe that has not run. The
+     * API binds to the wired IP first (the wireless IP is often the camera's
+     * own AP subnet, 192.168.55.x, unroutable from here).
+     */
+    addAnnouncement(a) {
+        const mac = a.mac.toLowerCase();
+        const existing = this.byMac.get(mac);
+        if (existing) {
+            for (const h of a.hosts)
+                if (!existing.hosts.includes(h))
+                    existing.hosts.push(h);
+            return existing;
+        }
+        const entry = {
+            mac,
+            name: a.name,
+            hosts: [...a.hosts],
+            api: this.makeApi(a.hosts[0] ?? mac),
+        };
+        this.byMac.set(mac, entry);
+        return entry;
+    }
+    /**
+     * Discovery: listen for the camera's mDNS announcements (its own control
+     * channel — it multicasts a device digest every few seconds), and fall back
+     * to the HTTP subnet sweep only when nothing was heard, for networks where
+     * multicast is filtered. `OBSBOT_TAIL2_MDNS=0` skips the listen.
+     */
+    async scan(opts = {}) {
+        let heard = [];
+        // An injected listener (tests) always runs; the env kill-switch governs
+        // only the default one.
+        const listen = opts.listen ?? (process.env.OBSBOT_TAIL2_MDNS === "0" ? null : listenForTail2Announcements);
+        if (listen) {
+            try {
+                heard = await listen(opts.mdnsMs ?? 5000);
+            }
+            catch {
+                heard = []; // listening is best-effort; the sweep still covers it
+            }
+        }
+        const found = new Map();
+        for (const a of heard) {
+            const e = this.addAnnouncement(a);
+            found.set(e.mac, e);
+        }
+        if (heard.length > 0 || opts.sweep === false)
+            return [...found.values()];
+        const swept = await this.scanSubnet({ subnets: opts.subnets, concurrency: opts.concurrency });
+        for (const e of swept)
+            found.set(e.mac, e);
+        return [...found.values()];
+    }
+    /**
+     * Sweep every IPv4 /24 this machine belongs to (excluding loopback) for
+     * Tail 2 cameras, registering what answers. The mDNS listen in scan()
+     * covers every network the camera's announcements can reach; this sweep is
+     * the fallback for the rest — an HTTP GET of /camera/sdk/device_info per
+     * candidate address, the same probe OBSBOT Center's discovery uses, so the
+     * traffic pattern is one the camera expects to see. Bounded concurrency
+     * keeps the sweep from socket-bombing the host; per-address timeouts keep
+     * one slow device from stretching the scan.
+     */
+    async scanSubnet(opts = {}) {
+        const concurrency = opts.concurrency ?? 32;
+        // Overridable for tests (and for pinning a scan to one network when this
+        // machine straddles several); default is every non-internal IPv4 /24.
+        const subnets = new Set(opts.subnets ?? []);
+        if (subnets.size === 0) {
+            for (const addrs of Object.values(networkInterfaces())) {
+                for (const a of addrs ?? []) {
+                    if (a.family !== "IPv4" || a.internal)
+                        continue;
+                    subnets.add(a.address.split(".").slice(0, 3).join("."));
+                }
+            }
+        }
+        const candidates = [];
+        for (const s of subnets) {
+            for (let i = 1; i <= 254; i++)
+                candidates.push(`${s}.${i}`);
+        }
+        // addHost returns the entry for every host that ANSWERED as a Tail 2 —
+        // including already-registered cameras — so the result is "reachable on
+        // this sweep", not "new since last time".
+        const found = new Map();
+        for (let i = 0; i < candidates.length; i += concurrency) {
+            const results = await Promise.all(candidates.slice(i, i + concurrency).map((h) => this.addHost(h)));
+            for (const e of results)
+                if (e)
+                    found.set(e.mac, e);
+        }
+        return [...found.values()];
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tail2/registry.js.map

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

package/dist/tail2/snapshot.d.ts

@@ -0,0 +1,54 @@
+import { spawn } from "node:child_process";
+/**
+ * Pull one still frame from a Tail 2's video output with ffmpeg.
+ *
+ * Primary source: the camera's SRT listener (the one streaming output this
+ * firmware actually serves; TAIL2-PROTOCOL.md §9) — requires Center's SRT
+ * toggle, exclusive with NDI. Because that toggle is a human-in-the-GUI step
+ * and this server is driven by AI agents that should stay autonomous, the
+ * fallback layer grabs from the NDI Tools "NDI Webcam" DirectShow device
+ * instead (Windows only): if the bridge is running and pointed at the
+ * camera's NDI feed, ffmpeg can read it directly and no Center trip is
+ * needed. When neither source is live, `snapshotOptions()` reports what it
+ * found and what each path costs, so the calling agent can pick.
+ *
+ * Note Center only allows changing streaming settings while the output is
+ * OFF, so probes landing in a configuration window see a dead port — not a
+ * startup delay (an earlier "minutes to bind" claim here was wrong and is
+ * retracted).
+ */
+export interface SrtSnapshotOpts {
+    maxDim?: number;
+    quality?: number;
+    port?: number;
+    streamId?: string;
+    /** Socket I/O budget for ffmpeg, ms. Generous: SRT handshake + first keyframe. */
+    timeoutMs?: number;
+}
+export interface SrtSnapshot {
+    mime: string;
+    width: number;
+    height: number;
+    base64: string;
+}
+export declare class SrtNotEnabledError extends Error {
+    constructor();
+}
+export declare function srtSnapshot(host: string, opts?: SrtSnapshotOpts, spawnImpl?: typeof spawn): Promise<SrtSnapshot>;
+/**
+ * Grab a frame from the NDI Tools "NDI Webcam" DirectShow device (Windows
+ * only). NOT used by the snapshot tool automatically: on the reference
+ * machine (2026-09-26) the bridge's user-configured output slots delivered
+ * uniformly black frames to ffmpeg (YAVG=YMAX=16) while other slots hung,
+ * and probing the devices disrupts the app. Kept for manual/verified use —
+ * if a slot is confirmed live (e.g. previews correctly in OBS), this works.
+ * Never force-kill the Webcam app: that corrupts its output-slot config.
+ */
+export declare function ndiWebcamSnapshot(opts?: {
+    maxDim?: number;
+    quality?: number;
+    timeoutMs?: number;
+}, spawnImpl?: typeof spawn): Promise<SrtSnapshot | null>;
+/** Standard NDI Tools install location, for the options report. */
+export declare const NDI_WEBCAM_EXE = "C:\\Program Files\\NDI\\NDI 6 Tools\\Webcam\\Webcam.exe";
+export declare const ndiToolsInstalled: () => boolean;