@jobshimo/browser-link 0.28.9 → 0.30.0

package/dist/downloads.js

@@ -0,0 +1,303 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { extname, isAbsolute, join } from 'node:path';
+/**
+ * `browser.download` support: everything the tool needs that is NOT talking
+ * to Chrome — filename policy, the download directory, the file write, the
+ * in-page fetch expression and the shaping of the result the agent sees.
+ *
+ * WHY THE BYTES COME THROUGH THE SERVER. The obvious design — tell Chrome
+ * "save downloads to <dir>, never ask" with CDP `Browser.setDownloadBehavior`
+ * — is not available to us: Chromium refuses it (and the tab-scoped
+ * `Page.setDownloadBehavior`, which delegates to the same check) for any
+ * `chrome.debugger` client, because the extension debugger host reports
+ * `MayWriteLocalFiles() == false`. And `chrome.downloads.download({saveAs:
+ * false})` does NOT suppress the dialog either: Chrome still prompts when the
+ * user enabled "Ask where to save each file". So instead the bytes are
+ * fetched IN THE PAGE (with the page's own cookies) and written here, into a
+ * directory only the human configures.
+ *
+ * Chrome's download manager never SAVES anything. In url mode it is not
+ * involved at all. In selector mode the extension uses it only to catch the
+ * download a click starts: it hooks `chrome.downloads.onDeterminingFilename`,
+ * which Chrome consults before prompting, cancels and erases that download
+ * there, and hands its URL to the same in-page fetch (see the extension's
+ * `download-capture.ts`).
+ */
+export const DEFAULT_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const MAX_DOWNLOAD_TIMEOUT_MS = 120_000;
+/** Hard cap on one download's size. The bytes travel base64-encoded inside a
+ * CDP `Runtime.evaluate` result and then a bridge frame, so this also bounds
+ * the memory both hops can be asked to hold. */
+export const MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
+/** Extra bridge timeout on top of each hop's own budget (selector mode has
+ * two hops: capture, then fetch), for the round trip only — the capture and
+ * the in-page fetch enforce their budgets themselves and always answer, so
+ * this is spent only when the bridge itself stalls. */
+export const DOWNLOAD_BRIDGE_SLACK_MS = 10_000;
+const MAX_FILENAME_LENGTH = 200;
+// Characters no filename may carry on any OS we run on (Windows is the
+// strictest) — plus the two path separators.
+// eslint-disable-next-line no-control-regex
+const RESERVED_CHARS = /[<>:"/\\|?*\u0000-\u001f]/;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/g;
+/**
+ * Validate a filename the AGENT asked for. Strict on purpose: the agent may
+ * name the file but never choose where it lands, so anything that could be
+ * read as a path (separators, `..`, a drive prefix) is rejected outright
+ * rather than quietly cleaned up.
+ */
+export function validateRequestedFilename(name) {
+    const fail = (why) => {
+        throw new Error(`browser.download: filename ${why} — pass a plain basename like "report.pdf"`);
+    };
+    if (typeof name !== 'string')
+        return fail('must be a string');
+    if (name.trim().length === 0)
+        return fail('must not be empty');
+    if (name.length > MAX_FILENAME_LENGTH)
+        return fail(`must be at most ${MAX_FILENAME_LENGTH} characters`);
+    if (name === '.' || name === '..')
+        return fail('must not be "." or ".."');
+    if (RESERVED_CHARS.test(name))
+        return fail('must not contain path separators or reserved characters');
+    if (/[.\s]$/.test(name))
+        return fail('must not end with a dot or a space');
+    if (WINDOWS_DEVICE_NAME.test(name)) {
+        return fail('must not be a Windows device name (CON, PRN, AUX, NUL, COM1-9, LPT1-9)');
+    }
+    return name;
+}
+/**
+ * Windows device names — `NUL`, `con.txt`, `LPT1.log`: with or without an
+ * extension, any case. Writing to one on Windows hits the device (or a
+ * normalized name), so the server would report a file that does not exist.
+ */
+const WINDOWS_DEVICE_NAME = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i;
+/**
+ * Make a filename that came from the PAGE (Chrome's suggestion, a
+ * Content-Disposition header, a URL) safe to write: keep the last path
+ * segment, replace reserved characters, drop control characters and leading
+ * or trailing dots/spaces, and defuse Windows device names with a `_`
+ * prefix. Cleaned up rather than rejected: the page, not the agent, chose
+ * it. Returns null when nothing usable is left.
+ */
+export function sanitizeDerivedFilename(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const lastSegment = raw.split(/[/\\]/).pop() ?? '';
+    const cleaned = lastSegment
+        .replace(CONTROL_CHARS, '')
+        .replace(/[<>:"|?*]/g, '_')
+        .replace(/^[.\s]+/, '')
+        .slice(0, MAX_FILENAME_LENGTH - 1)
+        .replace(/[.\s]+$/, '');
+    if (cleaned.length === 0)
+        return null;
+    return WINDOWS_DEVICE_NAME.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+/** Extract the filename from a Content-Disposition header, preferring the
+ * RFC 5987 `filename*=` form (it carries non-ASCII names correctly). */
+export function filenameFromContentDisposition(header) {
+    if (typeof header !== 'string')
+        return null;
+    const star = /filename\*\s*=\s*([^']*)'[^']*'([^;]+)/i.exec(header);
+    if (star) {
+        try {
+            return decodeURIComponent(star[2].trim().replace(/^"|"$/g, ''));
+        }
+        catch {
+            // Malformed percent-encoding — fall through to the plain form.
+        }
+    }
+    const plain = /filename\s*=\s*("[^"]*"|[^;]+)/i.exec(header);
+    if (!plain)
+        return null;
+    const value = plain[1].trim().replace(/^"|"$/g, '');
+    return value.length > 0 ? value : null;
+}
+/** Last path segment of an http(s) URL, decoded. Null for `blob:`/`data:`
+ * URLs (their "path" is an opaque id or the payload itself). */
+export function filenameFromUrl(url) {
+    if (typeof url !== 'string')
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return null;
+    const segment = parsed.pathname.split('/').pop() ?? '';
+    if (segment.length === 0)
+        return null;
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+}
+/** requested → Chrome's suggestion → Content-Disposition → URL → "download". */
+export function pickFilename(sources) {
+    if (sources.requested !== undefined)
+        return sources.requested;
+    return (sanitizeDerivedFilename(sources.suggested) ??
+        sanitizeDerivedFilename(filenameFromContentDisposition(sources.contentDisposition)) ??
+        sanitizeDerivedFilename(filenameFromUrl(sources.url)) ??
+        'download');
+}
+export function clampDownloadTimeoutMs(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        return DEFAULT_DOWNLOAD_TIMEOUT_MS;
+    }
+    return Math.min(Math.floor(value), MAX_DOWNLOAD_TIMEOUT_MS);
+}
+/**
+ * Where downloads land: the human-configured `downloads.dir` when it is an
+ * absolute path, otherwise `<dataDir>/downloads`. config.json is untrusted
+ * (hand-edited, corrupted), so a relative or non-string value falls back to
+ * the default instead of resolving against whatever the cwd happens to be.
+ */
+export function resolveDownloadsDir(cfg, dataDir) {
+    const configured = cfg.downloadsDir;
+    if (typeof configured === 'string' && configured.length > 0 && isAbsolute(configured)) {
+        return configured;
+    }
+    return join(dataDir, 'downloads');
+}
+/**
+ * Write `data` as `filename` inside `dir`, creating `dir` if needed. Never
+ * overwrites: an existing name becomes `name (1).ext`, `name (2).ext`, …
+ * (the `wx` flag makes the existence check and the create one atomic step).
+ * Returns the absolute path written.
+ */
+export function writeDownloadFile(dir, filename, data) {
+    mkdirSync(dir, { recursive: true });
+    const ext = extname(filename);
+    const stem = ext.length > 0 ? filename.slice(0, -ext.length) : filename;
+    for (let attempt = 0; attempt < 1000; attempt++) {
+        const name = attempt === 0 ? filename : `${stem} (${attempt})${ext}`;
+        const path = join(dir, name);
+        try {
+            writeFileSync(path, data, { flag: 'wx' });
+            return path;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+        }
+    }
+    throw new Error(`could not find a free filename for ${filename} in ${dir}`);
+}
+/**
+ * Build the expression `Runtime.evaluate` runs in the page: fetch `url` with
+ * the page's credentials, stream the body (so `maxBytes` is enforced while
+ * reading, not after buffering everything), and base64 it. Every exit path
+ * resolves to a `FetchDownloadOutcome` — a timeout or an error reports how
+ * far it got rather than throwing, so the agent always gets partial info.
+ */
+export function buildFetchDownloadJs(opts) {
+    const url = JSON.stringify(opts.url);
+    const timeoutMs = Math.floor(opts.timeoutMs);
+    const maxBytes = Math.floor(opts.maxBytes);
+    return `(async () => {
+  const url = ${url};
+  const timeoutMs = ${timeoutMs};
+  const maxBytes = ${maxBytes};
+  const ctrl = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => { timedOut = true; ctrl.abort(); }, timeoutMs);
+  const out = { state: 'interrupted', bytes: 0, mime: null, content_disposition: null, final_url: null };
+  try {
+    const res = await fetch(url, { credentials: 'include', signal: ctrl.signal });
+    out.status = res.status;
+    out.mime = res.headers.get('content-type');
+    out.content_disposition = res.headers.get('content-disposition');
+    out.final_url = res.url || url;
+    if (!res.ok) {
+      out.error = 'HTTP ' + res.status;
+      return out;
+    }
+    const chunks = [];
+    if (res.body) {
+      const reader = res.body.getReader();
+      for (;;) {
+        const step = await reader.read();
+        if (step.done) break;
+        out.bytes += step.value.byteLength;
+        if (out.bytes > maxBytes) {
+          ctrl.abort();
+          out.error = 'download exceeds the ' + maxBytes + ' bytes cap';
+          return out;
+        }
+        chunks.push(step.value);
+      }
+    }
+    let binary = '';
+    for (const chunk of chunks) {
+      for (let i = 0; i < chunk.length; i += 0x8000) {
+        binary += String.fromCharCode.apply(null, chunk.subarray(i, i + 0x8000));
+      }
+    }
+    out.data_b64 = btoa(binary);
+    out.state = 'complete';
+    return out;
+  } catch (err) {
+    if (timedOut) {
+      out.state = 'timeout';
+      out.error = 'timed out after ' + timeoutMs + 'ms';
+    } else {
+      out.error = err && err.message ? err.message : String(err);
+    }
+    return out;
+  } finally {
+    clearTimeout(timer);
+  }
+})()`;
+}
+/**
+ * Turn the in-page fetch outcome into the agent-facing result, writing the
+ * file on `complete`. A failed write downgrades to `interrupted` with the
+ * error — the agent must never be told a file exists when it does not.
+ */
+export function shapeDownloadResult(outcome, sources, save) {
+    const filename = pickFilename({
+        ...sources,
+        contentDisposition: outcome.content_disposition,
+        url: outcome.final_url ?? sources.url,
+    });
+    const base = {
+        filename,
+        mime: outcome.mime ?? null,
+        url: outcome.final_url ?? sources.url,
+    };
+    if (outcome.state === 'complete' && typeof outcome.data_b64 === 'string') {
+        const data = Buffer.from(outcome.data_b64, 'base64');
+        try {
+            const path = save(filename, data);
+            return { ok: true, state: 'complete', path, bytes: data.length, ...base };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                state: 'interrupted',
+                path: null,
+                bytes: data.length,
+                ...base,
+                error: `could not write the file: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    return {
+        ok: false,
+        state: outcome.state === 'timeout' ? 'timeout' : 'interrupted',
+        path: null,
+        bytes: outcome.bytes,
+        ...base,
+        error: outcome.error ?? 'download did not complete',
+    };
+}
+//# sourceMappingURL=downloads.js.map

package/dist/downloads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloads.js","sourceRoot":"","sources":["../src/downloads.ts"],"names":[],"mappings":"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"}

package/dist/extension/background.js

@@ -1,6 +1,8 @@
-import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, buildFocusJs, buildStateJs, buildDragProbeJs, } from './inpage/builders.js';
+import { buildSnapshotJs, buildFindJs, buildClickResolveJs, buildTypeResolveJs, buildFocusJs, buildStateJs, buildDragProbeJs, buildElementRectJs, } from './inpage/builders.js';
+import { runScreenshot } from './screenshot.js';
 import { buildKeyEventSequence, resolveKey, modifiersToBitmask, MODIFIER_BITS, } from './keymap.js';
 import { resolveSettleParams, settleSafely } from './settle.js';
+import { captureAround, createDownloadCapture } from './download-capture.js';
 import { runFlow, } from './flow.js';
 import { MAX_DETACHED_FLOW_MS, appendFlowHistory, createFlowRegistry, detachedFlowKey, detachedFlowRecordsToEvict, finishedDetachedFlowRecord, flowHistoryKey, flowIdFromDetachedFlowKey, minimalDetachedFlowRecord, parseDetachedFlowRecord, parseFlowHistory, startedDetachedFlowRecord, terminatedDetachedFlowRecord, terminatedFlowHistoryEntry, toFlowStatus, toHistoryEntry, } from './flow-registry.js';
 import { DEFAULT_IDLE_TTL_MINUTES, IDLE_TTL_STORAGE_KEY, IDLE_TTL_UPDATED_AT_STORAGE_KEY, clampIdleTtlMinutes, parseIncomingSettings, shouldAcceptIncomingSettings, shouldDisconnectForIdle, shouldScheduleIdleSweep, } from './idle-policy.js';
@@ -1393,6 +1395,27 @@ async function handleCanvasScreenshot(tabId, msg, p, optStr) {
     const value = await evaluateInTab(tabId, buildCanvasScreenshotJs({ selector, region, format }));
     return { kind: 'tool.response', id: msg.id, ok: true, result: value };
 }
+/**
+ * `browser.screenshot`: viewport / full page / one element through the
+ * already-attached debugger. `Page.captureScreenshot` with
+ * `captureBeyondViewport` and a `clip` renders past the viewport, so no
+ * scrolling or stitching is needed. Planning and the byte cap live in
+ * `screenshot.ts` (unit-tested; shared verbatim with cdp-direct).
+ */
+async function handleScreenshot(tabId, msg, p, optStr) {
+    const mode = p.mode === 'full_page' || p.mode === 'element' ? p.mode : 'viewport';
+    const result = await runScreenshot({
+        send: (method, params) => cdp(tabId, method, params ?? {}),
+        resolveElementRect: (selector) => evaluateInTab(tabId, buildElementRectJs({ selector })),
+    }, {
+        mode,
+        selector: optStr('selector'),
+        format: optStr('format') === 'jpeg' ? 'jpeg' : 'png',
+        quality: typeof p.quality === 'number' ? p.quality : undefined,
+        maxDimension: typeof p.max_dimension === 'number' ? p.max_dimension : undefined,
+    });
+    return { kind: 'tool.response', id: msg.id, ok: true, result };
+}
 function handleConsole(state, msg, optStr) {
     const level = optStr('level');
     const entries = level
@@ -1895,6 +1918,52 @@ async function handleDialogRespond(tabId, msg, p, optStr) {
         result: { accepted: accept },
     };
 }
+/** One worker-wide capture: `chrome.downloads` events are not tied to a tab,
+ * so only one `browser.download` may wait for a download at a time. */
+const downloadCapture = createDownloadCapture(chrome.downloads);
+/** The tab's origin for `mayComeFrom`, or undefined when it has none worth
+ * matching (opaque `null` origins, unparseable URLs). */
+function downloadOriginOf(url) {
+    try {
+        const origin = new URL(url).origin;
+        return origin === 'null' ? undefined : origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * `browser.download`'s selector mode: arm the capture, click, and wait for
+ * the download the click starts. The capture cancels that download before
+ * Chrome can show "Save as" (see `download-capture.ts`) and hands its URL
+ * back; the server then fetches the bytes in the page and writes the file.
+ * A click that starts nothing within `timeout_ms` answers `state: "timeout"`.
+ */
+async function handleDownloadCapture(tabId, msg, p) {
+    const selector = typeof p.selector === 'string' ? p.selector : '';
+    // No local default: the server always sends a clamped budget, and a second
+    // copy of its default here would only drift.
+    if (typeof p.timeout_ms !== 'number' || !(p.timeout_ms > 0)) {
+        return { kind: 'tool.response', id: msg.id, ok: false, error: 'download: timeout_ms required' };
+    }
+    const timeoutMs = p.timeout_ms;
+    // Narrow the capture to downloads that may come from this tab's origin —
+    // `chrome.downloads` items carry no tab id (see `mayComeFrom`).
+    const tab = await chrome.tabs.get(tabId).catch(() => null);
+    const origin = tab?.url ? downloadOriginOf(tab.url) : undefined;
+    const outcome = await captureAround(downloadCapture, { timeoutMs, ...(origin ? { origin } : {}) }, 
+    // settle_ms: 0 — the thing to wait for is the download, not DOM quiet.
+    () => performClick(tabId, { selector, settle_ms: 0 }));
+    if (!outcome.ok) {
+        return { kind: 'tool.response', id: msg.id, ok: false, error: outcome.error };
+    }
+    return {
+        kind: 'tool.response',
+        id: msg.id,
+        ok: true,
+        result: outcome.captured ? { state: 'captured', ...outcome.captured } : { state: 'timeout' },
+    };
+}
 async function handleSetPermission(msg, str) {
     const origin = str('origin');
     const name = str('name');
@@ -1978,6 +2047,8 @@ async function handleTool(state, msg) {
             }
             case 'canvas_screenshot':
                 return await handleCanvasScreenshot(tabId, msg, p, optStr);
+            case 'screenshot':
+                return await handleScreenshot(tabId, msg, p, optStr);
             case 'console':
                 return handleConsole(state, msg, optStr);
             case 'network':
@@ -2059,6 +2130,8 @@ async function handleTool(state, msg) {
                 return await handleDialogRespond(tabId, msg, p, optStr);
             case 'set_permission':
                 return await handleSetPermission(msg, str);
+            case 'download':
+                return await handleDownloadCapture(tabId, msg, p);
             default:
                 return { kind: 'tool.response', id: msg.id, ok: false, error: `Unknown tool: ${msg.tool}` };
         }