Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

Nick:

Nicolasf0aebdb7db31
diff --git a/apps/api/requests/v2/browser.requests.http b/apps/api/requests/v2/browser.requests.http
index fbceca1a6..fe046fc92 100644
--- a/apps/api/requests/v2/browser.requests.http
+++ b/apps/api/requests/v2/browser.requests.http
@@ -81,6 +81,23 @@ content-type: application/json
"language": "python"
}
+### Get Session Replay metadata β€” works after the session is destroyed
+GET {{baseUrl}}/v2/interact/{{sessionId}}/replay HTTP/1.1
+Authorization: Bearer {{$dotenv TEST_API_KEY}}
+
+### Get Session Replay HLS playlist for tab 0
+GET {{baseUrl}}/v2/interact/{{sessionId}}/replay/0 HTTP/1.1
+Authorization: Bearer {{$dotenv TEST_API_KEY}}
+
+### Create Browser Session without recording
+POST {{baseUrl}}/v2/browser HTTP/1.1
+Authorization: Bearer {{$dotenv TEST_API_KEY}}
+content-type: application/json
+
+{
+ "recordSession": false
+}
+
### Delete Browser Session β€” replace sessionId with actual id
DELETE {{baseUrl}}/v2/browser/{{sessionId}} HTTP/1.1
Authorization: Bearer {{$dotenv TEST_API_KEY}}
diff --git a/apps/api/src/__tests__/snips/v2/browser-replay.test.ts b/apps/api/src/__tests__/snips/v2/browser-replay.test.ts
new file mode 100644
index 000000000..f43a4b0d7
--- /dev/null
+++ b/apps/api/src/__tests__/snips/v2/browser-replay.test.ts
@@ -0,0 +1,174 @@
+import crypto from "crypto";
+import { config } from "../../../config";
+import {
+ ALLOW_TEST_SUITE_WEBSITE,
+ HAS_FIRE_ENGINE,
+ TEST_PRODUCTION,
+ TEST_SELF_HOST,
+ TEST_SUITE_WEBSITE,
+ itIf,
+} from "../lib";
+import {
+ Identity,
+ idmux,
+ browserCreateRaw,
+ browserExecuteRaw,
+ browserDeleteRaw,
+ browserReplayRaw,
+ browserReplayPageRaw,
+ scrapeTimeout,
+} from "./lib";
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+describe("Interact session replay", () => {
+ let identity: Identity;
+ let otherIdentity: Identity;
+
+ beforeAll(async () => {
+ identity = await idmux({
+ name: "browser-replay",
+ concurrency: 20,
+ credits: 1_000_000,
+ });
+ otherIdentity = await idmux({
+ name: "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)(
+ "records a session and serves replay metadata + HLS playlist after destroy",
+ async () => {
+ let sessionId: string | null = null;
+
+ try {
+ const createResponse = await browserCreateRaw(
+ { ttl: 120, activityTtl: 120 },
+ identity,
+ );
+ expect(createResponse.statusCode).toBe(200);
+ expect(createResponse.body.success).toBe(true);
+ sessionId = createResponse.body.id as string;
+
+ // Generate on-screen activity so the screencast has frames to record.
+ const executeResponse = await browserExecuteRaw(
+ sessionId,
+ {
+ language: "node",
+ timeout: 60,
+ code: `
+ await page.goto("${TEST_SUITE_WEBSITE}?testId=${crypto.randomUUID()}");
+ console.log("navigated");
+ `,
+ },
+ identity,
+ );
+ expect(executeResponse.statusCode).toBe(200);
+ expect(executeResponse.body.success).toBe(true);
+
+ // Wait past a segment boundary (10s) so at least one segment uploads.
+ await sleep(15_000);
+ } finally {
+ if (sessionId) {
+ await browserDeleteRaw(sessionId, identity);
+ }
+ }
+
+ // Replay must be available after the session is destroyed.
+ let replayResponse = await browserReplayRaw(sessionId!, identity);
+ for (let i = 0; i < 10 && replayResponse.statusCode === 404; i++) {
+ await sleep(2000);
+ replayResponse = await browserReplayRaw(sessionId!, identity);
+ }
+
+ expect(replayResponse.statusCode).toBe(200);
+ expect(replayResponse.body.success).toBe(true);
+ expect(replayResponse.body.pageCount).toBeGreaterThan(0);
+ expect(Array.isArray(replayResponse.body.pages)).toBe(true);
+
+ const page = replayResponse.body.pages[0];
+ expect(typeof page.pageId).toBe("string");
+ expect(page.url).toBe(
+ `/v2/interact/${sessionId}/replay/${page.pageId}`,
+ );
+ expect(page.endTimeMs).toBeGreaterThan(page.startTimeMs);
+
+ const playlistResponse = await browserReplayPageRaw(
+ sessionId!,
+ page.pageId,
+ identity,
+ );
+ expect(playlistResponse.statusCode).toBe(200);
+ expect(playlistResponse.headers["content-type"]).toContain(
+ "application/vnd.apple.mpegurl",
+ );
+ const playlist = playlistResponse.text as string;
+ expect(playlist).toContain("#EXTM3U");
+ expect(playlist).toContain("#EXT-X-ENDLIST");
+ expect(playlist).toContain("https://");
+ },
+ scrapeTimeout + 60_000,
+ );
+
+ itIf(!TEST_SELF_HOST)(
+ "returns 404 when the session does not exist",
+ async () => {
+ const response = await browserReplayRaw(crypto.randomUUID(), identity);
+
+ expect(response.statusCode).toBe(404);
+ expect(response.body.success).toBe(false);
+ expect(response.body.error).toBe("Browser session not found.");
+ },
+ );
+
+ itIf(!TEST_SELF_HOST)(
+ "returns 400 for an invalid pageId",
+ async () => {
+ const response = await browserReplayPageRaw(
+ crypto.randomUUID(),
+ "not-a-page",
+ identity,
+ );
+
+ expect(response.statusCode).toBe(400);
+ expect(response.body.success).toBe(false);
+ expect(response.body.error).toBe("Invalid pageId.");
+ },
+ );
+
+ itIf(canRunReplayHappyPath && !!config.IDMUX_URL)(
+ "returns 403 when the session belongs to another team",
+ async () => {
+ if (identity.teamId === otherIdentity.teamId) {
+ return;
+ }
+
+ let sessionId: string | null = null;
+ try {
+ const createResponse = await browserCreateRaw(
+ { ttl: 60, activityTtl: 60 },
+ identity,
+ );
+ expect(createResponse.statusCode).toBe(200);
+ sessionId = createResponse.body.id as string;
+
+ const response = await browserReplayRaw(sessionId, otherIdentity);
+ expect(response.statusCode).toBe(403);
+ expect(response.body.success).toBe(false);
+ expect(response.body.error).toBe("Forbidden.");
+ } finally {
+ if (sessionId) {
+ await browserDeleteRaw(sessionId, identity);
+ }
+ }
+ },
+ scrapeTimeout,
+ );
+});
diff --git a/apps/api/src/__tests__/snips/v2/lib.ts b/apps/api/src/__tests__/snips/v2/lib.ts
index 68fa667f3..9199a9698 100644
--- a/apps/api/src/__tests__/snips/v2/lib.ts
+++ b/apps/api/src/__tests__/snips/v2/lib.ts
@@ -340,6 +340,71 @@ export async function scrapeStopInteractiveBrowserRaw(
.send();
}
+// =========================================
+// Interact (standalone browser sessions)
+// =========================================
+
+export async function browserCreateRaw(
+ body: {
+ ttl?: number;
+ activityTtl?: number;
+ recordSession?: boolean;
+ },
+ identity: Identity,
+) {
+ return await request(TEST_API_URL)
+ .post("/v2/interact")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("Content-Type", "application/json")
+ .send(body);
+}
+
+export async function browserExecuteRaw(
+ sessionId: string,
+ body: {
+ code: string;
+ language?: "python" | "node" | "bash";
+ timeout?: number;
+ },
+ identity: Identity,
+) {
+ return await request(TEST_API_URL)
+ .post("/v2/interact/" + encodeURIComponent(sessionId) + "/execute")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .set("Content-Type", "application/json")
+ .send(body);
+}
+
+export async function browserDeleteRaw(sessionId: string, identity: Identity) {
+ return await request(TEST_API_URL)
+ .delete("/v2/interact/" + encodeURIComponent(sessionId))
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .send();
+}
+
+export async function browserReplayRaw(sessionId: string, identity: Identity) {
+ return await request(TEST_API_URL)
+ .get("/v2/interact/" + encodeURIComponent(sessionId) + "/replay")
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .send();
+}
+
+export async function browserReplayPageRaw(
+ sessionId: string,
+ pageId: string,
+ identity: Identity,
+) {
+ return await request(TEST_API_URL)
+ .get(
+ "/v2/interact/" +
+ encodeURIComponent(sessionId) +
+ "/replay/" +
+ encodeURIComponent(pageId),
+ )
+ .set("Authorization", `Bearer ${identity.apiKey}`)
+ .send();
+}
+
// =========================================
// Crawl API
// =========================================
diff --git a/apps/api/src/controllers/v2/browser-replay.ts b/apps/api/src/controllers/v2/browser-replay.ts
new file mode 100644
index 000000000..458e454e0
--- /dev/null
+++ b/apps/api/src/controllers/v2/browser-replay.ts
@@ -0,0 +1,193 @@
+import { Response } from "express";
+import { logger as _logger } from "../../lib/logger";
+import { config } from "../../config";
+import { getBrowserSession } from "../../lib/browser-sessions";
+import {
+ browserServiceRequest,
+ browserServiceRequestText,
+ BrowserServiceError,
+} from "../../lib/scrape-interact/browser-service-client";
+import { RequestWithAuth } from "./types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface BrowserServiceRecordingPage {
+ pageId: string;
+ url: string;
+ startTimeMs: number;
+ endTimeMs: number;
+}
+
+interface BrowserServiceRecordingResponse {
+ pages: BrowserServiceRecordingPage[];
+ pageCount: number;
+}
+
+interface BrowserReplayResponse {
+ success: boolean;
+ pages?: Array<{
+ pageId: string;
+ /** Path (relative to the API origin) serving this page's HLS playlist. */
+ url: string;
+ /** First page URL recorded on this tab. */
+ pageUrl: string;
+ /** Milliseconds from session start, not Unix epoch. */
+ startTimeMs: number;
+ endTimeMs: number;
+ }>;
+ pageCount?: number;
+ error?: string;
+}
+
+const PAGE_ID_RE = /^\d{1,3}$/;
+
+// ---------------------------------------------------------------------------
+// Shared session resolution
+// ---------------------------------------------------------------------------
+
+async function resolveReplaySession(
+ req: RequestWithAuth<{ sessionId: string }, any, any>,
+ res: Response,
+): Promise<{ browserId: string } | null> {
+ if (!config.BROWSER_SERVICE_URL) {
+ res.status(503).json({
+ success: false,
+ error:
+ "Browser feature is not configured (BROWSER_SERVICE_URL is missing).",
+ });
+ return null;
+ }
+
+ const session = await getBrowserSession(req.params.sessionId);
+
+ if (!session) {
+ res.status(404).json({
+ success: false,
+ error: "Browser session not found.",
+ });
+ return null;
+ }
+
+ if (session.team_id !== req.auth.team_id) {
+ res.status(403).json({
+ success: false,
+ error: "Forbidden.",
+ });
+ return null;
+ }
+
+ // Note: destroyed sessions are intentionally allowed β€” replay is most
+ // useful after the session has ended.
+ return { browserId: session.browser_id };
+}
+
+// ---------------------------------------------------------------------------
+// Controllers
+// ---------------------------------------------------------------------------
+
+/**
+ * GET /v2/interact/:sessionId/replay
+ *
+ * Lists the recorded pages (tabs) of a session. Each page has its own HLS
+ * playlist; timestamps are milliseconds from session start on a shared
+ * timeline across tabs.
+ */
+export async function browserReplayController(
+ req: RequestWithAuth<{ sessionId: string }, BrowserReplayResponse>,
+ res: Response<BrowserReplayResponse>,
+) {
+ const logger = _logger.child({
+ sessionId: req.params.sessionId,
+ teamId: req.auth.team_id,
+ module: "api/v2",
+ method: "browserReplayController",
+ });
+
+ const resolved = await resolveReplaySession(req, res);
+ if (!resolved) return;
+
+ let recording: BrowserServiceRecordingResponse;
+ try {
+ recording = await browserServiceRequest<BrowserServiceRecordingResponse>(
+ "GET",
+ `/browsers/${resolved.browserId}/recording`,
+ );
+ } catch (err) {
+ if (err instanceof BrowserServiceError && err.status === 404) {
+ return res.status(404).json({
+ success: false,
+ error: "Replay not found.",
+ });
+ }
+ logger.error("Failed to fetch recording metadata", { error: err });
+ return res.status(502).json({
+ success: false,
+ error: "Failed to fetch session replay.",
+ });
+ }
+
+ return res.status(200).json({
+ success: true,
+ pages: recording.pages.map(page => ({
+ pageId: page.pageId,
+ url: `/v2/interact/${req.params.sessionId}/replay/${page.pageId}`,
+ pageUrl: page.url,
+ startTimeMs: page.startTimeMs,
+ endTimeMs: page.endTimeMs,
+ })),
+ pageCount: recording.pageCount,
+ });
+}
+
+/**
+ * GET /v2/interact/:sessionId/replay/:pageId
+ *
+ * Returns the HLS VOD playlist (.m3u8) for one recorded page. Segment URLs
+ * inside the playlist are pre-signed and expire (~6h); re-request the
+ * playlist to mint fresh ones. Hand the body to any HLS-capable player.
+ */
+export async function browserReplayPageController(
+ req: RequestWithAuth<{ sessionId: string; pageId: string }, any>,
+ res: Response,
+) {
+ const logger = _logger.child({
+ sessionId: req.params.sessionId,
+ teamId: req.auth.team_id,
+ module: "api/v2",
+ method: "browserReplayPageController",
+ });
+
+ if (!PAGE_ID_RE.test(req.params.pageId)) {
+ return res.status(400).json({
+ success: false,
+ error: "Invalid pageId.",
+ });
+ }
+
+ const resolved = await resolveReplaySession(req, res);
+ if (!resolved) return;
+
+ try {
+ const { body } = await browserServiceRequestText(
+ "GET",
+ `/browsers/${resolved.browserId}/recording/${req.params.pageId}`,
+ );
+ res.setHeader("Content-Type", "application/vnd.apple.mpegurl");
+ res.setHeader("Cache-Control", "no-store");
+ return res.status(200).send(body);
+ } catch (err) {
+ if (err instanceof BrowserServiceError && err.status === 404) {
+ return res.status(404).json({
+ success: false,
+ error: "Replay not found.",
+ });
+ }
+ logger.error("Failed to fetch recording playlist", { error: err });
+ return res.status(502).json({
+ success: false,
+ error: "Failed to fetch session replay.",
+ });
+ }
+}
diff --git a/apps/api/src/controllers/v2/browser.ts b/apps/api/src/controllers/v2/browser.ts
index ae15531f5..745c0b934 100644
--- a/apps/api/src/controllers/v2/browser.ts
+++ b/apps/api/src/controllers/v2/browser.ts
@@ -42,6 +42,7 @@ 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),
+ recordSession: z.boolean().default(true),
integration: integrationSchema.optional().transform(val => val || null),
profile: z
.object({
@@ -212,7 +213,8 @@ export async function browserCreateController(
req.body = browserCreateRequestSchema.parse(req.body);
- const { ttl, activityTtl, streamWebView, profile, integration } = req.body;
+ const { ttl, activityTtl, streamWebView, recordSession, profile, integration } =
+ req.body;
if (!config.BROWSER_SERVICE_URL) {
return res.status(503).json({
@@ -282,6 +284,7 @@ export async function browserCreateController(
"/browsers",
{
ttl,
+ record: recordSession,
...(activityTtl !== undefined ? { activityTtl } : {}),
...(persistentStorage !== undefined ? { persistentStorage } : {}),
},
diff --git a/apps/api/src/controllers/v2/scrape-browser.ts b/apps/api/src/controllers/v2/scrape-browser.ts
index eb9129b64..8638f9754 100644
--- a/apps/api/src/controllers/v2/scrape-browser.ts
+++ b/apps/api/src/controllers/v2/scrape-browser.ts
@@ -99,6 +99,7 @@ type BrowserExecuteRequest = z.infer<typeof browserExecuteRequestSchema>;
interface BrowserExecuteResponse {
success: boolean;
+ sessionId?: string;
cdpUrl?: string;
liveViewUrl?: string;
interactiveLiveViewUrl?: string;
@@ -370,6 +371,7 @@ export async function scrapeInteractController(
return res.status(200).json({
success: !hasError,
+ sessionId: session.id,
cdpUrl: session.cdp_url,
liveViewUrl: session.cdp_path,
interactiveLiveViewUrl: session.cdp_interactive_path,
diff --git a/apps/api/src/lib/scrape-interact/browser-service-client.ts b/apps/api/src/lib/scrape-interact/browser-service-client.ts
index 371c0dca3..bd06c9c09 100644
--- a/apps/api/src/lib/scrape-interact/browser-service-client.ts
+++ b/apps/api/src/lib/scrape-interact/browser-service-client.ts
@@ -82,3 +82,31 @@ export async function browserServiceRequest<T>(
if (res.status === 204) return undefined as T;
return res.json() as Promise<T>;
}
+
+/**
+ * Call the browser service and return the raw response body as text
+ * (used for HLS playlists). Throws `BrowserServiceError` on non-2xx.
+ */
+export async function browserServiceRequestText(
+ method: string,
+ path: string,
+): Promise<{ body: string; contentType: string | null }> {
+ const url = `${config.BROWSER_SERVICE_URL}${path}`;
+ const res = await fetch(url, {
+ method,
+ headers: browserServiceHeaders(),
+ });
+
+ if (!res.ok) {
+ const text = await res.text();
+ throw new BrowserServiceError(
+ res.status,
+ `Browser service ${method} ${path} failed (${res.status}): ${text}`,
+ );
+ }
+
+ return {
+ body: await res.text(),
+ contentType: res.headers.get("content-type"),
+ };
+}
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index f45bb0a68..2e02c923f 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -59,6 +59,10 @@ import {
browserListController,
browserWebhookDestroyedController,
} from "../controllers/v2/browser";
+import {
+ browserReplayController,
+ browserReplayPageController,
+} from "../controllers/v2/browser-replay";
import { activityController } from "../controllers/v1/activity";
import { supportProxyController } from "../controllers/v2/support-proxy";
import { createResearchRouter } from "../controllers/v2/research-proxy";
@@ -525,6 +529,18 @@ v2Router.post(
wrap(browserExecuteController),
);
+v2Router.get(
+ ["/browser/:sessionId/replay", "/interact/:sessionId/replay"],
+ authMiddleware(RateLimiterMode.BrowserExecute),
+ wrap(browserReplayController),
+);
+
+v2Router.get(
+ ["/browser/:sessionId/replay/:pageId", "/interact/:sessionId/replay/:pageId"],
+ authMiddleware(RateLimiterMode.BrowserExecute),
+ wrap(browserReplayPageController),
+);
+
v2Router.delete(
["/browser/:sessionId", "/interact/:sessionId"],
authMiddleware(RateLimiterMode.BrowserExecute),