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
browser: persistentsession (#2919)
Thomas Kosmase4915199c5d7
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.tsindex 16f531d57..88d2c7ad6 100644--- a/apps/api/src/controllers/v2/browser.ts+++ b/apps/api/src/controllers/v2/browser.ts@@ -1,3 +1,4 @@+import { createHash } from "crypto";import { v7 as uuidv7 } from "uuid";import { Request, Response } from "express";import { z } from "zod";@@ -40,6 +41,10 @@ const browserCreateRequestSchema = z.object({ttl: z.number().min(30).max(3600).default(300),activityTtl: z.number().min(10).max(3600).default(120),streamWebView: z.boolean().default(true),+ persistentSession: z.object({+ name: z.string().min(1).max(128),+ writeMode: z.enum(["readonly", "readwrite"]).default("readwrite"),+ }).optional(),});type BrowserCreateRequest = z.infer<typeof browserCreateRequestSchema>;@@ -114,6 +119,14 @@ function browserServiceHeaders(return headers;}+class BrowserServiceError extends Error {+ status: number;+ constructor(status: number, message: string) {+ super(message);+ this.status = status;+ }+}+/*** Call the browser service and return parsed JSON.* Throws on non-2xx responses.@@ -132,7 +145,8 @@ async function browserServiceRequest<T>(if (!res.ok) {const text = await res.text();- throw new Error(+ throw new BrowserServiceError(+ res.status,`Browser service ${method} ${path} failed (${res.status}): ${text}`,);}@@ -193,7 +207,7 @@ export async function browserCreateController(req.body = browserCreateRequestSchema.parse(req.body);- const { ttl, activityTtl, streamWebView } = req.body;+ const { ttl, activityTtl, streamWebView, persistentSession } = req.body;if (!config.BROWSER_SERVICE_URL) {return res.status(503).json({@@ -237,6 +251,19 @@ export async function browserCreateController(let svcResponse: BrowserServiceCreateResponse | undefined;let lastCreateError: unknown;+ // Build persistentStorage from persistentSession if provided+ let persistentStorage: { uniqueId: string; write: boolean } | undefined;+ if (persistentSession) {+ const teamHash = createHash("sha256")+ .update(req.auth.team_id)+ .digest("hex")+ .slice(0, 16);+ persistentStorage = {+ uniqueId: `${teamHash}_${persistentSession.name}`,+ write: persistentSession.writeMode === "readwrite",+ };+ }+for (let attempt = 1; attempt <= MAX_CREATE_RETRIES; attempt++) {try {svcResponse = await browserServiceRequest<BrowserServiceCreateResponse>(@@ -245,10 +272,23 @@ export async function browserCreateController({ttl,...(activityTtl !== undefined ? { activityTtl } : {}),+ ...(persistentStorage !== undefined ? { persistentStorage } : {}),},);break;} catch (err) {+ // 409 means the persistent session profile is locked by another writer — don't retry+ if (err instanceof BrowserServiceError && err.status === 409) {+ logger.warn("Persistent session profile is locked", {+ persistentSessionName: persistentSession?.name,+ error: err,+ });+ return res.status(409).json({+ success: false,+ error: "Another session is currently writing to this persistent session profile. Only one writer is allowed at a time. You can still access it with writeMode \"readonly\", or try again later.",+ });+ }+lastCreateError = err;logger.warn("Browser session creation attempt failed", {attempt,diff --git a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts b/apps/js-sdk/firecrawl/src/v2/methods/browser.tsindex a1cb62fd6..a0c6d9406 100644--- a/apps/js-sdk/firecrawl/src/v2/methods/browser.ts+++ b/apps/js-sdk/firecrawl/src/v2/methods/browser.ts@@ -13,12 +13,17 @@ export async function browser(ttl?: number;activityTtl?: number;streamWebView?: boolean;+ persistentSession?: {+ name: string;+ writeMode?: "readonly" | "readwrite";+ };} = {}): Promise<BrowserCreateResponse> {const body: Record<string, unknown> = {};if (args.ttl != null) body.ttl = args.ttl;if (args.activityTtl != null) body.activityTtl = args.activityTtl;if (args.streamWebView != null) body.streamWebView = args.streamWebView;+ if (args.persistentSession != null) body.persistentSession = args.persistentSession;try {const res = await http.post<BrowserCreateResponse>("/v2/browser", body);diff --git a/apps/python-sdk/firecrawl/v2/client.py b/apps/python-sdk/firecrawl/v2/client.pyindex b5a393c78..2c02299a0 100644--- a/apps/python-sdk/firecrawl/v2/client.py+++ b/apps/python-sdk/firecrawl/v2/client.py@@ -984,6 +984,7 @@ class FirecrawlClient:ttl: Optional[int] = None,activity_ttl: Optional[int] = None,stream_web_view: Optional[bool] = None,+ persistent_session: Optional[Dict[str, Any]] = None,):"""Create a new browser session.@@ -991,6 +992,8 @@ class FirecrawlClient:ttl: Total time-to-live in seconds (30-3600, default 300)activity_ttl: Inactivity TTL in seconds (10-3600)stream_web_view: Whether to enable webview streaming+ persistent_session: Persistent session config with ``name`` (str) and+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)Returns:BrowserCreateResponse with session id and CDP URL@@ -1000,6 +1003,7 @@ class FirecrawlClient:ttl=ttl,activity_ttl=activity_ttl,stream_web_view=stream_web_view,+ persistent_session=persistent_session,)def browser_execute(diff --git a/apps/python-sdk/firecrawl/v2/client_async.py b/apps/python-sdk/firecrawl/v2/client_async.pyindex cd7afbc49..58197837b 100644--- a/apps/python-sdk/firecrawl/v2/client_async.py+++ b/apps/python-sdk/firecrawl/v2/client_async.py@@ -468,6 +468,7 @@ class AsyncFirecrawlClient:ttl: Optional[int] = None,activity_ttl: Optional[int] = None,stream_web_view: Optional[bool] = None,+ persistent_session: Optional[Dict[str, Any]] = None,):"""Create a new browser session.@@ -475,6 +476,8 @@ class AsyncFirecrawlClient:ttl: Total time-to-live in seconds (30-3600, default 300)activity_ttl: Inactivity TTL in seconds (10-3600)stream_web_view: Whether to enable webview streaming+ persistent_session: Persistent session config with ``name`` (str) and+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)Returns:BrowserCreateResponse with session id and CDP URL@@ -484,6 +487,7 @@ class AsyncFirecrawlClient:ttl=ttl,activity_ttl=activity_ttl,stream_web_view=stream_web_view,+ persistent_session=persistent_session,)async def browser_execute(diff --git a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py b/apps/python-sdk/firecrawl/v2/methods/aio/browser.pyindex e9d8e4715..5ae662540 100644--- a/apps/python-sdk/firecrawl/v2/methods/aio/browser.py+++ b/apps/python-sdk/firecrawl/v2/methods/aio/browser.py@@ -4,7 +4,7 @@ Async browser session methods for Firecrawl v2 API.Provides async create, execute, delete, and list operations for browser sessions."""-from typing import Any, Dict, List, Literal, Optional+from typing import Any, Dict, Literal, Optionalfrom ...types import (BrowserCreateResponse,@@ -53,6 +53,7 @@ async def browser(ttl: Optional[int] = None,activity_ttl: Optional[int] = None,stream_web_view: Optional[bool] = None,+ persistent_session: Optional[Dict[str, Any]] = None,) -> BrowserCreateResponse:"""Create a new browser session.@@ -61,6 +62,8 @@ async def browser(ttl: Total time-to-live in seconds (30-3600, default 300)activity_ttl: Inactivity TTL in seconds (10-3600)stream_web_view: Whether to enable webview streaming+ persistent_session: Persistent session config with ``name`` (str) and+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)Returns:BrowserCreateResponse with session id and CDP URL@@ -72,6 +75,11 @@ async def browser(body["activityTtl"] = activity_ttlif stream_web_view is not None:body["streamWebView"] = stream_web_view+ if persistent_session is not None:+ body["persistentSession"] = {+ "name": persistent_session["name"],+ "writeMode": persistent_session.get("write_mode", "readwrite"),+ }resp = await client.post("/v2/browser", body)payload = _normalize_browser_create_response(resp.json())diff --git a/apps/python-sdk/firecrawl/v2/methods/browser.py b/apps/python-sdk/firecrawl/v2/methods/browser.pyindex 1215be448..b667fca4d 100644--- a/apps/python-sdk/firecrawl/v2/methods/browser.py+++ b/apps/python-sdk/firecrawl/v2/methods/browser.py@@ -54,6 +54,7 @@ def browser(ttl: Optional[int] = None,activity_ttl: Optional[int] = None,stream_web_view: Optional[bool] = None,+ persistent_session: Optional[Dict[str, Any]] = None,) -> BrowserCreateResponse:"""Create a new browser session.@@ -62,6 +63,8 @@ def browser(ttl: Total time-to-live in seconds (30-3600, default 300)activity_ttl: Inactivity TTL in seconds (10-3600)stream_web_view: Whether to enable webview streaming+ persistent_session: Persistent session config with ``name`` (str) and+ optional ``write_mode`` (``"readonly"`` | ``"readwrite"``, default ``"readwrite"``)Returns:BrowserCreateResponse with session id and CDP URL@@ -73,6 +76,11 @@ def browser(body["activityTtl"] = activity_ttlif stream_web_view is not None:body["streamWebView"] = stream_web_view+ if persistent_session is not None:+ body["persistentSession"] = {+ "name": persistent_session["name"],+ "writeMode": persistent_session.get("write_mode", "readwrite"),+ }resp = client.post("/v2/browser", body)if not resp.ok: