Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
feat(api): add scrape-to-browser api flow (ENG-4603) (#3184)
Gergő Móriczffa3ea5fac1f
diff --git a/.gitignore b/.gitignoreindex 4e2511851..47dcc2df7 100644--- a/.gitignore+++ b/.gitignore@@ -58,3 +58,6 @@ target/# local files_local/+++apps/api/src/lib/scrape-interact/*.md\ No newline at end of filediff --git a/apps/api/package.json b/apps/api/package.jsonindex b4b7dc6e0..6d19641ee 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -75,7 +75,7 @@"@ai-sdk/anthropic": "^2.0.41","@ai-sdk/deepinfra": "^1.0.27","@ai-sdk/fireworks": "^1.0.27",- "@ai-sdk/google": "^2.0.28",+ "@ai-sdk/google": "^3.0.29","@ai-sdk/google-vertex": "^3.0.86","@ai-sdk/groq": "^2.0.28","@ai-sdk/openai": "2.0.64",@@ -93,7 +93,7 @@"@x402/core": "^2.4.0","@x402/evm": "^2.4.0","@x402/express": "^2.4.0",- "ai": "5.0.89",+ "ai": "6.0.86","ajv": "^8.18.0","ajv-formats": "^3.0.1","amqplib": "^0.10.9",diff --git a/apps/api/pnpm-lock.yaml b/apps/api/pnpm-lock.yamlindex 4816ff560..7f59a0d26 100644--- a/apps/api/pnpm-lock.yaml+++ b/apps/api/pnpm-lock.yaml@@ -33,8 +33,8 @@ importers:specifier: ^1.0.27version: 1.0.29([email protected])'@ai-sdk/google':- specifier: ^2.0.28- version: 2.0.44([email protected])+ specifier: ^3.0.29+ version: 3.0.52([email protected])'@ai-sdk/google-vertex':specifier: ^3.0.86version: 3.0.86([email protected])@@ -87,8 +87,8 @@ importers:specifier: ^2.4.0version: 2.4.0([email protected])([email protected])([email protected]([email protected])([email protected]))([email protected])([email protected])([email protected])([email protected])([email protected]([email protected])([email protected]))ai:- specifier: 5.0.89- version: 5.0.89([email protected])+ specifier: 6.0.86+ version: 6.0.86([email protected])ajv:specifier: ^8.18.0version: 8.18.0@@ -387,8 +387,8 @@ packages:peerDependencies:zod: ^3.25.76 || ^4.1.8- '@ai-sdk/[email protected]':- resolution: {integrity: sha512-/AI5AKi4vOK9SEb8Z1dfXkhsJ5NAfWsoJQc96B/mzn2KIrjw5occOjIwD06scuhV9xWlghCoXJT1sQD9QH/tyg==}+ '@ai-sdk/[email protected]':+ resolution: {integrity: sha512-zH1UbNRjG5woOXXFOrVCZraqZuFTtmPvLardMGcgLkzpxKV0U3tAGoyWKSZ862H+eBJfI/Hf2yj/zzGJcCkycg==}engines: {node: '>=18'}peerDependencies:zod: ^3.25.76 || ^4.1.8@@ -405,6 +405,12 @@ packages:peerDependencies:zod: ^3.25.76 || ^4.1.8+ '@ai-sdk/[email protected]':+ resolution: {integrity: sha512-HiFB4VlHnv55k9xIbgQW9tHw5OsLXzbAghnDUqrnk/S94QpQuyrDwLSDsk/tUkxJeT00B+wvhL1y6/SARdLeXw==}+ engines: {node: '>=18'}+ peerDependencies:+ zod: ^3.25.76 || ^4.1.8+'@ai-sdk/[email protected]':resolution: {integrity: sha512-5kadf9Mjd4Ep6jVhrIy56UL7DV5HDisW8UakwB11IN7lSLi8Qwb1fB9uO34GT7JxYqE4w7qZXVuelOmTH9m2Mg==}engines: {node: '>=18'}@@ -453,6 +459,18 @@ packages:peerDependencies:zod: ^3.25.76 || ^4.1.8+ '@ai-sdk/[email protected]':+ resolution: {integrity: sha512-8XiKWbemmCbvNN0CLR9u3PQiet4gtEVIrX4zzLxnCj06AwsEDJwJVBbKrEI4t6qE8XRSIvU2irka0dcpziKW6w==}+ engines: {node: '>=18'}+ peerDependencies:+ zod: ^3.25.76 || ^4.1.8++ '@ai-sdk/[email protected]':+ resolution: {integrity: sha512-MtFUYI1/8mgDvRmaBDjbLJPFFrMG777AvSgyIFQtZHIMzm88R/12vYBBpnk7pfiWLFE1DSZzY4WDYzGbKAcmiw==}+ engines: {node: '>=18'}+ peerDependencies:+ zod: ^3.25.76 || ^4.1.8+'@ai-sdk/[email protected]':resolution: {integrity: sha512-f9jSYwKMdXvm44Dmab1vUBnfCDSFfI5rOtvV1W9oKB7WYHR5dGvCC6x68Mk3NUfrdmNoMVHGoh6JT9HCVMlMow==}engines: {node: '>=18'}@@ -465,6 +483,10 @@ packages:resolution: {integrity: sha512-6o7Y2SeO9vFKB8lArHXehNuusnpddKPk7xqL7T2/b+OvXMRIXUO1rR4wcv1hAFUAT9avGZshty3Wlua/XA7TvA==}engines: {node: '>=18'}+ '@ai-sdk/[email protected]':+ resolution: {integrity: sha512-oGMAgGoQdBXbZqNG0Ze56CHjDZ1IDYOwGYxYjO5KLSlz5HiNQ9udIXsPZ61VWaHGZ5XW/jyjmr6t2xz2jGVwbQ==}+ engines: {node: '>=18'}+'@apidevtools/[email protected]':resolution: {integrity: sha512-54vnqDyGsDAVM0LOIdGMnfVyCN1NlqoGnHEGpMfaDBLMvClfT4j2XbJgvfuF0Ca0kxT6Gb7xUgS5W1I14QqjiQ==}engines: {node: '>=20'}@@ -2536,6 +2558,9 @@ packages:'@standard-schema/[email protected]':resolution: {integrity: sha512-m2bOd0f2RT9k8QJx1JN85cZYyH1RqFBdlwtkSlf4tBDYLCiiZnv1fIIwacK6cqwXavOydf0NPToMQgpKq+dVlA==}+ '@standard-schema/[email protected]':+ resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}+'@supabase/[email protected]':resolution: {integrity: sha512-mMIQHBRc+SKpZFRB2qtupuzulaUhFYupNyxqDj5Jp/LyPvcWvjaJzZzObv6URtL/O6lPxkanASnotGtNpS3H2Q==}@@ -2846,8 +2871,8 @@ packages:cpu: [x64]os: [win32]- '@vercel/[email protected]':- resolution: {integrity: sha512-yNEQvPcVrK9sIe637+I0jD6leluPxzwJKx/Haw6F4H77CdDsszUn5V3o96LPziXkSNE2B83+Z3mjqGKBK/R6Gg==}+ '@vercel/[email protected]':+ resolution: {integrity: sha512-Fw28YZpRnA3cAHHDlkt7xQHiJ0fcL+NRcIqsocZQUSmbzeIKRpwttJjik5ZGanXP+vlA4SbTg+AbA3bP363l+w==}engines: {node: '>= 20'}'@x402/[email protected]':@@ -2936,8 +2961,8 @@ packages:resolution: {integrity: sha512-5GG/5IbQQpC9FpkRGsSvZI5QYeSCzlJHdpBQntCsuTOxhKD8lqKhrleg2Yi7yvMIf82Ycmmqln9U8V9qwEiJew==}engines: {node: '>= 8.0.0'}- resolution: {integrity: sha512-8Nq+ZojGacQrupoJEQLrTDzT5VtR3gyp5AaqFSV3tzsAXlYQ9Igb7QE3yeoEdzOk5IRfDwWL7mDCUD+oBg1hDA==}+ resolution: {integrity: sha512-U2W2LBCHA/pr0Ui7vmmsjBiLEzBbZF3yVHNy7Rbzn7IX+SvoQPFM5rN74hhfVzZoE8zBuGD4nLLk+j0elGacvQ==}engines: {node: '>=18'}peerDependencies:zod: ^3.25.76 || ^4.1.8@@ -5814,11 +5839,11 @@ snapshots:'@ai-sdk/provider-utils': 3.0.18([email protected])zod: 4.1.12- '@ai-sdk/[email protected]([email protected])':+ '@ai-sdk/[email protected]([email protected])':dependencies:- '@ai-sdk/provider': 2.0.0- '@ai-sdk/provider-utils': 3.0.16([email protected])- '@vercel/oidc': 3.0.3+ '@ai-sdk/provider': 3.0.8+ '@ai-sdk/provider-utils': 4.0.15([email protected])+ '@vercel/oidc': 3.1.0zod: 4.1.12'@ai-sdk/[email protected]([email protected])':@@ -5838,6 +5863,12 @@ snapshots:'@ai-sdk/provider-utils': 3.0.18([email protected])zod: 4.1.12+ '@ai-sdk/[email protected]([email protected])':+ dependencies:+ '@ai-sdk/provider': 3.0.8+ '@ai-sdk/provider-utils': 4.0.21([email protected])+ zod: 4.1.12+'@ai-sdk/[email protected]([email protected])':dependencies:'@ai-sdk/provider': 2.0.0@@ -5888,6 +5919,20 @@ snapshots:eventsource-parser: 3.0.6zod: 4.1.12+ '@ai-sdk/[email protected]([email protected])':+ dependencies:+ '@ai-sdk/provider': 3.0.8+ '@standard-schema/spec': 1.1.0+ eventsource-parser: 3.0.6+ zod: 4.1.12++ '@ai-sdk/[email protected]([email protected])':+ dependencies:+ '@ai-sdk/provider': 3.0.8+ '@standard-schema/spec': 1.1.0+ eventsource-parser: 3.0.6+ zod: 4.1.12+'@ai-sdk/[email protected]':dependencies:json-schema: 0.4.0@@ -5900,6 +5945,10 @@ snapshots:dependencies:json-schema: 0.4.0+ '@ai-sdk/[email protected]':+ dependencies:+ json-schema: 0.4.0+'@apidevtools/[email protected](@types/[email protected])':dependencies:'@types/json-schema': 7.0.15@@ -8080,6 +8129,8 @@ snapshots:'@standard-schema/[email protected]': {}+ '@standard-schema/[email protected]': {}+'@supabase/[email protected]':dependencies:'@supabase/node-fetch': 2.6.15@@ -8407,7 +8458,7 @@ snapshots:'@unrs/[email protected]':optional: true- '@vercel/[email protected]': {}+ '@vercel/[email protected]': {}'@x402/[email protected]':dependencies:@@ -8508,11 +8559,11 @@ snapshots:dependencies:humanize-ms: 1.2.1dependencies:- '@ai-sdk/gateway': 2.0.7([email protected])- '@ai-sdk/provider': 2.0.0- '@ai-sdk/provider-utils': 3.0.16([email protected])+ '@ai-sdk/gateway': 3.0.46([email protected])+ '@ai-sdk/provider': 3.0.8+ '@ai-sdk/provider-utils': 4.0.15([email protected])'@opentelemetry/api': 1.9.0zod: 4.1.12diff --git a/apps/api/requests.http b/apps/api/requests.httpindex 5ffc11708..9fe6a6012 100644--- a/apps/api/requests.http+++ b/apps/api/requests.http@@ -12,6 +12,44 @@ content-type: application/json"url": "https://firecrawl.dev"}+### Scrape Website (Replay-ready for scrape interact APIs)+# @name scrapeForBrowser+POST {{baseUrl}}/v2/scrape HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}+content-type: application/json++{+ "url": "https://firecrawl.dev",+ "actions": [+ {+ "type": "executeJavascript",+ "script": "window.location.href = 'https://roastmywebsite.ai'"+ },+ {+ "type": "wait",+ "milliseconds": 2000+ }+ ]+}++### Interact With Scrape Browser Session (POST /interact)+@scrapeJobId = {{scrapeForBrowser.response.body.$.data.metadata.scrapeId}}+# @name scrapeInteract+POST {{baseUrl}}/v2/scrape/{{scrapeJobId}}/interact HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}+content-type: application/json++{+ "code": "const title = await page.title(); const url = page.url(); console.log('url=', url, 'title=', JSON.stringify(title)); JSON.stringify({ url, title });",+ "language": "node",+ "timeout": 30+}++### Stop Interactive Browser Session (DELETE /interact)+# @name scrapeStopInteractiveBrowser+DELETE {{baseUrl}}/v2/scrape/{{scrapeJobId}}/interact HTTP/1.1+Authorization: Bearer {{$dotenv TEST_API_KEY}}+### Crawl Website# @name crawlPOST {{baseUrl}}/v2/crawl HTTP/1.1diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.tsindex 2a119a4c8..2f3384f0a 100644--- a/apps/api/src/__tests__/snips/v2/lib.ts+++ b/apps/api/src/__tests__/snips/v2/lib.ts@@ -104,6 +104,33 @@ export async function scrapeStatus(return raw.body.data;}+export async function scrapeInteractRaw(+ jobId: string,+ body: {+ code: string;+ language?: "python" | "node" | "bash";+ timeout?: number;+ origin?: string;+ },+ identity: Identity,+) {+ return await request(TEST_API_URL)+ .post("/v2/scrape/" + encodeURIComponent(jobId) + "/interact")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .set("Content-Type", "application/json")+ .send(body);+}++export async function scrapeStopInteractiveBrowserRaw(+ jobId: string,+ identity: Identity,+) {+ return await request(TEST_API_URL)+ .delete("/v2/scrape/" + encodeURIComponent(jobId) + "/interact")+ .set("Authorization", `Bearer ${identity.apiKey}`)+ .send();+}+// =========================================// Crawl API// =========================================diff --git a/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts b/apps/api/src/__tests__/snips/v2/scrape-browser.test.tsnew file mode 100644index 000000000..960df30c0--- /dev/null+++ b/apps/api/src/__tests__/snips/v2/scrape-browser.test.ts@@ -0,0 +1,289 @@+import crypto from "crypto";+import { config } from "../../../config";+import {+ ALLOW_TEST_SUITE_WEBSITE,+ HAS_FIRE_ENGINE,+ TEST_PRODUCTION,+ TEST_SUITE_WEBSITE,+ itIf,+} from "../lib";+import {+ Identity,+ idmux,+ scrapeStopInteractiveBrowserRaw,+ scrapeInteractRaw,+ scrapeRaw,+ scrapeTimeout,+} from "./lib";++const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));++async function interactWithReplicaRetry(+ jobId: string,+ body: {+ code: string;+ language?: "python" | "node" | "bash";+ timeout?: number;+ },+ identity: Identity,+ attempts: number = 5,+) {+ let lastResponse: Awaited<ReturnType<typeof scrapeInteractRaw>> | null = null;++ for (let i = 0; i < attempts; i += 1) {+ const response = await scrapeInteractRaw(jobId, body, identity);+ lastResponse = response;+ if (response.statusCode !== 404) return response;+ await sleep(500);+ }++ return lastResponse!;+}++describe("Scrape browser interact replay", () => {+ let identity: Identity;+ let otherIdentity: Identity;++ beforeAll(async () => {+ identity = await idmux({+ name: "scrape-browser-replay",+ concurrency: 20,+ credits: 1_000_000,+ });+ otherIdentity = await idmux({+ name: "scrape-browser-replay-other",+ concurrency: 10,+ credits: 1_000_000,+ });+ }, 10000 + scrapeTimeout);++ const canRunReplayHappyPath =+ ALLOW_TEST_SUITE_WEBSITE &&+ !!config.BROWSER_SERVICE_URL &&+ (TEST_PRODUCTION || HAS_FIRE_ENGINE);++ itIf(canRunReplayHappyPath)(+ "replays scrape URL/waitFor/actions before interactive code runs",+ async () => {+ const marker = crypto.randomUUID();+ const url = `${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}`;+ let scrapeId: string | null = null;++ try {+ const scrapeResponse = await scrapeRaw(+ {+ url,+ origin: "website-replay-test",+ waitFor: 500,+ actions: [+ {+ type: "executeJavascript",+ script: `window.__firecrawlReplayMarker = "${marker}";`,+ },+ ],+ },+ identity,+ );++ expect(scrapeResponse.statusCode).toBe(200);+ expect(scrapeResponse.body.success).toBe(true);+ expect(typeof scrapeResponse.body.scrape_id).toBe("string");+ scrapeId = scrapeResponse.body.scrape_id as string;++ const executeResponse = await interactWithReplicaRetry(+ scrapeId,+ {+ language: "node",+ timeout: 60,+ code: `+ const replayMarker = await page.evaluate(() => window.__firecrawlReplayMarker ?? null);+ console.log(replayMarker ?? "missing-marker");+ `,+ },+ identity,+ );++ expect(executeResponse.statusCode).toBe(200);+ expect(executeResponse.body.success).toBe(true);+ expect(executeResponse.body.stdout).toContain(marker);+ } finally {+ if (scrapeId) {+ await scrapeStopInteractiveBrowserRaw(scrapeId, identity);+ }+ }+ },+ scrapeTimeout,+ );++ itIf(canRunReplayHappyPath)(+ "keeps a non-blank replay tab in the foreground for follow-up execs",+ async () => {+ const url = `${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}`;+ let scrapeId: string | null = null;++ try {+ const scrapeResponse = await scrapeRaw(+ {+ url,+ origin: "website-replay-test",+ actions: [+ {+ type: "executeJavascript",+ script: "window.open('about:blank', '_blank');",+ },+ ],+ },+ identity,+ );++ expect(scrapeResponse.statusCode).toBe(200);+ expect(scrapeResponse.body.success).toBe(true);+ expect(typeof scrapeResponse.body.scrape_id).toBe("string");+ scrapeId = scrapeResponse.body.scrape_id as string;++ const executeResponse = await interactWithReplicaRetry(+ scrapeId,+ {+ language: "node",+ timeout: 60,+ code: `+ const visibleUrls = [];+ for (const candidate of page.context().pages()) {+ try {+ const isVisible = await candidate.evaluate(+ () => document.visibilityState === "visible",+ );+ if (isVisible) {+ visibleUrls.push(candidate.url());+ }+ } catch {}+ }++ const visibleNonBlankUrl =+ visibleUrls.find(value => value !== "about:blank") ?? "about:blank";+ console.log(visibleNonBlankUrl);+ `,+ },+ identity,+ );++ expect(executeResponse.statusCode).toBe(200);+ expect(executeResponse.body.success).toBe(true);++ const visibleUrl =+ executeResponse.body.stdout+ ?.trim()+ .split("\n")+ .filter(Boolean)+ .pop() ?? "";++ expect(visibleUrl).not.toBe("about:blank");+ expect(visibleUrl).toContain(TEST_SUITE_WEBSITE);+ } finally {+ if (scrapeId) {+ await scrapeStopInteractiveBrowserRaw(scrapeId, identity);+ }+ }+ },+ scrapeTimeout,+ );++ it("returns 400 for invalid scrape job id format", async () => {+ const response = await scrapeInteractRaw(+ "not-a-valid-uuid",+ {+ code: "console.log('hi')",+ language: "node",+ },+ identity,+ );++ expect(response.statusCode).toBe(400);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toBe(+ "Invalid job ID format. Job ID must be a valid UUID.",+ );+ });++ it("returns 404 when scrape job does not exist", async () => {+ const response = await scrapeInteractRaw(+ crypto.randomUUID(),+ {+ code: "console.log('hi')",+ language: "node",+ },+ identity,+ );++ expect(response.statusCode).toBe(404);+ expect(response.body.success).toBe(false);+ expect(response.body.error).toBe("Job not found.");+ });++ itIf(ALLOW_TEST_SUITE_WEBSITE && !!config.IDMUX_URL)(+ "returns 403 when scrape job belongs to another team",+ async () => {+ const scrapeResponse = await scrapeRaw(+ {+ url: `${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}`,+ origin: "website-replay-test",+ },+ identity,+ );++ expect(scrapeResponse.statusCode).toBe(200);+ expect(scrapeResponse.body.success).toBe(true);+ expect(typeof scrapeResponse.body.scrape_id).toBe("string");++ const scrapeId = scrapeResponse.body.scrape_id as string;+ const executeResponse = await interactWithReplicaRetry(+ scrapeId,+ {+ code: "console.log('should fail')",+ language: "node",+ },+ otherIdentity,+ );++ expect(executeResponse.statusCode).toBe(403);+ expect(executeResponse.body.success).toBe(false);+ expect(executeResponse.body.error).toBe("Forbidden.");+ },+ scrapeTimeout,+ );++ itIf(ALLOW_TEST_SUITE_WEBSITE)(+ "returns replay-context error when scrape data is not retained",+ async () => {+ const scrapeResponse = await scrapeRaw(+ {+ url: `${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}`,+ origin: "website-replay-test",+ zeroDataRetention: true,+ },+ identity,+ );++ expect(scrapeResponse.statusCode).toBe(200);+ expect(scrapeResponse.body.success).toBe(true);+ expect(typeof scrapeResponse.body.scrape_id).toBe("string");++ const scrapeId = scrapeResponse.body.scrape_id as string;+ const executeResponse = await interactWithReplicaRetry(+ scrapeId,+ {+ code: "console.log('should not run')",+ language: "node",+ },+ identity,+ );++ expect(executeResponse.statusCode).toBe(409);+ expect(executeResponse.body.success).toBe(false);+ expect(executeResponse.body.error).toContain(+ "Replay context is unavailable",+ );+ },+ scrapeTimeout,+ );+});diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.tsindex 14385cb0d..78e2024ce 100644--- a/apps/api/src/controllers/v2/browser.ts+++ b/apps/api/src/controllers/v2/browser.ts@@ -464,6 +464,7 @@ export async function browserExecuteController(enqueueBrowserSessionActivity({team_id: req.auth.team_id,session_id: id,+ source: "browser",language,timeout,exit_code: execResult.exitCode ?? null,@@ -552,8 +553,11 @@ export async function browserDeleteController(});}+ const wallClockMs = Date.now() - new Date(session.created_at).getTime();const durationMs =- sessionDurationMs ?? Date.now() - new Date(session.created_at).getTime();+ sessionDurationMs && sessionDurationMs > 0+ ? sessionDurationMs+ : wallClockMs;const creditsBilled = calculateBrowserSessionCredits(durationMs);updateBrowserSessionCreditsUsed(session.id, creditsBilled).catch(error => {@@ -623,8 +627,8 @@ export async function browserListController(id: r.id,status: r.status,cdpUrl: r.cdp_url,- liveViewUrl: r.cdp_path, // cdp_path stores the view URL- interactiveLiveViewUrl: r.cdp_interactive_path, // cdp_interactive_path stores the interactive view URL+ liveViewUrl: r.cdp_path,+ interactiveLiveViewUrl: r.cdp_interactive_path,streamWebView: r.stream_web_view,createdAt: r.created_at,lastActivity: r.updated_at,diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.tsnew file mode 100644index 000000000..aba06ada7--- /dev/null+++ b/apps/api/src/controllers/v2/scrape-browser.ts@@ -0,0 +1,647 @@+import { createHash } from "crypto";+import { v7 as uuidv7 } from "uuid";+import { Response } from "express";+import { z } from "zod";+import { logger as _logger } from "../../lib/logger";+import { config } from "../../config";+import {+ insertBrowserSession,+ updateBrowserSessionActivity,+ updateBrowserSessionCreditsUsed,+ claimBrowserSessionDestroyed,+ getActiveBrowserSessionCount,+ invalidateActiveBrowserSessionCount,+ MAX_ACTIVE_BROWSER_SESSIONS_PER_TEAM,+ getBrowserSessionFromScrape,+} from "../../lib/browser-sessions";+import {+ browserServiceRequest,+ BrowserServiceError,+ BrowserServiceExecResponse,+ BrowserServiceCreateResponse,+ BrowserServiceDeleteResponse,+} from "../../lib/scrape-interact/browser-service-client";+import {+ ScrapeContextRow,+ buildReplayContextFromScrape,+ estimateReplayTimeoutSeconds,+ buildReplayScript,+} from "../../lib/scrape-interact/scrape-replay";+import {+ executePromptViaBrowserAgent,+ AgentResult,+} from "../../lib/scrape-interact/browser-agent";+import { RequestWithAuth, ScrapeOptions } from "./types";+import { billTeam } from "../../services/billing/credit_billing";+import { enqueueBrowserSessionActivity } from "../../lib/browser-session-activity";+import { logRequest } from "../../services/logging/log_job";+import { integrationSchema } from "../../utils/integration";+import { supabaseGetScrapeById } from "../../lib/supabase-jobs";++// ---------------------------------------------------------------------------+// Constants & schemas+// ---------------------------------------------------------------------------++const BROWSER_CREDITS_PER_HOUR = 120;++function calculateBrowserSessionCredits(durationMs: number): number {+ const hours = durationMs / 3_600_000;+ return Math.max(1, Math.ceil(hours * BROWSER_CREDITS_PER_HOUR));+}++const browserCreateRequestSchema = z.object({+ ttl: z.number().min(30).max(3600).default(600),+ activityTtl: z.number().min(10).max(3600).default(300),+ streamWebView: z.boolean().default(true),+ integration: integrationSchema.optional().transform(val => val || null),+ profile: z+ .object({+ name: z.string().min(1).max(128),+ saveChanges: z.boolean().default(true),+ })+ .optional(),+});++const browserExecuteRequestSchema = z+ .object({+ code: z.string().min(1).max(100_000).optional(),+ prompt: z.string().min(1).max(10_000).optional(),+ language: z.enum(["python", "node", "bash"]).default("node"),+ timeout: z.number().min(1).max(300).default(30),+ origin: z.string().optional(),+ integration: integrationSchema.optional().transform(val => val || null),+ })+ .refine(data => data.code || data.prompt, {+ message: "Either 'code' or 'prompt' must be provided.",+ });++type BrowserExecuteRequest = z.infer<typeof browserExecuteRequestSchema>;++interface BrowserExecuteResponse {+ success: boolean;+ liveViewUrl?: string;+ interactiveLiveViewUrl?: string;+ output?: string;+ stdout?: string;+ result?: string;+ stderr?: string;+ exitCode?: number;+ killed?: boolean;+ error?: string;+}++interface BrowserDeleteResponse {+ success: boolean;+ sessionDurationMs?: number;+ creditsBilled?: number;+ error?: string;+}++// ---------------------------------------------------------------------------+// POST /v2/scrape/:jobId/interact+// ---------------------------------------------------------------------------++export async function scrapeInteractController(+ req: RequestWithAuth<+ { jobId: string },+ BrowserExecuteResponse,+ BrowserExecuteRequest+ >,+ res: Response<BrowserExecuteResponse>,+) {+ req.body = browserExecuteRequestSchema.parse(req.body);++ const scrapeId = req.params.jobId;+ const { code: rawCode, prompt, language, timeout, origin } = req.body;++ let logger = _logger.child({+ scrapeId,+ teamId: req.auth.team_id,+ module: "api/v2",+ method: "scrapeInteractController",+ });++ // --- Validate scrape ownership ---++ const scrape = (await supabaseGetScrapeById(+ scrapeId,+ )) as ScrapeContextRow | null;+ if (!scrape) {+ return res.status(404).json({ success: false, error: "Job not found." });+ }+ if (scrape.team_id !== req.auth.team_id) {+ return res.status(403).json({ success: false, error: "Forbidden." });+ }++ // --- Build replay context from original scrape ---++ const replay = buildReplayContextFromScrape(scrape);+ if (!replay.context) {+ return res.status(409).json({+ success: false,+ error:+ replay.error ??+ "Replay context is unavailable for this scrape job. Please rerun the scrape.",+ });+ }+ const replayContext = replay.context;++ logger = logger.child({+ replayTargetUrl: replayContext.targetUrl,+ replayWaitForMs: replayContext.waitForMs,+ replayActions: replayContext.actions.length,+ });++ // --- Ensure a browser session exists (create + replay if needed) ---++ let session = await getBrowserSessionFromScrape(scrapeId);++ if (!session) {+ const created = await createSessionForScrape(+ req,+ scrapeId,+ replayContext,+ logger,+ (scrape.options as ScrapeOptions).profile,+ );+ if ("error" in created) {+ return res.status(created.status).json(created.body);+ }+ session = created.session;++ logger = logger.child({+ sessionId: session.id,+ browserId: session.browser_id,+ });+ logger.info("Browser session created for scrape", {+ scrapeId,+ sessionId: session.id,+ browserId: session.browser_id,+ });+ }++ if (session.team_id !== req.auth.team_id) {+ return res.status(403).json({ success: false, error: "Forbidden." });+ }+ if (session.status === "destroyed") {+ return res+ .status(410)+ .json({ success: false, error: "Browser session has been destroyed." });+ }++ updateBrowserSessionActivity(session.id).catch(() => {});++ // --- Execute: prompt-based agent loop OR direct code ---++ let execResult: BrowserServiceExecResponse | AgentResult;++ if (prompt && !rawCode) {+ logger.info("Starting agent loop from prompt", { prompt, timeout });++ try {+ execResult = await executePromptViaBrowserAgent(+ prompt,+ session.browser_id,+ timeout,+ logger,+ );+ } catch (err) {+ logger.error("Agent loop failed", { error: err });+ return res.status(502).json({+ success: false,+ error: "Browser agent failed to execute the task.",+ });+ }++ enqueueBrowserSessionActivity({+ team_id: req.auth.team_id,+ session_id: session.id,+ source: "interact",+ language: "bash",+ timeout,+ exit_code: execResult.exitCode ?? null,+ killed: execResult.killed ?? false,+ });+ } else {+ logger.info("Executing code in browser session", { language, timeout });++ try {+ execResult = await browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${session.browser_id}/exec`,+ { code: rawCode!, language, timeout, origin },+ );+ } catch (err) {+ logger.error("Failed to execute code via browser service", {+ error: err,+ });+ return res.status(502).json({+ success: false,+ error: "Failed to execute code in browser session.",+ });+ }++ enqueueBrowserSessionActivity({+ team_id: req.auth.team_id,+ session_id: session.id,+ source: "interact",+ language,+ timeout,+ exit_code: execResult.exitCode ?? null,+ killed: execResult.killed ?? false,+ });+ }++ // --- Respond ---++ logger.debug("Execution result", {+ exitCode: execResult.exitCode,+ killed: execResult.killed,+ stdoutLength: execResult.stdout?.length,+ stderrLength: execResult.stderr?.length,+ });++ const hasError = execResult.exitCode !== 0 || execResult.killed;+ const agentOutput = "output" in execResult ? execResult.output : undefined;++ return res.status(200).json({+ success: !hasError,+ liveViewUrl: session.cdp_path,+ interactiveLiveViewUrl: session.cdp_interactive_path,+ ...(agentOutput ? { output: agentOutput } : {}),+ stdout: execResult.stdout,+ result: execResult.result,+ stderr: execResult.stderr,+ exitCode: execResult.exitCode,+ killed: execResult.killed,+ ...(hasError ? { error: execResult.stderr || "Execution failed" } : {}),+ });+}++// ---------------------------------------------------------------------------+// DELETE /v2/scrape/:jobId/interact+// ---------------------------------------------------------------------------++export async function scrapeStopInteractiveBrowserController(+ req: RequestWithAuth<{ jobId: string }, BrowserDeleteResponse>,+ res: Response<BrowserDeleteResponse>,+) {+ let logger = _logger.child({+ scrapeId: req.params.jobId,+ teamId: req.auth.team_id,+ module: "api/v2",+ method: "scrapeStopInteractiveBrowserController",+ });++ const session = await getBrowserSessionFromScrape(req.params.jobId);++ if (!session) {+ return res+ .status(404)+ .json({ success: false, error: "Browser session not found." });+ }+ if (session.team_id !== req.auth.team_id) {+ return res.status(403).json({ success: false, error: "Forbidden." });+ }++ logger = logger.child({+ sessionId: session.id,+ browserId: session.browser_id,+ });+ logger.info("Deleting browser session");++ let sessionDurationMs: number | undefined;+ try {+ const deleteResult =+ await browserServiceRequest<BrowserServiceDeleteResponse>(+ "DELETE",+ `/browsers/${session.browser_id}`,+ );+ sessionDurationMs = deleteResult?.sessionDurationMs;+ } catch (err) {+ logger.warn("Failed to delete browser session via browser service", {+ error: err,+ });+ }++ const claimed = await claimBrowserSessionDestroyed(session.id);++ invalidateActiveBrowserSessionCount(session.team_id).catch(() => {});++ if (!claimed) {+ logger.info("Session already destroyed by another path, skipping billing", {+ sessionId: session.id,+ });+ return res.status(200).json({ success: true });+ }++ const wallClockMs = Date.now() - new Date(session.created_at).getTime();+ const durationMs =+ sessionDurationMs && sessionDurationMs > 0+ ? sessionDurationMs+ : wallClockMs;+ const creditsBilled = calculateBrowserSessionCredits(durationMs);++ updateBrowserSessionCreditsUsed(session.id, creditsBilled).catch(error => {+ logger.error("Failed to update credits_used on browser session", {+ error,+ sessionId: session.id,+ creditsBilled,+ });+ });++ billTeam(+ req.auth.team_id,+ req.acuc?.sub_id ?? undefined,+ creditsBilled,+ req.acuc?.api_key_id ?? null,+ { endpoint: "interact", jobId: session.id },+ ).catch(error => {+ logger.error("Failed to bill team for interact session", {+ error,+ creditsBilled,+ durationMs,+ });+ });++ logger.info("Browser session destroyed", {+ sessionDurationMs: durationMs,+ creditsBilled,+ });++ return res.status(200).json({ success: true });+}++// ---------------------------------------------------------------------------+// Internal: create a browser session for a scrape, replay original context+// ---------------------------------------------------------------------------++async function createSessionForScrape(+ req: RequestWithAuth<any, any, any>,+ scrapeId: string,+ replayContext: ReturnType<typeof buildReplayContextFromScrape> extends {+ context?: infer C;+ }+ ? NonNullable<C>+ : never,+ logger: typeof _logger,+ profile: { name: string; saveChanges: boolean } | undefined,+): Promise<+ | { session: Awaited<ReturnType<typeof insertBrowserSession>> }+ | { status: number; body: { success: false; error: string }; error: true }+> {+ const sessionId = uuidv7();+ const { ttl, activityTtl, streamWebView } = browserCreateRequestSchema.parse(+ {},+ );+ const integration = req.body?.integration ?? null;++ if (!config.BROWSER_SERVICE_URL) {+ return {+ status: 503,+ body: {+ success: false,+ error:+ "Browser feature is not configured (BROWSER_SERVICE_URL is missing).",+ },+ error: true,+ };+ }++ logger.info("No browser session found for scrape. Creating one.", {+ scrapeId,+ ttl,+ activityTtl,+ });++ // Credit check+ const estimatedCredits = calculateBrowserSessionCredits(ttl * 1000);+ if (req.acuc && req.acuc.remaining_credits < estimatedCredits) {+ return {+ status: 402,+ body: {+ success: false,+ error: `Insufficient credits for a ${ttl}s browser session (requires ~${estimatedCredits} credits). For more credits, you can upgrade your plan at https://firecrawl.dev/pricing.`,+ },+ error: true,+ };+ }++ // Active session limit+ const activeCount = await getActiveBrowserSessionCount(req.auth.team_id);+ if (activeCount >= MAX_ACTIVE_BROWSER_SESSIONS_PER_TEAM) {+ return {+ status: 429,+ body: {+ success: false,+ error: `You have reached the maximum number of active browser sessions (${MAX_ACTIVE_BROWSER_SESSIONS_PER_TEAM}). Please destroy existing sessions before creating new ones.`,+ },+ error: true,+ };+ }++ // Create the browser session (retry up to 3 times)+ const MAX_CREATE_RETRIES = 3;+ let svcResponse: BrowserServiceCreateResponse | undefined;+ let lastCreateError: unknown;++ let persistentStorage: { uniqueId: string; write: boolean } | undefined;+ if (profile) {+ const teamHash = createHash("sha256")+ .update(req.auth.team_id)+ .digest("hex")+ .slice(0, 16);+ persistentStorage = {+ uniqueId: `${teamHash}_${profile.name}`,+ write: profile.saveChanges !== false,+ };+ }++ for (let attempt = 1; attempt <= MAX_CREATE_RETRIES; attempt++) {+ try {+ svcResponse = await browserServiceRequest<BrowserServiceCreateResponse>(+ "POST",+ "/browsers",+ {+ ttl,+ ...(activityTtl !== undefined ? { activityTtl } : {}),+ ...(persistentStorage !== undefined ? { persistentStorage } : {}),+ },+ );+ break;+ } catch (err) {+ if (err instanceof BrowserServiceError && err.status === 409) {+ return {+ status: 409,+ body: {+ success: false,+ error:+ "Another session is currently writing to this profile. Only one writer is allowed at a time. You can still access it with saveChanges: false, or try again later.",+ },+ error: true,+ };+ }+ lastCreateError = err;+ logger.warn("Browser session creation attempt failed", {+ attempt,+ maxRetries: MAX_CREATE_RETRIES,+ error: err,+ });+ if (attempt < MAX_CREATE_RETRIES) {+ await new Promise(resolve => setTimeout(resolve, 200 * attempt));+ }+ }+ }++ if (!svcResponse) {+ logger.error("Failed to create browser session after all retries", {+ error: lastCreateError,+ });+ return {+ status: 502,+ body: { success: false, error: "Failed to create browser session." },+ error: true,+ };+ }++ // Replay original scrape context+ try {+ const replayResult =+ await browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${svcResponse.sessionId}/exec`,+ {+ code: buildReplayScript(replayContext),+ language: "node",+ timeout: estimateReplayTimeoutSeconds(replayContext),+ origin: "scrape_replay",+ },+ );++ if (replayResult.exitCode !== 0 || replayResult.killed) {+ throw new Error(+ replayResult.stderr?.trim() ||+ replayResult.stdout?.trim() ||+ "Replay script exited with an error.",+ );+ }++ // Ensure only one tab exists with the content page in the foreground.+ // The replay may have created extra tabs. Find the one with content,+ // close everything else, update the REPL's page var, and bring to front.+ await browserServiceRequest(+ "POST",+ `/browsers/${svcResponse.sessionId}/exec`,+ {+ code: [+ `const ctx = page.context();`,+ `const pages = ctx.pages();`,+ `if (pages.length > 1) {`,+ ` const target = pages.find(p => { const u = p.url(); return u && u !== 'about:blank'; }) || pages[pages.length - 1];`,+ ` for (const p of pages) { if (p !== target) await p.close().catch(() => {}); }`,+ ` page = target;`,+ `}`,+ `await page.bringToFront();`,+ ].join("\n"),+ language: "node",+ timeout: 10,+ origin: "tab_sync",+ },+ ).catch(() => {});++ // Sync agent-browser to the correct page+ const syncResult = await browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${svcResponse.sessionId}/exec`,+ {+ code: `agent-browser get url`,+ language: "bash",+ timeout: 10,+ origin: "scrape_replay_sync",+ },+ );++ const agentUrl = (syncResult.stdout || "").trim();+ if (!agentUrl || agentUrl === "about:blank") {+ logger.info("agent-browser on wrong page after replay, navigating", {+ agentUrl,+ targetUrl: replayContext.targetUrl,+ });+ await browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${svcResponse.sessionId}/exec`,+ {+ code: `await page.goto(${JSON.stringify(replayContext.targetUrl)}, { waitUntil: "networkidle0" });`,+ language: "node",+ timeout: 30,+ origin: "scrape_replay_sync",+ },+ );+ }+ } catch (err) {+ logger.error("Failed to initialize scrape browser session context", {+ error: err,+ });+ await browserServiceRequest(+ "DELETE",+ `/browsers/${svcResponse.sessionId}`,+ ).catch(() => {});+ return {+ status: 409,+ body: {+ success: false,+ error:+ "Failed to initialize browser session from the original scrape context. Please rerun the scrape and try again.",+ },+ error: true,+ };+ }++ // Persist in Supabase+ try {+ await logRequest({+ id: sessionId,+ kind: "interact",+ api_version: "v2",+ team_id: req.auth.team_id,+ target_hint: "Interact session",+ origin: req.body?.origin ?? "api",+ integration: integration ?? null,+ zeroDataRetention: false,+ api_key_id: req.acuc?.api_key_id ?? null,+ });+ const session = await insertBrowserSession({+ id: sessionId,+ team_id: req.auth.team_id,+ scrape_id: scrapeId,+ browser_id: svcResponse.sessionId,+ workspace_id: "",+ context_id: "",+ cdp_url: svcResponse.cdpUrl,+ cdp_path: svcResponse.iframeUrl,+ cdp_interactive_path: svcResponse.interactiveIframeUrl,+ stream_web_view: streamWebView,+ status: "active",+ ttl_total: ttl,+ ttl_without_activity: activityTtl ?? null,+ credits_used: null,+ });++ invalidateActiveBrowserSessionCount(req.auth.team_id).catch(() => {});++ return { session };+ } catch (err) {+ logger.error("Failed to persist browser session, cleaning up", {+ error: err,+ });+ await browserServiceRequest(+ "DELETE",+ `/browsers/${svcResponse.sessionId}`,+ ).catch(() => {});+ return {+ status: 500,+ body: { success: false, error: "Failed to persist browser session." },+ error: true,+ };+ }+}diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.tsindex b14c31ac0..7bbcbb888 100644--- a/apps/api/src/controllers/v2/types.ts+++ b/apps/api/src/controllers/v2/types.ts@@ -571,6 +571,14 @@ const baseScrapeOptions = z.strictObject({maxAge: z.int().gte(0).optional(),minAge: z.int().gte(0).optional(),storeInCache: z.boolean().prefault(true),++ profile: z+ .object({+ name: z.string().min(1).max(128),+ saveChanges: z.boolean().default(true),+ })+ .optional(),+// @deprecated__searchPreviewToken: z.string().optional(),__experimental_omce: z.boolean().prefault(false).optional(),diff --git a/apps/api/src/lib/browser-session-activity.ts b/apps/api/src/lib/browser-session-activity.tsindex 06b418da7..74d7659b8 100644--- a/apps/api/src/lib/browser-session-activity.ts+++ b/apps/api/src/lib/browser-session-activity.ts@@ -10,6 +10,7 @@ const BATCH_SIZE = 500;interface BrowserSessionActivityEvent {team_id: string;session_id: string;+ source: "interact" | "browser";language: string;timeout: number;exit_code: number | null;@@ -25,17 +26,14 @@ export function enqueueBrowserSessionActivity(created_at: new Date().toISOString(),};- redisEvictConnection- .rpush(QUEUE_KEY, JSON.stringify(row))- .catch(() => {});+ redisEvictConnection.rpush(QUEUE_KEY, JSON.stringify(row)).catch(() => {});}export async function processBrowserSessionActivityJobs() {- const raw =- (await redisEvictConnection.lpop(QUEUE_KEY, BATCH_SIZE)) ?? [];+ const raw = (await redisEvictConnection.lpop(QUEUE_KEY, BATCH_SIZE)) ?? [];if (raw.length === 0) return;- const rows: BrowserSessionActivityEvent[] = raw.map((x) => JSON.parse(x));+ const rows: BrowserSessionActivityEvent[] = raw.map(x => JSON.parse(x));try {const { error } = await supabase_servicediff --git a/apps/api/src/lib/browser-sessions.ts b/apps/api/src/lib/browser-sessions.tsindex 1c6d8ea3f..18308e3c0 100644--- a/apps/api/src/lib/browser-sessions.ts+++ b/apps/api/src/lib/browser-sessions.ts@@ -16,6 +16,7 @@ type BrowserSessionStatus = "active" | "destroyed" | "error";interface BrowserSessionRow {id: string;team_id: string;+ scrape_id?: string | null; // linked scrape job id for /scrape/:jobId/interact sessionsbrowser_id: string; // browser service sessionIdworkspace_id: string; // unused (legacy), stored as ""context_id: string; // unused (legacy), stored as ""@@ -79,6 +80,26 @@ export async function getBrowserSession(return data as BrowserSessionRow;}+export async function getBrowserSessionFromScrape(+ id: string,+): Promise<BrowserSessionRow | null> {+ const { data, error } = await supabase_service+ .from(TABLE)+ .select("*")+ .eq("scrape_id", id)+ .single();++ if (error) {+ if (isPostgrestNoRowsError(error)) return null;+ logger.error("Failed to get browser session from scrape", { error, id });+ throw new Error(+ `Failed to get browser session from scrape: ${error.message}`,+ );+ }++ return data as BrowserSessionRow;+}+export async function listBrowserSessions(teamId: string,opts?: { status?: BrowserSessionStatus },diff --git a/apps/api/src/lib/scrape-interact/browser-agent.ts b/apps/api/src/lib/scrape-interact/browser-agent.tsnew file mode 100644index 000000000..941fcc048--- /dev/null+++ b/apps/api/src/lib/scrape-interact/browser-agent.ts@@ -0,0 +1,365 @@+import { z } from "zod";+import { promises as fs } from "fs";+import path from "path";+import { generateText, tool, stepCountIs } from "ai";+import { logger as _logger } from "../logger";+import { getModel } from "../generic-ai";+import {+ browserServiceRequest,+ BrowserServiceExecResponse,+} from "./browser-service-client";+import { config } from "../../config";++// ---------------------------------------------------------------------------+// Constants+// ---------------------------------------------------------------------------++const MAX_STEPS = 25;+const SNAPSHOT_TIMEOUT = 15;+const SNAPSHOT_MAX_CHARS = 40_000;++// ---------------------------------------------------------------------------+// Debug log+// ---------------------------------------------------------------------------++const AGENT_LOG_DIR = path.join(+ __dirname,+ "../../logs/scrape-interact-agent-logs",+);++const IS_PRODUCTION = config.IS_PRODUCTION === true;++class AgentDebugLog {+ private filePath: string;+ private lines: string[] = [];+ private enabled: boolean;++ constructor(browserId: string) {+ this.enabled = !IS_PRODUCTION;+ const ts = new Date().toISOString().replace(/[:.]/g, "-");+ this.filePath = path.join(AGENT_LOG_DIR, `${ts}_${browserId}.log`);+ }++ add(text: string) {+ if (!this.enabled) return;+ this.lines.push(text);+ }++ async flush() {+ if (!this.enabled || this.lines.length === 0) return;+ try {+ await fs.mkdir(AGENT_LOG_DIR, { recursive: true });+ await fs.appendFile(this.filePath, this.lines.join("\n") + "\n");+ this.lines = [];+ } catch (err) {+ _logger.error("AgentDebugLog flush failed", {+ filePath: this.filePath,+ agentLogDir: AGENT_LOG_DIR,+ error: err,+ });+ }+ }++ getPath() {+ return this.filePath;+ }+}++// ---------------------------------------------------------------------------+// System prompt+// ---------------------------------------------------------------------------++const SYSTEM_PROMPT = `You are an autonomous browser automation agent. You complete tasks by interacting with a browser using the browser tool. Be autonomous — break tasks into steps, execute ALL steps without stopping early, and be concise.++## Browser Tool — agent-browser commands+The browser tool runs agent-browser CLI commands. Each tool call should contain a single command or a short chain (joined with &&).++Commands:+ agent-browser snapshot Get full accessibility tree with clickable refs (@e1, @e2...)+ agent-browser snapshot -i Only interactive elements+ agent-browser snapshot -s "#css" Scope snapshot to a CSS selector+ agent-browser click @e1 Click element by ref+ agent-browser fill @e2 "text" Clear field and type text+ agent-browser type @e2 "text" Type without clearing+ agent-browser select @e1 "option" Select dropdown option+ agent-browser check @e1 Toggle checkbox+ agent-browser press Enter Press a key+ agent-browser keyboard type "text" Type at current focus+ agent-browser hover @e1 Hover element+ agent-browser scroll down 500 Scroll down (px)+ agent-browser scroll up 500 Scroll up (px)+ agent-browser get text @e1 Get text content of element+ agent-browser get title Get page title+ agent-browser get url Get current URL+ agent-browser wait @e1 Wait for element to appear+ agent-browser wait --load networkidle Wait for network idle+ agent-browser wait --text "Welcome" Wait for text to appear+ agent-browser wait 2000 Wait milliseconds+ agent-browser find text "X" click Find element by text and click+ agent-browser find role button click --name "Submit"+ agent-browser find placeholder "Q" type "query"+ agent-browser frame @e2 Scope to iframe+ agent-browser frame main Return to main frame+ agent-browser eval "js code" Run JavaScript in page+ agent-browser back Go back++## Workflow+1. An initial page snapshot is provided — use it immediately, don't re-snapshot.+2. Interact with elements using @refs from the snapshot.+3. After interactions that change the page, call snapshot to see the updated state.+4. Use the new @refs from the latest snapshot for further interactions.+5. Repeat until the task is complete.++## Rules+1. You are already on the target page. Do NOT navigate to external sites or search engines.+2. @refs are invalidated after page changes — always snapshot again after interactions.+3. Chain independent commands with && to save round-trips.+4. When extracting data, use agent-browser get text or agent-browser eval to pull content.+5. If a command fails, try a different approach (different selector, wait first, use find, etc.).+6. NEVER open new tabs. Always work in the current tab. Do not use agent-browser tab new or agent-browser open. If you need to navigate within the site, click links directly.++## Output Format+Your final text response is what the user sees. It MUST be a clean, human-readable answer:+- If asked for a price → respond with the product name and price (e.g. "iPhone 15 Pro Max: $1,199")+- If asked for a list → respond with a clean list of items+- If asked to perform an action → confirm what was done+- NEVER dump raw HTML, accessibility trees, or @ref identifiers in your final response+- Be concise and direct — just the answer the user asked for`;++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++export interface AgentResult extends BrowserServiceExecResponse {+ output: string;+}++async function execInBrowser(+ browserId: string,+ code: string,+ timeout: number,+ origin: string,+): Promise<BrowserServiceExecResponse> {+ return browserServiceRequest<BrowserServiceExecResponse>(+ "POST",+ `/browsers/${browserId}/exec`,+ { code, language: "bash", timeout, origin },+ );+}++async function getCurrentUrl(browserId: string): Promise<string> {+ try {+ const result = await execInBrowser(+ browserId,+ "agent-browser get url",+ SNAPSHOT_TIMEOUT,+ "agent_get_url",+ );+ return (result.stdout || result.result || "").trim();+ } catch {+ return "";+ }+}++async function takeSnapshot(browserId: string): Promise<string> {+ try {+ const result = await execInBrowser(+ browserId,+ "agent-browser snapshot -i",+ SNAPSHOT_TIMEOUT,+ "agent_snapshot",+ );+ return (result.stdout || result.result || "").slice(0, SNAPSHOT_MAX_CHARS);+ } catch {+ return "";+ }+}++// ---------------------------------------------------------------------------+// Main agent — tool-calling loop via AI SDK+// ---------------------------------------------------------------------------++export async function executePromptViaBrowserAgent(+ prompt: string,+ browserId: string,+ stepTimeout: number,+ logger: typeof _logger,+): Promise<AgentResult> {+ const debugLog = new AgentDebugLog(browserId);+ debugLog.add(`=== AGENT RUN ===`);+ debugLog.add(`Time: ${new Date().toISOString()}`);+ debugLog.add(`Browser: ${browserId}`);+ debugLog.add(`Prompt: ${prompt}\n`);+ logger.info("Agent debug log", { path: debugLog.getPath() });++ const [initialSnapshot, initialUrl] = await Promise.all([+ takeSnapshot(browserId),+ getCurrentUrl(browserId),+ ]);++ debugLog.add(`URL: ${initialUrl}`);+ debugLog.add(+ `Snapshot (${initialSnapshot.length} chars):\n${initialSnapshot || "(empty)"}\n`,+ );+ debugLog.flush();++ let toolCallCount = 0;+ const allOutputs: string[] = [];+ let lastSnapshotResult = initialSnapshot;+ const actionLog: string[] = [];++ const browserTool = tool({+ description:+ "Run an agent-browser CLI command in the browser. Each call should be one command or a short && chain.",+ inputSchema: z.object({+ code: z.string().describe("The agent-browser command(s) to execute"),+ }),+ execute: async ({ code }) => {+ toolCallCount++;+ const start = Date.now();+ debugLog.add(`--- [${toolCallCount}] ${code} ---`);++ if (/agent-browser\s+(tab\s+new|open\s)/.test(code)) {+ const msg =+ "Blocked: opening new tabs/URLs is not allowed. Use click to navigate within the site.";+ debugLog.add(`BLOCKED: ${msg}\n`);+ actionLog.push(`${toolCallCount}. ${code} → BLOCKED`);+ return { error: msg };+ }++ try {+ const result = await execInBrowser(+ browserId,+ code,+ stepTimeout,+ "agent_action",+ );+ const output = (result.stdout || result.result || "").trim();++ // Ensure only one tab exists and it's in the foreground for live view+ try {+ await browserServiceRequest("POST", `/browsers/${browserId}/exec`, {+ code: [+ `const ctx = page.context();`,+ `const pages = ctx.pages();`,+ `if (pages.length > 1) {`,+ ` const target = pages.find(p => { const u = p.url(); return u && u !== 'about:blank'; }) || pages[pages.length - 1];`,+ ` for (const p of pages) { if (p !== target) await p.close().catch(() => {}); }`,+ ` page = target;`,+ `}`,+ `await page.bringToFront();`,+ ].join("\n"),+ language: "node",+ timeout: 5,+ origin: "tab_sync",+ });+ } catch {}++ const elapsed = Date.now() - start;++ debugLog.add(`Exit: ${result.exitCode} (${elapsed}ms)`);+ if (output) debugLog.add(`Output:\n${output}`);+ if (result.stderr) debugLog.add(`Stderr:\n${result.stderr}`);+ debugLog.add("");+ debugLog.flush();++ if (code.includes("snapshot")) lastSnapshotResult = output;+ if (output) allOutputs.push(output);++ const brief = code.includes("snapshot")+ ? `(${output.length} chars)`+ : (output || result.stderr || "").slice(0, 120);+ const status =+ result.exitCode === 0 ? "OK" : `FAIL(${result.exitCode})`;+ actionLog.push(`${toolCallCount}. ${code} → ${status}: ${brief}`);++ if (result.exitCode !== 0) {+ return {+ error: result.stderr || "Command failed",+ exit_code: result.exitCode,+ output,+ };+ }+ return { result: output || "(no output)" };+ } catch (err: unknown) {+ const msg = err instanceof Error ? err.message : String(err);+ debugLog.add(`Error: ${msg}\n`);+ debugLog.flush();+ actionLog.push(+ `${toolCallCount}. ${code} → ERROR: ${msg.slice(0, 120)}`,+ );+ return { error: msg };+ }+ },+ });++ try {+ const result = await generateText({+ model: getModel("gemini-2.5-flash", "google"),+ system: SYSTEM_PROMPT,+ messages: [+ {+ role: "user" as const,+ content: [+ {+ type: "text" as const,+ text: `Current URL: ${initialUrl || "(unknown)"}\n\nPage snapshot:\n${initialSnapshot || "(empty — page may still be loading)"}\n\nTask: ${prompt}`,+ },+ ],+ },+ ],+ tools: { browser: browserTool },+ stopWhen: stepCountIs(MAX_STEPS),+ temperature: 0,+ prepareStep: async ({ stepNumber, messages }) => {+ if (actionLog.length === 0) return {};+ return {+ messages: [+ ...messages,+ {+ role: "user" as const,+ content: [+ {+ type: "text" as const,+ text: `ACTION LOG (your commands so far):\n${actionLog.join("\n")}\n\nReview this log before your next action. Common mistakes to check for:\n- Typed text but forgot to press Enter\n- Clicked a link but didn't wait or re-snapshot\n- Used stale @refs from a previous snapshot\n- Scrolled but didn't snapshot to see new content`,+ },+ ],+ },+ ],+ };+ },+ onStepFinish: ({ text, toolCalls }) => {+ if (toolCalls?.length) {+ debugLog.add(`[Step: ${toolCalls.length} tool call(s)]`);+ }+ if (text) debugLog.add(`Assistant: ${text}`);+ },+ });++ debugLog.add(`\n=== END: completed (${toolCallCount} tool calls) ===\n`);+ await debugLog.flush();++ return {+ output: result.text || "",+ stdout: allOutputs.join("\n"),+ result: lastSnapshotResult,+ stderr: "",+ exitCode: 0,+ killed: false,+ };+ } catch (err: unknown) {+ const msg = err instanceof Error ? err.message : String(err);+ logger.error("Agent failed", { error: err });+ debugLog.add(`\n=== END: error — ${msg} ===\n`);+ await debugLog.flush();++ return {+ output: "",+ stdout: allOutputs.join("\n"),+ result: lastSnapshotResult,+ stderr: msg,+ exitCode: 1,+ killed: false,+ };+ }+}diff --git a/apps/api/src/lib/scrape-interact/browser-service-client.ts b/apps/api/src/lib/scrape-interact/browser-service-client.tsnew file mode 100644index 000000000..371c0dca3--- /dev/null+++ b/apps/api/src/lib/scrape-interact/browser-service-client.ts@@ -0,0 +1,84 @@+import { config } from "../../config";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++export interface BrowserServiceCreateResponse {+ sessionId: string;+ cdpUrl: string;+ viewUrl: string;+ iframeUrl: string;+ interactiveIframeUrl: string;+ expiresAt: string;+}++export interface BrowserServiceExecResponse {+ stdout: string;+ result: string;+ stderr: string;+ exitCode: number;+ killed: boolean;+}++export interface BrowserServiceDeleteResponse {+ ok: boolean;+ sessionDurationMs?: number;+}++// ---------------------------------------------------------------------------+// Error+// ---------------------------------------------------------------------------++export class BrowserServiceError extends Error {+ status: number;+ constructor(status: number, message: string) {+ super(message);+ this.status = status;+ }+}++// ---------------------------------------------------------------------------+// HTTP client+// ---------------------------------------------------------------------------++function browserServiceHeaders(+ extra?: Record<string, string>,+): Record<string, string> {+ const headers: Record<string, string> = {+ "Content-Type": "application/json",+ ...(extra ?? {}),+ };+ if (config.BROWSER_SERVICE_API_KEY) {+ headers["Authorization"] = `Bearer ${config.BROWSER_SERVICE_API_KEY}`;+ }+ return headers;+}++/**+ * Call the browser service and return parsed JSON.+ * Throws `BrowserServiceError` on non-2xx responses.+ */+export async function browserServiceRequest<T>(+ method: string,+ path: string,+ body?: unknown,+): Promise<T> {+ const url = `${config.BROWSER_SERVICE_URL}${path}`;+ const res = await fetch(url, {+ method,+ headers: browserServiceHeaders(),+ body: body ? JSON.stringify(body) : undefined,+ });++ if (!res.ok) {+ const text = await res.text();+ throw new BrowserServiceError(+ res.status,+ `Browser service ${method} ${path} failed (${res.status}): ${text}`,+ );+ }++ if (res.status === 204) return undefined as T;+ return res.json() as Promise<T>;+}diff --git a/apps/api/src/lib/scrape-interact/scrape-replay.ts b/apps/api/src/lib/scrape-interact/scrape-replay.tsnew file mode 100644index 000000000..e7f401afd--- /dev/null+++ b/apps/api/src/lib/scrape-interact/scrape-replay.ts@@ -0,0 +1,370 @@+import { rewriteUrl } from "../../scraper/scrapeURL/lib/rewriteUrl";++// ---------------------------------------------------------------------------+// Types+// ---------------------------------------------------------------------------++export interface ScrapeContextRow {+ id: string;+ team_id: string;+ url: string | null;+ options: unknown;+}++type ReplayAction =+ | { type: "wait"; milliseconds?: number; selector?: string }+ | { type: "click"; selector: string; all?: boolean }+ | { type: "write"; text: string }+ | { type: "press"; key: string }+ | { type: "scroll"; direction?: "up" | "down"; selector?: string }+ | { type: "executeJavascript"; script: string }+ | { type: "screenshot" | "pdf" | "scrape" };++interface ScrapeReplayContext {+ targetUrl: string;+ waitForMs: number;+ actions: ReplayAction[];+}++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++function isRecord(value: unknown): value is Record<string, unknown> {+ return value !== null && typeof value === "object";+}++function clampPositiveInteger(value: unknown, max: number): number | undefined {+ if (typeof value !== "number" || !Number.isFinite(value)) return undefined;+ if (value <= 0) return undefined;+ return Math.min(Math.floor(value), max);+}++// ---------------------------------------------------------------------------+// Action sanitization+// ---------------------------------------------------------------------------++function sanitizeReplayActions(rawActions: unknown): ReplayAction[] {+ if (!Array.isArray(rawActions)) return [];++ const actions: ReplayAction[] = [];++ for (const rawAction of rawActions) {+ if (!isRecord(rawAction)) continue;+ const type = rawAction.type;++ if (type === "wait") {+ const milliseconds = clampPositiveInteger(rawAction.milliseconds, 60_000);+ const selector =+ typeof rawAction.selector === "string" &&+ rawAction.selector.trim().length > 0+ ? rawAction.selector+ : undefined;+ if (+ (milliseconds === undefined && !selector) ||+ (milliseconds && selector)+ ) {+ continue;+ }+ actions.push({+ type,+ ...(milliseconds !== undefined ? { milliseconds } : {}),+ ...(selector ? { selector } : {}),+ });+ continue;+ }++ if (type === "click") {+ if (+ typeof rawAction.selector !== "string" ||+ rawAction.selector.length === 0+ ) {+ continue;+ }+ actions.push({+ type,+ selector: rawAction.selector,+ all: rawAction.all === true,+ });+ continue;+ }++ if (type === "write") {+ if (typeof rawAction.text !== "string") continue;+ actions.push({ type, text: rawAction.text });+ continue;+ }++ if (type === "press") {+ if (typeof rawAction.key !== "string") continue;+ actions.push({ type, key: rawAction.key });+ continue;+ }++ if (type === "scroll") {+ const direction = rawAction.direction === "up" ? "up" : "down";+ const selector =+ typeof rawAction.selector === "string" &&+ rawAction.selector.trim().length > 0+ ? rawAction.selector+ : undefined;+ actions.push({+ type,+ direction,+ ...(selector ? { selector } : {}),+ });+ continue;+ }++ if (type === "executeJavascript") {+ if (typeof rawAction.script !== "string") continue;+ actions.push({ type, script: rawAction.script });+ continue;+ }++ if (type === "screenshot" || type === "pdf" || type === "scrape") {+ actions.push({ type });+ }+ }++ return actions;+}++// ---------------------------------------------------------------------------+// Build replay context from a saved scrape row+// ---------------------------------------------------------------------------++export function buildReplayContextFromScrape(scrape: ScrapeContextRow): {+ context?: ScrapeReplayContext;+ error?: string;+} {+ if (+ typeof scrape.url !== "string" ||+ scrape.url.trim().length === 0 ||+ scrape.url.startsWith("<redacted")+ ) {+ return {+ error:+ "Replay context is unavailable for this scrape job because the source URL was not retained.",+ };+ }++ if (!isRecord(scrape.options)) {+ return {+ error:+ "Replay context is unavailable for this scrape job because scrape options were not retained.",+ };+ }++ let targetUrl: string;+ try {+ targetUrl = rewriteUrl(scrape.url) ?? scrape.url;+ } catch {+ return {+ error:+ "Replay context is unavailable for this scrape job because the stored URL is invalid.",+ };+ }++ const waitForMs = clampPositiveInteger(scrape.options.waitFor, 60_000) ?? 0;+ const actions = sanitizeReplayActions(scrape.options.actions);++ return {+ context: {+ targetUrl,+ waitForMs,+ actions,+ },+ };+}++// ---------------------------------------------------------------------------+// Estimate timeout for the replay script+// ---------------------------------------------------------------------------++export function estimateReplayTimeoutSeconds(+ context: ScrapeReplayContext,+): number {+ const actionWaitMs = context.actions.reduce((total, action) => {+ if (action.type !== "wait") return total;+ if (typeof action.milliseconds === "number")+ return total + action.milliseconds;+ if (action.selector) return total + 1_000;+ return total;+ }, 0);++ const waitBudgetMs = context.waitForMs + actionWaitMs;+ return Math.min(300, Math.max(30, Math.ceil((waitBudgetMs + 45_000) / 1000)));+}++// ---------------------------------------------------------------------------+// Generate the Playwright replay script+// ---------------------------------------------------------------------------++export function buildReplayScript(context: ScrapeReplayContext): string {+ const payload = JSON.stringify(context);+ return `+const replay = ${payload};++const failReplay = (step, error) => {+ const reason = error instanceof Error ? error.message : String(error ?? "unknown error");+ throw new Error(\`\${step}: \${reason}\`);+};++const listReplayPages = () => page.context().pages().filter(candidate => !candidate.isClosed());++const candidateReplayPages = () => {+ const pages = listReplayPages();+ const nonExtensionPages = pages.filter(+ candidate => !candidate.url().startsWith("chrome-extension://"),+ );+ return nonExtensionPages.length > 0 ? nonExtensionPages : pages;+};++const syncReplayPage = async () => {+ const pages = candidateReplayPages();+ if (pages.length === 0) return;++ const isBlankLikeUrl = (url) => url === "" || url === "about:blank";++ let selected = null;++ for (let idx = pages.length - 1; idx >= 0; idx -= 1) {+ const candidate = pages[idx];+ const url = candidate.url();+ if (isBlankLikeUrl(url)) continue;+ try {+ const isVisible = await candidate.evaluate(+ () => document.visibilityState === "visible",+ );+ if (isVisible) {+ selected = candidate;+ break;+ }+ } catch {}+ }++ if (!selected) {+ for (let idx = pages.length - 1; idx >= 0; idx -= 1) {+ const candidate = pages[idx];+ if (!isBlankLikeUrl(candidate.url())) {+ selected = candidate;+ break;+ }+ }+ }++ if (!selected) {+ for (let idx = pages.length - 1; idx >= 0; idx -= 1) {+ const candidate = pages[idx];+ try {+ const isVisible = await candidate.evaluate(+ () => document.visibilityState === "visible",+ );+ if (isVisible) {+ selected = candidate;+ break;+ }+ } catch {}+ }+ }++ if (!selected) {+ selected = pages[pages.length - 1];+ }+ page = selected;++ try {+ await page.bringToFront();+ } catch {}+};++try {+ await page.goto(replay.targetUrl, { waitUntil: "domcontentloaded" });+} catch (error) {+ failReplay("Failed to load scrape URL", error);+}++await syncReplayPage();++if (typeof replay.waitForMs === "number" && replay.waitForMs > 0) {+ await page.waitForTimeout(Math.min(replay.waitForMs, 30000));+}++for (let i = 0; i < replay.actions.length; i += 1) {+ const action = replay.actions[i];+ const step = \`Replay action #\${i + 1} (\${action.type})\`;++ try {+ await syncReplayPage();++ switch (action.type) {+ case "wait":+ if (typeof action.milliseconds === "number") {+ await page.waitForTimeout(Math.min(action.milliseconds, 60000));+ } else if (typeof action.selector === "string") {+ await page.waitForSelector(action.selector, { timeout: 60000 });+ }+ break;+ case "click":+ if (action.all) {+ const locator = page.locator(action.selector);+ const count = await locator.count();+ for (let idx = 0; idx < count; idx += 1) {+ await locator.nth(idx).click();+ }+ } else {+ await page.click(action.selector);+ }+ break;+ case "write":+ await page.keyboard.type(action.text);+ break;+ case "press":+ await page.keyboard.press(action.key);+ break;+ case "scroll":+ if (typeof action.selector === "string") {+ await page.evaluate(+ ({ selector, direction }) => {+ const el = document.querySelector(selector);+ if (!el) {+ throw new Error(\`Selector not found: \${selector}\`);+ }+ const delta = direction === "up" ? -window.innerHeight : window.innerHeight;+ if (typeof el.scrollBy === "function") {+ el.scrollBy(0, delta);+ } else {+ window.scrollBy(0, delta);+ }+ },+ { selector: action.selector, direction: action.direction ?? "down" },+ );+ } else {+ await page.mouse.wheel(0, action.direction === "up" ? -800 : 800);+ }+ break;+ case "executeJavascript": {+ const wrapped = \`(async () => { \${action.script} })()\`;+ await page.evaluate(script => (0, eval)(script), wrapped);+ break;+ }+ case "screenshot":+ case "pdf":+ case "scrape":+ console.log(\`[firecrawl-replay] skipping output-only action: \${action.type}\`);+ break;+ default:+ console.log(\`[firecrawl-replay] skipping unsupported action type: \${String(action.type)}\`);+ break;+ }++ await syncReplayPage();+ } catch (error) {+ failReplay(step, error);+ }+}++await syncReplayPage();+`;+}diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.tsindex 6e6ca9bd9..6e10084e0 100644--- a/apps/api/src/routes/v2.ts+++ b/apps/api/src/routes/v2.ts@@ -55,6 +55,10 @@ import {agentSignupConfirmController,agentSignupBlockController,} from "../controllers/v2/agent-signup-confirm";+import {+ scrapeInteractController,+ scrapeStopInteractiveBrowserController,+} from "../controllers/v2/scrape-browser";expressWs(express());@@ -203,6 +207,20 @@ v2Router.get(wrap(scrapeStatusController),);+v2Router.post(+ "/scrape/:jobId/interact",+ authMiddleware(RateLimiterMode.BrowserExecute),+ validateJobIdParam,+ wrap(scrapeInteractController),+);++v2Router.delete(+ "/scrape/:jobId/interact",+ authMiddleware(RateLimiterMode.BrowserExecute),+ validateJobIdParam,+ wrap(scrapeStopInteractiveBrowserController),+);+v2Router.post("/batch/scrape",authMiddleware(RateLimiterMode.Scrape),diff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.tsindex e1652dcbf..862ff643b 100644--- a/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts@@ -37,6 +37,7 @@ import { withSpan, setSpanAttributes } from "../../../../lib/otel-tracer";import { getBrandingScript } from "./brandingScript";import { abTestFireEngine } from "../../../../services/ab-test";import { scheduleABComparison } from "../../../../services/ab-test-comparison";+import { createHash } from "node:crypto";/** Default wait (ms) before running the branding script when user did not set waitFor. Lets the page settle so DOM/images are ready and reduces JS errors. */const BRANDING_DEFAULT_WAIT_MS = 2000;@@ -353,6 +354,11 @@ export async function scrapeURLWithFireEngineChromeCDP(meta.internalOptions.saveScrapeResultToGCS,zeroDataRetention: meta.internalOptions.zeroDataRetention,...(shouldAllowMedia ? { blockMedia: false } : {}),+ persistentStorage: meta.options.profile+ ? {+ uniqueId: `${createHash("sha256").update(meta.internalOptions.teamId).digest("hex").slice(0, 16)}_${meta.options.profile.name}`,+ }+ : undefined,};let response = await performFireEngineScrape(diff --git a/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts b/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.tsindex c7d80ce01..8cb691601 100644--- a/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts+++ b/apps/api/src/scraper/scrapeURL/engines/fire-engine/scrape.ts@@ -53,6 +53,7 @@ export type FireEngineScrapeRequestChromeCDP = {blockMedia?: boolean;mobile?: boolean;disableSmartWaitCache?: boolean;+ persistentStorage?: { uniqueId: string };};export type FireEngineScrapeRequestTLSClient = {diff --git a/apps/api/src/scraper/scrapeURL/engines/index.ts b/apps/api/src/scraper/scrapeURL/engines/index.tsindex 876ea0e21..9f17ff620 100644--- a/apps/api/src/scraper/scrapeURL/engines/index.ts+++ b/apps/api/src/scraper/scrapeURL/engines/index.ts@@ -467,7 +467,8 @@ export function shouldUseIndex(meta: Meta) {meta.options.maxAge !== 0 &&(meta.options.headers === undefined ||Object.keys(meta.options.headers).length === 0) &&- (meta.options.actions === undefined || meta.options.actions.length === 0)+ (meta.options.actions === undefined || meta.options.actions.length === 0) &&+ meta.options.profile === undefined);}diff --git a/apps/api/src/scraper/scrapeURL/engines/index/index.ts b/apps/api/src/scraper/scrapeURL/engines/index/index.tsindex 955c14f7e..b7b84652f 100644--- a/apps/api/src/scraper/scrapeURL/engines/index/index.ts+++ b/apps/api/src/scraper/scrapeURL/engines/index/index.ts@@ -14,7 +14,12 @@ import {generateDomainSplits,addOMCEJob,} from "../../../../services";-import { AgentIndexOnlyError, EngineError, IndexMissError, NoCachedDataError } from "../../error";+import {+ AgentIndexOnlyError,+ EngineError,+ IndexMissError,+ NoCachedDataError,+} from "../../error";import { shouldParsePDF } from "../../../../controllers/v2/types";import { hasFormatOfType } from "../../../../lib/format-utils";@@ -48,7 +53,8 @@ export async function sendDocumentToIndex(meta: Meta, document: Document) {!meta.featureFlags.has("actions") &&!hasCustomScreenshotSettings &&(meta.options.headers === undefined ||- Object.keys(meta.options.headers).length === 0);+ Object.keys(meta.options.headers).length === 0) &&+ meta.options.profile === undefined;if (!shouldCache) {return document;diff --git a/apps/api/src/services/billing/types.ts b/apps/api/src/services/billing/types.tsindex f7bda2750..33326465c 100644--- a/apps/api/src/services/billing/types.ts+++ b/apps/api/src/services/billing/types.ts@@ -6,6 +6,7 @@ export type BillingEndpoint =| "deep_research"| "extract"| "fireclaw"+ | "interact"| "llms_txt"| "map"| "scrape"diff --git a/apps/api/src/services/logging/log_job.ts b/apps/api/src/services/logging/log_job.tsindex 88d164d15..8a20cdbc5 100644--- a/apps/api/src/services/logging/log_job.ts+++ b/apps/api/src/services/logging/log_job.ts@@ -155,7 +155,8 @@ type LoggedRequest = {| "deep_research"| "map"| "agent"- | "browser";+ | "browser"+ | "interact";api_version: string;team_id: string;origin?: string;diff --git a/apps/java-sdk/README.md b/apps/java-sdk/README.mdindex 8c776d60f..bc8191ca6 100644--- a/apps/java-sdk/README.md+++ b/apps/java-sdk/README.md@@ -82,13 +82,13 @@ Before using the Java SDK, ensure you have the following installed:### Gradle (Kotlin DSL)```kotlin-implementation("com.firecrawl:firecrawl-java:1.1.0")+implementation("com.firecrawl:firecrawl-java:1.1.1")```### Gradle (Groovy)```groovy-implementation 'com.firecrawl:firecrawl-java:1.1.0'+implementation 'com.firecrawl:firecrawl-java:1.1.1'```### Maven@@ -97,7 +97,7 @@ implementation 'com.firecrawl:firecrawl-java:1.1.0'<dependency><groupId>com.firecrawl</groupId><artifactId>firecrawl-java</artifactId>- <version>1.1.0</version>+ <version>1.1.1</version></dependency>```@@ -171,6 +171,27 @@ Document doc = client.scrape("https://example.com/product",System.out.println(doc.getJson());```+#### Scrape-Bound Interactive Session++Run browser automation against the page context captured by a scrape job:++```java+Document doc = client.scrape("https://example.com");+String scrapeId = String.valueOf(doc.getMetadata().get("scrapeId"));++BrowserExecuteResponse exec = client.interact(+ scrapeId,+ "console.log(await page.title());",+ "node",+ 30+);++System.out.println(exec.getStdout());++BrowserDeleteResponse deleted = client.stopInteractiveBrowser(scrapeId);+System.out.println("Deleted: " + deleted.isSuccess());+```+### CrawlCrawl an entire website. The `crawl()` method polls until completion.@@ -350,14 +371,14 @@ gradle build```bashgradle jar-# Output: build/libs/firecrawl-java-1.1.0.jar+# Output: build/libs/firecrawl-java-1.1.1.jar```### Install Locally```bashgradle publishToMavenLocal-# Now available as: com.firecrawl:firecrawl-java:1.1.0 in local Maven repository+# Now available as: com.firecrawl:firecrawl-java:1.1.1 in local Maven repository```## Running Testsdiff --git a/apps/java-sdk/build.gradle.kts b/apps/java-sdk/build.gradle.ktsindex 0b9524755..e87f9f923 100644--- a/apps/java-sdk/build.gradle.kts+++ b/apps/java-sdk/build.gradle.kts@@ -4,7 +4,7 @@ plugins {}group = "com.firecrawl"-version = "1.1.0"+version = "1.1.1"java {sourceCompatibility = JavaVersion.VERSION_11diff --git a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.javaindex dcf0408ae..15ed50a30 100644--- a/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java+++ b/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java@@ -103,6 +103,98 @@ public class FirecrawlClient {return extractData(http.post("/v2/scrape", body, Map.class), Document.class);}+ /**+ * Interacts with the scrape-bound browser session for a scrape job.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @return the execution result including stdout, stderr, and exit code+ */+ public BrowserExecuteResponse interact(String jobId, String code) {+ return interact(jobId, code, "node", null, null);+ }++ /**+ * Interacts with the scrape-bound browser session for a scrape job.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @param language the language: "python", "node", or "bash" (default: "node")+ * @param timeout execution timeout in seconds (1-300), or null for default (30)+ * @return the execution result including stdout, stderr, and exit code+ */+ public BrowserExecuteResponse interact(String jobId, String code,+ String language, Integer timeout) {+ return interact(jobId, code, language, timeout, null);+ }++ /**+ * Interacts with the scrape-bound browser session for a scrape job.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @param language the language: "python", "node", or "bash" (default: "node")+ * @param timeout execution timeout in seconds (1-300), or null for default (30)+ * @param origin optional origin tag for request attribution+ * @return the execution result including stdout, stderr, and exit code+ */+ public BrowserExecuteResponse interact(String jobId, String code,+ String language, Integer timeout, String origin) {+ Objects.requireNonNull(jobId, "Job ID is required");+ Objects.requireNonNull(code, "Code is required");+ Map<String, Object> body = new LinkedHashMap<>();+ body.put("code", code);+ body.put("language", language != null ? language : "node");+ if (timeout != null) body.put("timeout", timeout);+ if (origin != null) body.put("origin", origin);+ return http.post("/v2/scrape/" + jobId + "/interact", body, BrowserExecuteResponse.class);+ }++ /**+ * Stops the interactive browser session for a scrape job.+ *+ * @param jobId the scrape job ID+ * @return the stop response with session duration and billing info+ */+ public BrowserDeleteResponse stopInteractiveBrowser(String jobId) {+ Objects.requireNonNull(jobId, "Job ID is required");+ return http.delete("/v2/scrape/" + jobId + "/interact", BrowserDeleteResponse.class);+ }++ /**+ * @deprecated Use {@link #interact(String, String)}.+ */+ @Deprecated+ public BrowserExecuteResponse scrapeExecute(String jobId, String code) {+ return interact(jobId, code);+ }++ /**+ * @deprecated Use {@link #interact(String, String, String, Integer)}.+ */+ @Deprecated+ public BrowserExecuteResponse scrapeExecute(String jobId, String code,+ String language, Integer timeout) {+ return interact(jobId, code, language, timeout);+ }++ /**+ * @deprecated Use {@link #interact(String, String, String, Integer, String)}.+ */+ @Deprecated+ public BrowserExecuteResponse scrapeExecute(String jobId, String code,+ String language, Integer timeout, String origin) {+ return interact(jobId, code, language, timeout, origin);+ }++ /**+ * @deprecated Use {@link #stopInteractiveBrowser(String)}.+ */+ @Deprecated+ public BrowserDeleteResponse deleteScrapeBrowser(String jobId) {+ return stopInteractiveBrowser(jobId);+ }+// ================================================================// CRAWL// ================================================================@@ -533,6 +625,96 @@ public class FirecrawlClient {return CompletableFuture.supplyAsync(() -> scrape(url, options), asyncExecutor);}+ /**+ * Asynchronously executes code in a scrape-bound browser session.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @return a CompletableFuture that resolves to the BrowserExecuteResponse+ */+ public CompletableFuture<BrowserExecuteResponse> interactAsync(String jobId, String code) {+ return CompletableFuture.supplyAsync(() -> interact(jobId, code), asyncExecutor);+ }++ /**+ * Asynchronously executes code in a scrape-bound browser session.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @param language the language: "python", "node", or "bash"+ * @param timeout execution timeout in seconds, or null for default+ * @return a CompletableFuture that resolves to the BrowserExecuteResponse+ */+ public CompletableFuture<BrowserExecuteResponse> interactAsync(String jobId, String code,+ String language, Integer timeout) {+ return CompletableFuture.supplyAsync(+ () -> interact(jobId, code, language, timeout),+ asyncExecutor+ );+ }++ /**+ * Asynchronously executes code in a scrape-bound browser session.+ *+ * @param jobId the scrape job ID+ * @param code the code to execute+ * @param language the language: "python", "node", or "bash"+ * @param timeout execution timeout in seconds, or null for default+ * @param origin optional origin tag for request attribution+ * @return a CompletableFuture that resolves to the BrowserExecuteResponse+ */+ public CompletableFuture<BrowserExecuteResponse> interactAsync(String jobId, String code,+ String language, Integer timeout, String origin) {+ return CompletableFuture.supplyAsync(+ () -> interact(jobId, code, language, timeout, origin),+ asyncExecutor+ );+ }++ /**+ * Asynchronously deletes a scrape-bound browser session.+ *+ * @param jobId the scrape job ID+ * @return a CompletableFuture that resolves to the BrowserDeleteResponse+ */+ public CompletableFuture<BrowserDeleteResponse> stopInteractiveBrowserAsync(String jobId) {+ return CompletableFuture.supplyAsync(() -> stopInteractiveBrowser(jobId), asyncExecutor);+ }++ /**+ * @deprecated Use {@link #interactAsync(String, String)}.+ */+ @Deprecated+ public CompletableFuture<BrowserExecuteResponse> scrapeExecuteAsync(String jobId, String code) {+ return interactAsync(jobId, code);+ }++ /**+ * @deprecated Use {@link #interactAsync(String, String, String, Integer)}.+ */+ @Deprecated+ public CompletableFuture<BrowserExecuteResponse> scrapeExecuteAsync(String jobId, String code,+ String language, Integer timeout) {+ return interactAsync(jobId, code, language, timeout);+ }++ /**+ * @deprecated Use {@link #interactAsync(String, String, String, Integer, String)}.+ */+ @Deprecated+ public CompletableFuture<BrowserExecuteResponse> scrapeExecuteAsync(String jobId, String code,+ String language, Integer timeout, String origin) {+ return interactAsync(jobId, code, language, timeout, origin);+ }++ /**+ * @deprecated Use {@link #stopInteractiveBrowserAsync(String)}.+ */+ @Deprecated+ public CompletableFuture<BrowserDeleteResponse> deleteScrapeBrowserAsync(String jobId) {+ return stopInteractiveBrowserAsync(jobId);+ }+/*** Asynchronously crawls a website and waits for completion.*diff --git a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.javaindex 7aa4d5c74..a8a513a78 100644--- a/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java+++ b/apps/java-sdk/src/test/java/com/firecrawl/FirecrawlClientTest.java@@ -120,6 +120,26 @@ class FirecrawlClientTest {);}+ @Test+ void testInteractRequiresJobId() {+ FirecrawlClient client = FirecrawlClient.builder()+ .apiKey("fc-test-key")+ .build();+ assertThrows(NullPointerException.class, () ->+ client.interact(null, "console.log('hi')")+ );+ }++ @Test+ void testInteractRequiresCode() {+ FirecrawlClient client = FirecrawlClient.builder()+ .apiKey("fc-test-key")+ .build();+ assertThrows(NullPointerException.class, () ->+ client.interact("job-id", null)+ );+ }+@Testvoid testBrowserDeleteRequiresSessionId() {FirecrawlClient client = FirecrawlClient.builder()@@ -130,6 +150,16 @@ class FirecrawlClientTest {);}+ @Test+ void testStopInteractiveBrowserRequiresJobId() {+ FirecrawlClient client = FirecrawlClient.builder()+ .apiKey("fc-test-key")+ .build();+ assertThrows(NullPointerException.class, () ->+ client.stopInteractiveBrowser(null)+ );+ }+// ================================================================// E2E TESTS (require FIRECRAWL_API_KEY)// ================================================================diff --git a/apps/js-sdk/firecrawl/README.md b/apps/js-sdk/firecrawl/README.mdindex 9142099b4..07f242ac0 100644--- a/apps/js-sdk/firecrawl/README.md+++ b/apps/js-sdk/firecrawl/README.md@@ -110,6 +110,28 @@ const mapResult = await app.map('https://example.com');console.log(mapResult);```+### Scrape-bound interactive browsing (v2)++Use a scrape job ID to keep interacting with the replayed browser context:++```js+const doc = await app.scrape('https://example.com', {+ actions: [{ type: 'click', selector: 'a[href="/pricing"]' }],+});++const scrapeJobId = doc?.metadata?.scrapeId;+if (!scrapeJobId) throw new Error('Missing scrapeId');++const run = await app.interact(scrapeJobId, {+ code: 'console.log(await page.url())',+ language: 'node',+ timeout: 60,+});+console.log(run.stdout);++await app.stopInteraction(scrapeJobId);+```+### Crawl a website with real‑time updatesTo receive real‑time updates, start a crawl and attach a watcher.diff --git a/apps/js-sdk/firecrawl/package.json b/apps/js-sdk/firecrawl/package.jsonindex 9a8ed5a17..ffa227aaf 100644--- a/apps/js-sdk/firecrawl/package.json+++ b/apps/js-sdk/firecrawl/package.json@@ -1,6 +1,6 @@{"name": "@mendable/firecrawl-js",- "version": "4.16.0",+ "version": "4.17.0","description": "JavaScript SDK for Firecrawl API","main": "dist/index.js","types": "dist/index.d.ts",diff --git a/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrape-browser.unit.test.ts b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrape-browser.unit.test.tsnew file mode 100644index 000000000..1ddc6a747--- /dev/null+++ b/apps/js-sdk/firecrawl/src/__tests__/unit/v2/scrape-browser.unit.test.ts@@ -0,0 +1,104 @@+import { describe, test, expect, jest } from "@jest/globals";+import { interact, stopInteraction } from "../../../v2/methods/scrape";+import { SdkError } from "../../../v2/types";++describe("JS SDK v2 scrape-browser methods", () => {+ test("interact posts to scrape interact endpoint", async () => {+ const post = jest.fn(async () => ({+ status: 200,+ data: {+ success: true,+ stdout: "ok",+ exitCode: 0,+ },+ }));++ const http = { post } as any;+ const response = await interact(http, "job-123", { code: "console.log('ok')" });++ expect(post).toHaveBeenCalledWith("/v2/scrape/job-123/interact", {+ code: "console.log('ok')",+ language: "node",+ });+ expect(response.success).toBe(true);+ expect(response.exitCode).toBe(0);+ });++ test("interact with prompt posts prompt to endpoint", async () => {+ const post = jest.fn(async () => ({+ status: 200,+ data: {+ success: true,+ output: "Clicked the button",+ liveViewUrl: "https://live.example.com/view",+ interactiveLiveViewUrl: "https://live.example.com/interactive",+ stdout: "",+ exitCode: 0,+ },+ }));++ const http = { post } as any;+ const response = await interact(http, "job-456", { prompt: "Click the login button" });++ expect(post).toHaveBeenCalledWith("/v2/scrape/job-456/interact", {+ prompt: "Click the login button",+ language: "node",+ });+ expect(response.success).toBe(true);+ expect(response.output).toBe("Clicked the button");+ expect(response.liveViewUrl).toBe("https://live.example.com/view");+ expect(response.interactiveLiveViewUrl).toBe("https://live.example.com/interactive");+ });++ test("interact throws when neither code nor prompt provided", async () => {+ const http = { post: jest.fn() } as any;+ await expect(interact(http, "job-123", {})).rejects.toThrow(+ "Either 'code' or 'prompt' must be provided"+ );+ });++ test("interact throws on non-200 response", async () => {+ const post = jest.fn(async () => ({+ status: 400,+ data: {+ success: false,+ error: "Invalid job ID format",+ },+ }));++ const http = { post } as any;+ await expect(+ interact(http, "bad-id", { code: "console.log('ok')" })+ ).rejects.toBeInstanceOf(SdkError);+ });++ test("stopInteraction calls delete endpoint", async () => {+ const del = jest.fn(async () => ({+ status: 200,+ data: {+ success: true,+ },+ }));++ const http = { delete: del } as any;+ const response = await stopInteraction(http, "job-123");++ expect(del).toHaveBeenCalledWith("/v2/scrape/job-123/interact");+ expect(response.success).toBe(true);+ });++ test("stopInteraction throws on non-200 response", async () => {+ const del = jest.fn(async () => ({+ status: 404,+ data: {+ success: false,+ error: "Browser session not found.",+ },+ }));++ const http = { delete: del } as any;+ await expect(stopInteraction(http, "job-123")).rejects.toBeInstanceOf(+ SdkError+ );+ });+});diff --git a/apps/js-sdk/firecrawl/src/v2/client.ts b/apps/js-sdk/firecrawl/src/v2/client.tsindex 5dea615a8..f76a6d909 100644--- a/apps/js-sdk/firecrawl/src/v2/client.ts+++ b/apps/js-sdk/firecrawl/src/v2/client.ts@@ -1,5 +1,9 @@import { HttpClient } from "./utils/httpClient";-import { scrape } from "./methods/scrape";+import {+ scrape,+ interact as interactMethod,+ stopInteraction as stopInteractionMethod,+} from "./methods/scrape";import { search } from "./methods/search";import { map as mapMethod } from "./methods/map";import {@@ -50,6 +54,9 @@ import type {BrowserExecuteResponse,BrowserDeleteResponse,BrowserListResponse,+ ScrapeExecuteRequest,+ ScrapeExecuteResponse,+ ScrapeBrowserDeleteResponse,} from "./types";import { Watcher } from "./watcher";import type { WatcherOptions } from "./watcher";@@ -129,6 +136,46 @@ export class FirecrawlClient {async scrape(url: string, options?: ScrapeOptions): Promise<Document> {return scrape(this.http, url, options);}+ /**+ * Interact with the browser session associated with a scrape job.+ * @param jobId Scrape job id.+ * @param args Code or prompt to execute, with language/timeout options.+ * @returns Execution result including output, stdout, stderr, exitCode, and killed status.+ */+ async interact(+ jobId: string,+ args: ScrapeExecuteRequest+ ): Promise<ScrapeExecuteResponse> {+ return interactMethod(this.http, jobId, args);+ }+ /**+ * Stop the interaction session associated with a scrape job.+ * @param jobId Scrape job id.+ */+ async stopInteraction(jobId: string): Promise<ScrapeBrowserDeleteResponse> {+ return stopInteractionMethod(this.http, jobId);+ }+ /**+ * @deprecated Use interact().+ */+ async scrapeExecute(+ jobId: string,+ args: ScrapeExecuteRequest+ ): Promise<ScrapeExecuteResponse> {+ return this.interact(jobId, args);+ }+ /**+ * @deprecated Use stopInteraction().+ */+ async stopInteractiveBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse> {+ return this.stopInteraction(jobId);+ }+ /**+ * @deprecated Use stopInteraction().+ */+ async deleteScrapeBrowser(jobId: string): Promise<ScrapeBrowserDeleteResponse> {+ return this.stopInteraction(jobId);+ }// Search/**diff --git a/apps/js-sdk/firecrawl/src/v2/methods/scrape.ts b/apps/js-sdk/firecrawl/src/v2/methods/scrape.tsindex c2ddfc045..b6d8acda2 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/scrape.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/scrape.ts@@ -1,4 +1,10 @@-import { type Document, type ScrapeOptions } from "../types";+import {+ type Document,+ type ScrapeBrowserDeleteResponse,+ type ScrapeExecuteRequest,+ type ScrapeExecuteResponse,+ type ScrapeOptions,+} from "../types";import { HttpClient } from "../utils/httpClient";import { ensureValidScrapeOptions } from "../utils/validation";import { throwForBadResponse, normalizeAxiosError } from "../utils/errorHandler";@@ -24,3 +30,82 @@ export async function scrape(http: HttpClient, url: string, options?: ScrapeOpti}}+export async function interact(+ http: HttpClient,+ jobId: string,+ args: ScrapeExecuteRequest+): Promise<ScrapeExecuteResponse> {+ if (!jobId || !jobId.trim()) {+ throw new Error("Job ID cannot be empty");+ }+ const hasCode = args?.code && args.code.trim();+ const hasPrompt = args?.prompt && args.prompt.trim();+ if (!hasCode && !hasPrompt) {+ throw new Error("Either 'code' or 'prompt' must be provided");+ }++ const body: Record<string, unknown> = {};+ if (hasCode) body.code = args.code;+ if (hasPrompt) body.prompt = args.prompt;+ body.language = args.language ?? "node";+ if (args.timeout != null) body.timeout = args.timeout;+ if (args.origin) body.origin = args.origin;++ try {+ const res = await http.post<ScrapeExecuteResponse>(+ `/v2/scrape/${jobId}/interact`,+ body+ );+ if (res.status !== 200) throwForBadResponse(res, "interact with scrape browser");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "interact with scrape browser");+ throw err;+ }+}++export async function stopInteraction(+ http: HttpClient,+ jobId: string+): Promise<ScrapeBrowserDeleteResponse> {+ if (!jobId || !jobId.trim()) {+ throw new Error("Job ID cannot be empty");+ }++ try {+ const res = await http.delete<ScrapeBrowserDeleteResponse>(+ `/v2/scrape/${jobId}/interact`+ );+ if (res.status !== 200) throwForBadResponse(res, "stop interaction");+ return res.data;+ } catch (err: any) {+ if (err?.isAxiosError) return normalizeAxiosError(err, "stop interaction");+ throw err;+ }+}++/** @deprecated Use interact(). */+export async function scrapeExecute(+ http: HttpClient,+ jobId: string,+ args: ScrapeExecuteRequest+): Promise<ScrapeExecuteResponse> {+ return interact(http, jobId, args);+}++/** @deprecated Use stopInteraction(). */+export async function stopInteractiveBrowser(+ http: HttpClient,+ jobId: string+): Promise<ScrapeBrowserDeleteResponse> {+ return stopInteraction(http, jobId);+}++/** @deprecated Use stopInteraction(). */+export async function deleteScrapeBrowser(+ http: HttpClient,+ jobId: string+): Promise<ScrapeBrowserDeleteResponse> {+ return stopInteraction(http, jobId);+}+diff --git a/apps/js-sdk/firecrawl/src/v2/types.ts b/apps/js-sdk/firecrawl/src/v2/types.tsindex 21e294a7c..bd974a7b1 100644--- a/apps/js-sdk/firecrawl/src/v2/types.ts+++ b/apps/js-sdk/firecrawl/src/v2/types.ts@@ -163,6 +163,10 @@ export interface ScrapeOptions {maxAge?: number;minAge?: number;storeInCache?: boolean;+ profile?: {+ name: string;+ saveChanges?: boolean;+ };integration?: string;origin?: string;}@@ -711,6 +715,9 @@ export interface BrowserCreateResponse {export interface BrowserExecuteResponse {success: boolean;+ liveViewUrl?: string;+ interactiveLiveViewUrl?: string;+ output?: string;stdout?: string;result?: string;stderr?: string;@@ -726,6 +733,17 @@ export interface BrowserDeleteResponse {error?: string;}+export interface ScrapeExecuteRequest {+ code?: string;+ prompt?: string;+ language?: "python" | "node" | "bash";+ timeout?: number;+ origin?: string;+}++export type ScrapeExecuteResponse = BrowserExecuteResponse;+export type ScrapeBrowserDeleteResponse = BrowserDeleteResponse;+export interface BrowserSession {id: string;status: string;diff --git a/apps/python-sdk/README.md b/apps/python-sdk/README.mdindex 50aa82ca2..4b3797051 100644--- a/apps/python-sdk/README.md+++ b/apps/python-sdk/README.md@@ -132,6 +132,31 @@ map_result = firecrawl.map('https://firecrawl.dev')print(map_result)```+### Scrape-bound interactive browsing (v2)++Use a scrape job ID to keep interacting with the replayed browser context:++```python+doc = firecrawl.scrape(+ "https://example.com",+ actions=[{"type": "click", "selector": "a[href='/pricing']"}],+)++scrape_job_id = doc.metadata_typed.scrape_id+if not scrape_job_id:+ raise RuntimeError("Missing scrape job id")++run = firecrawl.interact(+ scrape_job_id,+ code="print(await page.url())",+ language="python",+ timeout=60,+)+print(run.stdout)++firecrawl.stop_interaction(scrape_job_id)+```+{/* ### Extracting Structured Data from WebsitesTo extract structured data from websites, use the `extract` method. It takes the URLs to extract data from, a prompt, and a schema as arguments. The schema is a Pydantic model that defines the structure of the extracted data.diff --git a/apps/python-sdk/firecrawl/__init__.py b/apps/python-sdk/firecrawl/__init__.pyindex c2f626428..04db4894c 100644--- a/apps/python-sdk/firecrawl/__init__.py+++ b/apps/python-sdk/firecrawl/__init__.py@@ -17,7 +17,7 @@ from .v1 import (V1ChangeTrackingOptions,)-__version__ = "4.19.0"+__version__ = "4.20.0"# Define the logger for the Firecrawl projectlogger: logging.Logger = logging.getLogger("firecrawl")diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_scrape_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_scrape_request_preparation.pyindex ed76d132a..1ecb54ab5 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_scrape_request_preparation.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/aio/test_aio_scrape_request_preparation.py@@ -1,6 +1,44 @@import pytestfrom firecrawl.v2.types import ScrapeOptions, Location-from firecrawl.v2.methods.aio.scrape import _prepare_scrape_request+from firecrawl.v2.methods.aio.scrape import (+ _prepare_scrape_request,+ interact,+ stop_interaction,+)+++class _FakeAsyncResponse:+ def __init__(self, status_code: int, payload):+ self.status_code = status_code+ self._payload = payload++ def json(self):+ return self._payload++ @property+ def text(self):+ return str(self._payload)+++class _FakeAsyncClient:+ def __init__(+ self,+ *,+ post_response: _FakeAsyncResponse,+ delete_response: _FakeAsyncResponse,+ ):+ self.post_response = post_response+ self.delete_response = delete_response+ self.last_post = None+ self.last_delete = None++ async def post(self, endpoint, payload):+ self.last_post = (endpoint, payload)+ return self.post_response++ async def delete(self, endpoint):+ self.last_delete = endpoint+ return self.delete_responseclass TestAsyncScrapeRequestPreparation:@@ -48,3 +86,112 @@ class TestAsyncScrapeRequestPreparation:assert payload["maxAge"] == 1000assert payload["storeInCache"] is False+ @pytest.mark.asyncio+ async def test_interact_request_and_response_normalization(self):+ client = _FakeAsyncClient(+ post_response=_FakeAsyncResponse(+ 200,+ {+ "success": True,+ "stdout": "ok",+ "exitCode": 0,+ },+ ),+ delete_response=_FakeAsyncResponse(200, {"success": True}),+ )+ response = await interact(+ client,+ "job-123",+ "console.log('ok')",+ timeout=30,+ origin="_unit-test",+ )++ assert client.last_post[0] == "/v2/scrape/job-123/interact"+ assert client.last_post[1] == {+ "code": "console.log('ok')",+ "language": "node",+ "timeout": 30,+ "origin": "_unit-test",+ }+ assert response.success is True+ assert response.exit_code == 0++ @pytest.mark.asyncio+ async def test_interact_with_prompt(self):+ client = _FakeAsyncClient(+ post_response=_FakeAsyncResponse(+ 200,+ {+ "success": True,+ "output": "Clicked the button",+ "liveViewUrl": "https://live.example.com/view",+ "interactiveLiveViewUrl": "https://live.example.com/interactive",+ "stdout": "",+ "exitCode": 0,+ },+ ),+ delete_response=_FakeAsyncResponse(200, {"success": True}),+ )+ response = await interact(+ client,+ "job-456",+ prompt="Click the login button",+ )++ assert client.last_post[0] == "/v2/scrape/job-456/interact"+ assert client.last_post[1] == {+ "language": "node",+ "prompt": "Click the login button",+ }+ assert response.success is True+ assert response.output == "Clicked the button"+ assert response.live_view_url == "https://live.example.com/view"+ assert response.interactive_live_view_url == "https://live.example.com/interactive"++ @pytest.mark.asyncio+ async def test_interact_validates_required_inputs(self):+ client = _FakeAsyncClient(+ post_response=_FakeAsyncResponse(200, {"success": True}),+ delete_response=_FakeAsyncResponse(200, {"success": True}),+ )+ with pytest.raises(ValueError, match="Job ID cannot be empty"):+ await interact(client, "", "console.log('ok')")+ with pytest.raises(ValueError, match="Either 'code' or 'prompt' must be provided"):+ await interact(client, "job-123")++ @pytest.mark.asyncio+ async def test_interact_raises_when_success_false(self):+ client = _FakeAsyncClient(+ post_response=_FakeAsyncResponse(+ 200,+ {+ "success": False,+ "error": "Replay context is unavailable",+ },+ ),+ delete_response=_FakeAsyncResponse(200, {"success": True}),+ )+ with pytest.raises(Exception, match="Replay context is unavailable"):+ await interact(client, "job-123", "console.log('ok')")++ @pytest.mark.asyncio+ async def test_stop_interaction_request_and_response_normalization(self):+ client = _FakeAsyncClient(+ post_response=_FakeAsyncResponse(200, {"success": True}),+ delete_response=_FakeAsyncResponse(+ 200,+ {+ "success": True,+ "sessionDurationMs": 900,+ "creditsBilled": 2,+ },+ ),+ )+ response = await stop_interaction(client, "job-123")++ assert client.last_delete == "/v2/scrape/job-123/interact"+ assert response.success is True+ assert response.session_duration_ms == 900+ assert response.credits_billed == 2+diff --git a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_scrape_request_preparation.py b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_scrape_request_preparation.pyindex 6002a6b70..a4b4d4867 100644--- a/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_scrape_request_preparation.py+++ b/apps/python-sdk/firecrawl/__tests__/unit/v2/methods/test_scrape_request_preparation.py@@ -1,6 +1,40 @@import pytestfrom firecrawl.v2.types import ScrapeOptions, Viewport, ScreenshotAction-from firecrawl.v2.methods.scrape import _prepare_scrape_request+from firecrawl.v2.methods.scrape import (+ _prepare_scrape_request,+ interact,+ stop_interaction,+)+++class _FakeResponse:+ def __init__(self, status_code: int, payload):+ self.status_code = status_code+ self._payload = payload+ self.ok = status_code < 400++ def json(self):+ return self._payload++ @property+ def text(self):+ return str(self._payload)+++class _FakeClient:+ def __init__(self, *, post_response: _FakeResponse, delete_response: _FakeResponse):+ self.post_response = post_response+ self.delete_response = delete_response+ self.last_post = None+ self.last_delete = None++ def post(self, endpoint, payload):+ self.last_post = (endpoint, payload)+ return self.post_response++ def delete(self, endpoint):+ self.last_delete = endpoint+ return self.delete_responseclass TestScrapeRequestPreparation:@@ -106,4 +140,109 @@ class TestScrapeRequestPreparation:integration=" _unit-test ",)data = _prepare_scrape_request("https://example.com", opts)- assert data["integration"] == "_unit-test"\ No newline at end of file+ assert data["integration"] == "_unit-test"++ def test_interact_request_and_response_normalization(self):+ client = _FakeClient(+ post_response=_FakeResponse(+ 200,+ {+ "success": True,+ "stdout": "ok",+ "exitCode": 0,+ },+ ),+ delete_response=_FakeResponse(200, {"success": True}),+ )+ response = interact(+ client,+ "job-123",+ "console.log('ok')",+ timeout=45,+ origin="_unit-test",+ )++ assert client.last_post[0] == "/v2/scrape/job-123/interact"+ assert client.last_post[1] == {+ "code": "console.log('ok')",+ "language": "node",+ "timeout": 45,+ "origin": "_unit-test",+ }+ assert response.success is True+ assert response.exit_code == 0++ def test_interact_with_prompt(self):+ client = _FakeClient(+ post_response=_FakeResponse(+ 200,+ {+ "success": True,+ "output": "Clicked the button",+ "liveViewUrl": "https://live.example.com/view",+ "interactiveLiveViewUrl": "https://live.example.com/interactive",+ "stdout": "",+ "exitCode": 0,+ },+ ),+ delete_response=_FakeResponse(200, {"success": True}),+ )+ response = interact(+ client,+ "job-456",+ prompt="Click the login button",+ )++ assert client.last_post[0] == "/v2/scrape/job-456/interact"+ assert client.last_post[1] == {+ "language": "node",+ "prompt": "Click the login button",+ }+ assert response.success is True+ assert response.output == "Clicked the button"+ assert response.live_view_url == "https://live.example.com/view"+ assert response.interactive_live_view_url == "https://live.example.com/interactive"++ def test_interact_validates_required_inputs(self):+ client = _FakeClient(+ post_response=_FakeResponse(200, {"success": True}),+ delete_response=_FakeResponse(200, {"success": True}),+ )+ with pytest.raises(ValueError, match="Job ID cannot be empty"):+ interact(client, "", "console.log('ok')")+ with pytest.raises(ValueError, match="Either 'code' or 'prompt' must be provided"):+ interact(client, "job-123")++ def test_interact_raises_when_success_false(self):+ client = _FakeClient(+ post_response=_FakeResponse(+ 200,+ {+ "success": False,+ "error": "Replay context is unavailable",+ },+ ),+ delete_response=_FakeResponse(200, {"success": True}),+ )++ with pytest.raises(Exception, match="Replay context is unavailable"):+ interact(client, "job-123", "console.log('ok')")++ def test_stop_interaction_request_and_response_normalization(self):+ client = _FakeClient(+ post_response=_FakeResponse(200, {"success": True}),+ delete_response=_FakeResponse(+ 200,+ {+ "success": True,+ "sessionDurationMs": 1200,+ "creditsBilled": 3,+ },+ ),+ )+ response = stop_interaction(client, "job-123")++ assert client.last_delete == "/v2/scrape/job-123/interact"+ assert response.success is True+ assert response.session_duration_ms == 1200+ assert response.credits_billed == 3\ No newline at end of filediff --git a/apps/python-sdk/firecrawl/client.py b/apps/python-sdk/firecrawl/client.pyindex a1ca1ccb2..bf77b443a 100644--- a/apps/python-sdk/firecrawl/client.py+++ b/apps/python-sdk/firecrawl/client.py@@ -57,6 +57,11 @@ class V2Proxy:if client_instance:self.scrape = client_instance.scrape+ self.interact = client_instance.interact+ self.stop_interaction = client_instance.stop_interaction+ self.stop_interactive_browser = client_instance.stop_interactive_browser+ self.scrape_execute = self.interact+ self.delete_scrape_browser = self.stop_interactionself.search = client_instance.searchself.crawl = client_instance.crawlself.start_crawl = client_instance.start_crawl@@ -129,6 +134,11 @@ class AsyncV2Proxy:if client_instance:self.scrape = client_instance.scrape+ self.interact = client_instance.interact+ self.stop_interaction = client_instance.stop_interaction+ self.stop_interactive_browser = client_instance.stop_interactive_browser+ self.scrape_execute = self.interact+ self.delete_scrape_browser = self.stop_interactionself.search = client_instance.searchself.crawl = client_instance.crawlself.start_crawl = client_instance.start_crawl@@ -221,6 +231,11 @@ class Firecrawl:self.v2 = V2Proxy(self._v2_client)self.scrape = self._v2_client.scrape+ self.interact = self._v2_client.interact+ self.stop_interaction = self._v2_client.stop_interaction+ self.stop_interactive_browser = self._v2_client.stop_interactive_browser+ self.scrape_execute = self.interact+ self.delete_scrape_browser = self.stop_interactionself.search = self._v2_client.searchself.map = self._v2_client.map@@ -293,6 +308,11 @@ class AsyncFirecrawl:# Expose v2 async surface directly on the top-level client for ergonomic access# Keep method names aligned with the sync clientself.scrape = self._v2_client.scrape+ self.interact = self._v2_client.interact+ self.stop_interaction = self._v2_client.stop_interaction+ self.stop_interactive_browser = self._v2_client.stop_interactive_browser+ self.scrape_execute = self.interact+ self.delete_scrape_browser = self.stop_interactionself.search = self._v2_client.searchself.map = self._v2_client.mapdiff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex 54b65a4f8..43990c683 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -185,6 +185,82 @@ class FirecrawlClient:) if any(v is not None for v in [formats, headers, include_tags, exclude_tags, only_main_content, timeout, wait_for, mobile, parsers, actions, location, skip_tls_verification, remove_base64_images, fast_mode, use_mock, block_ads, proxy, max_age, store_in_cache, integration]) else Nonereturn scrape_module.scrape(self.http_client, url, options)+ def interact(+ self,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+ ):+ """+ Interact with the browser session associated with a scrape job.++ Either ``code`` or ``prompt`` must be provided.++ Args:+ job_id: Scrape job ID+ code: Code to execute (optional if prompt is provided)+ prompt: Natural-language instruction for the browser agent (optional if code is provided)+ language: Programming language ("python", "node", or "bash")+ timeout: Execution timeout in seconds (1-300)+ origin: Optional request origin tag++ Returns:+ BrowserExecuteResponse with execution result+ """+ return scrape_module.interact(+ self.http_client,+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )++ def stop_interaction(self, job_id: str):+ """+ Stop the interaction session associated with a scrape job.++ Args:+ job_id: Scrape job ID++ Returns:+ BrowserDeleteResponse+ """+ return scrape_module.stop_interaction(self.http_client, job_id)++ def stop_interactive_browser(self, job_id: str):+ """Deprecated alias for stop_interaction()."""+ return self.stop_interaction(job_id)++ def scrape_execute(+ self,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+ ):+ """Deprecated alias for interact()."""+ return self.interact(+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )++ def delete_scrape_browser(self, job_id: str):+ """Deprecated alias for stop_interaction()."""+ return self.stop_interaction(job_id)+def search(self,query: str,diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex aaae8899e..5f368ac7f 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -91,6 +91,60 @@ class AsyncFirecrawlClient:options = ScrapeOptions(**{k: v for k, v in kwargs.items() if v is not None}) if kwargs else Nonereturn await async_scrape.scrape(self.async_http_client, url, options)+ async def interact(+ self,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+ ):+ return await async_scrape.interact(+ self.async_http_client,+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )++ async def stop_interaction(self, job_id: str):+ return await async_scrape.stop_interaction(+ self.async_http_client,+ job_id,+ )++ async def stop_interactive_browser(self, job_id: str):+ """Deprecated alias for stop_interaction()."""+ return await self.stop_interaction(job_id)++ async def scrape_execute(+ self,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+ ):+ """Deprecated alias for interact()."""+ return await self.interact(+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )++ async def delete_scrape_browser(self, job_id: str):+ """Deprecated alias for stop_interaction()."""+ return await self.stop_interaction(job_id)+# Searchasync def search(self,diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/scrape.py b/apps/python-sdk/firecrawl/v2/methods/aio/scrape.pyindex 848f6e278..df1065a93 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/scrape.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/scrape.py@@ -1,5 +1,10 @@-from typing import Optional, Dict, Any-from ...types import ScrapeOptions, Document+from typing import Optional, Dict, Any, Literal+from ...types import (+ ScrapeOptions,+ Document,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+)from ...utils.normalize import normalize_document_inputfrom ...utils.error_handler import handle_response_errorfrom ...utils.validation import prepare_scrape_options, validate_scrape_options@@ -31,3 +36,109 @@ async def scrape(client: AsyncHttpClient, url: str, options: Optional[ScrapeOptinormalized = normalize_document_input(document_data)return Document(**normalized)++async def interact(+ client: AsyncHttpClient,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+) -> BrowserExecuteResponse:+ if not job_id or not job_id.strip():+ raise ValueError("Job ID cannot be empty")+ has_code = code and code.strip()+ has_prompt = prompt and prompt.strip()+ if not has_code and not has_prompt:+ raise ValueError("Either 'code' or 'prompt' must be provided")++ payload: Dict[str, Any] = {+ "language": language,+ }+ if has_code:+ payload["code"] = code+ if has_prompt:+ payload["prompt"] = prompt+ if timeout is not None:+ payload["timeout"] = timeout+ if origin is not None:+ payload["origin"] = origin++ response = await client.post(f"/v2/scrape/{job_id}/interact", payload)+ if response.status_code >= 400:+ handle_response_error(response, "interact with scrape browser")++ body = response.json()+ if not body.get("success"):+ raise Exception(body.get("error", "Unknown error occurred"))++ normalized = dict(body)+ if "exitCode" in normalized and "exit_code" not in normalized:+ normalized["exit_code"] = normalized["exitCode"]+ if "liveViewUrl" in normalized and "live_view_url" not in normalized:+ normalized["live_view_url"] = normalized["liveViewUrl"]+ if "interactiveLiveViewUrl" in normalized and "interactive_live_view_url" not in normalized:+ normalized["interactive_live_view_url"] = normalized["interactiveLiveViewUrl"]+ return BrowserExecuteResponse(**normalized)+++async def stop_interaction(+ client: AsyncHttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ if not job_id or not job_id.strip():+ raise ValueError("Job ID cannot be empty")++ response = await client.delete(f"/v2/scrape/{job_id}/interact")+ if response.status_code >= 400:+ handle_response_error(response, "stop interaction")++ body = response.json()+ normalized = dict(body)+ if "sessionDurationMs" in normalized and "session_duration_ms" not in normalized:+ normalized["session_duration_ms"] = normalized["sessionDurationMs"]+ if "creditsBilled" in normalized and "credits_billed" not in normalized:+ normalized["credits_billed"] = normalized["creditsBilled"]++ return BrowserDeleteResponse(**normalized)+++async def stop_interactive_browser(+ client: AsyncHttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ """Deprecated alias for stop_interaction()."""+ return await stop_interaction(client, job_id)+++async def scrape_execute(+ client: AsyncHttpClient,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+) -> BrowserExecuteResponse:+ """Deprecated alias for interact()."""+ return await interact(+ client,+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )+++async def delete_scrape_browser(+ client: AsyncHttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ """Deprecated alias for stop_interaction()."""+ return await stop_interaction(client, job_id)+diff --git a/apps/python-sdk/firecrawl/v2/methods/scrape.py b/apps/python-sdk/firecrawl/v2/methods/scrape.pyindex 733f5e318..073a41890 100644--- a/apps/python-sdk/firecrawl/v2/methods/scrape.py+++ b/apps/python-sdk/firecrawl/v2/methods/scrape.py@@ -2,8 +2,13 @@Scraping functionality for Firecrawl v2 API."""-from typing import Optional, Dict, Any-from ..types import ScrapeOptions, Document+from typing import Optional, Dict, Any, Literal+from ..types import (+ ScrapeOptions,+ Document,+ BrowserExecuteResponse,+ BrowserDeleteResponse,+)from ..utils.normalize import normalize_document_inputfrom ..utils import HttpClient, handle_response_error, prepare_scrape_options, validate_scrape_options@@ -61,4 +66,139 @@ def scrape(client: HttpClient, url: str, options: Optional[ScrapeOptions] = Nonedocument_data = body.get("data", {})normalized = normalize_document_input(document_data)- return Document(**normalized)\ No newline at end of file+ return Document(**normalized)+++def interact(+ client: HttpClient,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+) -> BrowserExecuteResponse:+ """+ Interact with the scrape-bound browser session for a scrape job.++ Either ``code`` or ``prompt`` must be provided. When ``prompt`` is given+ the server runs an AI agent that translates the natural-language instruction+ into browser actions.++ Args:+ client: HTTP client instance+ job_id: Scrape job ID+ code: Code to execute (optional if prompt is provided)+ prompt: Natural-language instruction for the browser agent (optional if code is provided)+ language: Programming language ("python", "node", or "bash")+ timeout: Execution timeout in seconds (1-300)+ origin: Optional request origin tag++ Returns:+ BrowserExecuteResponse with execution output+ """+ if not job_id or not job_id.strip():+ raise ValueError("Job ID cannot be empty")+ has_code = code and code.strip()+ has_prompt = prompt and prompt.strip()+ if not has_code and not has_prompt:+ raise ValueError("Either 'code' or 'prompt' must be provided")++ body: Dict[str, Any] = {+ "language": language,+ }+ if has_code:+ body["code"] = code+ if has_prompt:+ body["prompt"] = prompt+ if timeout is not None:+ body["timeout"] = timeout+ if origin is not None:+ body["origin"] = origin++ response = client.post(f"/v2/scrape/{job_id}/interact", body)+ if not response.ok:+ handle_response_error(response, "interact with scrape browser")++ payload = response.json()+ if not payload.get("success"):+ raise Exception(payload.get("error", "Unknown error occurred"))++ normalized = dict(payload)+ if "exitCode" in normalized and "exit_code" not in normalized:+ normalized["exit_code"] = normalized["exitCode"]+ if "liveViewUrl" in normalized and "live_view_url" not in normalized:+ normalized["live_view_url"] = normalized["liveViewUrl"]+ if "interactiveLiveViewUrl" in normalized and "interactive_live_view_url" not in normalized:+ normalized["interactive_live_view_url"] = normalized["interactiveLiveViewUrl"]+ return BrowserExecuteResponse(**normalized)+++def stop_interaction(+ client: HttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ """+ Stop the interaction session for a scrape job.++ Args:+ client: HTTP client instance+ job_id: Scrape job ID++ Returns:+ BrowserDeleteResponse+ """+ if not job_id or not job_id.strip():+ raise ValueError("Job ID cannot be empty")++ response = client.delete(f"/v2/scrape/{job_id}/interact")+ if not response.ok:+ handle_response_error(response, "stop interaction")++ payload = response.json()+ normalized = dict(payload)+ if "sessionDurationMs" in normalized and "session_duration_ms" not in normalized:+ normalized["session_duration_ms"] = normalized["sessionDurationMs"]+ if "creditsBilled" in normalized and "credits_billed" not in normalized:+ normalized["credits_billed"] = normalized["creditsBilled"]++ return BrowserDeleteResponse(**normalized)+++def stop_interactive_browser(+ client: HttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ """Deprecated alias for stop_interaction()."""+ return stop_interaction(client, job_id)+++def scrape_execute(+ client: HttpClient,+ job_id: str,+ code: Optional[str] = None,+ *,+ prompt: Optional[str] = None,+ language: Literal["python", "node", "bash"] = "node",+ timeout: Optional[int] = None,+ origin: Optional[str] = None,+) -> BrowserExecuteResponse:+ """Deprecated alias for interact()."""+ return interact(+ client,+ job_id,+ code,+ prompt=prompt,+ language=language,+ timeout=timeout,+ origin=origin,+ )+++def delete_scrape_browser(+ client: HttpClient,+ job_id: str,+) -> BrowserDeleteResponse:+ """Deprecated alias for stop_interaction()."""+ return stop_interaction(client, job_id)\ No newline at end of filediff --git a/apps/python-sdk/firecrawl/v2/types.py b/apps/python-sdk/firecrawl/v2/types.pyindex 6f5bf37f6..e19653262 100644--- a/apps/python-sdk/firecrawl/v2/types.py+++ b/apps/python-sdk/firecrawl/v2/types.py@@ -543,6 +543,7 @@ class ScrapeOptions(BaseModel):max_age: Optional[int] = Nonemin_age: Optional[int] = Nonestore_in_cache: Optional[bool] = None+ profile: Optional[Dict[str, Any]] = Noneintegration: Optional[str] = None@field_validator("formats")@@ -845,6 +846,9 @@ class BrowserExecuteResponse(BaseModel):"""Response from executing code in a browser session."""success: bool+ live_view_url: Optional[str] = None+ interactive_live_view_url: Optional[str] = None+ output: Optional[str] = Nonestdout: Optional[str] = Noneresult: Optional[str] = Nonestderr: Optional[str] = Nonediff --git a/apps/python-sdk/firecrawl/v2/utils/validation.py b/apps/python-sdk/firecrawl/v2/utils/validation.pyindex 2de93f69c..0a13f2dcb 100644--- a/apps/python-sdk/firecrawl/v2/utils/validation.py+++ b/apps/python-sdk/firecrawl/v2/utils/validation.py@@ -714,11 +714,22 @@ def prepare_scrape_options(options: Optional[ScrapeOptions]) -> Optional[Dict[stconverted_parsers.append(parser_data)scrape_data["parsers"] = converted_parserselif key == "location":- # Handle location conversionif isinstance(value, dict):scrape_data["location"] = valueelse:scrape_data["location"] = value.model_dump(exclude_none=True)+ elif key == "profile":+ if isinstance(value, dict):+ profile_data = {+ "name": value["name"],+ "saveChanges": value.get("save_changes", value.get("saveChanges", True)),+ }+ else:+ profile_data = {+ "name": value.name,+ "saveChanges": getattr(value, "save_changes", getattr(value, "saveChanges", True)),+ }+ scrape_data["profile"] = profile_dataelse:# For fields that don't need conversion, use as-isscrape_data[key] = valuediff --git a/apps/rust-sdk/Cargo.lock b/apps/rust-sdk/Cargo.lockindex 90c4fc326..120fe7e5e 100644--- a/apps/rust-sdk/Cargo.lock+++ b/apps/rust-sdk/Cargo.lock@@ -685,7 +685,7 @@ checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"[[package]]name = "firecrawl"-version = "1.2.2"+version = "1.2.3"dependencies = ["assert_matches","axum",diff --git a/apps/rust-sdk/Cargo.toml b/apps/rust-sdk/Cargo.tomlindex 502d31f6e..5d86ffe2f 100644--- a/apps/rust-sdk/Cargo.toml+++ b/apps/rust-sdk/Cargo.toml@@ -1,7 +1,7 @@[package]name = "firecrawl"author= "Mendable.ai"-version = "1.2.2"+version = "1.3.0"edition = "2021"license = "MIT"homepage = "https://www.firecrawl.dev/"diff --git a/apps/rust-sdk/README.md b/apps/rust-sdk/README.mdindex 248dde1b0..771272b56 100644--- a/apps/rust-sdk/README.md+++ b/apps/rust-sdk/README.md@@ -141,6 +141,32 @@ match map_result {}```+### Scrape-bound interactive browsing (v2)++Use a scrape job ID to keep interacting with the replayed browser context:++```rust+use firecrawl::v2::{Client, ScrapeExecuteLanguage, ScrapeExecuteOptions};++let client = Client::new("fc-YOUR-API-KEY")?;+let job_id = "550e8400-e29b-41d4-a716-446655440000";++let run = client+ .interact(+ job_id,+ ScrapeExecuteOptions {+ code: Some("console.log(await page.url())".to_string()),+ language: Some(ScrapeExecuteLanguage::Node),+ timeout: Some(60),+ ..Default::default()+ },+ )+ .await?;++println!("{:?}", run.stdout);+client.stop_interaction(job_id).await?;+```+## Error HandlingThe SDK handles errors returned by the Firecrawl API and by our dependencies, and combines them into the `FirecrawlError` enum, implementing `Error`, `Debug` and `Display`. All of our methods return a `Result<T, FirecrawlError>`.diff --git a/apps/rust-sdk/src/v2/scrape.rs b/apps/rust-sdk/src/v2/scrape.rsindex 83c934b04..94db9c8fa 100644--- a/apps/rust-sdk/src/v2/scrape.rs+++ b/apps/rust-sdk/src/v2/scrape.rs@@ -7,7 +7,7 @@ use std::collections::HashMap;use super::client::Client;use super::types::{Action, AttributeSelector, ChangeTrackingOptions, Document, Format, JsonOptions,- LocationConfig, ProxyType, ScreenshotOptions,+ LocationConfig, ProfileConfig, ProxyType, ScreenshotOptions,};use crate::FirecrawlError;@@ -73,6 +73,9 @@ pub struct ScrapeOptions {/// Store the result in cache for future requests.pub store_in_cache: Option<bool>,+ /// Persistent browser profile for maintaining state across scrapes.+ pub profile: Option<ProfileConfig>,+/// Integration identifier for tracking.pub integration: Option<String>,@@ -123,6 +126,76 @@ struct ScrapeResponse {warning: Option<String>,}+/// Supported languages for scrape-bound browser execution.+#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]+#[serde(rename_all = "lowercase")]+pub enum ScrapeExecuteLanguage {+ Python,+ Node,+ Bash,+}++/// Options for executing code or a prompt in a scrape-bound browser session.+///+/// At least one of `code` or `prompt` must be provided.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct ScrapeExecuteOptions {+ /// Code to execute (optional if `prompt` is provided).+ pub code: Option<String>,+ /// Natural-language instruction for the browser agent (optional if `code` is provided).+ pub prompt: Option<String>,+ /// Runtime language for the code.+ pub language: Option<ScrapeExecuteLanguage>,+ /// Execution timeout in seconds.+ pub timeout: Option<u32>,+ /// Optional origin tag for request attribution.+ pub origin: Option<String>,+}++/// Response from scrape-bound browser execution.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct ScrapeExecuteResponse {+ /// Whether the request succeeded.+ pub success: bool,+ /// Live-view URL for the browser session.+ pub live_view_url: Option<String>,+ /// Interactive live-view URL for the browser session.+ pub interactive_live_view_url: Option<String>,+ /// Agent output when a prompt was used.+ pub output: Option<String>,+ /// Captured stdout from execution.+ pub stdout: Option<String>,+ /// Optional execution result payload.+ pub result: Option<String>,+ /// Captured stderr from execution.+ pub stderr: Option<String>,+ /// Process exit code.+ pub exit_code: Option<i32>,+ /// Whether execution was killed by timeout or system.+ pub killed: Option<bool>,+ /// Error message when execution fails.+ pub error: Option<String>,+}++/// Response from deleting a scrape-bound browser session.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Clone)]+#[serde(rename_all = "camelCase")]+pub struct ScrapeBrowserDeleteResponse {+ /// Whether the delete request succeeded.+ pub success: bool,+ /// Session duration in milliseconds when available.+ pub session_duration_ms: Option<u64>,+ /// Credits billed when available.+ pub credits_billed: Option<u32>,+ /// Error message when deletion fails.+ pub error: Option<String>,+}+impl Client {/// Scrapes a URL and returns the content in the requested formats.///@@ -248,6 +321,109 @@ impl Client {let document = self.scrape(url, options).await?;Ok(document.json.unwrap_or(Value::Null))}++ /// Interacts with the browser session associated with a scrape job.+ ///+ /// # Arguments+ ///+ /// * `job_id` - The scrape job ID.+ /// * `options` - Execution options including code and runtime config.+ ///+ /// # Returns+ ///+ /// A `ScrapeExecuteResponse` containing execution output.+ pub async fn interact(+ &self,+ job_id: impl AsRef<str>,+ options: ScrapeExecuteOptions,+ ) -> Result<ScrapeExecuteResponse, FirecrawlError> {+ let has_code = options.code.as_ref().is_some_and(|c| !c.trim().is_empty());+ let has_prompt = options.prompt.as_ref().is_some_and(|p| !p.trim().is_empty());+ if !has_code && !has_prompt {+ return Err(FirecrawlError::Missuse(+ "Either 'code' or 'prompt' must be provided".into(),+ ));+ }++ let mut body = options;+ if body.language.is_none() {+ body.language = Some(ScrapeExecuteLanguage::Node);+ }++ let response = self+ .client+ .post(self.url(&format!("/scrape/{}/interact", job_id.as_ref())))+ .headers(self.prepare_headers(None))+ .json(&body)+ .send()+ .await+ .map_err(|e| {+ FirecrawlError::HttpError(+ format!("Interacting with scrape browser for {}", job_id.as_ref()),+ e,+ )+ })?;++ self.handle_response(response, "scrape interact").await+ }++ /// Stops the interaction session associated with a scrape job.+ ///+ /// # Arguments+ ///+ /// * `job_id` - The scrape job ID.+ ///+ /// # Returns+ ///+ /// A `ScrapeBrowserDeleteResponse` indicating stop status.+ pub async fn stop_interaction(+ &self,+ job_id: impl AsRef<str>,+ ) -> Result<ScrapeBrowserDeleteResponse, FirecrawlError> {+ let response = self+ .client+ .delete(self.url(&format!("/scrape/{}/interact", job_id.as_ref())))+ .headers(self.prepare_headers(None))+ .send()+ .await+ .map_err(|e| {+ FirecrawlError::HttpError(+ format!("Stopping interaction for {}", job_id.as_ref()),+ e,+ )+ })?;++ self.handle_response(response, "stop interaction")+ .await+ }++ /// Deprecated alias for [`Client::interact`].+ #[deprecated(note = "Use interact() instead")]+ pub async fn scrape_execute(+ &self,+ job_id: impl AsRef<str>,+ options: ScrapeExecuteOptions,+ ) -> Result<ScrapeExecuteResponse, FirecrawlError> {+ self.interact(job_id, options).await+ }++ /// Deprecated alias for [`Client::stop_interaction`].+ #[deprecated(note = "Use stop_interaction() instead")]+ pub async fn stop_interactive_browser(+ &self,+ job_id: impl AsRef<str>,+ ) -> Result<ScrapeBrowserDeleteResponse, FirecrawlError> {+ self.stop_interaction(job_id).await+ }++ /// Deprecated alias for [`Client::stop_interaction`].+ #[deprecated(note = "Use stop_interaction() instead")]+ pub async fn delete_scrape_browser(+ &self,+ job_id: impl AsRef<str>,+ ) -> Result<ScrapeBrowserDeleteResponse, FirecrawlError> {+ self.stop_interaction(job_id).await+ }}#[cfg(test)]@@ -401,4 +577,144 @@ mod tests {assert!(result.is_err());mock.assert();}++ #[tokio::test]+ async fn test_interact_with_mock() {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("POST", "/v2/scrape/job-123/interact")+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": true,+ "stdout": "ok",+ "result": "done",+ "stderr": "",+ "exitCode": 0,+ "killed": false+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key")).unwrap();+ let response = client+ .interact(+ "job-123",+ ScrapeExecuteOptions {+ code: Some("console.log('ok')".to_string()),+ timeout: Some(30),+ ..Default::default()+ },+ )+ .await+ .unwrap();++ assert!(response.success);+ assert_eq!(response.exit_code, Some(0));+ assert_eq!(response.result, Some("done".to_string()));+ mock.assert();+ }++ #[tokio::test]+ async fn test_interact_with_prompt() {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("POST", "/v2/scrape/job-789/interact")+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": true,+ "output": "Clicked the login button",+ "liveViewUrl": "https://live.example.com/view",+ "interactiveLiveViewUrl": "https://live.example.com/interactive",+ "stdout": "",+ "exitCode": 0,+ "killed": false+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key")).unwrap();+ let response = client+ .interact(+ "job-789",+ ScrapeExecuteOptions {+ prompt: Some("Click the login button".to_string()),+ ..Default::default()+ },+ )+ .await+ .unwrap();++ assert!(response.success);+ assert_eq!(response.output, Some("Clicked the login button".to_string()));+ assert_eq!(response.live_view_url, Some("https://live.example.com/view".to_string()));+ assert_eq!(response.interactive_live_view_url, Some("https://live.example.com/interactive".to_string()));+ mock.assert();+ }++ #[tokio::test]+ async fn test_stop_interaction_with_mock() {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("DELETE", "/v2/scrape/job-123/interact")+ .with_status(200)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": true,+ "sessionDurationMs": 1200,+ "creditsBilled": 3+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key")).unwrap();+ let response = client.stop_interaction("job-123").await.unwrap();++ assert!(response.success);+ assert_eq!(response.session_duration_ms, Some(1200));+ assert_eq!(response.credits_billed, Some(3));+ mock.assert();+ }++ #[tokio::test]+ async fn test_interact_error_response() {+ let mut server = mockito::Server::new_async().await;++ let mock = server+ .mock("POST", "/v2/scrape/job-404/interact")+ .with_status(404)+ .with_header("content-type", "application/json")+ .with_body(+ json!({+ "success": false,+ "error": "Job not found."+ })+ .to_string(),+ )+ .create();++ let client = Client::new_selfhosted(server.url(), Some("test_key")).unwrap();+ let result = client+ .interact(+ "job-404",+ ScrapeExecuteOptions {+ code: Some("console.log('ok')".to_string()),+ ..Default::default()+ },+ )+ .await;++ assert!(result.is_err());+ mock.assert();+ }}diff --git a/apps/rust-sdk/src/v2/types.rs b/apps/rust-sdk/src/v2/types.rsindex 5d119fd42..06736f0b0 100644--- a/apps/rust-sdk/src/v2/types.rs+++ b/apps/rust-sdk/src/v2/types.rs@@ -112,6 +112,17 @@ pub struct LocationConfig {pub languages: Option<Vec<String>>,}+/// Persistent browser profile for maintaining state across scrapes.+#[serde_with::skip_serializing_none]+#[derive(Deserialize, Serialize, Debug, Default, Clone)]+#[serde(rename_all = "camelCase")]+pub struct ProfileConfig {+ /// Profile name (1–128 characters).+ pub name: String,+ /// Whether to persist changes made during the session (defaults to true).+ pub save_changes: Option<bool>,+}+/// Proxy type for scraping.#[derive(Deserialize, Serialize, Clone, Copy, Debug, PartialEq, Eq)]#[serde(rename_all = "lowercase")]