cdp-toolkit 1.4.0 → 1.6.0

package/src/cdp/driver.ts

@@ -259,12 +259,15 @@ async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{
  * not "not armed in advance", so an honest capability set omits it rather than reading true by
  * construction. locate.text/locate.xpath both ride DOM.performSearch (see searchLocate above),
  * which is a real Chrome capability, not a line-budget artifact, so both ARE declared.
+ * capture.screencast rides Page.startScreencast / Page.screencastFrame / Page.screencastFrameAck,
+ * the streamed-repaint primitive behind start_screen_recording and stop_screen_recording.
  */
 const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "trace.performance", "heap.snapshot", "audit.lighthouse", "emulate.cpuThrottling",
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
   "screenshot.fullPage", "screenshot.element", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
+  "capture.screencast",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */
 class CdpPageDriver implements PageDriver {

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 36 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 41 tools.
  *
  * Context. Every tool in src/tools/ is a stateless one-shot on withPage():
  * open a socket, act, always close. That is only correct because a CDP `Uid`
@@ -126,6 +126,7 @@ export type Capability =
   | "trace.performance" // Chrome tracing, behind every performance_* tool
   | "heap.snapshot" // V8 heap snapshots
   | "audit.lighthouse" // shelling out to lighthouse against a debug port
+  | "capture.screencast" // streamed repaint frames (CDP Page.startScreencast); BiDi has no equivalent
   | "emulate.cpuThrottling" // CPU multiplier; absent from BiDi's emulation module
   | "emulate.mediaFeatures" // media type + features, e.g. prefers-color-scheme
   | "emulate.deviceMetrics" // past width/height: scale factor, mobile flag
@@ -151,6 +152,8 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   performance_trace: ["trace.performance"],
   take_heapsnapshot: ["heap.snapshot"],
   lighthouse_audit: ["audit.lighthouse"],
+  start_screen_recording: ["capture.screencast"],
+  stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],

package/src/index.ts

@@ -3,7 +3,8 @@
  *
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
- *      (snake_case string, all 29) to its raw-CDP implementation function. The
+ *      (snake_case string, all 29 of them) plus the toolkit's own superset
+ *      tools, 41 entries in all, to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
  *      flows on the same connection/timeout machinery the tools use.
@@ -12,8 +13,9 @@
  * value (or throws). See CONTRACT.md for the design rules each module follows.
  */
 
-// --- the 20 tools unified with Firefox onto one Driver-based implementation ---
+// --- the 23 tools unified with Firefox onto one Driver-based implementation ---
 // (list_pages/new_page/close_page/select_page, navigate_page/wait_for, evaluate_script,
+// list_cookies/set_cookie/delete_cookies,
 // take_snapshot, click/hover/drag/fill/fill_form/type_text/press_key/upload_file,
 // take_screenshot/emulate/resize_page, handle_dialog). See shared-tools.ts's file header for
 // the byte-identical-Chrome-behavior contract this bind honors, and for the 7 tools that stay
@@ -31,6 +33,8 @@ import {
   performanceAnalyzeInsight,
   performanceTrace,
 } from "./tools/performance.ts";
+// --- screen recording (Page.startScreencast + ffmpeg) ---
+import { startScreenRecording, stopScreenRecording } from "./tools/screencast.ts";
 // --- heap ---
 import { takeHeapsnapshot } from "./tools/heap.ts";
 // --- lighthouse (the sole non-CDP tool) ---
@@ -59,8 +63,12 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * (mock_request/list_mocks/clear_mocks : a persistent per-target fake backend),
  * plus a 3-tool cookie group (list_cookies/set_cookie/delete_cookies : the
  * cookie store including httpOnly cookies, which no page script can read or
- * write).
- * 39 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * write), plus a 3-tool lease group (claim_page/release_page/list_leases :
+ * opt-in tab ownership so many agents can share one browser), plus a 2-tool
+ * screen-recording pair (start_screen_recording/stop_screen_recording : a tab
+ * captured to an H.265 MP4 with per-frame durations, so a variable-rate
+ * repaint stream plays back at wallclock speed).
+ * 29 + 1 + 3 + 3 + 3 + 2 = 41 entries total. Listed explicitly so the mapping is auditable at a glance and
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -110,6 +118,9 @@ export const TOOLS = {
   performance_stop_trace: performanceStopTrace,
   performance_analyze_insight: performanceAnalyzeInsight,
   performance_trace: performanceTrace,
+  // screen recording (2) : toolkit addition, a tab-to-H.265-MP4 pair over Page.startScreencast
+  start_screen_recording: startScreenRecording,
+  stop_screen_recording: stopScreenRecording,
   // heap (1)
   take_heapsnapshot: takeHeapsnapshot,
   // lighthouse (1) : the only non-CDP tool

package/src/leases-tools.ts

@@ -1,7 +1,7 @@
 /**
  * The three lease tools, shaped like src/shared-tools.ts entries
  * ((driver, args) => Promise<result>) so ONE implementation serves Chrome and
- * Firefox, exactly as the other 20 unified tools do.
+ * Firefox, exactly as the 23 unified tools in that file do.
  */
 import type { BrowserDriver } from "./driver.ts";
 import { newTrackedPage } from "./origins.ts";

package/src/leases.ts

@@ -265,7 +265,7 @@ export async function releaseLeaseFor(backend: LeaseBackend, targetId: string):
  * This exists so enforcement can stay at ONE point per resolution path while
  * the token still reaches it. The token arrives as a key on a tool's args
  * object, many frames above resolveTarget, and threading a parameter through
- * all 36 tools would put the burden on every future contributor to remember
+ * all 41 tools would put the burden on every future contributor to remember
  * the check exists: one missed tool would silently defeat the feature for that
  * tool. mcp.ts and cli.ts open this scope once per dispatch instead, so a tool
  * added tomorrow is covered with no action from whoever writes it.

package/src/manifest.ts

@@ -1118,6 +1118,76 @@ export const MANIFEST: ToolSpec[] = [
       "additionalProperties": false
     }
   },
