obsbot-mcp 0.4.1 → 0.6.0

package/dist/mcp/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { encodeSetRunStatus, zoomRatioToUnits, encodeAiTrackSpeed, encodeAiTracking, encodeAiMode, encodeFaceAe, encodeVendorProbe, encodeVendorGet, encodeZoomWithSpeed, encodeFaceFocus, encodeSetExposure, decodeStatus, encodeFov, encodeHdr, percentToRange, AI_FRAMING_MODES, AI_SCENE_MODES, AI_TRACK_SPEEDS, FOV_TYPES, UVC_XU_SELECTOR, CAMERA_CONTROL_PAN, CAMERA_CONTROL_TILT, CAMERA_CONTROL_FOCUS, VIDEO_PROCAMP_WHITE_BALANCE, IMAGE_CONTROL_PROP, IMAGE_CONTROLS, UVC_FLAG_AUTO, UVC_FLAG_MANUAL, } from "../codec/commands.js";
+import { encodeSetRunStatus, zoomRatioToUnits, encodeAiTrackSpeed, encodeAiTracking, encodeAiMode, encodeFaceAe, encodeVendorProbe, encodeVendorGet, encodeZoomWithSpeed, encodeFaceFocus, encodeSetExposure, decodeStatus, encodeFov, encodeHdr, percentToRange, rangeToPercent, AI_FRAMING_MODES, AI_SCENE_MODES, AI_TRACK_SPEEDS, FOV_TYPES, UVC_XU_SELECTOR, CAMERA_CONTROL_PAN, CAMERA_CONTROL_TILT, CAMERA_CONTROL_FOCUS, VIDEO_PROCAMP_WHITE_BALANCE, IMAGE_CONTROL_PROP, IMAGE_CONTROLS, UVC_FLAG_AUTO, UVC_FLAG_MANUAL, } from "../codec/commands.js";
+import { aimAtPixel, GIMBAL_YAW_LIMIT_DEG, GIMBAL_PITCH_LIMIT_DEG, FOV_MAGNIFICATION, magnificationFromZoomRatio, zoomRatioFromMagnification, MIN_MAGNIFICATION, MAX_MAGNIFICATION, } from "../geometry/aim.js";
 import { verifyFraming } from "./framing.js";
 import { parseFrame } from "../codec/frame.js";
 import { OP_BY_NAME } from "../codec/opcodes.js";
@@ -8,6 +9,61 @@ import { CameraBusyError } from "../transport/transport.js";
 import { ensureReady, msg } from "./ready.js";
 import { CaptureError } from "../capture/manager.js";
 const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+ * The camera's total magnification relative to wide, from its reported state.
+ *
+ * A discrete FOV mode and a continuous zoom are two ways of writing to one
+ * scale, so this returns one number either way. Fails (`ok: false`) for
+ * anything that cannot be trusted:
+ *  - `reason: "unknown-fov"` — the status byte didn't decode, a state to
+ *    refuse on rather than guess at.
+ *  - `reason: "implausible-zoom"` — a `"custom"` mode whose derived
+ *    magnification falls outside the camera's known range
+ *    [MIN_MAGNIFICATION, MAX_MAGNIFICATION] — a corrupt or implausible
+ *    `zoomPercent` reading (e.g. a garbled status byte reporting
+ *    zoomPercent > 100). Callers should refuse rather than pass this through:
+ *    the geometry module's own guard (halfAngleTangents in src/geometry/aim.ts)
+ *    would otherwise be the only thing standing between a bad reading and a
+ *    silently wrong — or NaN/Infinity — aim.
+ */
+export function resolveMagnification(status) {
+    if (status.fovMode === "unknown")
+        return { ok: false, reason: "unknown-fov" };
+    if (status.fovMode === "custom") {
+        const m = magnificationFromZoomRatio(1 + status.zoomPercent / 100);
+        if (!Number.isFinite(m) || m < MIN_MAGNIFICATION || m > MAX_MAGNIFICATION) {
+            return { ok: false, reason: "implausible-zoom", zoomPercent: status.zoomPercent };
+        }
+        return { ok: true, magnification: m };
+    }
+    return { ok: true, magnification: FOV_MAGNIFICATION[status.fovMode] };
+}
+/**
+ * Refuse a frameWidth/frameHeight pair that isn't 16:9. Shared by
+ * `obsbot_aim_at_pixel` and `obsbot_zoom_to_fit` — both take frame dimensions
+ * from the same `obsbot_capture_snapshot` result, and both are equally exposed
+ * to a caller that swaps width and height.
+ *
+ * 16:9 is preserved by the capture path at every resolution (verified at
+ * 256x144, 1280x720, 1920x1080), so a non-16:9 pair did not come from that path
+ * as-is — it was transposed (width/height swapped) or came from somewhere else
+ * entirely, since passing the values through unchanged always yields 16:9. For
+ * `obsbot_zoom_to_fit` a transposed pair is worse than a bad aim: it also flips
+ * which axis `Math.min(frameWidth/width, frameHeight/height)` selects, so the
+ * camera would frame the wrong region at the wrong zoom while still reporting
+ * `ok: true`.
+ */
+function refuseIfNot169(frameWidth, frameHeight) {
+    if (Math.abs(frameWidth / frameHeight - 16 / 9) > 0.02) {
+        return {
+            ok: false,
+            error: `frame ${frameWidth}x${frameHeight} is not 16:9, but obsbot_capture_snapshot always ` +
+                `returns 16:9 frames. This looks like frameWidth/frameHeight were transposed, or came ` +
+                `from something other than that tool's result.`,
+        };
+    }
+    return null;
+}
 // Some MCP clients serialize numbers and booleans as strings when the advertised
 // inputSchema lacks type info. We now advertise a proper JSON Schema (see
 // mcp/server.ts), but also accept string-encoded values defensively so the tools
