@browserbridge/bbx 1.12.5 → 1.14.1

package/PRIVACY.md

@@ -89,6 +89,10 @@ Browser Bridge keeps data only as long as needed for the current local session a
 - Optional CDP network capture is bounded in memory, explicitly started/stopped, expires after a safety interval, and is cleared on relevant debugger, tab, or access teardown.
 - HAR export does not start, stop, or clear capture. Inline size limits remove whole oldest entries; artifact delivery uses opaque owner-scoped handles with no browser-host path. Artifacts expire after five minutes, are removed on daemon/extension teardown, and use private daemon directory/file modes on POSIX systems.
 - Recovery telemetry is held in fixed five-second buckets over a five-minute process-local window. Extension-side summaries reset with the extension service worker, daemon summaries reset with the daemon, and neither is durable history.
+- Opt-in activity recording captures event-time labels/selectors, route changes, and timing correlations. Input values are redacted. Optional network response bodies and messages receive best-effort text redaction; binary content and renderer pixels are not redacted. Child-tab capture is limited to opener descendants inside the enabled window.
+- Opt-in durable recording writes private, bounded journals on the daemon machine. A secret journal capability permits retrieval after client, extension, or daemon restart. Journals expire 24 hours after the last write and are pruned during journal operations, or can be explicitly deleted. Revocation stops capture but preserves already-written evidence. Files exported by the client persist until you delete them.
+- The `downloads` permission supports browser-native downloads, progress, pause/resume, and cancellation for downloads BBX starts. Downloaded files and browser download history follow Chrome's retention rules. Releasing a BBX handle does not delete either. BBX does not expose general download-history search.
+- Explicit trusted image paste overwrites the system clipboard with the supplied PNG and dispatches native paste into a focused editor. It does not read existing clipboard content.
 - Dialog message/default prompt text is returned to the requesting caller when inspected but is excluded from persisted action-log summaries and size diagnostics.
 - Exact sensitive values traverse the selected client in memory but are excluded from action summaries, diagnostic size counters, daemon logs, and automatic artifact storage.
 - Patch rollback records and remembered element references live in the current document. Browser Bridge attempts patch rollback when access is disabled or switched, while page replacement/navigation removes document-local state.

package/README.md

@@ -127,6 +127,8 @@ MCP mode is self-contained: the dual-era stdio server supports legacy MCP client
 - Native pointer/text input, dialog handling, all-resource network capture, accessibility trees, screenshots, and raw CDP reads use the existing debugger permission only when requested
 - HAR export is a read of an already armed CDP capture: start capture, reproduce, export, then stop. Export never starts, stops, or clears capture, and omits headers, cookies, bodies, authorization values, and unsupported size/timing detail
 - HAR and screenshot artifacts are opaque, owner-scoped daemon handles with a five-minute lifetime and no browser-host path; CLI capture commands download, verify, delete, and write them on the CLI host