+  {
+    "name": "start_screen_recording",
+    "description": "Start recording the target tab to video over raw CDP (Page.startScreencast), holding one persistent connection open and spooling every Page.screencastFrame to disk. Chrome emits a frame ON REPAINT, not on a clock, so the stream is variable-rate: each frame is timestamped into a ledger and stop_screen_recording turns those timestamps into per-frame display durations, which is what makes a still page hold one long frame instead of the video racing or freezing. Every frame is acked immediately (an unacked frame stalls the stream). ffmpeg is probed here, not at stop, so a missing encoder fails before a recording is captured and thrown away. Must be paired with stop_screen_recording WITHIN THE SAME PROCESS (the frames are events on this connection and cannot be re-attached from another process, so the pair works under the MCP server, not the one-process-per-call CLI). Throws if a recording is already in progress for the target; recordings on DIFFERENT targets run concurrently. Chrome only: WebDriver BiDi has no screencast primitive, so both tools are absent under --browser firefox.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
+        "target": {
+          "type": "string",
+          "description": "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "jpeg",
+            "png"
+          ],
+          "description": "Frame image format. Defaults to jpeg (far smaller per repaint); png is lossless. quality applies to jpeg only."
+        },
+        "quality": {
+          "type": "number",
+          "description": "JPEG frame quality 0-100. Ignored for png. Omitted by default, which leaves Chrome's own default in place."
+        },
+        "maxWidth": {
+          "type": "number",
+          "description": "Cap the streamed frame width in pixels. Also the way to pin frame size if the viewport might change mid-recording."
+        },
+        "maxHeight": {
+          "type": "number",
+          "description": "Cap the streamed frame height in pixels."
+        },
+        "everyNthFrame": {
+          "type": "number",
+          "description": "Capture only every Nth repaint (1 = every frame). Reduces spool size on a busy page; per-frame durations keep playback at wallclock speed either way."
+        },
+        "bringToFront": {
+          "type": "boolean",
+          "description": "Activate the tab (Page.bringToFront) before recording. Default false. A fully backgrounded or occluded tab may never repaint, and a recording of one captures 0 frames."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "stop_screen_recording",
+    "description": "Stop the recording started by start_screen_recording, assemble the spooled frames into an MP4 with ffmpeg using PER-FRAME durations from the ledger (frame N is held until frame N+1 painted; the last frame is held until this call), and return {path,bytes,durationMs,frameCount,encodedFrames,codec,encoder,width,height,droppedFrames,target}. Encoder ladder, probed once at start: hevc_videotoolbox then h264_videotoolbox then libx265 then libx264, with -tag:v hvc1 on HEVC so QuickTime plays it, +faststart, yuv420p, and even dimensions forced. With one recording in flight 'target' may be omitted; with several it is required, because guessing which to stop can lose another agent's recording. Throws if nothing is recording in this process, and throws rather than writing a silent empty video when 0 frames arrived. On an ffmpeg failure the spooled frames are KEPT and the spool path plus the exact command are named in the error. Encoded video tops out at 25 fps: ffmpeg's concat demuxer represents image timestamps on a 1/25s grid, so frames captured less than 40ms apart are coalesced deliberately (frameCount reports what was captured, encodedFrames what reached the video) instead of being dropped silently by ffmpeg. durationMs is the sum of the encoded durations; the file itself runs one 40ms step longer, because the concat demuxer needs the final frame repeated for its hold to count.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Opaque lease token from claim_page. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
+        "target": {
+          "type": "string",
+          "description": "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        },
+        "savePath": {
+          "type": "string",
+          "description": "Override the output file path. Default: /tmp/cdp-toolkit/screen-recording-<targetIdShort>-<stamp>.mp4."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "take_heapsnapshot",
     "description": "Capture a V8 heap snapshot of the selected page target over raw CDP (HeapProfiler.takeHeapSnapshot, accumulating addHeapSnapshotChunk events) and write it as a .heapsnapshot JSON file loadable by the DevTools Memory panel; returns {path,bytes,chunks,target} only and does not parse/summarize the snapshot. Writes under /tmp/cdp-toolkit (CDP_ARTIFACT_DIR) unless savePath is given.",

package/src/mcp.ts

@@ -23,7 +23,7 @@ import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
 
-const VERSION = "1.4.0";
+const VERSION = "1.6.0";
 
 // --browser is read once at startup (MCP has no per-call notion of backend): explicit flag,
 // else CDP_BROWSER env var, else "chrome" (zero behavior change for existing users/configs).

package/src/shared-tools.ts

@@ -3,7 +3,8 @@
  * (ADR-001), used by BOTH Chrome (via cdp/driver.ts's createCdpDriver()) and Firefox (via
  * bidi/driver.ts's createFirefoxDriver()). This file replaces the split that used to exist
  * between src/tools/*.ts (raw CDP, Chrome only) and src/neutral.ts (Driver-based, Firefox only)
- * for the 20 tools below.
+ * for 20 of the 23 tools below. The other three, the list_cookies/set_cookie/delete_cookies
+ * cookie group, landed here directly and never had a Chrome-only copy.
  *
  * THE HARD REQUIREMENT this file exists to satisfy: Chrome's return shape, timing, and quirks
  * stay byte-identical to what src/tools/*.ts produced before this migration: that already