cbrowser 18.70.0 → 18.71.0

package/dist/mcp-tools/base/capture-tools.js

@@ -0,0 +1,667 @@
+/**
+ * CBrowser MCP Tools - Screen Capture Tools
+ *
+ * Screen capture (pixels -> GIF/WebP/video), exposed as `capture_start`,
+ * `capture_stop`, `capture_status`.
+ *
+ * Distinct from the `record` feature, which records user ACTIONS for test
+ * generation. Nothing here touches that.
+ *
+ * The response discipline is the point of this module: a recording is hundreds
+ * of frames and tens of megabytes of video, none of which can cross an MCP
+ * boundary. Frames and artifacts are returned as PATHS; the only inlined pixels
+ * are a contact sheet sized to whatever is left of the response budget after
+ * the JSON payload is measured.
+ *
+ * @copyright 2026 Alexandria Eden alexandria.shai.eden@gmail.com https://cbrowser.ai
+ * @license MIT
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { z } from "zod";
+import { getPaths } from "../../config.js";
+import { buildContactSheet } from "../../recording/contact-sheet.js";
+import { VideoCaptureSession } from "../../recording/engine.js";
+import { VIEWPORT_PRESETS } from "../../types.js";
+import { buildContentWithScreenshots, MAX_RESPONSE_SIZE } from "../screenshot-utils.js";
+/** Formats the engine can encode. */
+const CAPTURE_FORMATS = ["gif", "webp", "mp4", "webm"];
+/** Change points and gaps are truncated at these counts before serialising. */
+const MAX_CHANGE_POINTS = 200;
+const MAX_FRAME_GAPS = 50;
+const MAX_CONSOLE_ERRORS = 20;
+/**
+ * Base64 inflates a payload by 4/3; the same 1.37 fudge `screenshot` uses in
+ * src/browser.ts, which also covers the JSON envelope around the block.
+ */
+const BASE64_OVERHEAD = 1.37;
+/**
+ * A contact sheet smaller than this is not worth inlining — below roughly this
+ * size the JPEG is too degraded to read, so the path alone is more useful.
+ */
+const MIN_USEFUL_SHEET_BYTES = 12000;
+// ===========================================================================
+// Session registry
+// ===========================================================================
+/**
+ * Live capture sessions, keyed by browser token.
+ *
+ * Capture is stateful across tool calls — `capture_start` returns before the
+ * recording ends — so the session has to outlive the handler. Keying by the
+ * same `_browserToken` that carries page continuity means a caller driving two
+ * browsers gets two independent captures.
+ */
+const sessions = new Map();
+/**
+ * The most recent finished capture per key.
+ *
+ * Without this, `capture_status` after a stop reports "no capture has been
+ * started" — the session is gone from the live map and the completed run
+ * vanishes with it, which reads as though the capture never happened.
+ */
+const finished = new Map();
+/** Sessions are keyed by token; an untokened caller shares the default slot. */
+function sessionKey(token) {
+    return token ?? "__default__";
+}
+/** Exposed for tests and for `reset_browser`-style teardown. */
+export function clearCaptureSessions() {
+    sessions.clear();
+    finished.clear();
+}
+/**
+ * A capture started by another process (the CLI or its daemon), discovered
+ * through the pointer file the CLI maintains at `videosDir/active.json`.
+ *
+ * Read-only on purpose: this surface does not write the pointer, because the
+ * CLI's `capture stop` signals the pid it finds there, and pointing that at the
+ * long-lived MCP server would let a CLI command kill an unrelated process.
+ * Cross-surface visibility is one-directional until the daemon owns the pointer.
+ */
+function foreignActiveCapture() {
+    try {
+        const pointer = join(getPaths().videosDir, "active.json");
+        if (!existsSync(pointer))
+            return null;
+        const active = JSON.parse(readFileSync(pointer, "utf-8"));
+        if (typeof active.pid !== "number")
+            return null;
+        // A stale pointer outlives its process; signal 0 tests liveness without
+        // touching the process.
+        try {
+            process.kill(active.pid, 0);
+        }
+        catch {
+            return null;
+        }
+        return active;
+    }
+    catch {
+        return null;
+    }
+}
+// ===========================================================================
+// Argument parsing
+// ===========================================================================
+/** Parse "5s", "2m", "1500ms" or a bare millisecond count. */
+export function parseDurationMs(input) {
+    const match = /^(\d+(?:\.\d+)?)\s*(ms|s|m)?$/i.exec(input.trim());
+    if (!match) {
+        throw new Error(`Invalid duration "${input}" - use 5s, 2m, 1500ms or a millisecond count`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = (match[2] || "ms").toLowerCase();
+    const ms = unit === "s" ? value * 1000 : unit === "m" ? value * 60_000 : value;
+    if (ms <= 0)
+        throw new Error(`Invalid duration "${input}" - must be greater than zero`);
+    return Math.round(ms);
+}
+/** Parse "gif,webp,mp4" into validated formats. */
+export function parseFormats(input) {
+    const parsed = input.split(",").map((f) => f.trim().toLowerCase()).filter(Boolean);
+    const bad = parsed.filter((f) => !CAPTURE_FORMATS.includes(f));
+    if (bad.length > 0) {
+        throw new Error(`Unknown format(s): ${bad.join(", ")}. Supported: ${CAPTURE_FORMATS.join(", ")}`);
+    }
+    if (parsed.length === 0)
+        throw new Error("format requires at least one format");
+    return parsed;
+}
+/**
+ * Resolve a viewport argument: either `WxH` or the name of a built-in preset
+ * (`mobile`, `tablet`, `desktop-lg`, ...).
+ */
+export function parseViewport(input) {
+    const trimmed = input.trim();
+    const match = /^(\d+)\s*x\s*(\d+)$/i.exec(trimmed);
+    if (match) {
+        const width = parseInt(match[1], 10);
+        const height = parseInt(match[2], 10);
+        if (width < 1 || height < 1) {
+            throw new Error(`Invalid viewport "${input}" - width and height must be positive`);
+        }
+        return { width, height };
+    }
+    const preset = VIEWPORT_PRESETS.find((p) => p.name.toLowerCase() === trimmed.toLowerCase());
+    if (preset)
+        return { width: preset.width, height: preset.height };
+    throw new Error(`Invalid viewport "${input}" - use WIDTHxHEIGHT (e.g. 1280x720) or a preset: ` +
+        VIEWPORT_PRESETS.map((p) => p.name).join(", "));
+}
+/** Parse "x,y,width,height" into a rect. */
+export function parseRegion(input) {
+    const parts = input.split(",").map((p) => Number(p.trim()));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n))) {
+        throw new Error(`Invalid region "${input}" - use x,y,width,height (e.g. 0,0,800,600)`);
+    }
+    const [x, y, width, height] = parts;
+    if (width <= 0 || height <= 0) {
+        throw new Error(`Invalid region "${input}" - width and height must be positive`);
+    }
+    return { x, y, width, height };
+}
+/**
+ * Build the `capture_stop` JSON payload from a manifest.
+ *
+ * Deliberately excludes the frame array: 500 frames of paths, crops, SSIM
+ * scores and per-frame console/network records is megabytes of JSON that would
+ * blow the response budget and tell the model nothing it can act on. The frames
+ * live on disk and the directory is named instead. Unbounded lists
+ * (change points, gaps, console errors) are truncated with their true totals
+ * reported alongside, so the model can tell "3 change points" from
+ * "200 shown of 4,812".
+ *
+ * Pure and exported so the budget can be tested without running a browser.
+ */
+export function buildCaptureStopPayload(manifest, extra) {
+    const consoleErrors = [];
+    let networkTotal = 0;
+    let consoleErrorTotal = 0;
+    for (const frame of manifest.frames) {
+        networkTotal += frame.network.length;
+        for (const entry of frame.console) {
+            if (entry.type !== "error")
+                continue;
+            consoleErrorTotal++;
+            if (consoleErrors.length < MAX_CONSOLE_ERRORS) {
+                // Long stack-trace-bearing messages are the usual budget offender.
+                consoleErrors.push(entry.text.length > 300 ? `${entry.text.slice(0, 300)}...` : entry.text);
+            }
+        }
+    }
+    const encodeErrors = extra.encodeErrors && Object.keys(extra.encodeErrors).length > 0
+        ? extra.encodeErrors
+        : undefined;
+    return {
+        success: true,
+        slug: manifest.slug,
+        manifest_path: extra.manifestPath,
+        out_dir: extra.outDir,
+        frames: manifest.frames.length,
+        target_fps: manifest.target_fps,
+        actual_fps: manifest.actual_fps,
+        duration_ms: manifest.duration_ms,
+        capture_method: manifest.capture_method,
+        engine: manifest.engine,
+        output_dims: manifest.output_dims,
+        target: manifest.target,
+        ...(manifest.region_clamped !== undefined ? { region_clamped: manifest.region_clamped } : {}),
+        artifacts: manifest.artifacts,
+        ...(encodeErrors ? { encode_errors: encodeErrors } : {}),
+        change_points: manifest.change_points.slice(0, MAX_CHANGE_POINTS),
+        change_points_total: manifest.change_points.length,
+        frame_gaps: manifest.frame_gaps.slice(0, MAX_FRAME_GAPS),
+        frame_gaps_total: manifest.frame_gaps.length,
+        console_errors: consoleErrors,
+        console_errors_total: consoleErrorTotal,
+        network_requests_total: networkTotal,
+        frames_dir: join(extra.outDir, "frames"),
+        ...(extra.contactSheet ? { contact_sheet: extra.contactSheet } : {}),
+        ...(extra.contactSheetNote ? { contact_sheet_note: extra.contactSheetNote } : {}),
+        note: "Individual frames and video artifacts are on disk, not inlined — read them by path. " +
+            "The contact sheet is an evenly spaced visual sample of the recording.",
+    };
+}
+/**
+ * Last line of defence on the response budget.
+ *
+ * The payload builder and the contact-sheet budget already keep the response
+ * small, but "small by construction" is a claim about code that can drift. This
+ * measures the actual serialized content blocks and sheds until they fit:
+ * image blocks first (the sheet is a convenience, the paths are the payload),
+ * then the text block itself, replaced by a minimal pointer to the manifest.
+ *
+ * An over-budget response is therefore not merely unlikely, it cannot be
+ * returned — the tool would have to skip this function to emit one.
+ */
+export function enforceResponseBudget(content, maxBytes = MAX_RESPONSE_SIZE, fallbackText = '{"success":true,"note":"Response exceeded the size budget; read the manifest from disk."}') {
+    const size = (blocks) => Buffer.byteLength(JSON.stringify(blocks));
+    if (size(content) <= maxBytes)
+        return content;
+    // Shed pixels before prose: the paths are what the caller acts on.
+    const withoutImages = content.filter((block) => block.type !== "image");
+    if (size(withoutImages) <= maxBytes)
+        return withoutImages;
+    const minimal = withoutImages
+        .filter((block) => block.type === "text")
+        .slice(0, 1)
+        .map((block) => ({ ...block, text: fallbackText }));
+    return (size(minimal) <= maxBytes ? minimal : []);
+}
+/**
+ * Byte budget left for an inlined contact sheet once the JSON payload is
+ * accounted for. Returns 0 when there is no room worth using.
+ */
+export function contactSheetBudget(payloadBytes, totalBudget = MAX_RESPONSE_SIZE) {
+    const remaining = totalBudget - payloadBytes;
+    if (remaining <= 0)
+        return 0;
+    const budget = Math.floor(remaining / BASE64_OVERHEAD);
+    return budget >= MIN_USEFUL_SHEET_BYTES ? budget : 0;
+}
+/**
+ * Resolve a selector to a fixed capture region.
+ *
+ * The engine has no element target, so an element capture is resolved to the
+ * element's bounding box ONCE, at start. The region does not follow the element
+ * if it later moves — that limitation is reported back to the caller rather
+ * than hidden.
+ */
+async function resolveElementRegion(page, selector, padding) {
+    const box = await page.locator(selector).first().boundingBox();
+    if (!box) {
+        throw new Error(`Element "${selector}" is not visible, so it has no region to capture`);
+    }
+    return {
+        x: box.x - padding,
+        y: box.y - padding,
+        width: box.width + padding * 2,
+        height: box.height + padding * 2,
+    };
+}
+/** Start a capture on the given browser. Returns the payload object. */
+export async function startCapture(browser, args, token) {
+    const key = sessionKey(token);
+    const existing = sessions.get(key);
+    if (existing && existing.session.status().state === "recording") {
+        throw new Error(`A capture is already running (${existing.session.status().slug}). ` +
+            "Call capture_stop before starting another.");
+    }
+    if (args.viewport) {
+        const size = parseViewport(args.viewport);
+        const page = await browser.getPage();
+        await page.setViewportSize(size);
+    }
+    if (args.url)
+        await browser.navigate(args.url);
+    const page = await browser.getPage();
+    if (args.region && args.element) {
+        throw new Error("Pass region or element, not both");
+    }
+    let target;
+    let elementNote;
+    if (args.region) {
+        target = { kind: "region", rect: parseRegion(args.region) };
+    }
+    else if (args.element) {
+        const padding = args.padding ?? 0;
+        target = { kind: "region", rect: await resolveElementRegion(page, args.element, padding) };
+        elementNote =
+            `Region resolved from selector "${args.element}" at capture start. ` +
+                "It is fixed for the run and does not follow the element if it moves.";
+    }
+    // The browser's own config is private, so the engine family is read off the
+    // live Playwright context rather than duplicated from CBrowser config.
+    const engineName = page.context().browser()?.browserType().name();
+    const engine = engineName === "firefox" ? "firefox" : engineName === "webkit" ? "webkit" : "chromium";
+    const options = {
+        ...(args.fps !== undefined ? { fps: args.fps } : {}),
+        ...(args.duration !== undefined ? { durationMs: parseDurationMs(args.duration) } : {}),
+        ...(target ? { target } : {}),
+        ...(args.format !== undefined ? { format: parseFormats(args.format) } : {}),
+        ...(args.quality !== undefined ? { quality: args.quality } : {}),
+        ...(args.max_frames !== undefined ? { maxFrames: args.max_frames } : {}),
+        ...(args.name !== undefined ? { slug: args.name } : {}),
+        ...(args.out_dir !== undefined ? { outDir: resolve(args.out_dir) } : {}),
+    };
+    // videosDir, not recordingsDir — the latter is the ACTION-recording feature's
+    // .json store, and screenshotsDir is swept by the 1-hour retention cleanup,
+    // which would delete users' GIFs. Session-scoped to match the CLI layout
+    // (~/.cbrowser/videos/<sessionId>/<slug>/): without the session segment, two
+    // concurrent captures that pick the same slug interleave frames into one dir.
+    const paths = getPaths();
+    const session = new VideoCaptureSession(page, engine, join(paths.videosDir, paths.sessionId));
+    const status = await session.start(options);
+    sessions.set(key, { session, ...(args.url ? { url: args.url } : {}) });
+    return {
+        success: true,
+        state: status.state,
+        slug: status.slug,
+        out_dir: status.outDir,
+        capture_method: status.captureMethod,
+        engine,
+        ...(elementNote ? { element_note: elementNote } : {}),
+        note: "Capture is event-driven: a page that never repaints emits no frames, and still " +
+            "stretches are reported as frame_gaps rather than padded out. Interact with the page " +
+            "(navigate, click, scroll) to produce frames, then call capture_stop.",
+    };
+}
+/**
+ * Stop the capture and build the response payload plus a budget-fitted contact
+ * sheet. Returns the payload and the sheet path (if one was produced).
+ */
+export async function stopCapture(token) {
+    const key = sessionKey(token);
+    const entry = sessions.get(key);
+    if (!entry) {
+        throw new Error("No capture has been started on this browser session. Call capture_start first.");
+    }
+    const result = await entry.session.stop();
+    const status = entry.session.status();
+    const manifest = result.manifest;
+    // Frame paths are relative to the manifest, so they resolve against outDir.
+    const framePaths = manifest.frames.map((f) => isAbsolute(f.path) ? f.path : join(status.outDir, f.path));
+    // Size the JSON first, then spend what is left of the budget on pixels.
+    const provisional = buildCaptureStopPayload(manifest, {
+        manifestPath: result.manifestPath,
+        outDir: status.outDir,
+        encodeErrors: result.encodeErrors,
+        contactSheet: join(status.outDir, "contact-sheet.jpg"),
+    });
+    const budget = contactSheetBudget(Buffer.byteLength(JSON.stringify(provisional, null, 2)));
+    let contactSheet;
+    let contactSheetNote;
+    const usable = framePaths.filter((p) => existsSync(p));
+    if (usable.length === 0) {
+        contactSheetNote = "No frames were captured, so there is no contact sheet.";
+    }
+    else if (budget === 0) {
+        contactSheetNote = "Response budget left no room to inline a contact sheet.";
+    }
+    else {
+        try {
+            const sheet = await buildContactSheet({
+                framePaths: usable,
+                outPath: join(status.outDir, "contact-sheet.jpg"),
+                maxBytes: budget,
+            });
+            contactSheet = sheet.path;
+        }
+        catch (e) {
+            // A capture that succeeded is not failed by an unrenderable summary.
+            contactSheetNote = `Contact sheet could not be built: ${e.message}`;
+        }
+    }
+    const payload = buildCaptureStopPayload(manifest, {
+        manifestPath: result.manifestPath,
+        outDir: status.outDir,
+        encodeErrors: result.encodeErrors,
+        ...(contactSheet ? { contactSheet } : {}),
+        ...(contactSheetNote ? { contactSheetNote } : {}),
+    });
+    finished.set(key, {
+        slug: manifest.slug,
+        outDir: status.outDir,
+        manifestPath: result.manifestPath,
+        frames: manifest.frames.length,
+        durationMs: manifest.duration_ms,
+        actualFps: manifest.actual_fps,
+        stoppedAt: new Date().toISOString(),
+    });
+    sessions.delete(key);
+    return { payload, ...(contactSheet ? { contactSheet } : {}) };
+}
+/**
+ * Describe a capture running somewhere other than this browser session, if any:
+ * another token on this server, or another process (CLI / daemon).
+ */
+function runningElsewhere() {
+    for (const [otherKey, other] of sessions) {
+        const status = other.session.status();
+        if (status.state !== "recording")
+            continue;
+        return {
+            scope: "another browser token on this server",
+            slug: status.slug,
+            out_dir: status.outDir,
+            frames: status.frames,
+            elapsed_ms: status.elapsedMs,
+            ...(other.url ? { url: other.url } : {}),
+            note: "Pass that call's _browserToken to capture_stop; this session's " +
+                "capture_stop will not find it." +
+                (otherKey === "__default__" ? " It was started without a token." : ""),
+        };
+    }
+    const foreign = foreignActiveCapture();
+    if (foreign) {
+        return {
+            scope: `another process (pid ${foreign.pid})`,
+            slug: foreign.slug,
+            out_dir: foreign.outDir,
+            started_at: foreign.startedAt,
+            ...(foreign.url ? { url: foreign.url } : {}),
+            note: "Started outside the MCP server (CLI or daemon). It is stopped from the " +
+                "process that started it; capture_stop here will not find it.",
+        };
+    }
+    return null;
+}
+/**
+ * Report the running or most recent capture for this browser session.
+ *
+ * Two rules, in tension, both honoured:
+ *   - A running capture is never invisible. If one is live on another token or
+ *     in another process, it is always surfaced.
+ *   - The caller's own capture is never masked by someone else's. A session
+ *     that just finished a recording is told about its own run first, with the
+ *     other capture attached alongside rather than in place of it.
+ *
+ * The failure this replaces: after `capture_stop`, status reported
+ * "No capture has been started on this browser session" — the completed run
+ * vanished with the session object, reading as though it never happened.
+ */
+export function captureStatus(token) {
+    const key = sessionKey(token);
+    const elsewhere = runningElsewhere();
+    const withElsewhere = (base) => elsewhere ? { ...base, also_running_elsewhere: elsewhere } : base;
+    // 1. This session's own capture, running or just stopped.
+    const entry = sessions.get(key);
+    if (entry) {
+        const status = entry.session.status();
+        return withElsewhere({
+            success: true,
+            state: status.state,
+            slug: status.slug,
+            out_dir: status.outDir,
+            frames: status.frames,
+            elapsed_ms: status.elapsedMs,
+            capture_method: status.captureMethod,
+            ...(status.manifestPath ? { manifest_path: status.manifestPath } : {}),
+            ...(entry.url ? { url: entry.url } : {}),
+        });
+    }
+    // 2. This session's most recent completed capture.
+    const own = finished.get(key);
+    if (own)
+        return withElsewhere(finishedPayload(own));
+    // 3. Nothing of this session's own — surface whatever is running elsewhere.
+    if (elsewhere) {
+        return {
+            success: true,
+            state: "recording",
+            started_by: elsewhere.scope,
+            ...elsewhere,
+        };
+    }
+    // 4. Any other session's completed capture.
+    const recent = mostRecentFinished();
+    if (recent)
+        return finishedPayload(recent);
+    return {
+        success: true,
+        state: "idle",
+        note: "No capture has been started on this browser session.",
+    };
+}
+function finishedPayload(capture) {
+    return {
+        success: true,
+        state: "stopped",
+        slug: capture.slug,
+        out_dir: capture.outDir,
+        manifest_path: capture.manifestPath,
+        frames: capture.frames,
+        duration_ms: capture.durationMs,
+        actual_fps: capture.actualFps,
+        stopped_at: capture.stoppedAt,
+        note: "No capture is running on this session. This is its most recent completed capture.",
+    };
+}
+/** Most recently stopped capture across all keys. */
+function mostRecentFinished() {
+    let best;
+    for (const candidate of finished.values()) {
+        if (!best || candidate.stoppedAt > best.stoppedAt)
+            best = candidate;
+    }
+    return best;
+}
+/** Shared error envelope, matching the house shape for tool failures. */
+function errorContent(error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+            },
+        ],
+    };
+}
+// ===========================================================================
+// Registration
+// ===========================================================================
+/** Input schema shared by both servers, so the two cannot drift. */
+export const captureStartSchema = {
+    url: z.string().optional().describe("URL to navigate to before capturing. Omit to capture the current page."),
+    fps: z.number().optional().describe("Target frames per second (default: 10)"),
+    duration: z.string().optional().describe("Auto-stop after this long: 5s, 2m, 1500ms. Omit for an open-ended capture stopped by capture_stop."),
+    viewport: z.string().optional().describe("Viewport as WIDTHxHEIGHT (e.g. 1280x720) or a preset name (mobile, tablet, desktop, desktop-lg)"),
+    region: z.string().optional().describe("Capture a fixed region as x,y,width,height (e.g. 0,0,800,600). Clamped to the viewport."),
+    element: z.string().optional().describe("CSS selector to capture. Resolved to the element's bounding box once at start; the region does not follow the element if it moves."),
+    padding: z.number().optional().describe("Padding in pixels around the element region (default: 0)"),
+    format: z.string().optional().describe("Comma-separated output formats: gif,webp,mp4,webm (default: gif). mp4 needs a full ffmpeg; the bundled one does webm."),
+    quality: z.number().optional().describe("JPEG quality for captured frames, 1-100 (default: 80)"),
+    max_frames: z.number().optional().describe("Hard cap on retained frames (default: 3000)"),
+    name: z.string().optional().describe("Capture name / slug"),
+    out_dir: z.string().optional().describe("Output directory (default: a slug directory under the recordings dir)"),
+    _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
+};
+export const captureStopSchema = {
+    _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
+};
+export const captureStatusSchema = {
+    _browserToken: z.string().optional().describe("Browser session token from a previous tool call"),
+};
+const CAPTURE_START_DESCRIPTION = "Start capturing the screen to GIF/WebP/video. Records PIXELS over time — distinct from the " +
+    "`record` tool family, which records user actions for test generation. Capture runs in the " +
+    "background: call capture_start, interact with the page, then capture_stop. " +
+    "IMPORTANT: If you received a _browserToken from a previous tool call, you MUST pass it here " +
+    "to capture the same page. Without it, you get a blank new browser.";
+const CAPTURE_STOP_DESCRIPTION = "Stop the running screen capture, encode the requested formats and return the manifest path, " +
+    "artifact paths, change points and an inlined contact sheet (an evenly spaced visual sample). " +
+    "Frames and video are returned as paths, never inlined — read them from disk if you need them.";
+const CAPTURE_STATUS_DESCRIPTION = "Report the running or most recent screen capture for this browser session: state, frame count, " +
+    "elapsed time and output directory.";
+/**
+ * Register capture tools (3 tools: capture_start, capture_stop, capture_status)
+ */
+export function registerCaptureTools(server, { getBrowser, getBrowserByToken }) {
+    /** Resolve the browser + token exactly as the other tool modules do. */
+    const resolveBrowser = async (_browserToken) => {
+        if (getBrowserByToken) {
+            const result = await getBrowserByToken(_browserToken);
+            return { browser: result.browser, token: result.token };
+        }
+        return { browser: await getBrowser() };
+    };
+    server.registerTool("capture_start", {
+        title: "Start Screen Capture",
+        description: CAPTURE_START_DESCRIPTION,
+        inputSchema: captureStartSchema,
+        annotations: {
+            title: "Start Screen Capture",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
+    }, async ({ _browserToken, ...args }) => {
+        try {
+            const { browser, token } = await resolveBrowser(_browserToken);
+            const payload = await startCapture(browser, args, token);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...payload, ...(token ? { _browserToken: token } : {}) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return errorContent(error);
+        }
+    });
+    server.registerTool("capture_stop", {
+        title: "Stop Screen Capture",
+        description: CAPTURE_STOP_DESCRIPTION,
+        inputSchema: captureStopSchema,
+        annotations: {
+            title: "Stop Screen Capture",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ _browserToken }) => {
+        try {
+            const { token } = await resolveBrowser(_browserToken);
+            const { payload, contactSheet } = await stopCapture(token);
+            return {
+                content: enforceResponseBudget(buildContentWithScreenshots({ ...payload, ...(token ? { _browserToken: token } : {}) }, contactSheet)),
+            };
+        }
+        catch (error) {
+            return errorContent(error);
+        }
+    });
+    server.registerTool("capture_status", {
+        title: "Screen Capture Status",
+        description: CAPTURE_STATUS_DESCRIPTION,
+        inputSchema: captureStatusSchema,
+        annotations: {
+            title: "Screen Capture Status",
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ _browserToken }) => {
+        try {
+            const { token } = await resolveBrowser(_browserToken);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ ...captureStatus(token), ...(token ? { _browserToken: token } : {}) }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return errorContent(error);
+        }
+    });
+}
+export { CAPTURE_START_DESCRIPTION, CAPTURE_STOP_DESCRIPTION, CAPTURE_STATUS_DESCRIPTION };
+//# sourceMappingURL=capture-tools.js.map