@@ -113,6 +169,33 @@ const imageExposureManualSchema = withCamera({
     level: num().pipe(z.number().min(0).max(100)).default(50),
 });
 const gimbalPositionSchema = withCamera({});
+const captureSourceEnum = z.enum(["device", "virtual", "ndi"]);
+// `source` is a DECLARATION, not a selector: these tools never fetch a frame, they
+// are handed one. It exists because the frame's origin is otherwise unknowable —
+// see frameSourceNote — and it defaults to `device`, which is what every caller
+// got implicitly before.
+const aimAtPixelSchema = withCamera({
+    x: num().pipe(z.number().finite()),
+    y: num().pipe(z.number().finite()),
+    frameWidth: num().pipe(z.number().finite().min(1)),
+    frameHeight: num().pipe(z.number().finite().min(1)),
+    source: captureSourceEnum.default("device"),
+});
+// width/height/x/y are deliberately unconstrained beyond "finite": a negative
+// width or an off-frame region is a valid INPUT (the schema's job), just not a
+// valid REGION (the handler's job, so it can return a structured ok:false with
+// the reason instead of a schema parse throw — matching how aimAtPixelSchema's
+// own x/y-in-frame check works one level up, in the handler, not the schema).
+const zoomToFitSchema = withCamera({
+    x: num().pipe(z.number().finite()),
+    y: num().pipe(z.number().finite()),
+    width: num().pipe(z.number().finite()),
+    height: num().pipe(z.number().finite()),
+    frameWidth: num().pipe(z.number().finite().min(1)),
+    frameHeight: num().pipe(z.number().finite().min(1)),
+    margin: num().pipe(z.number().finite().min(0)).default(0.1),
+    source: captureSourceEnum.default("device"),
+});
 const presetListSchema = withCamera({});
 const presetSaveSchema = withCamera({
     slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
@@ -149,10 +232,15 @@ const PRESET_NAME_MAX = 40;
 const snapshotSchema = withCamera({
     resolution: num().pipe(z.number().min(256).max(1920)).default(640),
     quality: num().pipe(z.number().min(1).max(100)).default(80),
-    settleMs: num().pipe(z.number().min(0).max(5000)).default(600),
+    // Ceiling raised from 5000 on 2026-07-25. A source that connects lazily needs
+    // longer than a UVC camera does to hand over its first frame — NDI Webcam Input
+    // measured 4-5s — and 5000 sat right on that threshold, so the one value that
+    // worked was also the largest the schema allowed. The helper now budgets its
+    // own grace period on top of this, so callers rarely need to raise it at all;
+    // the headroom is for the genuinely slow case rather than the normal one.
+    settleMs: num().pipe(z.number().min(0).max(15000)).default(600),
     source: z.enum(["device", "virtual", "ndi"]).default("device"),
 });
-const captureSourceEnum = z.enum(["device", "virtual", "ndi"]);
 const recordStartSchema = z.object({
     durationSec: num().pipe(z.number().positive()).optional(),
     audio: bool().default(true),
@@ -261,6 +349,147 @@ async function getPresetSlots(t) {
 // window. Latency is the cheapest thing we can spend here.
 const PRESET_READ_DEFAULTS = { attempts: 3, backoffMs: [200, 500, 1000] };
 const napMs = (ms) => new Promise((r) => setTimeout(r, ms));
+// Pan/tilt readback is a float now (see transport/linux.ts, transport/macos.ts),
+// which can carry many more digits than the hardware's ±1° accuracy justifies —
+// e.g. 5.975277777777778 from an arc-second division. Round to 2 decimal places
+// for reporting: enough to show sub-degree structure (useful on Linux, where it
+// reflects the last commanded pose) without implying precision the readout
+// doesn't have.
+const round2 = (deg) => Math.round(deg * 100) / 100;
+// motionPollMs is the sensitivity knob for readSteadyStatus: zoomPercent is an
+// integer, so a beat of B ms detects any ramp travelling faster than 1000/B
+// percentage points per second. 80ms => 12.5 pt/s, against a measured UVC ramp of
+// ~42 pt/s (2026-07-25: a full ratio 1->2 sweep took 2397ms) — comfortable margin,
+// while costing every aim only one extra status read and 80ms.
+const ZOOM_SETTLE_DEFAULTS = {
+    pollMs: 100,
+    timeoutMs: 3000,
+    motionPollMs: 80,
+};
+// zoomPercent tracks the zoom's actual travel, not the commanded value, which is
+// what makes it a usable arrival signal — a status read taken right after
+// commanding the write can catch it mid-ramp (observed: commanding ratio 1.5
+// read back zoomPercent 33 in transit before settling at 50). zoomPercent is on
+// the SAME 0-100 scale resolveMagnification reads it on (ratio = 1 + pct/100),
+// so the target is expressed on that scale too, not the raw device units
+// zoomSet takes (those come from zoomRange(), which can differ per device).
+const ZOOM_SETTLE_TOLERANCE_PCT = 1;
+/**
+ * Poll the status block until `zoomPercent` shows the zoom has actually arrived
+ * at `targetRatio`, or give up after the bound. Returns false rather than
+ * throwing on timeout: a camera moving slower than expected (or a hardware zoom
+ * that overshoots/undershoots slightly) is information the caller needs, not a
+ * failure — the caller decides what to do with `settled:false`, this function
+ * just refuses to lie about it.
+ *
+ * A transient read failure inside the loop is swallowed the same way: by the
+ * time this runs, the gimbal move and the zoom write have already happened, so
+ * throwing here would lose the `target`/`ratio` the caller needs to know what
+ * the camera just did. A read that throws is treated as "not settled yet" —
+ * the loop keeps polling until the deadline and resolves `false` rather than
+ * rejecting, so the tool still returns its normal result.
+ */
+async function waitForZoomSettle(t, targetRatio, opts = {}) {
+    const { pollMs, timeoutMs } = { ...ZOOM_SETTLE_DEFAULTS, ...opts };
+    const targetPct = (targetRatio - 1) * 100;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            const status = decodeStatus(await t.recvStatus());
+            if (Math.abs(status.zoomPercent - targetPct) <= ZOOM_SETTLE_TOLERANCE_PCT)
+                return true;
+        }
+        catch {
+            // Transient read failure — treat as not-yet-settled rather than propagating.
+        }
+        if (Date.now() >= deadline)
+            return false;
+        await napMs(pollMs);
+    }
+}
+async function readSteadyStatus(t, opts = {}) {
+    const { motionPollMs } = { ...ZOOM_SETTLE_DEFAULTS, ...opts };
+    const firstPct = decodeStatus(await t.recvStatus()).zoomPercent;
+    await napMs(motionPollMs);
+    // The SECOND read is the one handed back: it is the fresher of the two, and by
+    // the time it is returned it has been confirmed equal to the first anyway.
+    const block = await t.recvStatus();
+    const status = decodeStatus(block);
+    if (status.zoomPercent !== firstPct) {
+        return { ok: false, fromPct: firstPct, toPct: status.zoomPercent };
+    }
+    return { ok: true, block, status };
+}
+/** The refusal both aiming tools give when {@link readSteadyStatus} sees travel. */
+const zoomMovingError = (r, verb) => `the zoom is still moving (zoomPercent read ${r.fromPct} then ${r.toPct}), so the frame you ` +
+    `measured was captured at a magnification the camera has already left — ${verb} from it would ` +
+    `be wrong in proportion. Wait for the zoom to finish, take a fresh snapshot, and try again.`;
+/**
+ * Read the focus control for {@link obsbot_status}.
+ *
+ * Focus is a standard UVC control, not a field of the 60-byte vendor status
+ * block, so reporting it costs two extra reads. Worth it: obsbot_focus_auto and
+ * obsbot_focus_manual were write-only, and answering "is it still in autofocus?"
+ * previously meant going underneath the tool surface to the helper's camctrl_get
+ * by hand.
+ *
+ * NEVER THROWS. The status block is what this tool is for, and focus is an
+ * addition to it — trading awake/aiMode/zoomPercent for a failed focus query
+ * would be a bad deal on any device or platform that cannot answer it. A failure
+ * reports mode "unknown" and omits the position, which is also what an
+ * unrecognised flags value gets: the same refuse-to-guess rule the FOV and
+ * AI-mode decodes already follow.
+ *
+ * focusPosition is reported ONLY in manual mode, where it is the setpoint and
+ * round-trips exactly (write 25, read 25). Under autofocus the device does not
+ * expose the motor: MEASURED 2026-07-25, the value stayed pinned at the last
+ * written position across a 40-degree pan, a zoom from 3.34x to 1x, and 9s of
+ * settling — a scene change that must have re-focused the lens. It is the same
+ * setpoint-echo this camera does for pan/tilt. Reporting that number under
+ * autofocus would look like a live focus distance while being a stale write, so
+ * the field is omitted instead and the caller can tell the difference.
+ *
+ * In manual mode the position is normalised onto the same 0-100 scale
+ * obsbot_focus_manual accepts, so the control reads back in the units it was
+ * written in.
+ */
+async function readFocus(t) {
+    try {
+        const { value, flags } = await t.camCtrlGet(CAMERA_CONTROL_FOCUS);
+        const focusMode = flags === UVC_FLAG_AUTO ? "auto" : flags === UVC_FLAG_MANUAL ? "manual" : "unknown";
+        if (focusMode !== "manual")
+            return { focusMode };
+        const { min, max } = await t.camCtrlRange(CAMERA_CONTROL_FOCUS);
+        return { focusMode, focusPosition: rangeToPercent(value, min, max) };
+    }
+    catch {
+        return { focusMode: "unknown" };
+    }
+}
+/**
+ * What a non-device frame declaration commits the caller to.
+ *
+ * obsbot_aim_at_pixel and obsbot_zoom_to_fit compute an angle from the CAMERA's
+ * own field of view and magnification, but they only ever receive pixels — there
+ * is nothing in x/y/frameWidth/frameHeight from which the frame's origin could be
+ * inferred. A frame that OBSBOT Center or OBS has rescaled, cropped or letterboxed
+ * therefore yields a confidently wrong aim, reported as a clean success.
+ *
+ * A blanket refusal would be wrong: a feed configured as a true pass-through aims
+ * correctly. MEASURED 2026-07-25 against an OBS -> NDI chain, a dedicated
+ * (uncomposited) output at 1080p30 matched the camera's own frame to fill 1.0000
+ * and scale 1.03 +/- 0.03, and obsbot_zoom_to_fit framed a target through it
+ * correctly. The SAME chain via OBS's canvas measured 0.900 scale with a 96px
+ * offset -- wrong by 11% plus a fixed bias -- and looked identical in the reply.
+ *
+ * So the caller declares the feed and this states the assumption back, where it
+ * lands in the transcript rather than in a README nobody re-reads mid-task.
+ */
+const frameSourceNote = (source) => `this aim was computed from a '${source}' frame, and is only correct if that feed is an ` +
+    `unmodified pass-through of the camera (no rescale, crop, letterbox or reframing) at the same ` +
+    `field of view — 1080p60 is a 1.214x crop of 1080p30 on this camera, and a compositor's canvas ` +
+    `scaling is invisible in the picture. Verify once by commanding a known gimbal rotation and ` +
+    `checking features move by the predicted number of pixels; a 'device' frame needs no such check.`;
 const allEmpty = (slots) => slots.every((s) => !s.occupied);
 /**
  * Read the preset slots with bounded retry, and confirm the one verdict whose error
@@ -302,7 +531,7 @@ async function readPresetSlots(t, gate, opts = {}) {
     }
     throw lastErr;
 }
-export function createTools(mgr, capture, debug = false, presetRead = {}) {
+export function createTools(mgr, capture, debug = false, presetRead = {}, zoomSettle = {}) {
     // Per-camera resolution derived from the manager. Every camera-addressing tool
     // takes an optional `camera` selector (the serial); it threads through here so
     // the transport, reconnect controller and readiness gate all target that one
@@ -375,13 +604,15 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
         {
             name: "obsbot_gimbal_move",
             description: "Move the gimbal to an absolute yaw/pitch angle (degrees); positive yaw pans to the " +
-                "camera's left, positive pitch tilts down. Yaw is clamped to [-150,150], pitch to " +
-                "[-90,90]. Absolute positioning (1:1 degrees), verified on hardware.",
+                `camera's left, positive pitch tilts down. Yaw is clamped to ` +
+                `[-${GIMBAL_YAW_LIMIT_DEG},${GIMBAL_YAW_LIMIT_DEG}], pitch to ` +
+                `[-${GIMBAL_PITCH_LIMIT_DEG},${GIMBAL_PITCH_LIMIT_DEG}]. ` +
+                "Absolute positioning (1:1 degrees), verified on hardware.",
             schema: ptzMoveAngleSchema,
             handler: async (args) => {
                 const parsed = ptzMoveAngleSchema.parse(args);
-                const yaw = clamp(parsed.yaw, -150, 150);
-                const pitch = clamp(parsed.pitch, -90, 90);
+                const yaw = clamp(parsed.yaw, -GIMBAL_YAW_LIMIT_DEG, GIMBAL_YAW_LIMIT_DEG);
+                const pitch = clamp(parsed.pitch, -GIMBAL_PITCH_LIMIT_DEG, GIMBAL_PITCH_LIMIT_DEG);
                 const roll = parsed.roll;
                 const ready = await gate(parsed.camera);
                 if (!ready.ok)
@@ -451,7 +682,11 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
             name: "obsbot_zoom_uvc",
             description: "Standard UVC zoom: set an absolute zoom ratio, clamped to [1.0, 2.0]. Snaps to the " +
                 "requested target exactly (unlike obsbot_zoom_vendor, whose ratio scale differs and " +
-                "may not land exactly where asked).",
+                "may not land exactly where asked). Waits for the zoom to actually arrive and returns " +
+                "{ settled }: the ramp is not instant (a full 1.0->2.0 sweep takes about 2.4s), and " +
+                "obsbot_aim_at_pixel and obsbot_zoom_to_fit both refuse while it is in flight, so this " +
+                "returning early would just move the failure downstream. settled:false means the zoom " +
+                "had not arrived within the timeout — the command was still sent.",
             schema: zoomAbsoluteSchema,
             handler: async (args) => {
                 const parsed = zoomAbsoluteSchema.parse(args);
@@ -459,7 +694,14 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
                 const t = await getTransport(parsed.camera);
                 const { min, max } = await t.zoomRange();
                 await t.zoomSet(zoomRatioToUnits(ratio, min, max));
-                return { ok: true, ratio };
+                // Deliberately NOT done for obsbot_zoom_vendor. waitForZoomSettle needs the
+                // target on the zoomPercent scale, and that tool's ratio scale is a different
+                // one that "may not land exactly where asked" — so it would report
+                // settled:false on a perfectly good zoom. The alternative signal, "zoomPercent
+                // stopped changing", reads as stopped during the ~140ms before the ramp starts
+                // moving, which would be a worse lie than saying nothing.
+                const settled = await waitForZoomSettle(t, ratio, zoomSettle);
+                return { ok: true, ratio, settled };
             },
         },
         {
@@ -545,10 +787,19 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
         },
         {
             name: "obsbot_status",
-            description: "Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed }: " +
+            description: "Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed, " +
+                "fovMode, zoomPercent, focusMode, focusPosition }: " +
                 "faceAe is whether auto-exposure is metering for a detected face; " +
                 "aiMode is the current AI framing (no-tracking|normal|upper-body|close-up|headless|" +
-                "lower-body|desk|whiteboard|hand|group|unknown); trackSpeed is standard|sport|unknown. " +
+                "lower-body|desk|whiteboard|hand|group|unknown); trackSpeed is standard|sport|unknown; " +
+                "fovMode is the field-of-view mode (wide|medium|narrow|custom|unknown), where custom means " +
+                "a continuous zoom overrode the discrete modes; zoomPercent is the zoom position, 0-100; " +
+                "focusMode is auto|manual|unknown. focusPosition is present ONLY in manual mode, on the " +
+                "same 0-100 scale obsbot_focus_manual takes: under autofocus this camera does not expose " +
+                "the motor, it echoes the last written value, so reporting it would look like a live " +
+                "focus distance while being stale. Focus is a standard UVC control rather than a field " +
+                "of the status block, so it costs an extra read; a device that cannot answer it reports " +
+                "focusMode unknown rather than failing the whole read. " +
                 "Under --debug the result also carries `raw`: the full 60-byte status block as hex " +
                 "(for reverse-engineering undecoded offsets).",
             schema: getStatusSchema,
@@ -557,7 +808,12 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
                 const t = await getTransport(camera);
                 try {
                     const block = await t.recvStatus();
-                    return { ok: true, ...decodeStatus(block), ...(debug ? { raw: block.toString("hex") } : {}) };
+                    return {
+                        ok: true,
+                        ...decodeStatus(block),
+                        ...(await readFocus(t)),
+                        ...(debug ? { raw: block.toString("hex") } : {}),
+                    };
                 }
                 catch (e) {
                     return { ok: false, error: `could not read camera status: ${e.message}` };
@@ -696,7 +952,8 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
             name: "obsbot_gimbal_position",
             description: "Read the gimbal's current absolute yaw/pitch in degrees (positive yaw = camera's " +
                 "left, positive pitch = down) via the standard UVC Pan/Tilt controls. This is a live " +
-                "hardware readout accurate to ±1°: it is valid during a move as well as after one, " +
+                "hardware readout accurate to ±1°, reported rounded to 2 decimal places (finer digits " +
+                "would be noise, not precision): it is valid during a move as well as after one, " +
                 "and reflects motion the host did not command (speed moves, recenter, tracking).",
             schema: gimbalPositionSchema,
             handler: async (args) => {
@@ -706,7 +963,288 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
                 const tilt = await t.camCtrlGet(CAMERA_CONTROL_TILT);
                 // UVC pan value is degrees, same sign as our yaw (+ = camera-left). UVC tilt
                 // is degrees but positive = up, so negate to match our +pitch = down convention.
-                return { yaw: pan.value, pitch: -tilt.value };
+                return { yaw: round2(pan.value), pitch: round2(-tilt.value) };
+            },
+        },
+        {
+            name: "obsbot_aim_at_pixel",
+            description: "Point the camera at a specific pixel in a frame you just captured. Give the pixel's x/y " +
+                "and the frameWidth/frameHeight from THE SAME obsbot_capture_snapshot result — mixing a " +
+                "pixel from one frame with dimensions from another aims at the wrong place and cannot be " +
+                "detected. `source` DECLARES which feed the frame came from (default device); it cannot be " +
+                "inferred from the pixels. A virtual or ndi frame is accepted, but only aims correctly if " +
+                "that feed is an unmodified pass-through of the camera — a compositor's rescale or " +
+                "letterbox is invisible in the picture and silently wrong here — so a non-device " +
+                "declaration comes back with that assumption stated. Takes no " +
+                "field-of-view or zoom argument: it reads the camera's magnification from its reported " +
+                "state, a discrete FOV mode or a continuous zoom alike, so it works at any zoom. Refuses " +
+                "when AI tracking is active (tracking moves the gimbal itself and would fight the aim), " +
+                "when the FOV mode can't be decoded, or when a corrupt zoom reading would resolve to an " +
+                "implausible magnification, so it never aims on an assumption it cannot check. If the " +
+                "camera was asleep, waking it moves the gimbal and invalidates the " +
+                "frame you measured, so the call refuses instead of aiming on stale geometry — take a fresh " +
+                "snapshot and retry. Returns clamped:true if the target was outside the gimbal's range; the " +
+                "camera still moves, to the nearest reachable pose. Refuses (ok:false) instead of moving when " +
+                "the pixel lies past vertical from the current pose — reachable only by an \"over the top\" " +
+                "rotation that would swing the camera toward the opposite side of the room, not toward the " +
+                "target; tilt toward the pixel first, then re-aim.",
+            schema: aimAtPixelSchema,
+            handler: async (args) => {
+                const { x, y, frameWidth, frameHeight, camera, source } = aimAtPixelSchema.parse(args);
+                const aspectRefusal = refuseIfNot169(frameWidth, frameHeight);
+                if (aspectRefusal)
+                    return aspectRefusal;
+                if (x < 0 || x > frameWidth || y < 0 || y > frameHeight) {
+                    return { ok: false, error: `pixel (${x},${y}) is outside the ${frameWidth}x${frameHeight} frame` };
+                }
+                // The gate wakes a sleeping camera and waits for it to settle. If it had
+                // to wake the camera, the gimbal just moved out from under the frame the
+                // caller measured — refuse below rather than read a pose that no longer
+                // corresponds to that frame.
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                if (ready.woke) {
+                    return {
+                        ok: false,
+                        error: "the camera was asleep and waking it moved the gimbal, so the frame you measured no " +
+                            "longer matches where the camera is pointing. Take a fresh snapshot and aim again.",
+                    };
+                }
+                const steady = await readSteadyStatus(t, zoomSettle);
+                if (!steady.ok)
+                    return { ok: false, error: zoomMovingError(steady, "aiming") };
+                const { block, status } = steady;
+                if (status.aiMode === "unknown") {
+                    return {
+                        ok: false,
+                        error: "could not read the camera's AI-tracking mode (the status block didn't decode this " +
+                            "read — this can happen during a brief mode-switch transient); retry the aim.",
+                    };
+                }
+                if (status.aiMode !== "no-tracking") {
+                    return {
+                        ok: false,
+                        error: `AI tracking is active (${status.aiMode}); it moves the gimbal itself and would ` +
+                            `fight the aim. Disable it with obsbot_ai_track {enabled:false} first.`,
+                    };
+                }
+                // One function decides whether the camera's reported state resolves to a
+                // usable magnification — discrete mode or continuous zoom alike — so there
+                // is exactly one place that decides to refuse rather than guess, AND
+                // exactly one place that decides WHY (see MagnificationResult).
+                const resolved = resolveMagnification(status);
+                if (!resolved.ok) {
+                    if (resolved.reason === "unknown-fov") {
+                        // block[0x11] is STATUS_OFF_FOV_MODE (src/codec/commands.ts) — same offset
+                        // decodeStatus reads to produce fovMode, surfaced raw since "unknown" means
+                        // it didn't match any known value.
+                        return {
+                            ok: false,
+                            error: `could not read the camera's FOV mode (raw byte 0x${block[0x11].toString(16).padStart(2, "0")}); ` +
+                                `refusing to guess it. Set a known mode with obsbot_image_fov (e.g. {fov:"wide"}) and retry.`,
+                        };
+                    }
+                    // reason "implausible-zoom": fovMode is "custom" but the zoom it derives
+                    // from is implausible — e.g. zoomPercent far outside 0-100 — so the
+                    // resulting magnification falls outside the camera's known range. That is
+                    // a corrupt reading, not a real optical state; refuse rather than aim
+                    // from a bad number.
+                    return {
+                        ok: false,
+                        error: `the camera's zoom reading (zoomPercent ${resolved.zoomPercent}) resolves to a ` +
+                            `magnification outside the camera's known range [${MIN_MAGNIFICATION}, ` +
+                            `${MAX_MAGNIFICATION}]; refusing rather than aim from what looks like a corrupt ` +
+                            `status read. Retry, or set a known mode with obsbot_image_fov.`,
+                    };
+                }
+                const magnification = resolved.magnification;
+                // Same read path as obsbot_gimbal_position: UVC pan is degrees with our
+                // yaw sign; UVC tilt is degrees but positive = up, so negate it.
+                const yaw = (await t.camCtrlGet(CAMERA_CONTROL_PAN)).value;
+                const pitch = -(await t.camCtrlGet(CAMERA_CONTROL_TILT)).value;
+                // resolveMagnification already folded fovMode and zoomPercent into one
+                // number — a discrete mode's inherent crop and a continuous zoom are two
+                // ways of writing to the SAME scale, so there is nothing left to combine.
+                const aim = aimAtPixel(x, y, { width: frameWidth, height: frameHeight }, { magnification }, { yaw, pitch });
+                // Over the top is not an ordinary clamp: the target ray points behind
+                // the camera's current heading, so the nearest reachable yaw is on the
+                // FAR side of the gimbal's range, not near the target. Moving there
+                // would slew ~150 degrees into the opposite corner of the room while
+                // reporting clamped:true, which reads as "landed short" rather than
+                // "went the wrong way" — refuse instead of moving.
+                if (aim.overTheTop) {
+                    return {
+                        ok: false,
+                        error: `pixel (${x},${y}) lies past vertical from the current pose (yaw ${yaw.toFixed(1)}, ` +
+                            `pitch ${pitch.toFixed(1)}); it is not reachable while keeping the image upright, only ` +
+                            `by an "over the top" rotation that would swing the camera the opposite way. Tilt toward ` +
+                            `the pixel first (e.g. obsbot_gimbal_move), then re-aim from the new pose.`,
+                    };
+                }
+                await t.gimbalSet(aim.target.yaw, aim.target.pitch, 0);
+                return {
+                    ok: true,
+                    target: aim.target,
+                    offset: aim.offset,
+                    clamped: aim.clamped,
+                    fovMode: status.fovMode,
+                    current: { yaw, pitch },
+                    source,
+                    ...(source === "device" ? {} : { note: frameSourceNote(source) }),
+                    ...(ready.reconnected ? { reconnected: true } : {}),
+                };
+            },
+        },
+        {
+            name: "obsbot_zoom_to_fit",
+            description: "Frame a region of a frame you just captured: centre the gimbal on it and zoom so the " +
+                "region fills the frame. Give x/y/width/height of the region plus the frameWidth/frameHeight " +
+                "from THE SAME obsbot_capture_snapshot result — mixing a region from one frame with " +
+                "dimensions from another frames the wrong place and cannot be detected. Must come from a " +
+                "snapshot, and takes the same `source` declaration as obsbot_aim_at_pixel. `margin` (default 0.1) " +
+                "backs the zoom off by that fraction so the region isn't framed edge-to-edge; the tighter of " +
+                "the region's two axes decides the zoom, so the WHOLE region stays visible rather than being " +
+                "cropped on one side. Moves the gimbal BEFORE zooming, since zooming first can push the " +
+                "region's centre out of frame. Refuses on the same conditions as obsbot_aim_at_pixel: AI " +
+                "tracking active, the camera was asleep (waking it moves the gimbal and invalidates the " +
+                "frame), the FOV mode can't be decoded, a corrupt zoom reading, or the region's centre lying " +
+                "past vertical from the current pose, or a frame that isn't 16:9 (obsbot_capture_snapshot " +
+                "always returns 16:9; a non-16:9 pair looks transposed). Also refuses a region that isn't " +
+                "within the frame (edges included), or has non-positive width/height. The requested zoom is " +
+                "clamped to the camera's [1x, 4x] magnification range and reported via `clamped`; a partial " +
+                "fit still moves and zooms to the limit. Zoom ramps rather than jumping, so the tool polls " +
+                "the status block for up to 3s waiting for it to arrive and returns `settled:false` (not an " +
+                "error) if it didn't — " +
+                "a frame captured mid-ramp is at an unknown magnification, so check `settled` before trusting " +
+                "a follow-up snapshot.",
+            schema: zoomToFitSchema,
+            handler: async (args) => {
+                const { x, y, width, height, frameWidth, frameHeight, margin, camera, source } = zoomToFitSchema.parse(args);
+                // Pure input validation first, no I/O — same placement as obsbot_aim_at_pixel's
+                // own frame/pixel checks, and the same order: the aspect check runs before
+                // the region-bounds check, matching obsbot_aim_at_pixel.
+                const aspectRefusal = refuseIfNot169(frameWidth, frameHeight);
+                if (aspectRefusal)
+                    return aspectRefusal;
+                // The region must lie within the frame, edges included: a region touching
+                // the frame's own edges is valid (a region that already IS the full frame
+                // must pass — the full-frame fit test depends on it), only crossing them
+                // is refused.
+                if (width <= 0 || height <= 0 ||
+                    x < 0 || y < 0 ||
+                    x + width > frameWidth || y + height > frameHeight) {
+                    return {
+                        ok: false,
+                        error: `region (${x},${y}) ${width}x${height} is not inside the ${frameWidth}x${frameHeight} ` +
+                            `frame, or has non-positive width/height.`,
+                    };
+                }
+                // The gate wakes a sleeping camera and waits for it to settle. If it had to
+                // wake the camera, the gimbal just moved out from under the frame the caller
+                // measured — refuse below rather than frame a region that no longer means
+                // what it did (same reasoning as obsbot_aim_at_pixel).
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                if (ready.woke) {
+                    return {
+                        ok: false,
+                        error: "the camera was asleep and waking it moved the gimbal, so the frame you measured no " +
+                            "longer matches where the camera is pointing. Take a fresh snapshot and try again.",
+                    };
+                }
+                const steady = await readSteadyStatus(t, zoomSettle);
+                if (!steady.ok)
+                    return { ok: false, error: zoomMovingError(steady, "framing") };
+                const { block, status } = steady;
+                if (status.aiMode === "unknown") {
+                    return {
+                        ok: false,
+                        error: "could not read the camera's AI-tracking mode (the status block didn't decode this " +
+                            "read — this can happen during a brief mode-switch transient); retry.",
+                    };
+                }
+                if (status.aiMode !== "no-tracking") {
+                    return {
+                        ok: false,
+                        error: `AI tracking is active (${status.aiMode}); it moves the gimbal itself and would ` +
+                            `fight the framing. Disable it with obsbot_ai_track {enabled:false} first.`,
+                    };
+                }
+                const resolved = resolveMagnification(status);
+                if (!resolved.ok) {
+                    if (resolved.reason === "unknown-fov") {
+                        return {
+                            ok: false,
+                            error: `could not read the camera's FOV mode (raw byte 0x${block[0x11].toString(16).padStart(2, "0")}); ` +
+                                `refusing to guess it. Set a known mode with obsbot_image_fov (e.g. {fov:"wide"}) and retry.`,
+                        };
+                    }
+                    return {
+                        ok: false,
+                        error: `the camera's zoom reading (zoomPercent ${resolved.zoomPercent}) resolves to a ` +
+                            `magnification outside the camera's known range [${MIN_MAGNIFICATION}, ` +
+                            `${MAX_MAGNIFICATION}]; refusing rather than frame from what looks like a corrupt ` +
+                            `status read. Retry, or set a known mode with obsbot_image_fov.`,
+                    };
+                }
+                const magnification = resolved.magnification;
+                // Same read path as obsbot_gimbal_position / obsbot_aim_at_pixel.
+                const yaw = (await t.camCtrlGet(CAMERA_CONTROL_PAN)).value;
+                const pitch = -(await t.camCtrlGet(CAMERA_CONTROL_TILT)).value;
+                // Aim uses the CURRENT magnification: it has to match the optics the
+                // caller's frame was actually captured at, not the new fitted zoom.
+                const centerX = x + width / 2;
+                const centerY = y + height / 2;
+                const aim = aimAtPixel(centerX, centerY, { width: frameWidth, height: frameHeight }, { magnification }, { yaw, pitch });
+                if (aim.overTheTop) {
+                    return {
+                        ok: false,
+                        error: `region centre (${centerX},${centerY}) lies past vertical from the current pose (yaw ` +
+                            `${yaw.toFixed(1)}, pitch ${pitch.toFixed(1)}); it is not reachable while keeping the ` +
+                            `image upright, only by an "over the top" rotation that would swing the camera the ` +
+                            `opposite way. Tilt toward the region first (e.g. obsbot_gimbal_move), then re-aim.`,
+                    };
+                }
+                // required = m * min(frameW/width, frameH/height) / (1+margin). The MIN
+                // (not MAX) is deliberate: it's the axis that needs LESS extra zoom to fill,
+                // and zooming only that far keeps the OTHER axis from overflowing the frame
+                // — i.e. it's what keeps the whole region visible instead of cropping it.
+                // Note the frame's aspect ratio and VERTICAL_TANGENT_CORRECTION (src/geometry/aim.ts)
+                // do NOT appear here: writing out the fit condition on each axis, those terms
+                // scale tanH and tanV identically on both sides and cancel. They matter for
+                // AIMING at the region's centre (already folded into `aim` above via
+                // aimAtPixel) and not at all for how far to zoom.
+                const requiredRaw = (magnification * Math.min(frameWidth / width, frameHeight / height)) / (1 + margin);
+                const requiredMagnification = clamp(requiredRaw, MIN_MAGNIFICATION, MAX_MAGNIFICATION);
+                const fitClamped = requiredMagnification !== requiredRaw;
+                const ratio = zoomRatioFromMagnification(requiredMagnification);
+                // Move BEFORE zoom. Zoom is centre-preserving but not target-preserving:
+                // zooming first can push the region's centre out of frame entirely, after
+                // which the move would be aiming at a pixel that no longer means what it
+                // did when it was measured.
+                await t.gimbalSet(aim.target.yaw, aim.target.pitch, 0);
+                const { min, max } = await t.zoomRange();
+                await t.zoomSet(zoomRatioToUnits(ratio, min, max));
+                // Zoom ramps rather than jumping, so a status read taken immediately after
+                // the write can catch it mid-transit — settled:false is a RESULT for the
+                // caller to check, not thrown as an error, since a slower-than-expected
+                // zoom is information, not a failure of this call.
+                const settled = await waitForZoomSettle(t, ratio, zoomSettle);
+                return {
+                    ok: true,
+                    target: aim.target,
+                    ratio,
+                    magnification: requiredMagnification,
+                    clamped: fitClamped || aim.clamped,
+                    settled,
+                    source,
+                    ...(source === "device" ? {} : { note: frameSourceNote(source) }),
+                    ...(ready.reconnected ? { reconnected: true } : {}),
+                };
             },
         },
         {
@@ -1086,7 +1624,15 @@ export function createTools(mgr, capture, debug = false, presetRead = {}) {
                             { type: "image", data: snap.base64, mimeType: snap.mime },
                             {
                                 type: "text",
-                                text: JSON.stringify({ width: snap.width, height: snap.height, source }),
+                                text: JSON.stringify({
+                                    width: snap.width,
+                                    height: snap.height,
+                                    source,
+                                    // Frame rate picks the field of view on this camera, so the
+                                    // negotiated format is part of what a pixel means. Reported
+                                    // when the platform helper knows it; see Snapshot.sourceFormat.
+                                    ...(snap.sourceFormat ? { sourceFormat: snap.sourceFormat } : {}),
+                                }),
                             },
                         ],
                     };