obsbot-mcp 0.3.1 → 0.4.1

package/dist/mcp/tools.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
-import { encodeSetRunStatus, encodePtzMoveAngle, encodePtzMoveSpeed, encodeRecenter, zoomRatioToUnits, encodeAiTrackSpeed, encodeAiTracking, encodeVendorProbe, encodeZoomWithSpeed, encodeFaceFocus, encodeSetExposureMode, encodeSetExposureValue, decodeStatus, encodeFov, encodeHdr, percentToRange, AI_FRAMING_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, 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 { verifyFraming } from "./framing.js";
 import { parseFrame } from "../codec/frame.js";
+import { OP_BY_NAME } from "../codec/opcodes.js";
+import { decodePresetList, decodePresetEntry, assemblePresetSlots, implausiblePresetListReason, encodePresetAdd, encodePresetUpdate, encodePresetRecall, encodePresetDelete, encodePresetSetName, } from "../codec/preset.js";
 import { CameraBusyError } from "../transport/transport.js";
-import { ensureReady } from "./ready.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));
 // Some MCP clients serialize numbers and booleans as strings when the advertised
@@ -13,34 +15,47 @@ const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
 // maps any non-empty string (including "false") to true, which would be a bug.
 const num = () => z.preprocess((v) => (typeof v === "string" && v.trim() !== "" && !Number.isNaN(Number(v)) ? Number(v) : v), z.number());
 const bool = () => z.preprocess((v) => (v === "true" ? true : v === "false" ? false : v), z.boolean());
+// Optional per-camera selector, shared by every camera-addressing tool. The value
+// is the camera's serial; the handler forwards it to DeviceManager.get(serial)
+// (via getTransport/gate) so the command targets that camera. Omitted + a single
+// camera attached resolves to that camera, so single-camera callers are unaffected.
+// EXEMPT tools (obsbot_devices, obsbot_capture_stop/list, obsbot_debug_probe) keep
+// a plain z.object and never advertise `camera`.
+const withCamera = (shape) => z.object({ ...shape, camera: z.string().optional() });
 const listDevicesSchema = z.object({});
-const setRunStatusSchema = z.object({ state: z.enum(["run", "sleep"]) });
-const ptzMoveAngleSchema = z.object({
+const wakeSchema = withCamera({});
+const sleepSchema = withCamera({});
+const ptzMoveAngleSchema = withCamera({
     yaw: num(),
     pitch: num(),
     roll: num().default(0),
 });
-const ptzMoveSpeedSchema = z.object({
+const ptzMoveSpeedSchema = withCamera({
     yaw: num(),
     pitch: num(),
     roll: num().default(0),
     autoStopMs: num().default(800),
 });
-const gimbalRecenterSchema = z.object({});
-const zoomAbsoluteSchema = z.object({ ratio: num() });
-const aiTrackingSchema = z.object({
+const gimbalRecenterSchema = withCamera({});
+const zoomAbsoluteSchema = withCamera({ ratio: num() });
+// mode covers the human framings AND the standalone scene modes (group/whiteboard/
+// desk/hand). For a framing, enable = human tracking with that framing; for a scene
+// mode, `enabled` is implied true (disable via enabled:false, which cancels tracking).
+const AI_TRACKING_MODES = [...AI_FRAMING_MODES, ...AI_SCENE_MODES];
+const aiTrackingSchema = withCamera({
     enabled: bool(),
-    mode: z.enum(AI_FRAMING_MODES).default("normal"),
+    mode: z.enum(AI_TRACKING_MODES).default("normal"),
 });
-const aiTrackSpeedSchema = z.object({
+const isSceneMode = (m) => AI_SCENE_MODES.includes(m);
+const aiTrackSpeedSchema = withCamera({
     speed: z.enum(AI_TRACK_SPEEDS),
 });
-const zoomSpeedSchema = z.object({
+const zoomSpeedSchema = withCamera({
     ratio: num(),
     speed: num().default(0),
 });
-const faceFocusSchema = z.object({ enabled: bool() });
-const getStatusSchema = z.object({});
+const faceFocusSchema = withCamera({ enabled: bool() });
+const getStatusSchema = withCamera({});
 // Generic RE/spelunking primitive: raw send-bytes / get-bytes on any XU selector,
 // plus a `query` convenience that frames a table opcode and reads the reply.
 const probeSchema = z.object({
@@ -51,27 +66,88 @@ const probeSchema = z.object({
     opcode: z.string().optional(), // table opcode name for mode "query"
     payloadHex: z.string().optional(), // nested payload for mode "query"
 });
-const fovSchema = z.object({ fov: z.enum(FOV_TYPES) });
-const hdrSchema = z.object({ enabled: bool() });
-const focusSchema = z.object({
-    mode: z.enum(["auto", "manual"]),
+// Vendor XU selector: SET_CUR request AND GET_CUR reply mailbox. Protocol
+// constant, not platform-specific — same value as the per-transport
+// VENDOR_XU_SELECTOR (transport/{macos,linux,windows,read-serial}.ts), kept
+// local here rather than imported so this module doesn't need a transport-layer
+// dependency for one constant.
+const PROBE_VENDOR_SELECTOR = 0x02;
+// The reply mailbox retains the PREVIOUS reply until the new one lands, so a
+// single unvalidated read can return stale data — same hazard readSerialVia
+// (transport/read-serial.ts) polls around. Mirrors its POLL_ATTEMPTS.
+const PROBE_QUERY_POLL_ATTEMPTS = 8;
+// ...and its POLL_DELAY_MS. The device does not populate the mailbox instantly, and
+// how long it takes depends on the opcode: cached state (AI_GET_QUICK_STATUS) comes
+// back sub-millisecond, but anything reading persistent storage (UG_GET_SN) is far
+// slower. An un-delayed loop spans only ~1-2ms end to end, so it polls entirely
+// within the gap and reports "no valid reply" for a command the device answered.
+// Measured on darwin-arm64 hardware 2026-07-21, UG_GET_SN over 25 trials:
+// no delay = 24 failures (96%), 30ms delay = 0. f27956f fixed exactly this in
+// read-serial.ts; the probe kept the un-delayed loop until 2026-07-21.
+const PROBE_QUERY_POLL_DELAY_MS = 30;
+// Max gimbal velocity accepted by obsbot_gimbal_move_speed, in degrees per
+// second. Hardware-measured 2026-07-21: 150/160/170 all drove the gimbal
+// linearly, while 180/200/300 each moved it EXACTLY 0° yet still reported
+// success — the firmware ignores an over-range speed rather than saturating.
+// The true cutoff lies somewhere in 170..180; 150 keeps margin under it and
+// matches obsbot_gimbal_move's yaw bound.
+const GIMBAL_MAX_SPEED_DPS = 150;
+const fovSchema = withCamera({ fov: z.enum(FOV_TYPES) });
+const hdrSchema = withCamera({ enabled: bool() });
+const focusAutoSchema = withCamera({});
+const focusManualSchema = withCamera({
     position: num().pipe(z.number().min(0).max(100)).default(50),
 });
-const whiteBalanceSchema = z.object({
-    mode: z.enum(["auto", "manual"]),
-    temperature: num().default(5000),
-});
-const imageControlSchema = z.object({
+const imageWbAutoSchema = withCamera({});
+const imageWbManualSchema = withCamera({ temperature: num().default(5000) });
+const imageControlSchema = withCamera({
     control: z.enum(IMAGE_CONTROLS),
     level: num().pipe(z.number().min(0).max(100)),
 });
-const exposureSchema = z.object({
-    mode: z.enum(["auto", "manual"]),
+const imageExposureAutoSchema = withCamera({
+    // Auto-exposure metering priority: global (whole frame) or face (meters for a
+    // detected face). Optional.
+    priority: z.enum(["global", "face"]).optional(),
+});
+const imageExposureManualSchema = withCamera({
     level: num().pipe(z.number().min(0).max(100)).default(50),
 });
-const gimbalPositionSchema = z.object({});
-const snapshotSchema = z.object({
-    maxDim: num().pipe(z.number().min(256).max(1920)).default(1024),
+const gimbalPositionSchema = withCamera({});
+const presetListSchema = withCamera({});
+const presetSaveSchema = withCamera({
+    slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
+});
+const presetSlotSchema = withCamera({
+    slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
+});
+const presetRecallSchema = presetSlotSchema;
+const presetUpdateSchema = withCamera({
+    slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
+});
+const presetRenameSchema = withCamera({
+    slot: num().pipe(z.union([z.literal(1), z.literal(2), z.literal(3)])),
+    name: z.string(),
+});
+const presetDeleteSchema = presetSlotSchema;
+// Rename frame payload is u32le(slot-1) [4 bytes] + ASCII name, inside a fixed 60-byte
+// frame whose payload region starts at offset 16 (see buildFrame). Max payload is
+// 60-16=44 bytes, so the name must fit in 44-4=40 bytes.
+const PRESET_NAME_MAX = 40;
+// `resolution` is the longest edge of the returned image, in pixels. It replaces
+// the old `maxDim`, and the default drops from 1024 to 640: the JPEG is base64'd
+// into a tool response that an LLM reads, so every pixel costs tokens. 640 is
+// enough to judge framing, lighting and exposure; a caller that needs detail asks
+// for it, and pays for it (640 -> ~86KB, 1920 -> ~413KB).
+//
+// Capped at 1920 even though the sensor offers 3840x2160. Reaching 4K needs an
+// explicit device activeFormat change (the session preset alone does not do it --
+// activeFormat governs and stays at 1080p), which mutates shared device state that
+// another app streaming the camera would feel. And a 4K frame is ~1.5MB, roughly
+// 2M base64 characters, which is far past a usable token budget for "let me look
+// at the shot". The cap is honest: asking for more than the ceiling is rejected
+// rather than silently answered with 1080p.
+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),
     source: z.enum(["device", "virtual", "ndi"]).default("device"),
@@ -86,12 +162,164 @@ const recordStartSchema = z.object({
 const previewStartSchema = z.object({ source: captureSourceEnum.default("device") });
 const captureStopSchema = z.object({ sessionId: z.string() });
 const captureListSchema = z.object({});
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export function createTools(getTransport, mgr, capture, session, debug = false) {
+// Preset read path: flat XU selectors 12 (list) + 13 (entry cursor). Hardware-verified
+// 2026-07-19 — NOT the framed-reply model (recvVendor + parseFrame); reads on the
+// vendor reply path just return the flat status block for this device. Three steps:
+//   1. GET selector 12 -> <count:u8> <slotIdx:u8> x count
+//   2. echo-write the just-read bytes back to selector 12 -> resets the entry cursor
+//      (echo is provably non-destructive; do NOT write zeros/synthesized bytes)
+//   3. GET selector 13, `count` times -> each read returns the next preset entry and
+//      advances the cursor, until the exhausted marker (status 0x02)
+//
+// Occupancy gates a create-once resource (save requires EMPTY, everything else
+// requires OCCUPIED), so a falsely-"empty" read here drives an irreversible write.
+// C1/I1/I3 below are all facets of the same unifying fix: never trust device bytes
+// enough to act on them (or echo them back) without a plausibility/consistency check.
+const isAllZero = (b) => b.equals(Buffer.alloc(b.length));
+// A genuinely EMPTY device and a not-serving read BOTH return an all-zero selector-12
+// block (hardware-established 2026-07-19 under controlled conditions: OBSBOT Center
+// closed so nothing could re-assert presets, camera measured awake at the moment of
+// the read, stable across repeated reads). So the block alone cannot tell them apart.
+//
+// Corroborate on the SAME XU surface and handle: the status block. When selector 12
+// read zeros on a genuinely empty device, the status block still returned real
+// non-zero data — a dead link or stale handle would zero BOTH.
+//
+// The check is deliberately TWO-part. decodeStatus reports awake for an ALL-ZERO block
+// (awake === block[0x02] === 0), so testing `awake` alone would let a dead link
+// masquerade as an empty device — manufacturing the exact false-EMPTY that gates the
+// irreversible create-once ADD. Requiring the status block to be non-zero AND awake
+// makes emptiness something we accept only on positive evidence.
+//
+// NOTE: UVC liveness is NOT valid corroboration here — obsbot_gimbal_position returns
+// a correct live pose even while the preset selectors aren't serving.
+async function presetSubsystemServing(t) {
+    try {
+        const status = await t.recvStatus(60);
+        if (isAllZero(status))
+            return false;
+        return decodeStatus(status).awake;
+    }
+    catch {
+        return false;
+    }
+}
+async function getPresetSlots(t) {
+    const block = await t.xuGetRaw(12, 60);
+    // Zero presets is a legitimate device state, and every preset tool routes through
+    // here — so refusing it outright left our toolset with no path OUT of it (save was
+    // gated behind the read that fails, making the first preset uncreatable where
+    // OBSBOT Center doesn't exist). Accept it only with positive corroboration, and
+    // skip the echo-write: with no entries there is no cursor to reset, which removes
+    // the C1 hazard at its root on this path rather than bypassing the check.
+    if (isAllZero(block) && (await presetSubsystemServing(t))) {
+        return assemblePresetSlots([]);
+    }
+    // C1: validate BEFORE the echo-write — see implausiblePresetListReason. A
+    // failed/short/garbage read must never be echoed back to a selector whose
+    // write semantics for anything but a genuine echo are undecoded.
+    const reason = implausiblePresetListReason(block);
+    if (reason) {
+        throw new Error(`preset list read implausible, refusing to reset the cursor: ${reason}`);
+    }
+    const list = decodePresetList(block);
+    await t.xuRaw(12, block); // echo-write resets the cursor — load-bearing, see above
+    // I3: never walk more entries than the device physically has, no matter what
+    // `count` claimed. C1 already rejects count>3 above, but this clamp is a
+    // second, independent guard against turning a garbage count into up to 255
+    // USB control transfers.
+    const walkCount = Math.min(list.count, 3);
+    const per = [];
+    for (let i = 0; i < walkCount; i++) {
+        const e = decodePresetEntry(await t.xuGetRaw(13, 60));
+        if (e.end)
+            break;
+        per.push({ slot: e.slot, name: e.name, pose: e.pose });
+    }
+    // I1: list.slots (from selector 12) is the device's own statement of WHICH
+    // slots are occupied. If the entry-cursor walk (selector 13) disagrees — it
+    // exhausted early, hit an implausible/all-zero entry, or decoded a different
+    // slot set — don't silently trust whichever answer under-reports. A false
+    // EMPTY is the dangerous direction for a create-once resource, so fail loudly
+    // instead of returning a confident wrong answer.
+    const walked = [...new Set(per.map((e) => e.slot - 1))].sort((a, b) => a - b);
+    const claimed = [...list.slots].sort((a, b) => a - b);
+    const agree = walked.length === claimed.length && walked.every((s, i) => s === claimed[i]);
+    if (!agree) {
+        throw new Error(`preset list mismatch: selector 12 claims occupied slots [${claimed.join(",")}] but the ` +
+            `entry-cursor walk (selector 13) found [${walked.join(",")}]`);
+    }
+    return assemblePresetSlots(per);
+}
+// This is a mechanical system: the gimbal does not switch between awake and asleep,
+// it travels through them (rising, settling, stowing), and subsystems come back
+// online in some order. A single sample of a system in motion describes one instant,
+// not the state the next call lands in — so a lone implausible read is expected
+// occasionally and is not, by itself, news.
+//
+// Backoff spans ~1.7s, chosen against the observed ~1-2s post-wake self-centering
+// 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));
+const allEmpty = (slots) => slots.every((s) => !s.occupied);
+/**
+ * Read the preset slots with bounded retry, and confirm the one verdict whose error
+ * destroys data.
+ *
+ * Reads can neither damage the camera nor delete anything, so retrying and
+ * re-reading is free in the only currencies that matter. Writes are never retried
+ * here — the caller's write sits outside this function by construction.
+ *
+ * EMPTY is confirmed by a second read because it is the sole verdict that authorizes
+ * an irreversible create-once ADD: a slot wrongly believed empty gets a customer's
+ * preset written over (firmware behaviour there is undecoded). The inverse error is
+ * benign — a slot wrongly believed occupied only makes delete a no-op and update
+ * fail. Disagreement between the two reads means the device is mid-transition, so we
+ * refuse rather than pick a side.
+ */
+async function readPresetSlots(t, gate, opts = {}) {
+    const { attempts, backoffMs } = { ...PRESET_READ_DEFAULTS, ...opts };
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        if (i > 0) {
+            await napMs(backoffMs[Math.min(i - 1, backoffMs.length - 1)]);
+            // Re-probe readiness between attempts: the failure mode we chase is the device
+            // being partway through a transition, and the wake it may send is a decoded,
+            // documented command — not an undecoded write.
+            await gate();
+        }
+        try {
+            const slots = await getPresetSlots(t);
+            if (allEmpty(slots) && !allEmpty(await getPresetSlots(t))) {
+                throw new Error("preset list unstable: one read reported every slot empty, an immediate " +
+                    "re-read disagreed — refusing to treat this as empty");
+            }
+            return slots;
+        }
+        catch (e) {
+            lastErr = e;
+        }
+    }
+    throw lastErr;
+}
+export function createTools(mgr, capture, debug = false, presetRead = {}) {
+    // 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
+    // camera. `camera` omitted + a single camera attached => that camera (identical
+    // to the pre-selector behaviour). `camera` omitted + several attached => mgr.get
+    // throws AmbiguousCameraError, and an unknown serial throws UnknownCameraError;
+    // both surface to the caller via the gate's "unreachable" path (its getTransport
+    // throwing is already treated as unreachable, and the message is carried through).
+    const getTransport = (camera) => mgr.get(camera);
+    const reconnectFor = (camera) => ({
+        invalidate: () => mgr.invalidate(camera),
+        takeReconnected: () => mgr.takeReconnected(camera),
+    });
     // Readiness gate for gimbal/AI commands: probe presence + auto-wake if asleep,
     // self-heal (invalidate + re-open) on a mid-session disconnect. Returns the
     // ready transport or an { ok:false } error the handler passes straight through.
-    const gate = () => ensureReady(getTransport, session);
+    const gate = (camera) => ensureReady(() => getTransport(camera), reconnectFor(camera));
     const needCapture = () => {
         if (!capture)
             throw new Error("capture manager not configured");
@@ -104,27 +332,48 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
     };
     const toolDefs = [
         {
-            name: "obsbot_list_devices",
-            description: "List connected OBSBOT-compatible video capture devices.",
+            name: "obsbot_devices",
+            description: "List attached OBSBOT-compatible cameras. Each entry is { serial?, locationId?, name, " +
+                "status, reason? }: serial is the value to pass as `camera` to any camera-addressing tool " +
+                "(present where obtainable — reading it requires briefly opening the camera); status " +
+                "is available (free to bind), bound (already opened by this process), or busy (could not " +
+                "be opened and identified, so it can't be targeted here — usually another process holds " +
+                "it, but it also covers a camera that opened yet would not answer). On a busy entry, " +
+                "`reason` carries the underlying error and distinguishes those cases.",
             schema: listDevicesSchema,
             handler: async (args) => {
                 listDevicesSchema.parse(args);
-                return { devices: await mgr.list() };
+                return { cameras: await mgr.listCameras() };
             },
         },
         {
-            name: "obsbot_set_run_status",
-            description: "Wake (\"run\") or sleep the camera/gimbal.",
-            schema: setRunStatusSchema,
+            name: "obsbot_wake",
+            description: "Wake the camera/gimbal (sends \"run\"). This MOVES the camera: waking un-stows the " +
+                "gimbal and brings it back to level (pitch ~0). Most control commands also wake the " +
+                "camera implicitly as a side effect.",
+            schema: wakeSchema,
             handler: async (args) => {
-                const { state } = setRunStatusSchema.parse(args);
-                const t = await getTransport();
-                await t.sendVendor(encodeSetRunStatus(state).buildFrame(t.nextSeq()));
-                return { ok: true, state };
+                const { camera } = wakeSchema.parse(args);
+                const t = await getTransport(camera);
+                await t.sendVendor(encodeSetRunStatus("run").buildFrame(t.nextSeq()));
+                return { ok: true, state: "run" };
+            },
+        },
+        {
+            name: "obsbot_sleep",
+            description: "Sleep the camera/gimbal (sends \"sleep\"). This MOVES the camera: sleeping STOWS the " +
+                "gimbal, tilting it face-down to roughly pitch 84°, so obsbot_gimbal_position will read " +
+                "~84 rather than the pose you left it in. obsbot_wake un-stows it.",
+            schema: sleepSchema,
+            handler: async (args) => {
+                const { camera } = sleepSchema.parse(args);
+                const t = await getTransport(camera);
+                await t.sendVendor(encodeSetRunStatus("sleep").buildFrame(t.nextSeq()));
+                return { ok: true, state: "sleep" };
             },
         },
         {
-            name: "obsbot_ptz_move_angle",
+            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.",
@@ -134,81 +383,98 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
                 const yaw = clamp(parsed.yaw, -150, 150);
                 const pitch = clamp(parsed.pitch, -90, 90);
                 const roll = parsed.roll;
-                const ready = await gate();
+                const ready = await gate(parsed.camera);
                 if (!ready.ok)
                     return ready;
                 const t = ready.transport;
-                // Vendor gimbal frame AI_SET_GIM_MOTOR_DEG. The wire payload order is [roll, pitch,
-                // yaw] — see encodePtzMoveAngle / gimbal3. Absolute, 1:1 degrees, HW-confirmed. (The
-                // earlier UVC pan/tilt/roll experiment was abandoned: it's flaky on the OBSBOT
-                // DirectShow driver, so PTZ rides the vendor frame instead.)
-                await t.sendVendor(encodePtzMoveAngle(yaw, pitch, roll).buildFrame(t.nextSeq()));
+                await t.gimbalSet(yaw, pitch, roll);
                 return ready.reconnected ? { yaw, pitch, roll, reconnected: true } : { yaw, pitch, roll };
             },
         },
         {
-            name: "obsbot_ptz_move_speed",
-            description: "Drive the gimbal at a yaw/pitch speed (positive yaw pans to the camera's left, matching " +
-                "obsbot_ptz_move_angle), then automatically stop after autoStopMs (default 800ms) so it can't run away.",
+            name: "obsbot_gimbal_move_speed",
+            description: "Drive the gimbal at a yaw/pitch speed in DEGREES PER SECOND (positive yaw pans to the " +
+                "camera's left, matching obsbot_gimbal_move), then automatically stop after autoStopMs " +
+                "(default 800ms) so it can't run away. Speed is clamped to ±150 °/s; the returned " +
+                "yaw/pitch are the speeds actually used.",
             schema: ptzMoveSpeedSchema,
             handler: async (args) => {
-                const { yaw, pitch, roll, autoStopMs } = ptzMoveSpeedSchema.parse(args);
-                const ready = await gate();
+                const parsed = ptzMoveSpeedSchema.parse(args);
+                // Degrees per second, measured on hardware 2026-07-21 against the live
+                // position readback: 10/1000ms -> 10°, 60/500ms -> 29°, 120/300ms -> 35°,
+                // 170/300ms -> 49° — linear across the band.
+                //
+                // Clamping matters more here than for absolute moves. Past the limit the
+                // firmware does not saturate, it silently IGNORES the command: 180, 200
+                // and 300 each produced EXACTLY 0° of motion while still reporting
+                // success. Unclamped, a caller gets ok:true and a camera that never
+                // moved. 150 sits inside the verified-good band (150/160/170 all moved)
+                // with margin, and matches obsbot_gimbal_move's yaw bound so the API has
+                // one number to remember.
+                const yaw = clamp(parsed.yaw, -GIMBAL_MAX_SPEED_DPS, GIMBAL_MAX_SPEED_DPS);
+                const pitch = clamp(parsed.pitch, -GIMBAL_MAX_SPEED_DPS, GIMBAL_MAX_SPEED_DPS);
+                const roll = clamp(parsed.roll, -GIMBAL_MAX_SPEED_DPS, GIMBAL_MAX_SPEED_DPS);
+                const ready = await gate(parsed.camera);
                 if (!ready.ok)
                     return ready;
                 const t = ready.transport;
-                // Firmware velocity-yaw is inverted relative to position-yaw (AI_SET_GIM_SPEED +yaw
-                // drives right, AI_SET_GIM_MOTOR_DEG +yaw drives left — HW-observed). Negate so the
-                // tool contract is consistent: +yaw pans to the camera's left on both PTZ tools.
-                await t.sendVendor(encodePtzMoveSpeed(-yaw, pitch, roll).buildFrame(t.nextSeq()));
-                if (autoStopMs > 0) {
-                    await sleep(autoStopMs);
-                    await t.sendVendor(encodePtzMoveSpeed(0, 0, 0).buildFrame(t.nextSeq()));
-                }
-                return { ok: true, stopped: autoStopMs > 0, ...(ready.reconnected && { reconnected: true }) };
+                // Firmware velocity-yaw is inverted relative to position-yaw: the vendor
+                // AI_SET_GIM_SPEED +yaw drives right (opposite of obsbot_gimbal_move).
+                // The transport's gimbalSpeed handles this per-platform as needed.
+                await t.gimbalSpeed(yaw, pitch, roll, parsed.autoStopMs);
+                return {
+                    ok: true,
+                    yaw,
+                    pitch,
+                    stopped: parsed.autoStopMs > 0,
+                    ...(ready.reconnected && { reconnected: true }),
+                };
             },
         },
         {
             name: "obsbot_gimbal_recenter",
-            description: "Recenter the gimbal.",
+            description: "Recenter the gimbal — drives it back to yaw 0 / pitch 0 (level and facing forward). " +
+                "Returns as soon as the command is sent: the gimbal may still be moving, so poll " +
+                "obsbot_gimbal_position if you need to know it has arrived.",
             schema: gimbalRecenterSchema,
             handler: async (args) => {
-                gimbalRecenterSchema.parse(args);
-                const ready = await gate();
+                const { camera } = gimbalRecenterSchema.parse(args);
+                const ready = await gate(camera);
                 if (!ready.ok)
                     return ready;
                 const t = ready.transport;
-                // Vendor recenter GIM_SET_MOTOR (0x00C3 + 6 zero bytes). HW-confirmed to recenter
-                // the gimbal.
-                await t.sendVendor(encodeRecenter().buildFrame(t.nextSeq()));
+                await t.gimbalRecenter();
                 return { ok: true, ...(ready.reconnected && { reconnected: true }) };
             },
         },
         {
-            name: "obsbot_zoom_absolute",
-            description: "Set absolute zoom ratio, clamped to [1.0, 2.0].",
+            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).",
             schema: zoomAbsoluteSchema,
             handler: async (args) => {
                 const parsed = zoomAbsoluteSchema.parse(args);
                 const ratio = clamp(parsed.ratio, 1.0, 2.0);
-                const t = await getTransport();
+                const t = await getTransport(parsed.camera);
                 const { min, max } = await t.zoomRange();
                 await t.zoomSet(zoomRatioToUnits(ratio, min, max));
                 return { ok: true, ratio };
             },
         },
         {
-            name: "obsbot_ai_tracking",
-            description: "Enable or disable AI subject tracking, and choose the framing sub-mode. When " +
-                "enabled the camera follows the subject; disabling stops tracking. `mode` forces " +
-                "the composition: normal | upper-body | close-up | headless | lower-body. After " +
-                "writing, the tool polls the status block until the framing settles and returns " +
+            name: "obsbot_ai_track",
+            description: "Enable or disable AI tracking and choose the mode. When enabled the camera " +
+                "follows the subject; disabling stops tracking. `mode` is either a human framing " +
+                "(normal | upper-body | close-up | headless | lower-body) or a standalone scene " +
+                "mode (group | whiteboard | desk | hand); scene modes imply enabled:true. After " +
+                "writing, the tool polls the status block until the mode settles and returns " +
                 "{ verified, matched } — the aiMode the device actually landed on (matched:false " +
-                "means no subject was being tracked, so the framing could not take effect yet).",
+                "means no subject was being tracked, so the mode could not take effect yet).",
             schema: aiTrackingSchema,
             handler: async (args) => {
-                const { enabled, mode } = aiTrackingSchema.parse(args);
-                const ready = await gate();
+                const { enabled, mode, camera } = aiTrackingSchema.parse(args);
+                const ready = await gate(camera);
                 if (!ready.ok)
                     return ready;
                 const t = ready.transport;
@@ -223,12 +489,17 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
                 // Snapshot the framing before the write so verify can tell a real change
                 // from the pre-write value (and skip the m=6 transient). See verifyFraming.
                 const before = await readAiMode();
-                // OBSBOT Center toggles tracking + framing with a raw uvcExt write to selector 6,
-                // NOT a framed V3 command (which the Tiny 2 ACKs but ignores). byte[3] is the
-                // framing sub-mode. See encodeAiTracking.
-                await t.xuRaw(UVC_XU_SELECTOR, encodeAiTracking(enabled, mode));
-                // Verify by readback: aiMode settles to (m=2, n=framing) after a brief m=6
-                // transient. want == the requested framing (or no-tracking on disable).
+                // OBSBOT Center toggles tracking/mode with a raw uvcExt write to selector 6,
+                // NOT a framed V3 command (which the Tiny 2 ACKs but ignores). byte[2] is the
+                // work mode, byte[3] the human framing sub-mode. A scene mode (group/whiteboard/
+                // desk/hand) is its own work mode; a framing is the human work mode. See
+                // encodeAiMode / encodeAiTracking.
+                const payload = !enabled ? encodeAiMode("none")
+                    : isSceneMode(mode) ? encodeAiMode(mode)
+                        : encodeAiTracking(true, mode);
+                await t.xuRaw(UVC_XU_SELECTOR, payload);
+                // Verify by readback: aiMode settles to the requested mode after a brief m=6
+                // transient. The mode name doubles as its aiMode readback value.
                 const want = enabled ? mode : "no-tracking";
                 const { verified, matched } = await verifyFraming(readAiMode, want, before);
                 return { ok: true, enabled, mode, verified, matched, ...(ready.reconnected && { reconnected: true }) };
@@ -240,48 +511,50 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
                 "speed: standard (slower follow) | sport (snappier follow).",
             schema: aiTrackSpeedSchema,
             handler: async (args) => {
-                const { speed } = aiTrackSpeedSchema.parse(args);
-                const t = await getTransport();
+                const { speed, camera } = aiTrackSpeedSchema.parse(args);
+                const t = await getTransport(camera);
                 await t.sendVendor(encodeAiTrackSpeed(speed).buildFrame(t.nextSeq()));
                 return { ok: true, speed };
             },
         },
         {
-            name: "obsbot_zoom_speed",
-            description: "Zoom to an absolute ratio at a chosen speed. ratio is clamped to [1.0,2.0]; " +
-                "speed 0=device default, 1-10 slow→fast, 255=maximum.",
+            name: "obsbot_zoom_vendor",
+            description: "Vendor zoom path with adjustable speed: zoom to a ratio at a chosen speed. This tool's " +
+                "ratio scale differs from obsbot_zoom_uvc's and may not land exactly on the requested " +
+                "target. ratio is clamped to [1.0,2.0]; speed 0=device default, 1-10 slow→fast, 255=maximum.",
             schema: zoomSpeedSchema,
             handler: async (args) => {
                 const parsed = zoomSpeedSchema.parse(args);
                 const ratio = clamp(parsed.ratio, 1.0, 2.0);
                 const speed = clamp(Math.round(parsed.speed), 0, 255);
-                const t = await getTransport();
+                const t = await getTransport(parsed.camera);
                 await t.sendVendor(encodeZoomWithSpeed(Math.round(ratio * 100), speed).buildFrame(t.nextSeq()));
                 return { ok: true, ratio, speed };
             },
         },
         {
-            name: "obsbot_face_focus",
+            name: "obsbot_focus_face",
             description: "Enable or disable face-priority autofocus.",
             schema: faceFocusSchema,
             handler: async (args) => {
-                const { enabled } = faceFocusSchema.parse(args);
-                const t = await getTransport();
+                const { enabled, camera } = faceFocusSchema.parse(args);
+                const t = await getTransport(camera);
                 await t.sendVendor(encodeFaceFocus(enabled).buildFrame(t.nextSeq()));
                 return { ok: true, enabled };
             },
         },
         {
-            name: "obsbot_get_status",
-            description: "Read the camera's live status block. Returns { awake, hdr, aiMode, trackSpeed }: " +
+            name: "obsbot_status",
+            description: "Read the camera's live status block. Returns { awake, hdr, faceAe, aiMode, trackSpeed }: " +
+                "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. " +
                 "Under --debug the result also carries `raw`: the full 60-byte status block as hex " +
                 "(for reverse-engineering undecoded offsets).",
             schema: getStatusSchema,
             handler: async (args) => {
-                getStatusSchema.parse(args);
-                const t = await getTransport();
+                const { camera } = getStatusSchema.parse(args);
+                const t = await getTransport(camera);
                 try {
                     const block = await t.recvStatus();
                     return { ok: true, ...decodeStatus(block), ...(debug ? { raw: block.toString("hex") } : {}) };
@@ -292,13 +565,15 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_probe",
+            name: "obsbot_debug_probe",
             description: "RE/diagnostics only — generic XU byte access for reverse-engineering the feedback surface. " +
                 "mode 'get': GET_CUR read `length` bytes from XU `selector` (default selector 6; use a large " +
                 "length to probe the status block's true size, or sweep other selectors). " +
                 "mode 'set': SET_CUR write raw `hex` bytes to XU `selector` (e.g. replay a captured frame). " +
-                "mode 'query': frame table `opcode` (default AI_GET_QUICK_STATUS) with optional `payloadHex`, " +
-                "send on the vendor selector, then read the reply frame. Returns raw hex. Not for normal use.",
+                "mode 'query': frame table `opcode` (default AI_GET_QUICK_STATUS) — a pure GET (no " +
+                "payloadHex) is framed header-only (flags 0x01, the only flavour this device answers for " +
+                "a GET); supplying `payloadHex` frames a SET/command instead (flags 0x25) — send on the " +
+                "vendor selector, then poll for the matching reply frame. Returns raw hex. Not for normal use.",
             schema: probeSchema,
             handler: async (args) => {
                 const { mode, selector, length, hex, opcode, payloadHex } = probeSchema.parse(args);
@@ -316,29 +591,54 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
                         await t.xuRaw(selector, Buffer.from(hex, "hex"));
                         return { ok: true, selector, sent: hex };
                     }
-                    // mode "query": build a framed V3 command, send it, read the reply frame.
+                    // mode "query": build a framed V3 command and poll the vendor reply mailbox
+                    // until a valid, matching reply appears.
                     const payload = payloadHex ? Buffer.from(payloadHex, "hex") : Buffer.alloc(0);
                     const name = opcode ?? "AI_GET_QUICK_STATUS";
-                    const frame = encodeVendorProbe(name, payload).buildFrame(t.nextSeq());
-                    const reply = await t.recvVendor(frame, length ?? 60);
-                    let parsed;
-                    try {
-                        const p = parseFrame(reply);
-                        parsed = {
-                            cmd: "0x" + p.cmd.toString(16).padStart(4, "0"),
-                            receiver: p.receiver,
-                            payloadHex: p.payload.toString("hex"),
-                        };
+                    const op = OP_BY_NAME.get(name);
+                    if (!op || op.wireCmd === null || op.receiver === null) {
+                        return { ok: false, error: `opcode "${name}" is not a sendable V3 command` };
                     }
-                    catch (e) {
-                        parsed = { parseError: e.message };
+                    // A pure GET (no nested payload) only gets an answer on this device when
+                    // framed header-only (flags 0x01, encodeVendorGet) — encodeVendorProbe's
+                    // SET flavour (flags 0x25) returns a stale echo instead of a real answer
+                    // when there's no payload for the device to act on. A supplied payloadHex
+                    // means an actual SET/command, so that keeps the 0x25 framing.
+                    const seq = t.nextSeq();
+                    const frame = (payload.length === 0 ? encodeVendorGet(name) : encodeVendorProbe(name, payload)).buildFrame(seq);
+                    await t.xuRaw(PROBE_VENDOR_SELECTOR, frame);
+                    // The reply mailbox retains the PREVIOUS reply until the new one lands, so
+                    // a single unvalidated read can return stale data. Trust a reply only once
+                    // it parses cleanly AND both its cmd and seq match what was just sent (same
+                    // validation readSerialVia does in transport/read-serial.ts).
+                    const replyLen = length ?? 60;
+                    for (let i = 0; i < PROBE_QUERY_POLL_ATTEMPTS; i++) {
+                        await napMs(PROBE_QUERY_POLL_DELAY_MS); // let the reply land before reading
+                        const raw = await t.xuGetRaw(PROBE_VENDOR_SELECTOR, replyLen);
+                        try {
+                            const p = parseFrame(raw);
+                            if (p.cmd === op.wireCmd && p.seq === seq) {
+                                return {
+                                    ok: true,
+                                    opcode: name,
+                                    sentFrame: frame.toString("hex"),
+                                    replyHex: raw.toString("hex"),
+                                    parsed: {
+                                        cmd: "0x" + p.cmd.toString(16).padStart(4, "0"),
+                                        receiver: p.receiver,
+                                        payloadHex: p.payload.toString("hex"),
+                                    },
+                                };
+                            }
+                        }
+                        catch {
+                            // Not our reply yet (stale mailbox, still in flight, or garbage) — keep polling.
+                        }
                     }
                     return {
-                        ok: true,
-                        opcode: name,
+                        ok: false,
+                        error: `no valid reply for ${name} (seq ${seq}) after ${PROBE_QUERY_POLL_ATTEMPTS} attempts`,
                         sentFrame: frame.toString("hex"),
-                        replyHex: reply.toString("hex"),
-                        parsed,
                     };
                 }
                 catch (e) {
@@ -347,54 +647,61 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_fov",
+            name: "obsbot_image_fov",
             description: "Set the field of view. fov: wide (86°) | medium (78°) | narrow (65°).",
             schema: fovSchema,
             handler: async (args) => {
-                const { fov } = fovSchema.parse(args);
-                const t = await getTransport();
+                const { fov, camera } = fovSchema.parse(args);
+                const t = await getTransport(camera);
                 await t.xuRaw(UVC_XU_SELECTOR, encodeFov(fov));
                 return { ok: true, fov };
             },
         },
         {
-            name: "obsbot_hdr",
+            name: "obsbot_image_hdr",
             description: "Toggle HDR/WDR imaging on or off.",
             schema: hdrSchema,
             handler: async (args) => {
-                const { enabled } = hdrSchema.parse(args);
-                const t = await getTransport();
+                const { enabled, camera } = hdrSchema.parse(args);
+                const t = await getTransport(camera);
                 await t.xuRaw(UVC_XU_SELECTOR, encodeHdr(enabled));
                 return { ok: true, enabled };
             },
         },
         {
-            name: "obsbot_focus",
-            description: "Set focus. mode 'auto' enables continuous autofocus; mode 'manual' sets the " +
-                "focus motor to position (0-100, near→far), mapped onto the device range.",
-            schema: focusSchema,
+            name: "obsbot_focus_auto",
+            description: "Enable continuous autofocus.",
+            schema: focusAutoSchema,
             handler: async (args) => {
-                const { mode, position } = focusSchema.parse(args);
-                const t = await getTransport();
-                if (mode === "auto") {
-                    await t.camCtrlSet(CAMERA_CONTROL_FOCUS, 0, UVC_FLAG_AUTO);
-                    return { ok: true, mode };
-                }
+                const { camera } = focusAutoSchema.parse(args);
+                const t = await getTransport(camera);
+                await t.camCtrlSet(CAMERA_CONTROL_FOCUS, 0, UVC_FLAG_AUTO);
+                return { ok: true, mode: "auto" };
+            },
+        },
+        {
+            name: "obsbot_focus_manual",
+            description: "Set the focus motor to position (0-100, near→far), mapped onto the device range.",
+            schema: focusManualSchema,
+            handler: async (args) => {
+                const { position, camera } = focusManualSchema.parse(args);
+                const t = await getTransport(camera);
                 const { min, max } = await t.camCtrlRange(CAMERA_CONTROL_FOCUS);
                 const value = percentToRange(position, min, max);
                 await t.camCtrlSet(CAMERA_CONTROL_FOCUS, value, UVC_FLAG_MANUAL);
-                return { ok: true, mode, position, value };
+                return { ok: true, mode: "manual", position, value };
             },
         },
         {
             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. Reports the " +
-                "actual position, which may lag a move that is still in progress.",
+                "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, " +
+                "and reflects motion the host did not command (speed moves, recenter, tracking).",
             schema: gimbalPositionSchema,
             handler: async (args) => {
-                gimbalPositionSchema.parse(args);
-                const t = await getTransport();
+                const { camera } = gimbalPositionSchema.parse(args);
+                const t = await getTransport(camera);
                 const pan = await t.camCtrlGet(CAMERA_CONTROL_PAN);
                 const tilt = await t.camCtrlGet(CAMERA_CONTROL_TILT);
                 // UVC pan value is degrees, same sign as our yaw (+ = camera-left). UVC tilt
@@ -403,33 +710,287 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_white_balance",
-            description: "Set white balance. mode 'auto' enables auto white balance; mode 'manual' sets a " +
-                "colour temperature in Kelvin (clamped to the device's supported range).",
-            schema: whiteBalanceSchema,
+            name: "obsbot_preset_list",
+            description: "Read the three gimbal preset slots (occupied/empty, name, pose in degrees). " +
+                "Reads flat XU selectors 12 (list) and 13 (entry cursor), NOT the vendor V3 " +
+                "framed-reply path (which is non-functional for preset data on this device).",
+            schema: presetListSchema,
             handler: async (args) => {
-                const { mode, temperature } = whiteBalanceSchema.parse(args);
-                const t = await getTransport();
-                const { min, max } = await t.procAmpRange(VIDEO_PROCAMP_WHITE_BALANCE);
-                if (mode === "auto") {
-                    await t.procAmpSet(VIDEO_PROCAMP_WHITE_BALANCE, min, UVC_FLAG_AUTO);
-                    return { ok: true, mode };
+                const { camera } = presetListSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                try {
+                    const slots = await readPresetSlots(t, () => gate(camera), presetRead);
+                    return { ok: true, slots, ...(ready.reconnected && { reconnected: true }) };
+                }
+                catch (e) {
+                    return { ok: false, error: msg(e) };
+                }
+            },
+        },
+        {
+            name: "obsbot_preset_save",
+            description: "Save the gimbal's current live pose (yaw/pitch, via the standard UVC Pan/Tilt " +
+                "controls) into preset slot 1|2|3. Slots are create-once on this device — there is " +
+                "no overwrite, so an occupied slot is rejected (delete it first). Verifies by " +
+                "re-reading the slot list after writing.",
+            schema: presetSaveSchema,
+            handler: async (args) => {
+                const { slot, camera } = presetSaveSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                let pose;
+                try {
+                    const before = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (before[slot - 1].occupied) {
+                        return { ok: false, error: `slot ${slot} is occupied; update or delete first` };
+                    }
+                    // Mirror obsbot_gimbal_position's read path exactly: UVC pan is degrees, same
+                    // sign as our yaw; UVC tilt is degrees but positive = up, so negate to match
+                    // our +pitch = down convention.
+                    const yaw = (await t.camCtrlGet(CAMERA_CONTROL_PAN)).value;
+                    const pitch = -(await t.camCtrlGet(CAMERA_CONTROL_TILT)).value;
+                    // T6: ObsbotTransport exposes no zoom getter, so the live zoom ratio can't be
+                    // read back here — zoom is hardcoded to 1 rather than guessed. Not an oversight.
+                    pose = { pan: yaw, tilt: pitch, roll: 0, zoom: 1 };
+                    await t.sendVendor(encodePresetAdd(t.nextSeq(), slot, pose));
+                }
+                catch (e) {
+                    return { ok: false, error: `preset save failed: ${msg(e)}` };
                 }
+                // M1: the ADD above has committed. From here on, a thrown error must say so —
+                // otherwise a retry hits "slot occupied" with no clue the save actually landed.
+                try {
+                    const after = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!after[slot - 1].occupied) {
+                        return { ok: false, error: "verification failed", expected: "occupied", actual: "empty" };
+                    }
+                    return { ok: true, slot: after[slot - 1], ...(ready.reconnected && { reconnected: true }) };
+                }
+                catch (e) {
+                    return {
+                        ok: false,
+                        error: `preset saved to slot ${slot} but verification failed: ${msg(e)}`,
+                    };
+                }
+            },
+        },
+        {
+            name: "obsbot_preset_recall",
+            description: "Recall preset slot 1|2|3, driving the gimbal to that slot's saved pose. The slot " +
+                "must be occupied. The gimbal may still be moving when this returns — verification " +
+                "only confirms the slot is still occupied, not that the pose has arrived.",
+            schema: presetRecallSchema,
+            handler: async (args) => {
+                const { slot, camera } = presetRecallSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                try {
+                    const before = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!before[slot - 1].occupied) {
+                        return { ok: false, error: `slot ${slot} is empty; save first` };
+                    }
+                    await t.sendVendor(encodePresetRecall(t.nextSeq(), slot));
+                    // Sync V4L2 pan/tilt register to the preset's saved pose. The vendor-frame
+                    // recall physically moves the gimbal but corrupts V4L2 pan_absolute/tilt_absolute
+                    // on Linux. Issuing gimbalSet (which uses V4L2 on Linux) to the known target
+                    // both moves the gimbal there and restores the V4L2 register.
+                    const recallPose = before[slot - 1].pose;
+                    if (recallPose) {
+                        await t.gimbalSet(recallPose.pan, recallPose.tilt);
+                    }
+                    const after = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!after[slot - 1].occupied) {
+                        return { ok: false, error: "verification failed", expected: "occupied", actual: "empty" };
+                    }
+                    return { ok: true, slot: after[slot - 1], ...(ready.reconnected && { reconnected: true }) };
+                }
+                catch (e) {
+                    return { ok: false, error: msg(e) };
+                }
+            },
+        },
+        {
+            name: "obsbot_preset_update",
+            description: "Overwrite preset slot 1|2|3 with the gimbal's current live pose (yaw/pitch via the " +
+                "standard UVC Pan/Tilt controls). The slot must already be occupied (save first to " +
+                "create it). Verifies by re-reading the slot list after writing.",
+            schema: presetUpdateSchema,
+            handler: async (args) => {
+                const { slot, camera } = presetUpdateSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                let pose;
+                let previous = null;
+                try {
+                    const before = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!before[slot - 1].occupied) {
+                        return { ok: false, error: `slot ${slot} is empty; save first` };
+                    }
+                    // The pose we are about to destroy. Already in hand from the guard read, so
+                    // handing it back costs nothing and is the only restore path the caller has:
+                    // the device keeps no history and UPDATE is not reversible.
+                    previous = before[slot - 1].pose;
+                    // Mirror obsbot_preset_save's read path exactly: UVC pan is degrees, same sign as
+                    // our yaw; UVC tilt is degrees but positive = up, so negate to match our +pitch =
+                    // down convention.
+                    const yaw = (await t.camCtrlGet(CAMERA_CONTROL_PAN)).value;
+                    const pitch = -(await t.camCtrlGet(CAMERA_CONTROL_TILT)).value;
+                    // T6: ObsbotTransport exposes no zoom getter, so the live zoom ratio can't be
+                    // read back here — zoom is hardcoded to 1 rather than guessed. Not an oversight.
+                    pose = { pan: yaw, tilt: pitch, roll: 0, zoom: 1 };
+                    await t.sendVendor(encodePresetUpdate(t.nextSeq(), slot, pose));
+                }
+                catch (e) {
+                    return { ok: false, error: `preset update failed: ${msg(e)}` };
+                }
+                // M1: the UPDATE above has committed. From here on, a thrown error must say so.
+                try {
+                    const after = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!after[slot - 1].occupied) {
+                        return { ok: false, error: "verification failed", expected: "occupied", actual: "empty" };
+                    }
+                    return {
+                        ok: true,
+                        slot: after[slot - 1],
+                        ...(previous && { previous }),
+                        ...(ready.reconnected && { reconnected: true }),
+                    };
+                }
+                catch (e) {
+                    return {
+                        ok: false,
+                        error: `preset updated in slot ${slot} but verification failed: ${msg(e)}`,
+                    };
+                }
+            },
+        },
+        {
+            name: "obsbot_preset_rename",
+            description: `Rename preset slot 1|2|3. The slot must already be occupied. Names longer than ` +
+                `${PRESET_NAME_MAX} bytes are truncated to fit the wire frame. Verifies by re-reading ` +
+                "the slot list after writing.",
+            schema: presetRenameSchema,
+            handler: async (args) => {
+                const { slot, name, camera } = presetRenameSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                try {
+                    const before = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!before[slot - 1].occupied) {
+                        return { ok: false, error: `slot ${slot} is empty; save first` };
+                    }
+                    const clean = name.slice(0, PRESET_NAME_MAX);
+                    // The read path (decodePresetEntry) base64-decodes the stored name, but the
+                    // captured OBSBOT Center rename frame carried raw ASCII ("Preset1", "3reset2A"),
+                    // so the write side sends raw ASCII here too — per the capture. Whether the
+                    // device actually expects ASCII or base64 on the WRITE side is NOT yet
+                    // hardware-confirmed; flagged for the hardware verification task.
+                    await t.sendVendor(encodePresetSetName(t.nextSeq(), slot, clean));
+                    const after = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (after[slot - 1].name !== clean) {
+                        return { ok: false, error: "verification failed", expected: clean, actual: after[slot - 1].name };
+                    }
+                    return { ok: true, slot: after[slot - 1], ...(ready.reconnected && { reconnected: true }) };
+                }
+                catch (e) {
+                    return { ok: false, error: msg(e) };
+                }
+            },
+        },
+        {
+            name: "obsbot_preset_delete",
+            description: "Delete preset slot 1|2|3. The slot must be occupied. Verifies by re-reading the " +
+                "slot list after writing.",
+            schema: presetDeleteSchema,
+            handler: async (args) => {
+                const { slot, camera } = presetDeleteSchema.parse(args);
+                const ready = await gate(camera);
+                if (!ready.ok)
+                    return ready;
+                const t = ready.transport;
+                // Tracks whether the destructive write already left the host. If the
+                // post-write verify read throws, a bare error reads as "nothing happened"
+                // and invites a blind retry of an operation that already committed.
+                let sent = false;
+                try {
+                    const before = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (!before[slot - 1].occupied) {
+                        return { ok: false, error: `slot ${slot} is already empty` };
+                    }
+                    // Everything the delete is about to destroy, captured from the guard read.
+                    // Slots are create-once with no device-side history, so this response is the
+                    // caller's ONLY route back if the wrong slot was named.
+                    const destroyed = { name: before[slot - 1].name, pose: before[slot - 1].pose };
+                    await t.sendVendor(encodePresetDelete(t.nextSeq(), slot));
+                    sent = true;
+                    const after = await readPresetSlots(t, () => gate(camera), presetRead);
+                    if (after[slot - 1].occupied) {
+                        return { ok: false, error: "verification failed", expected: "empty", actual: "occupied" };
+                    }
+                    return { ok: true, deleted: destroyed, ...(ready.reconnected && { reconnected: true }) };
+                }
+                catch (e) {
+                    if (sent) {
+                        return {
+                            ok: false,
+                            error: `delete was sent and may have been applied, but verification failed: ${msg(e)}`,
+                            committed: "unknown",
+                        };
+                    }
+                    return { ok: false, error: msg(e) };
+                }
+            },
+        },
+        {
+            name: "obsbot_image_wb_auto",
+            description: "Enable auto white balance.",
+            schema: imageWbAutoSchema,
+            handler: async (args) => {
+                const { camera } = imageWbAutoSchema.parse(args);
+                const t = await getTransport(camera);
+                const { min } = await t.procAmpRange(VIDEO_PROCAMP_WHITE_BALANCE);
+                await t.procAmpSet(VIDEO_PROCAMP_WHITE_BALANCE, min, UVC_FLAG_AUTO);
+                return { ok: true, mode: "auto" };
+            },
+        },
+        {
+            name: "obsbot_image_wb_manual",
+            description: "Set white balance to a colour temperature in Kelvin (clamped to the device's " +
+                "supported range).",
+            schema: imageWbManualSchema,
+            handler: async (args) => {
+                const { temperature, camera } = imageWbManualSchema.parse(args);
+                const t = await getTransport(camera);
+                const { min, max } = await t.procAmpRange(VIDEO_PROCAMP_WHITE_BALANCE);
                 const value = clamp(Math.round(temperature), min, max);
                 await t.procAmpSet(VIDEO_PROCAMP_WHITE_BALANCE, value, UVC_FLAG_MANUAL);
-                return { ok: true, mode, temperature: value };
+                return { ok: true, mode: "manual", temperature: value };
             },
         },
         {
-            name: "obsbot_image_control",
+            name: "obsbot_image_adjust",
             description: "Adjust a standard image control: control is brightness | contrast | hue | " +
                 "saturation | sharpness | gain | backlight-compensation; level 0-100 is mapped onto " +
-                "the device's supported range for that control. Standard UVC (IAMVideoProcAmp), no auto.",
+                "the device's supported range for that control. Standard UVC (IAMVideoProcAmp), no auto. " +
+                "NOTE: `gain` and `backlight-compensation` are NOT implemented on the Tiny 2 — it " +
+                "reports them as zero-length controls — so they are refused with an error rather than " +
+                "silently doing nothing. The other five work.",
             schema: imageControlSchema,
             handler: async (args) => {
-                const { control, level } = imageControlSchema.parse(args);
+                const { control, level, camera } = imageControlSchema.parse(args);
                 const property = IMAGE_CONTROL_PROP[control];
-                const t = await getTransport();
+                const t = await getTransport(camera);
                 const { min, max } = await t.procAmpRange(property);
                 const value = percentToRange(level, min, max);
                 await t.procAmpSet(property, value, UVC_FLAG_MANUAL);
@@ -437,39 +998,68 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_exposure",
-            description: "Set exposure. mode 'auto' enables auto-exposure; mode 'manual' sets level 0-100 " +
-                "(0 darkest → 100 brightest), mapped onto the device's exposure range. " +
-                "Uses proprietary V3 frame protocol (CAM_SET_EXPOSURE_MODE + CAM_SET_EXPOSURE_TINY2) " +
-                "because the standard UVC/IAMCameraControl V4L2 path is a stub on the Tiny 2.",
-            schema: exposureSchema,
+            name: "obsbot_image_exposure_auto",
+            description: "Enable auto-exposure. Optional priority 'global' | 'face' selects the metering " +
+                "region (face-priority meters for a detected face). " +
+                "Uses the proprietary V3 frame protocol (CAM_SET_EXPOSURE_TINY2, which carries mode " +
+                "and value in one command) because the standard UVC/IAMCameraControl V4L2 path is a " +
+                "stub on the Tiny 2.",
+            schema: imageExposureAutoSchema,
             handler: async (args) => {
-                const { mode, level } = exposureSchema.parse(args);
-                const t = await getTransport();
-                if (mode === "auto") {
-                    await t.sendVendor(encodeSetExposureMode(false).buildFrame(t.nextSeq()));
-                    return { ok: true, mode };
+                const { priority, camera } = imageExposureAutoSchema.parse(args);
+                const t = await getTransport(camera);
+                // Mode and value go in ONE command — CAM_SET_EXPOSURE_TINY2 with a 5-byte
+                // [mode][value] payload. The separate CAM_SET_EXPOSURE_MODE command is inert
+                // on this device, and a 4-byte value payload is silently discarded.
+                // Device exposure range is 1..2500 (read from CAM_GET_EXPOSURE_RANGE_TINY2;
+                // the previous 0..65535 figure came from the Tiny4Linux reference and does
+                // not match this hardware). This branch carries no `level` input, so the
+                // value byte mirrors the combined tool's pre-split default (50%) — the
+                // device only acts on it once manual mode is selected.
+                const raw = percentToRange(50, 1, 2500);
+                await t.sendVendor(encodeSetExposure(false, raw).buildFrame(t.nextSeq()));
+                // Face vs global metering is a sel-6 uvcExt write applied after auto-exposure
+                // is on (readback surfaces at status offset 0x07). See encodeFaceAe.
+                if (priority) {
+                    await t.xuRaw(UVC_XU_SELECTOR, encodeFaceAe(priority === "face"));
+                    return { ok: true, mode: "auto", priority };
                 }
-                // Switch to manual mode via V3 frame protocol (CAM_SET_EXPOSURE_MODE)
-                await t.sendVendor(encodeSetExposureMode(true).buildFrame(t.nextSeq()));
-                // Translate 0-100 percentage to raw 16-bit exposure value.
-                // Tiny 2 exposure range is 0-65535 (confirmed by Tiny4Linux reference).
-                const raw = percentToRange(level, 0, 65535);
-                await t.sendVendor(encodeSetExposureValue(raw).buildFrame(t.nextSeq()));
-                return { ok: true, mode, level, raw };
+                return { ok: true, mode: "auto" };
+            },
+        },
+        {
+            name: "obsbot_image_exposure_manual",
+            description: "Set exposure level 0-100 (0 darkest → 100 brightest), mapped onto the device's " +
+                "exposure range. Also returns `raw`: the device-native exposure value the level mapped " +
+                "to, for diagnostics — `level` is the number to reason with. " +
+                "Uses the proprietary V3 frame protocol (CAM_SET_EXPOSURE_TINY2, which carries mode " +
+                "and value in one command) because the standard UVC/IAMCameraControl V4L2 path is a " +
+                "stub on the Tiny 2.",
+            schema: imageExposureManualSchema,
+            handler: async (args) => {
+                const { level, camera } = imageExposureManualSchema.parse(args);
+                const t = await getTransport(camera);
+                // Device exposure range is 1..2500 (read from CAM_GET_EXPOSURE_RANGE_TINY2;
+                // the previous 0..65535 figure came from the Tiny4Linux reference and does
+                // not match this hardware).
+                const raw = percentToRange(level, 1, 2500);
+                await t.sendVendor(encodeSetExposure(true, raw).buildFrame(t.nextSeq()));
+                return { ok: true, mode: "manual", level, raw };
             },
         },
         {
-            name: "obsbot_snapshot",
+            name: "obsbot_capture_snapshot",
             description: "Grab one still frame from the camera and return it as an image (for you to see " +
-                "and for framing/lighting/exposure checks). NOTE: before calling, ensure the camera " +
-                "is focused (call obsbot_focus with mode:'auto' for autofocus) unless otherwise " +
+                "and for framing/lighting/exposure checks). resolution is the longest edge in pixels, " +
+                "256-1920, default 640 — larger images cost proportionally more tokens, so ask for " +
+                "more only when you need the detail. NOTE: before calling, ensure the camera " +
+                "is focused (call obsbot_focus_auto for autofocus) unless otherwise " +
                 "directed. source: device (default) | virtual | ndi. " +
                 "If the camera is in use by another app, returns a message instead of an image.",
             schema: snapshotSchema,
             handler: async (args) => {
-                const { maxDim, quality, settleMs, source } = snapshotSchema.parse(args);
-                const t = await getTransport();
+                const { resolution, quality, settleMs, source, camera } = snapshotSchema.parse(args);
+                const t = await getTransport(camera);
                 let path;
                 if (source !== "device") {
                     const devices = await mgr.list();
@@ -488,7 +1078,9 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
                     path = match.path;
                 }
                 try {
-                    const snap = await t.snapshot({ path, maxDim, quality, settleMs });
+                    // The helper's wire field is still maxDim (shared with the Windows and
+                    // Linux helpers); `resolution` is the tool-facing name.
+                    const snap = await t.snapshot({ path, maxDim: resolution, quality, settleMs });
                     return {
                         content: [
                             { type: "image", data: snap.base64, mimeType: snap.mime },
@@ -516,11 +1108,12 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_record_start",
+            name: "obsbot_capture_record",
             description: "Start recording the camera to an MP4 (for the user). durationSec optional (open-ended " +
                 "recordings auto-stop after 60 min); audio defaults to on (the OBSBOT mic); outputPath " +
-                "optional (defaults under Videos\\\\OBSBOT). NOTE: before calling, ensure the camera " +
-                "is focused (call obsbot_focus with mode:'auto' for autofocus) unless otherwise " +
+                "optional (defaults to ~/Videos/OBSBOT on every platform, including macOS, where that " +
+                "is NOT the usual ~/Movies). NOTE: before calling, ensure the camera " +
+                "is focused (call obsbot_focus_auto for autofocus) unless otherwise " +
                 "directed. source: device|virtual|ndi. Returns a sessionId " +
                 "for obsbot_capture_stop.",
             schema: recordStartSchema,
@@ -539,9 +1132,9 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
         {
-            name: "obsbot_preview_start",
+            name: "obsbot_capture_preview",
             description: "Open a live preview window of the camera (for the user to watch). NOTE: before calling, " +
-                "ensure the camera is focused (call obsbot_focus with mode:'auto' for autofocus) unless " +
+                "ensure the camera is focused (call obsbot_focus_auto for autofocus) unless " +
                 "otherwise directed. source: device|virtual|ndi. " +
                 "Returns a sessionId for obsbot_capture_stop.",
             schema: previewStartSchema,
@@ -582,9 +1175,17 @@ export function createTools(getTransport, mgr, capture, session, debug = false)
             },
         },
     ];
-    // obsbot_probe is an RE/diagnostics-only tool (raw XU byte access); expose it only
-    // under --debug so normal deployments don't advertise it. get_status's raw block is
-    // gated the same way, inside its handler.
-    return debug ? toolDefs : toolDefs.filter((t) => t.name !== "obsbot_probe");
+    // obsbot_debug_probe is an RE/diagnostics-only tool (raw XU byte access); expose it
+    // only under --debug so normal deployments don't advertise it. get_status's raw
+    // block is gated the same way, inside its handler.
+    const filtered = debug ? toolDefs : toolDefs.filter((t) => t.name !== "obsbot_debug_probe");
+    // obsbot_gimbal_move_speed is hidden on Linux specifically: without live position
+    // feedback there (see LinuxTransport's class comment), a speed×duration burst can't
+    // be verified to stay within the gimbal's mechanical range before it gets there —
+    // unlike an absolute target, which is clamped up front regardless of current
+    // position. obsbot_gimbal_move/obsbot_gimbal_recenter remain fully available.
+    return process.platform === "linux"
+        ? filtered.filter((t) => t.name !== "obsbot_gimbal_move_speed")
+        : filtered;
 }
 //# sourceMappingURL=tools.js.map