+- [File workflows](https://github.com/koltyakov/browser-bridge/blob/main/skills/browser-bridge/references/files.md) include staged uploads, trusted PNG paste, and browser-native large downloads with progress, pause/resume, and cancellation
+- [Opt-in recording](https://github.com/koltyakov/browser-bridge/blob/main/skills/browser-bridge/references/recording.md) supports child-tab watch, timing correlations, durable crash-recovery journals, continuous renderer playback, and local MP4 export
 - Element references are document-local and strict by default; stale input recovery is opt-in, same-document, requires one strong unique semantic match, and fails safely when its bounded scan cannot prove uniqueness
 - Semantic DOM baselines provide explicit create/compare/describe/release verification without modifying the page; compact snapshots stay memory-only, expire after five minutes, and are invalidated by navigation or access teardown
 - Patches keep per-document rollback history and Browser Bridge attempts best-effort rollback when window access is disabled or switched; committing the patch baseline keeps current changes but discards their rollback history

package/SECURITY.md

@@ -61,6 +61,16 @@ Out of scope:
   preventing SSH port forwarding from turning remote access into local control.
 - Daemon connections, registration time, malformed input, pending requests, and
   per-client pending requests are bounded to limit resource exhaustion.
+- File staging and artifact access use daemon-issued connection identities.
+  Copying a client ID or agent session label does not grant access to another
+  connection's file data. Artifacts are deleted on disconnect. Staged uploads
+  become inaccessible on disconnect and expire within five minutes.
+- Artifact ingress checks the requesting connection, routed extension, request
+  ID, artifact kind, chunk order, declared size, and SHA-256 checksum. File writes
+  account for partial writes and abort on failure before acknowledging progress.
+- TCP authentication does not encrypt traffic. Use SSH or another encrypted
+  tunnel for remote connections. The default proxy listener is loopback-only;
+  exposing plaintext TCP requires an explicit unsafe option.
 - Proxy mode (LAN exposure) is opt-in via `bbx proxy enable` and always provisions a
   token; an invalid `bindHost` in the config rejects the config rather than widening
   the bind address.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbridge/bbx",
-  "version": "1.12.5",
+  "version": "1.14.1",
   "private": false,
   "keywords": [
     "agent-tools",
@@ -78,18 +78,18 @@
     "@modelcontextprotocol/server": "^2.3.1",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",
-    "zod": "^4.6.5"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
-    "@types/chrome": "^0.3.4",
-    "@types/node": "^26.6.4",
+    "@types/chrome": "^0.3.5",
+    "@types/node": "^26.6.5",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "c8": "^12.0.0",
     "har-schema": "^2.0.0",
-    "oxfmt": "^0.72.0",
-    "oxlint": "^1.87.0",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   },

package/packages/agent-client/src/cli-output.js

@@ -52,7 +52,7 @@ export function printCallResponse(response, method) {
 }
 
 /**
- * @returns {void}
+ * @returns {Promise<void>}
  */
 export function printUsage() {
   const blocks = ['Usage: bbx [--remote <name>] <command> [args]'];
@@ -60,5 +60,11 @@ export function printUsage() {
     blocks.push('', `${section.title}:`);
     blocks.push(...section.lines.map((line) => `  ${line}`));
   }
-  process.stdout.write(`${blocks.join('\n')}\n`);
+  // Wait for piped output to flush before the CLI exits.
+  return new Promise((resolve, reject) => {
+    process.stdout.write(`${blocks.join('\n')}\n`, (error) => {
+      if (error) reject(error);
+      else resolve();
+    });
+  });
 }

package/packages/agent-client/src/cli.js

@@ -47,6 +47,9 @@ import { formatMcpConfig, isMcpClientName, MCP_CLIENT_NAMES } from './mcp-config
 import { getDoctorReport, requestBridge, resolveRef } from './runtime.js';
 import { createBridgeClientForDestination } from './remotes.js';
 import { atomicWriteFile } from './atomic-write.js';
+import { uploadFiles } from './file-transfer.js';
+import { recordSession } from './record-session.js';
+import { exportReplay } from './replay.js';
 
 /** @typedef {import('./types.js').BridgeMethod} BridgeMethod */
 /** @typedef {import('./types.js').ScreenshotResult} ScreenshotResult */
@@ -98,7 +101,7 @@ const remoteDestinationId =
     : (remoteFlag.remoteId ?? process.env[REMOTE_ENV] ?? null);
 
 if (!command || ['help', '--help', '-h'].includes(command)) {
-  printUsage();
+  await printUsage();
   process.exit(0);
 }
 
@@ -403,6 +406,130 @@ async function main() {
       return;
     }
 
+    if (command === 'replay') {
+      if (rest.length !== 2)
+        throw new Error(
+          'Usage: bbx replay <journalId|recording-file> <output.html|output.json|output.mp4>'
+        );
+      const result = await exportReplay(
+        (method, params) => requestBridge(client, method, params, { source: REQUEST_SOURCE }),
+        rest[0],
+        rest[1]
+      );
+      printJson({ ok: true, ...result });
+      return;
+    }
+    if (command === 'upload' || command === 'paste-image') {
+      const action = command === 'paste-image' ? 'input.paste_image' : 'input.set_files';
+      const args = [...rest];
+      const flags = [];
+      for (const flag of ['--tab', '--extension', '--browser', '--profile']) {
+        const index = args.indexOf(flag);
+        if (index < 0) continue;
+        flags.push(...args.splice(index, 2));
+      }
+      const [selector, ...files] = args;
+      if (!selector || !files.length)
+        throw new Error(
+          `Usage: bbx ${command} --tab <id> [--extension <id>] <ref|selector> <local-file>...`
+        );
+      const {
+        tabId,
+        method: _method,
+        params: _params,
+        ...route
+      } = await parseCallCommand([...flags, 'input.set_files', '{}']);
+      if (tabId === null)
+        throw new Error('upload requires --tab so every chunk targets the same tab.');
+      const response = await uploadFiles(
+        (method, params) =>
+          requestBridge(client, method, params, { ...route, tabId, source: REQUEST_SOURCE }),
+        isElementRef(selector) ? { elementRef: selector } : { selector },
+        files,
+        action
+      );
+      await printSummary(response, action);
+      return;
+    }
+
+    if (command === 'download') {
+      const args = [...rest];
+      const flags = [];
+      for (const flag of ['--tab', '--extension', '--browser', '--profile']) {
+        const index = args.indexOf(flag);
+        if (index >= 0) flags.push(...args.splice(index, 2));
+      }
+      const [url, output, ...extra] = args;
+      if (!url || !output || extra.length)
+        throw new Error('Usage: bbx download --tab <id> [--extension <id>] <url> <outPath>');
+      const {
+        tabId,
+        method: _method,
+        params: _params,
+        ...route
+      } = await parseCallCommand([...flags, 'download.resource', '{}']);
+      if (tabId === null) throw new Error('download requires --tab.');
+      const response = await requestBridge(
+        client,
+        'download.resource',
+        { url },
+        { ...route, tabId, source: REQUEST_SOURCE }
+      );
+      if (!response.ok) {
+        await printSummary(response);
+        return;
+      }
+      const result = /** @type {{ artifact: ArtifactDescriptor }} */ (response.result);
+      const bytes = await downloadArtifact(client, result.artifact, 'resource');
+      await atomicWriteFile(output, bytes);
+      printJson({ ok: true, path: output, byteLength: bytes.length });
+      return;
+    }
+
+    if (command === 'record') {
+      const args = [...rest];
+      const flags = [];
+      for (const flag of ['--tab', '--extension', '--browser', '--profile']) {
+        const index = args.indexOf(flag);
+        if (index >= 0) flags.push(...args.splice(index, 2));
+      }
+      const [config, output, ...extra] = args;
+      if (!config || !output || extra.length)
+        throw new Error(
+          'Usage: bbx record --tab <id> [--extension <id>] <options-json> <out.json|out.html>'
+        );
+      const {
+        tabId,
+        params,
+        method: _method,
+        ...route
+      } = await parseCallCommand([...flags, 'session.start', config]);
+      if (tabId === null) throw new Error('record requires --tab.');
+      if (!/\.(?:json|html|mp4)$/iu.test(output))
+        throw new Error('Recording output must be .json, .html, or .mp4.');
+      if (output.toLowerCase().endsWith('.mp4')) {
+        params.durable = true;
+        params.replay = true;
+      }
+      const result = await recordSession(
+        (method, params) =>
+          requestBridge(client, method, params, { ...route, tabId, source: REQUEST_SOURCE }),
+        params,
+        output.toLowerCase().endsWith('.html') ? 'html' : 'json',
+        async (artifact) =>
+          atomicWriteFile(output, await downloadArtifact(client, artifact, 'resource')),
+        (started) => printJson({ ok: true, recording: started }),
+        (journalId) =>
+          exportReplay(
+            (method, params) => requestBridge(client, method, params, { source: REQUEST_SOURCE }),
+            journalId,
+            output
+          )
+      );
+      printJson({ ok: true, path: output, ...result });
+      return;
+    }
+
     if (command === 'batch') {
       const { preset, rest: batchArgs } = extractPresetFlag(rest);
       const results = await runBatchCalls(client, batchArgs[0], REQUEST_SOURCE, { preset });
@@ -528,6 +655,8 @@ async function main() {
         evidence: {
           savedTo: filePath,
           rect: screenshotResult.rect,
+          dimensions: screenshotResult.dimensions,
+          ...(screenshotResult.context ? { context: screenshotResult.context } : {}),
           format: screenshotResult.format,
           complete: screenshotResult.complete,
           clipped: screenshotResult.clipped,
@@ -665,7 +794,7 @@ async function main() {
     }
 
     process.stderr.write(`Unknown command: ${command}\n`);
-    printUsage();
+    await printUsage();
     process.exitCode = 1;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -712,7 +841,7 @@ function decodeScreenshotDataUrl(value) {
 /**
  * @param {import('./client.js').BridgeClient} client
  * @param {ArtifactDescriptor} artifact
- * @param {'screenshot' | 'har'} [expectedKind]
+ * @param {import('../../protocol/src/types.js').ArtifactKind} [expectedKind]
  */
 async function downloadArtifact(client, artifact, expectedKind) {
   const chunks = [];

package/packages/agent-client/src/command-registry.js

@@ -300,6 +300,12 @@ export const CLI_HELP_SECTIONS = Object.freeze([
       '--preset fills budget gaps (maxNodes, maxDepth, textBudget, limit) from the shared quick|normal|deep presets; explicit params always win.',
       'Every bridge command accepts --remote <name> (or BBX_REMOTE env) to target a remote destination from `bbx remote list`.',
       'Advanced bridge params stay available through `bbx call`, even when shortcuts expose only the common case.',
+      'bbx upload --tab <id> [--extension <id>] <ref|selector> <local-file>...  Stream local files and assign a file input',
+      'bbx paste-image --tab <id> [--extension <id>] <ref|selector> <image.png>  Write clipboard and dispatch trusted paste into a focused editor',
+      'bbx download --tab <id> [--extension <id>] <url> <outPath>             Save a browser-authenticated resource locally',
+      'bbx record --tab <id> [--extension <id>] <options-json> <out.json|out.html|out.mp4>  Record and export on one connection',
+      'bbx replay <journalId|recording-file> <out.html|out.json|out.mp4>      Recover or render a replay; MP4 requires ffmpeg',
+      'bbx call download.start \'{"url":"https://example.com/export"}\'      Start a browser-native large download; use download.status/pause/resume/cancel with its handle',
       'For open-ended investigation, start with `bbx batch` on `page.get_state`, `dom.query`, and `page.get_text` before any screenshot or CDP call.',
       '',
       'Interaction methods need a target wrapper (not a bare ref):',

package/packages/agent-client/src/file-transfer.js

@@ -0,0 +1,88 @@
+// @ts-check
+
+import { open } from 'node:fs/promises';
+import path from 'node:path';
+import { FILE_CHUNK_BYTES, FILE_MAX_BYTES, FILE_TOTAL_BYTES } from '../../protocol/src/files.js';
+
+/** Upload agent-local files through bounded chunks, then assign them once. No byte payload enters output.
+ * @param {(method: import('../../protocol/src/types.js').BridgeMethod, params: Record<string, unknown>) => Promise<import('../../protocol/src/types.js').BridgeResponse>} call
+ * @param {Record<string, unknown>} target
+ * @param {string[]} paths
+ * @param {'input.set_files' | 'input.paste_image'} [action]
+ */
+export async function uploadFiles(call, target, paths, action = 'input.set_files') {
+  if (action === 'input.paste_image' && paths.length !== 1)
+    throw new Error('Paste requires exactly one PNG.');
+  if (!paths.length || paths.length > 10) throw new Error('Provide 1..10 local files.');
+  /** @type {Array<{ file: import('node:fs/promises').FileHandle, name: string, size: number }>} */
+  const opened = [];
+  /** @type {string[]} */
+  const handles = [];
+  try {
+    for (const filename of paths) {
+      const file = await open(filename, 'r');
+      opened.push({ file, name: path.basename(filename), size: 0 });
+      const stat = await file.stat();
+      if (!stat.isFile() || stat.size > FILE_MAX_BYTES)
+        throw new Error('Each upload must be a regular file of at most 16 MiB.');
+      opened[opened.length - 1].size = stat.size;
+    }
+    if (opened.reduce((sum, item) => sum + item.size, 0) > FILE_TOTAL_BYTES)
+      throw new Error('Combined upload size exceeds 32 MiB.');
+    for (const { file, name, size } of opened) {
+      let offset = 0;
+      let transferId;
+      do {
+        const buffer = Buffer.alloc(Math.min(FILE_CHUNK_BYTES, size - offset));
+        let used = 0;
+        while (used < buffer.length) {
+          const { bytesRead } = await file.read(buffer, used, buffer.length - used, offset + used);
+          if (!bytesRead) throw new Error('Upload file changed while reading.');
+          used += bytesRead;
+        }
+        const response = await call('files.stage', {
+          ...(transferId ? { transferId } : { name, mimeType: mimeForName(name), size }),
+          offset,
+          data: buffer.toString('base64'),
+        });
+        if (!response.ok) throw new Error(response.error.message);
+        const result = /** @type {{ transferId: string, nextOffset: number }} */ (response.result);
+        if (!transferId) {
+          transferId = result.transferId;
+          handles.push(transferId);
+        }
+        if (result.transferId !== transferId || result.nextOffset !== offset + used)
+          throw new Error('Invalid file staging acknowledgement.');
+        offset = result.nextOffset;
+      } while (offset < size);
+    }
+    return await call(
+      action,
+      action === 'input.paste_image'
+        ? { target, transferId: handles[0] }
+        : { target, files: handles }
+    );
+  } finally {
+    await Promise.allSettled(opened.map(({ file }) => file.close()));
+    await Promise.allSettled(handles.map((transferId) => call('files.release', { transferId })));
+  }
+}
+
+/** @param {string} name */
+function mimeForName(name) {
+  /** @type {Record<string, string>} */
+  const types = {
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.html': 'text/html',
+    '.zip': 'application/zip',
+  };
+  return types[path.extname(name).toLowerCase()] ?? 'application/octet-stream';
+}

package/packages/agent-client/src/record-session.js

@@ -0,0 +1,54 @@
+// @ts-check
+
+/** Retain one connection for capture, export, and artifact retrieval.
+ * @param {(method: import('../../protocol/src/types.js').BridgeMethod, params: Record<string, unknown>) => Promise<import('../../protocol/src/types.js').BridgeResponse>} call
+ * @param {Record<string, unknown>} options
+ * @param {'json' | 'html'} format
+ * @param {(artifact: import('../../protocol/src/types.js').ArtifactDescriptor) => Promise<void>} save
+ * @param {(result: Record<string, unknown>) => void} [started]
+ * @param {(journalId: string) => Promise<unknown>} [saveJournal]
+ */
+export async function recordSession(call, options, format, save, started = () => {}, saveJournal) {
+  /** @param {import('../../protocol/src/types.js').BridgeMethod} method @param {Record<string, unknown>} params */
+  async function invoke(method, params) {
+    const response = await call(method, params);
+    if (!response.ok) throw new Error(response.error.message);
+    return /** @type {Record<string, unknown>} */ (response.result);
+  }
+  const initial = await invoke('session.start', options);
+  const sessionId = String(initial.sessionId);
+  started(initial);
+  try {
+    let cursor = Number(initial.nextCursor);
+    while (true) {
+      const next = await invoke('session.read', { sessionId, cursor, limit: 100, waitMs: 25000 });
+      if (next.journalError)
+        throw new Error(
+          `Recording journal failed: ${next.journalError}. Recover acknowledged evidence with journal ${initial.journalId}.`
+        );
+      cursor = Number(next.nextCursor);
+      if (!next.active) break;
+    }
+    if (typeof initial.journalId === 'string' && saveJournal) {
+      const stopped = await invoke('session.stop', { sessionId });
+      if (stopped.journalError)
+        throw new Error(
+          `Recording journal failed: ${stopped.journalError}. Recover journal ${initial.journalId}.`
+        );
+      await saveJournal(initial.journalId);
+      return {
+        sessionId,
+        journalId: initial.journalId,
+        gaps: stopped.gaps,
+        dropped: stopped.dropped,
+      };
+    }
+    const exported = await invoke('session.export', { sessionId, format });
+    await save(
+      /** @type {import('../../protocol/src/types.js').ArtifactDescriptor} */ (exported.artifact)
+    );
+    return { sessionId, gaps: exported.gaps, dropped: exported.dropped };
+  } finally {
+    await call('session.release', { sessionId }).catch(() => {});
+  }
+}

package/packages/agent-client/src/replay.js

@@ -0,0 +1,124 @@
+// @ts-check
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { parseRecordingJournal, renderReplay } from '../../protocol/src/replay.js';
+
+/** @param {import('../../protocol/src/replay.js').Replay} recording @param {string} output */
+async function writeMp4(recording, output) {
+  if (!recording.frames.length) throw new Error('Recording has no frames to encode.');
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'bbx-replay-'));
+  try {
+    const frames = [...recording.frames].sort((a, b) => a.at - b.at);
+    const lines = ['ffconcat version 1.0'];
+    for (let index = 0; index < frames.length; index++) {
+      const frame = frames[index];
+      if (!Number.isFinite(frame.at) || !/^[A-Za-z0-9+/]+={0,2}$/u.test(frame.data))
+        throw new Error('Invalid recorded frame.');
+      const filename = `frame-${index}.jpg`;
+      await fs.writeFile(path.join(directory, filename), Buffer.from(frame.data, 'base64'), {
+        mode: 0o600,
+      });
+      lines.push(
+        `file '${filename}'`,
+        `duration ${Math.max(0.02, Math.min(1800, ((frames[index + 1]?.at ?? frame.at + 100) - frame.at) / 1000))}`
+      );
+    }
+    lines.push(`file 'frame-${frames.length - 1}.jpg'`);
+    await fs.writeFile(path.join(directory, 'frames.txt'), lines.join('\n'), { mode: 0o600 });
+    await promisify(execFile)(
+      'ffmpeg',
+      [
+        '-nostdin',
+        '-n',
+        '-loglevel',
+        'error',
+        '-f',
+        'concat',
+        '-safe',
+        '1',
+        '-i',
+        path.join(directory, 'frames.txt'),
+        '-vf',
+        'scale=1280:900:force_original_aspect_ratio=decrease,pad=1280:900:(ow-iw)/2:(oh-ih)/2',
+        '-c:v',
+        'libx264',
+        '-pix_fmt',
+        'yuv420p',
+        '-movflags',
+        '+faststart',
+        path.resolve(output),
+      ],
+      { timeout: 300000, maxBuffer: 1024 * 1024 }
+    );
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** Download an opaque journal capability or render a local recording without exposing frame bytes to the model.
+ * @param {(method: import('../../protocol/src/types.js').BridgeMethod, params: Record<string, unknown>) => Promise<import('../../protocol/src/types.js').BridgeResponse>} call
+ * @param {string} source @param {string} output */
+export async function exportReplay(call, source, output) {
+  let text;
+  if (/^journal_[a-f0-9]{64}$/u.test(source)) {
+    const chunks = [];
+    let offset = 0;
+    for (;;) {
+      const response = await call('session.journal_read', {
+        journalId: source,
+        offset,
+        maxBytes: 196608,
+      });
+      if (!response.ok) throw new Error(response.error.message);
+      const chunk =
+        /** @type {{ offset: number, byteLength: number, totalBytes: number, nextOffset: number | null, data: string }} */ (
+          response.result
+        );
+      const bytes = Buffer.from(chunk.data, 'base64');
+      if (
+        chunk.offset !== offset ||
+        chunk.byteLength !== bytes.length ||
+        offset + bytes.length > 128 * 1024 * 1024 ||
+        (chunk.nextOffset !== null && chunk.nextOffset !== offset + bytes.length)
+      )
+        throw new Error('Invalid journal chunk acknowledgement.');
+      chunks.push(bytes);
+      offset += bytes.length;
+      if (chunk.nextOffset === null) break;
+      if (!bytes.length) throw new Error('Journal read made no progress.');
+    }
+    text = Buffer.concat(chunks).toString('utf8');
+  } else {
+    const stat = await fs.stat(source);
+    if (!stat.isFile() || stat.size > 128 * 1024 * 1024)
+      throw new Error('Recording must be a file of at most 128 MiB.');
+    text = await fs.readFile(source, 'utf8');
+  }
+  let recording;
+  try {
+    const parsed = /** @type {import('../../protocol/src/replay.js').Replay} */ (JSON.parse(text));
+    if (!Array.isArray(parsed.frames) || !Array.isArray(parsed.events))
+      throw new Error('Not a recording');
+    recording = parsed;
+  } catch {
+    recording = parseRecordingJournal(text);
+  }
+  const extension = path.extname(output).toLowerCase();
+  if (extension === '.mp4') await writeMp4(recording, output);
+  else if (extension === '.html' || extension === '.json')
+    await fs.writeFile(
+      output,
+      extension === '.html' ? renderReplay(recording) : JSON.stringify(recording),
+      { mode: 0o600 }
+    );
+  else throw new Error('Replay output must be .html, .json, or .mp4. MP4 requires ffmpeg on PATH.');
+  return {
+    path: path.resolve(output),
+    frames: recording.frames.length,
+    gaps: recording.gaps,
+    dropped: recording.dropped,
+  };
+}

package/packages/mcp-server/src/handlers-capture.js

@@ -162,6 +162,9 @@ export function createScreenshotResult(response, method) {
         mimeType: result.mimeType,
         byteLength: result.byteLength,
         dimensions: result.dimensions,
+        ...(result.context && typeof result.context === 'object'
+          ? { context: boundStructuredValue(result.context).value }
+          : {}),
         rect: boundedRect(result.rect),
         complete: result.complete === true,
         clipped: result.clipped === true,
@@ -186,6 +189,12 @@ export function createScreenshotResult(response, method) {
       mimeType: image.mimeType,
       byteLength: image.byteLength,
       ...(rect ? { rect } : {}),
+      ...(result.dimensions && typeof result.dimensions === 'object'
+        ? { dimensions: boundStructuredValue(result.dimensions).value }
+        : {}),
+      ...(result.context && typeof result.context === 'object'
+        ? { context: boundStructuredValue(result.context).value }
+        : {}),
       format: result.format ?? image.mimeType.replace('image/', ''),
       complete: result.complete === true,
       clipped: result.clipped === true,

package/packages/mcp-server/src/handlers-page.js

@@ -547,6 +547,12 @@ export async function handleRawCallTool(args) {
       if (method === 'artifact.read') {
         return createArtifactReadResult(response);
       }
+      if (method === 'session.journal_read' && response.ok) {
+        return createToolResult('Read exact journal bytes; page until nextOffset is null.', {
+          ok: true,
+          evidence: response.result,
+        });
+      }
       return summarizeToolResponse(response, method, params);
     },
     { destinationId: args.destinationId ?? null }